@sema-agent/core/dist/core/runner/prepare-execution-env.d.ts

Stateless, task-oriented AI agent core

import type { ExecutionEnv } from "../../internal/harness.js";
import type { RunnerDeps, TaskSpec } from "../types.js";
import type { PrepareResume, RollbackStack, RunInternals } from "./contracts.js";
/**
 * The ONE reference to a factory-minted env, shared by the driver's detach guard and the rollback entry
 * this phase registers. `current` is the minted env, or `undefined` when the run has none / after the
 * driver detached an aliasing one. Written by: this phase (once, at the mint) and the driver's worktree
 * guard (the detach). Read by: the rollback entry (at unwind), and the driver, which settles it into a
 * plain `ownedEnv` binding once the guard has passed.
 */
export interface OwnedEnvSeat {
    current: ExecutionEnv | undefined;
}
export interface PrepareExecutionEnvInput {
    /** borrowed-readonly — the deployment's env seats: the per-task factory (wins), the static env, the
     *  declared root fence, and the incident sink for the bounded teardown legs. */
    deps: Pick<RunnerDeps, "executionEnvFactory" | "executionEnv" | "rootPath" | "onError" | "onNotice">;
    /** borrowed-readonly — the REBOUND spec; only the caller's task id rides into the factory ctx. */
    spec: Pick<TaskSpec, "taskId">;
    /** borrowed-readonly — the trusted spawn-side requests: the explicit cwd (a contract), the isolation
     *  request and the parent's cwd (both threaded to the factory ctx). */
    internals: Pick<RunInternals, "requestedCwd" | "isolation" | "parentCwd"> | undefined;
    /** borrowed-readonly — the resume leg, read only to refuse an explicit cwd that a checkpoint workspace
     *  restore would overrule. */
    resume: Pick<PrepareResume, "workspaceHandle"> | undefined;
    /** borrowed-readonly — the run tree's placement fixed point, resolved ONCE by the driver; the factory
     *  door refuses an empty value loudly before the factory is asked. */
    placementRootResolved: string;
    /** borrowed-readonly — the acquired session id (the factory ctx's identity, and the incident phase tag). */
    sessionId: string;
    /** borrowed-readonly — the driver's session-view forget leg; every refusal here runs it, bounded, before
     *  throwing (the acquired view must not outlive a prepare the caller never gets a handle to). */
    forgetOnThrow: () => Promise<void>;
    /** borrowed-mutable — the driver-owned prepare-failure stack; this phase pushes ONE entry (the minted
     *  env's destroy, read through the seat) and nothing else touches it here. */
    rollback: RollbackStack;
}
export interface PrepareExecutionEnvResult {
    /** borrowed-readonly — the run's resolved env: the minted one, else the static one, else the no-I/O stub. */
    executionEnv: ExecutionEnv;
    /** ownership-ref — the seat holding the factory-minted env (`current` undefined when none was minted).
     *  The exception-path protocol stays with the driver (D-8 案①): its worktree guard may detach through
     *  this seat before throwing; the rollback entry registered here reads it at unwind. */
    ownedEnvSeat: OwnedEnvSeat;
    /** borrowed-readonly — epoch ms at which the factory-minted env was obtained (the lifetime anchor of
     *  last resort); `undefined` for a static env or no env. */
    ownedEnvObservedAt: number | undefined;
    /** borrowed-readonly — whether a real fs env is present (a minted env, or a static one). */
    handsEnabled: boolean;
    /** borrowed-readonly — the INITIAL task root (the workspace-restore phase may re-root it and returns the
     *  settled root under the NEW name `taskRootFinal`). */
    taskRootInitial: string;
}
export declare function prepareExecutionEnv(input: PrepareExecutionEnvInput): Promise<PrepareExecutionEnvResult>;