@sema-agent/core
Version:
Stateless, task-oriented AI agent core
55 lines (54 loc) • 4.03 kB
TypeScript
import type { ExecutionEnv } from "../../internal/harness.js";
import type { RunnerDeps, TaskSpec } from "../types.js";
import type { PrepareResume, RunInternals } from "./contracts.js";
export { remoteEnvFailureNote, restoreWorkspaceWithRetry } from "./remote-env-retry.js";
export interface PrepareWorkspaceRestoreInput {
/** borrowed-readonly (the ownership-ref PROTOCOL stays with the driver — D-8 案①): the env this
* task owns, when the factory minted one. This phase reads and drives it (`resumeVM`,
* `postResumeInit`, `canonicalPath`) but NEVER rebinds or destroys it — the detach guard and the
* prepare-throw catch are the exception-path owners, both in the driver, and their reference
* must stay authoritative (a phase-local rebind could never reach them). */
ownedEnv: ExecutionEnv | undefined;
/** borrowed-readonly — the two deployment seats this phase reads, as a Pick over the SAME `deps`
* object (相 API 规则件 R-4: receiver preserved for `deps.onError?.()`; a new deps read must
* widen this Pick). `executionEnv` feeds only the observation sink's remote predicate. */
deps: Pick<RunnerDeps, "onError" | "executionEnv">;
/** borrowed-readonly — `signal` only: the caller's cancel signal, composed into the restore's
* abortSignal so a cancel DURING the restore short-circuits it (the live listener is attached
* only after the harness exists). */
spec: Pick<TaskSpec, "signal">;
/** borrowed-readonly — the trusted spawn-side seats the observation sink reads: the sink itself
* and the isolation REQUEST (by this point past the driver's fail-closed enforcement, so
* `isolated: true` is a receipt, not a restatement). */
internals: Pick<RunInternals, "onWorkspaceResolved" | "isolation"> | undefined;
/** borrowed-readonly — the durable-resume seats this phase reads: the checkpointed
* `workspaceHandle` (restore target) and `executesApprovedAction` (the divergence fail-closed
* key). Absent for a fresh/non-durable run: the phase is then root-passthrough. */
resume: Pick<PrepareResume, "workspaceHandle" | "executesApprovedAction"> | undefined;
/** owned (value) — the pre-restore task root (isolation-aware initial derivation, computed in the
* driver). Dead after this call by design (R-5): later phases read the returned
* `taskRootFinal`, never this spelling. */
taskRootInitial: string;
/** borrowed-readonly — prepare's abort seat; only `.signal` is read (kept as the object so the
* moved body's `abortController.signal` spelling stays verbatim). */
abortController: {
readonly signal: AbortSignal;
};
/** borrowed-readonly — the acquired session's id, for the observation arms' error tags. */
sessionId: string;
}
/** The phase's outputs (相 API 规则件 four-class form). */
export interface PrepareWorkspaceRestoreResult {
/** owned — the SETTLED task root (T6 FINAL semantics): the initial derivation, else the park-only
* handle's mountPath, else resumeVM's restored mountPath — settled before the observation sink
* fired. Bound to a NEW name by design (R-5): `taskRootPath` must not be re-spelled by later
* phases, so a consumer moved ahead of this call is a lexical error. */
taskRootFinal: string;
/** owned (pure function; closes over the phase-armed rebase state) — migrates one checkpointed
* absolute path from the OLD workspace root onto the restored one (any accepted
* spelling of the old root); the identity function when no divergence was armed. Consumers (T7):
* the readFileState checkpoint seed, the handsCwd seed, the activeWorktree restore. */
rebaseRestoredPath: (p: string) => string;
}
/** The B-4 phase body — the workspace-restore slice, verbatim (see the module header for the contract). */
export declare function prepareWorkspaceRestore(input: PrepareWorkspaceRestoreInput): Promise<PrepareWorkspaceRestoreResult>;