@sema-agent/core/dist/core/runner/checkpoint-scope.d.ts

Stateless, task-oriented AI agent core

/**
 * The durable-suspend checkpoint ROW-IDENTITY vocabulary — the default isolation scope, the ONE derivation of a row's
 * scope, and the ONE reading of the placement fields' empty string — moved whole out of the orchestrator so the
 * wiring-manifest phase (the synthesized durableApproval), the park-lane phases (the mint sites and the suspend stamp),
 * the driver (the restore fold) and runtask (the resume rung) reach DOWN for the same names. Pure: a constant and two
 * string functions.
 */
/** The multi-tenant scope used when a durable suspend fires for an IRREVERSIBLE tool in an
 *  unattended deployment that did NOT opt into `durableApproval` (so there is no caller-supplied scope). The
 *  checkpoint carries this scope; resume reads it back from the checkpoint (`cp.scope`), so it is
 *  self-consistent without needing the original `TaskSpec`. Kept distinct from any tenant key to make an
 *  unattended irreversible suspend auditable as such. */
export declare const DEFAULT_IRREVERSIBLE_SCOPE = "irreversible";
/**
 * The SINGLE derivation of a durable-suspend checkpoint's scope (both gate mint
 * sites + the bg-watcher park lane's expire compensation/arbitration consume THIS; a re-derived copy
 * that drifted was the exact bug the park tests caught — expire against the wrong scope silently
 * no-ops). `|| DEFAULT` (not `??`): an EMPTY-string principal must not become a shared scope bucket.
 *
 * That rule is stated twice in this file and was enforced on ONE of the two
 * inputs — the principal half used `||`, the `durableApproval.scope` half used `??`, so an empty string
 * arriving through the scope field (a config-centre / env lookup that came back blank is the realistic
 * source) sailed through as the literal scope `""`. Two different tenants both landed in that one bucket,
 * where `listByScope("")` reads BOTH their pending approvals — including each summary's `toolInput`
 * preview of the raw arguments — and `reap("")` / `resolve(token, "")` act across both. `durableApproval.
 * scope` is documented as "Multi-tenant isolation key … Required"; a blank string is the absence of an
 * isolation key wearing its clothes, so both halves now fall through to the default isolation scope.
 */
export declare function checkpointScopeOf(spec: {
    durableApproval?: {
        scope?: string;
    };
    principal?: string;
}): string;
/**
 * The ONE spelling of the placement fields' empty-string discipline: `""` is absence
 * wearing clothes (the resume entry's principal-rung posture), and every placement read that must
 * treat it so — the resume rung's two sides (runtask), the restore fold's seed and the suspend
 * stamp — goes through THIS helper, so three sites cannot drift into three readings. Deliberately
 * NOT applied to the live `internals.placementRoot`/`rootSessionId` reads of the RESOLUTION fold:
 * an empty supplied claim there is an assembly error the execution-env phase's `mintPlacementRootSessionId` refuses
 * loudly on the factory path, and normalizing it away would silently repair what should be loud.
 */
export declare function placementValueOrAbsent(value: string | undefined): string | undefined;