@sema-ai/core 1.275.1

package/dist/core/remote-env.d.ts

@@ -0,0 +1,432 @@
+/**
+ * Remote execution seam (design/48 §5) — the type-only contract a **remote/containerised** `ExecutionEnv`
+ * implementation (E2B/Firecracker, owned by the service control plane) must satisfy so the agent's "hand"
+ * (design/44) can act inside an isolated, *stateful*, *suspendable* workspace instead of the in-process
+ * `NodeExecutionEnv`.
+ *
+ * **This file is a SEAM, not an implementation.** The real `RemoteContainerExecutionEnv` (E2B SDK, warm
+ * pools, snapshot lifecycle, tier routing) lives in the service and is driven by real integration needs —
+ * exactly like `CheckpointStore` (design/45). Core owns the seam shape; service owns the backend.
+ *
+ * Design rulings folded in (design/48 §10/§11 DeepSeek council):
+ * - **#1 [blocker] interface extension, not capability probing**: `RemoteExecutionEnv extends ExecutionEnv`.
+ *   The base {@link ExecutionEnv} is UNCHANGED — `NodeExecutionEnv`/`StubExecutionEnv` need zero edits, and a
+ *   consumer that only needs buffered fs/shell keeps accepting the base type.
+ * - **#3 [major] do not overload `exec`**: `exec()` stays buffered; streaming is a NEW {@link execStream}.
+ * - **#4 [major] suspend × in-flight exec must not hang**: see {@link suspendVM}.
+ * - **#8 [major] post-resume consistency**: see {@link postResumeInit}.
+ * - **#10 naming**: the isolation level is `sandboxTier` (not `tier`) to avoid clashing with the existing
+ *   timeout-/degradation-"tier" in the codebase.
+ * - **#16 suspend/resume disambiguation**: the VM-lifecycle methods are `suspendVM`/`resumeVM` to keep them
+ *   distinct from the Runner gate-resume and design/45 wake/resume semantics.
+ *
+ * **Deferred (NOT modelled here — they are runtime, not seam):** actually suspending a running task and
+ * persisting the {@link WorkspaceHandle} into a design/45 `Checkpoint`; the `status:"suspended"` orchestrator
+ * mapping; tier *classification* (the static table + Tier1-safe allow-list + fail-closed routing) — all are
+ * service/design-45 implementation-time concerns. Core only declares the seam those will plug into.
+ */
+import type { ExecutionEnv } from "../internal/harness.js";
+/** Snapshot identifier returned by {@link RemoteExecutionEnv.suspendVM}; opaque to core, resolved by the provider. */
+export type SnapshotId = string;
+/**
+ * Token identifying a still-running remote session, used by {@link RemoteExecutionEnv.reconnect} to re-attach
+ * the control plane's transport after a control-plane replica crash/failover. The underlying VM state lives
+ * independently of any single control-plane TCP connection (a Firecracker process survives a dropped client),
+ * so reconnect re-binds rather than re-creates.
+ */
+export type SessionToken = string;
+/** Isolation routing level (design/48 §2). v1 runs everything as Tier 2; classification is DEFERRED to service. */
+export type SandboxTier = 1 | 2;
+/**
+ * Serializable identity of a remote workspace (design/48 §5 gap 1). The control plane persists this into its
+ * durable state (and design/45 `Checkpoint`) so a *different* replica can reconnect/resume the same workspace.
+ */
+export interface WorkspaceHandle {
+    /** Provider/VM/sandbox id (e.g. an E2B sandbox id). */
+    sandboxId: string;
+    /** Provider identifier (e.g. `"e2b"`), so the control plane routes reconnect/destroy to the right backend. */
+    provider: string;
+    /** Absolute mount path of the workspace root inside the remote env; remote paths normalize against this. */
+    mountPath: string;
+    /** Set when this env was produced by resuming a snapshot ({@link RemoteExecutionEnv.resumeVM}), else undefined. */
+    snapshotId?: SnapshotId;
+    /** Token for {@link RemoteExecutionEnv.reconnect} when the VM is still running (vs suspended to a snapshot). */
+    sessionToken?: SessionToken;
+    /** How a checkpointed workspace is restored on resume (1.257.2 hardening, codex review of [500]②):
+     *  `"park_only"` = durable-park-only suspend degrade (non-suspendable env; workspace persists on the
+     *  target, resume skips `resumeVM`). Absent = legacy/snapshot handle — resume treats a MISSING
+     *  `snapshotId` as corruption (fail-closed) unless the resumed env is itself non-suspendable
+     *  (tolerance for park handles minted by 1.257.1 before this field existed). */
+    restoreMode?: "park_only";
+}
+/**
+ * A reference to a secret injected at {@link RemoteExecutionEnv.connect}/{@link RemoteExecutionEnv.postResumeInit}
+ * time (design/48 §5 gap 7) — never baked into the image. The control plane resolves {@link ref} to a value out of
+ * band; only the reference travels through core.
+ */
+export interface SecretRef {
+    /** Logical name the secret is exposed under (an env-var name in the remote env for `destination:"remote"`). */
+    name: string;
+    /** Opaque locator the control plane resolves to a value (vault path, KMS key id, …). */
+    ref: string;
+    /**
+     * Where the resolved secret is consumed (design/61 §9 B, council). Default `"remote"` (the original
+     * semantics): injected **into the remote env** as `name` (E2B env-var) — visible to code running there.
+     * `"adapter"`: used by the **adapter itself** to establish/authenticate the connection (an SSH private key,
+     * an ADB token) and **MUST NOT be injected into the target machine/device** — a credential that reaches an
+     * un-isolated target's environment is the lethal trifecta (design/53 §C). An adapter MUST honor this.
+     */
+    destination?: "remote" | "adapter";
+}
+/** Configuration for {@link RemoteExecutionEnv.connect}. */
+export interface RemoteConnectConfig {
+    /** Resume from this snapshot instead of provisioning a fresh workspace. */
+    snapshotId?: SnapshotId;
+    /** Secrets to inject at connect time (design/48 §5 gap 7). */
+    secrets?: SecretRef[];
+    /** Abort provisioning/connection. */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Options for the VM-lifecycle ops {@link RemoteExecutionEnv.suspendVM} / {@link RemoteExecutionEnv.resumeVM}
+ * (design/49 v1.5, code-ready council BUG#2). Parity with {@link RemoteConnectConfig.abortSignal} /
+ * {@link ExecStreamOptions.signal}: without an abort hook a hung provider pause/restore (network partition)
+ * would pin the calling worker forever. The implementation races the op against this signal + an internal
+ * timeout; on abort it returns `{ok:false}` with code `"aborted"`.
+ */
+export interface VmLifecycleOptions {
+    /** Abort a hung pause/restore. */
+    abortSignal?: AbortSignal;
+}
+/**
+ * One chunk streamed from {@link RemoteExecutionEnv.execStream} (design/48 §5 gap 3, council BUG#3). A run is a
+ * sequence of `stdout`/`stderr` chunks terminated by exactly one `exit` chunk carrying the typed exit code.
+ *
+ * The async iterator THROWS a {@link RemoteExecutionError} if the stream fails before an `exit` chunk arrives
+ * (transport loss, or a {@link RemoteExecutionEnv.suspendVM} that aborts the in-flight command) — that is the
+ * streaming analogue of the base {@link ExecutionEnv}'s never-throw `Result` contract, and it guarantees a
+ * consumer is never left awaiting a chunk that will never come.
+ */
+export type OutputChunk = {
+    type: "stdout";
+    data: string;
+} | {
+    type: "stderr";
+    data: string;
+} | {
+    type: "exit";
+    exitCode: number;
+};
+/** Options for {@link RemoteExecutionEnv.execStream}. */
+export interface ExecStreamOptions {
+    /**
+     * Isolation routing hint (design/48 §2; renamed from `tier` per §11 #10). The *classification* that decides
+     * a command's tier — static tool table + Tier1-safe sub-command allow-list, fail-closed to Tier 2 — is the
+     * env/control-plane's job and is DEFERRED; this param only lets a caller pass an explicit route when known.
+     */
+    sandboxTier?: SandboxTier;
+    /** Working directory; relative paths resolve against the workspace root. */
+    cwd?: string;
+    /** Extra environment variables for the command. */
+    env?: Record<string, string>;
+    /**
+     * Total command wall-clock timeout in seconds. **🔴 Per-command — independent of the env/sandbox lifetime.**
+     * A remote adapter MUST NOT fall back to the sandbox lifetime when this is unset (service [45]: an E2B adapter
+     * that defaulted a missing per-command timeout to `cfg.timeoutMs` = the sandbox lifetime made a seconds-long
+     * command wait the *whole sandbox lifetime*, ~30 min, on a provider RPC hang). "No `timeout`" means "no
+     * wall-clock cap on a *making-progress* command" — NOT "wait until the env dies"; liveness is still bounded by
+     * {@link readTimeoutMs} (see below). Distinct concerns: `timeout` caps a slow-but-progressing command;
+     * `readTimeoutMs` catches a *hung/unreachable* one.
+     */
+    timeout?: number;
+    /** Abort the command. Aborting ends the stream with a {@link RemoteExecutionError} (code `"aborted"`, no `exit` chunk). */
+    signal?: AbortSignal;
+    /**
+     * Idle/liveness read timeout (ms). If no {@link OutputChunk} arrives within this window, `execStream` ends
+     * with a {@link RemoteExecutionError} (code `"timeout"`) instead of hanging. **Needed in practice for remote
+     * backends** (design/48 §5, service [7]): E2B issue #1128 — a *streaming* call sets no read timeout (only unary
+     * does), so an unreachable sandbox hangs the worker forever. Distinct from `timeout` (total wall-clock).
+     *
+     * 🔴 **Liveness contract (service [45]/[59]):** a remote adapter SHOULD enforce a default liveness bound even
+     * when this is unset (a missing idle timeout MUST NOT mean "wait forever / until the env dies"), and that bound
+     * MUST cover the **command-creation/handshake RPC**, not only the post-first-chunk loop — a provider hang
+     * typically occurs at creation, before any chunk arrives, so an idle timer started only after the first chunk
+     * misses it. On trigger, throw {@link RemoteExecutionError} with code `"timeout"` (retryable by the caller per
+     * the command's idempotency — the adapter MUST NOT blind-retry).
+     */
+    readTimeoutMs?: number;
+    /** Per-call output cap (design/48 §5 gap 8): stop streaming after this many bytes to avoid a `find /` flooding the control plane. */
+    maxOutputBytes?: number;
+}
+/** Stable error codes for the remote seam's lifecycle/streaming operations (design/48 §5/§11 BUG#2). */
+export type RemoteExecutionErrorCode = 
+/** A lifecycle/exec op failed because the workspace is (or became) suspended. */
+"suspended"
+/** {@link RemoteExecutionEnv.suspendVM} refused because a command was still in flight (council #4). */
+ | "command_in_flight"
+/** Connect/resume/reconnect failed to reach or provision the remote workspace. */
+ | "connect_failed"
+/** A post-resume consistency step failed (design/48 §5/#8) — caller must destroy the env. */
+ | "post_resume_failed"
+/** The command/stream was aborted via its `AbortSignal`. */
+ | "aborted"
+/**
+ * A command's wall-clock {@link ExecStreamOptions.timeout} or liveness {@link ExecStreamOptions.readTimeoutMs}
+ * was exceeded — including a provider RPC hang at command creation (service [45]/[59]). **Retryable** by the
+ * caller per the command's idempotency (the adapter MUST NOT blind-retry). Distinct from `"aborted"` (a
+ * caller-driven `AbortSignal`) and `"connect_failed"` (workspace provisioning, not a per-command hang).
+ */
+ | "timeout"
+/**
+ * The op is not supported by this adapter's capabilities (design/61 §9 A) — e.g. `suspendVM`/`resumeVM` on a
+ * non-suspendable SSH/ADB env. Permanent for this env; check {@link RemoteExecutionEnv.capabilities} first.
+ */
+ | "unsupported"
+/**
+ * A **transient** authentication step that is expected to succeed on a retry (design/61 §9 C) — e.g. an ADB
+ * device awaiting first-time authorization (connect once → user authorizes → connect again succeeds).
+ * **Retryable** (typically retry-exactly-once). Distinct from {@link "auth_failed"} so a real rejection isn't
+ * retried and a bounded ADB retry doesn't false-kill an SSH transient.
+ */
+ | "auth_transient"
+/**
+ * **Permanent** authentication failure (design/61 §9 C) — wrong/rejected SSH key, revoked token. **NEVER
+ * retry** (retrying burns the whole attempt budget and can lock accounts). The caller must surface it.
+ */
+ | "auth_failed"
+/**
+ * The transport connection dropped mid-session (TCP RST, network partition, peer close) — design/61 §9 C/#14.
+ * **Retryable** by re-establishing the connection (idempotent for a persistent SSH/ADB session). An adapter
+ * MUST map raw transport errors (DNS `ENOTFOUND`, TCP RST) onto a typed code, not leave them as `"unknown"`,
+ * else a retry whitelist misses them.
+ */
+ | "transport_lost"
+/** Unclassified provider/transport failure. */
+ | "unknown";
+/**
+ * Error surfaced by {@link RemoteExecutionEnv} lifecycle ops and by {@link RemoteExecutionEnv.execStream}'s
+ * iterator. Mirrors the vendored `ExecutionError` shape but carries the remote-specific code set; it is kept
+ * separate from the vendored `ExecutionErrorCode` union deliberately — those codes only need to widen once the
+ * design/45 suspend/resume *runtime* lands and the Runner/orchestrator layer must thread `"suspended"`.
+ */
+export declare class RemoteExecutionError extends Error {
+    readonly code: RemoteExecutionErrorCode;
+    constructor(code: RemoteExecutionErrorCode, message: string, cause?: Error);
+}
+/**
+ * A remote, stateful, suspendable {@link ExecutionEnv} (design/48 §5). Extends the base with workspace identity,
+ * connection lifecycle, streaming exec, and post-resume reconciliation. Every method follows the base contract:
+ * **never throw/reject** — encode failures in the returned `Result` (the one exception is {@link execStream},
+ * whose iterator may throw mid-stream; see {@link OutputChunk}).
+ *
+ * Lifecycle methods are typed but their RUNTIME wiring (task suspension, `Checkpoint` persistence of the
+ * {@link WorkspaceHandle}, cross-replica resume) is implemented with design/45 — see the file header.
+ *
+ * 🔴 **Universal liveness contract (service [45]/[59] class-fix) — applies to EVERY remote RPC**, not just
+ * `execStream`: the inherited {@link ExecutionEnv} filesystem ops (`readTextFile`/`writeFile`/`listDir`/…), the
+ * streaming/buffered exec, AND the VM-lifecycle ops below (`connect`/`reconnect`/`suspendVM`/`resumeVM`/
+ * `postResumeInit`/`destroy`). Each is a network round-trip to a provider that can hang. The contract:
+ * 1. **Every remote RPC SHOULD enforce a bounded default liveness/idle timeout** even when no `abortSignal`/
+ *    timeout is given — a hung provider call MUST NOT wait until the env/sandbox lifetime expires (the
+ *    service [45] bug, but generalized: it was found on `exec`, and `files.read`/`resumeVM`/etc. share the
+ *    exact exposure). An optional `abortSignal` (where present) composes with, but does not replace, this default.
+ * 2. **🔴 Bound on LIVENESS (no progress), not a fixed short wall-clock** — distinguish *hung* from *slow but
+ *    progressing* (search [60] / service [50] data-transfer sharpening). A **data-transfer** op — a large-workspace
+ *    `suspendVM` snapshot, a big `writeFile`/`readTextFile` — may legitimately run for minutes; a fixed short
+ *    wall-clock would false-kill the (durable-checkpoint *命门*) path. So such ops bound on an **idle/no-heartbeat**
+ *    window (reset by observable progress), not total elapsed time. Cheap control RPCs (`isRunning`, a small
+ *    `connect` handshake) may use a short wall-clock. The adapter sizes the bound per op class.
+ * 3. **A liveness breach surfaces as a typed, retryable error**: `RemoteExecutionError` code `"timeout"` for the
+ *    lifecycle/stream ops; for the inherited filesystem ops (which return the vendored `Result<_, FileError>`),
+ *    a `FileError` — but still **bounded, never an unbounded wait**. Retry is the caller's decision per the op's
+ *    idempotency; the adapter MUST NOT blind-retry.
+ */
+export interface RemoteExecutionEnv extends ExecutionEnv {
+    /**
+     * What this adapter can actually do (design/61 §9 A, council). The seam was built for E2B (a full
+     * `{isolation:true, suspendable:true}` adapter); **partial-capability** adapters (SSH/ADB: `{false, false}`
+     * — a real machine/device, not snapshotable and not isolated) declare it here. **Required + explicit** so
+     * the orchestrator never has to guess: there is no safe default (assuming isolation when there is none is a
+     * security hole; assuming suspendable crashes on `suspendVM`). Use {@link isSuspendable}/{@link isIsolated}
+     * rather than the structural {@link isRemoteExecutionEnv} (method presence ≠ semantics — a stub `suspendVM`
+     * that returns `"unsupported"` still satisfies the structural check). Extensible: add fields as new
+     * partial-capability classes appear.
+     */
+    readonly capabilities: {
+        /** True iff actions are contained (E2B microVM); false for a real target (SSH host / ADB device). The
+         *  orchestrator tightens autonomy + the design/37 policy gate when this is false (design/53 zero-trust). */
+        isolation: boolean;
+        /** True iff the env can be snapshot/`suspendVM`'d (E2B); false for SSH/ADB (durable suspend N/A).
+         *
+         *  ⚠️ LOAD-BEARING INVARIANT (opus review 1.257.2): `suspendable:false` on a remote env also asserts
+         *  the workspace is EXTERNALLY DURABLE — it persists on the target across the env object's lifetime
+         *  (true for SSH hosts / ADB devices). The durable-park-only suspend degrade (service [500]②) rests
+         *  on this: it skips `suspendVM` and trusts the factory to reconnect to the SAME workspace on resume.
+         *  An adapter for a non-suspendable EPHEMERAL backend (e.g. a snapshot-less container torn down with
+         *  the transport) must NOT be modeled as `suspendable:false` remote — it would silently take the
+         *  park-only branch and resume onto a fresh empty workspace. Model such a backend as a per-task env
+         *  without durable suspend instead (the human gate refuses it), or extend capabilities with an
+         *  explicit workspace-durability flag before building one. */
+        suspendable: boolean;
+    };
+    /** Identity of the connected workspace (design/48 §5 gap 1). Synchronous: it is data the env already holds. */
+    workspaceHandle(): WorkspaceHandle;
+    /** Provision/attach the remote workspace and inject secrets. Returns the resulting {@link WorkspaceHandle}. */
+    connect(config?: RemoteConnectConfig): Promise<{
+        ok: true;
+        value: WorkspaceHandle;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    /**
+     * Snapshot the workspace and (provider permitting) stop billing; returns the {@link SnapshotId} to resume from.
+     *
+     * **Council #4 — must not leave an in-flight command hung.** If a {@link Shell.exec}/{@link execStream} is in
+     * flight, an implementation MUST either (a) refuse with `RemoteExecutionError("command_in_flight")`, or (b)
+     * abort the in-flight command — buffered `exec` then resolves an `Err` and an in-flight {@link execStream}
+     * iterator throws `RemoteExecutionError("suspended")`. It must NOT silently snapshot and leave the command's
+     * promise/iterator pending forever.
+     *
+     * **🔴 Atomicity contract (design/49 v1.5, code-ready council BUG#1/#13).** This is the FIRST durable side
+     * effect of a remote durable-suspend, so its all-or-nothing semantics are load-bearing for the Runner's
+     * commit ordering:
+     * - `{ok:true}` ⇒ the VM is paused at `value` (a `SnapshotId`); the caller may now persist a checkpoint.
+     * - `{ok:false}` ⇒ the VM is left in its ORIGINAL (running) state, untouched — the caller can safely fall
+     *   back to the synchronous `onAsk` gate as if no suspend was attempted (Runner: design/49 §4①).
+     * An implementation MUST NOT return `{ok:false}` after it has already paused/snapshotted the VM. The gate
+     * path means no command is in flight (the batch's prior calls are awaited, the gated call has not run), so
+     * `command_in_flight` should not arise; if it does, the Runner treats it as an ordinary `{ok:false}` and
+     * falls back to `onAsk` — see {@link RemoteExecutionErrorCode}.
+     */
+    suspendVM(options?: VmLifecycleOptions): Promise<{
+        ok: true;
+        value: SnapshotId;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    /** Restore the workspace from a snapshot. Idempotent + re-entrant (a replica that crashed mid-suspend can be
+     *  superseded by another resuming the same {@link SnapshotId} without corruption — aligns with design/45 resolve-CAS).
+     *  Pass `options.abortSignal` so a hung restore cannot pin the resuming worker (design/49 BUG#2). */
+    resumeVM(snapshotId: SnapshotId, options?: VmLifecycleOptions): Promise<{
+        ok: true;
+        value: WorkspaceHandle;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    /** Re-attach the control-plane transport to a still-running VM after a control-plane reconnect (design/48 §5 gap 4). */
+    reconnect(sessionToken: SessionToken): Promise<{
+        ok: true;
+        value: WorkspaceHandle;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    /**
+     * Re-establish consistency AFTER {@link resumeVM}/{@link reconnect} (design/48 §5 gap, council #8): re-fetch git
+     * remote refs + invalidate stale package/index caches, and re-inject secrets (short-lived credentials may have
+     * expired while suspended). Any failed step → `Err("post_resume_failed")` and the caller MUST destroy the env.
+     *
+     * Note: a resumed guest's network/long-lived connections (git remote / API / registry) are NOT guaranteed to
+     * survive the snapshot (clay decision 2), so this is also where the VM-internal agent rebuilds those.
+     *
+     * 🔴 Ordering red line (design/48 §5/#6): at-rest encryption of the memory snapshot must be ensured BEFORE
+     * secrets are injected — never let plaintext credentials land in an unencrypted snapshot. That encryption is a
+     * service-side property of the snapshot store; this method must fail-and-clean if it cannot be guaranteed.
+     */
+    postResumeInit(): Promise<{
+        ok: true;
+        value: void;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    /**
+     * Stream a command's output (design/48 §5 gap 3) — the standard path for long build/test runs. Distinct from
+     * the buffered base `exec()` (council #3: no overload). Yields `stdout`/`stderr` chunks then exactly one `exit`
+     * chunk; the iterator throws {@link RemoteExecutionError} if the stream fails before `exit` (see {@link OutputChunk}).
+     *
+     * 🔴 **Timeout/liveness contract (service [45]/[59]) — applies to BOTH `execStream` and the base `exec`:** a
+     * per-command timeout is **independent of the env/sandbox lifetime** and an adapter MUST NOT fall back to the
+     * lifetime when none is given (else a hung provider RPC pins the worker for the whole sandbox lifetime). An
+     * adapter SHOULD enforce a bounded default liveness/idle timeout that also covers the command-creation RPC, and
+     * surface a liveness/timeout breach as a typed, retryable {@link RemoteExecutionError} code `"timeout"`. See
+     * {@link ExecStreamOptions.timeout} / {@link ExecStreamOptions.readTimeoutMs}.
+     */
+    execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
+    /**
+     * Tear down the workspace and release provider resources. Best-effort; must never throw (like `cleanup`).
+     * **Must be idempotent** — safe to call more than once (the second call is a no-op). The Runner calls it
+     * once on task end, and `prepareTask` calls it on a prepare-time throw; a remote impl may also be reaped,
+     * so a defensive double-call must not error or double-bill.
+     *
+     * 飞轮 [519] contract note: on a NON-isolated env (no `capabilities.isolation` — host lane, SSH host),
+     * destroy() is workspace/object-level cleanup and must NOT reap still-running background processes —
+     * that is `disposeBackgroundShells`' job, which honours the timeout/session keep-alive except-list
+     * ([511]③ monitor timeout anchor). An isolated env (container/VM) naturally takes everything down;
+     * the Runner's envDying settle accounts for that with an accurate killed receipt beforehand.
+     */
+    destroy(): Promise<void>;
+}
+/** Context handed to an {@link ExecutionEnvFactory} for each task (design/48 §5 / §7 Q7). Deliberately minimal:
+ *  per-task identity is enough to allocate/route a per-task container; richer routing (tenant/principal) is
+ *  captured in the factory closure by the trusted control plane that builds it. */
+export interface ExecutionEnvFactoryContext {
+    /** Resolved session id for the task — the stable identity of its per-task workspace. */
+    sessionId: string;
+    /** Caller-supplied task id, when set on the `TaskSpec`. */
+    taskId?: string;
+    /**
+     * design/97 CORE-6 — per-task ISOLATION hint threaded from the workflow's `ctx.agent({ isolation })` via the
+     * TRUSTED `RunInternals` channel (never from the untrusted `TaskSpec`). When `"worktree"`, a control-plane
+     * factory should mint a git-worktree-rooted env for this agent (e.g. via {@link addWorktree}) WITH a
+     * `destroy()` that removes the worktree, and return the SHARED base env (no `destroy`) otherwise. Unset =
+     * default (the factory's normal per-task env).
+     */
+    isolation?: "worktree";
+    /**
+     * Blackboard 2026-07-03 (clay dogfood — sub-agents landing in an EMPTY sandbox): the PARENT task's
+     * effective working root, threaded (like `isolation`) via the TRUSTED `RunInternals` channel when this
+     * task is a sub-agent (workflow `ctx.agent` / Task delegation). CC parity: a Task sub-agent inherits the
+     * main session's cwd. A single-user/TOC factory SHOULD root the child env here (unless `isolation`
+     * requests a worktree — that wins); a multi-tenant/TOB factory minting isolated containers may ignore
+     * it. Absent on top-level tasks. Static shared-`executionEnv` deployments need nothing — the child
+     * already shares the parent env (and its cwd).
+     */
+    parentCwd?: string;
+}
+/**
+ * A **trusted control-plane** factory that mints a per-task {@link ExecutionEnv} (design/48 §5 answers core
+ * gap-a / §7 Q7). Lives on `RunnerDeps` (deployment-level) — NOT on `TaskSpec` — so an untrusted caller can
+ * never inject its own env and escape the sandbox (design/44 §7 Q4 red line; clay decision 3: the Docker
+ * fast-lane must be control-plane-assigned, never task-selectable).
+ *
+ * The remote model is "one container per task", so the factory is invoked once per task. The Runner owns the
+ * lifetime of a factory-produced env: if it implements {@link RemoteExecutionEnv.destroy} (see {@link hasDestroy}),
+ * the Runner calls it when the task ends.
+ */
+export type ExecutionEnvFactory = (ctx: ExecutionEnvFactoryContext) => ExecutionEnv | Promise<ExecutionEnv>;
+/** True when `env` exposes a lifecycle {@link RemoteExecutionEnv.destroy} the Runner should call on task end. */
+export declare function hasDestroy(env: ExecutionEnv): env is ExecutionEnv & Pick<RemoteExecutionEnv, "destroy">;
+/** Structural check that `env` implements the remote seam (lifecycle + streaming surface + declared capabilities). */
+export declare function isRemoteExecutionEnv(env: ExecutionEnv): env is RemoteExecutionEnv;
+/**
+ * Can this env be durably suspended/snapshotted (design/61 §9 A)? Use this — NOT the structural
+ * {@link isRemoteExecutionEnv} — before calling `suspendVM` (a non-suspendable SSH/ADB env declares
+ * `capabilities.suspendable: false` but still has the method, which returns `"unsupported"`). Non-remote
+ * (in-process) envs are not suspendable.
+ *
+ * A composite type guard (structural AND capability) so a `suspendVM` call site narrowed by THIS predicate
+ * gets the {@link RemoteExecutionEnv} type without a cast — `true` always implies the structural check too.
+ */
+export declare function isSuspendable(env: ExecutionEnv): env is RemoteExecutionEnv;
+/**
+ * Is this env an isolated sandbox (design/61 §9 A, design/53)? `false` for a real SSH host / ADB device AND
+ * for any in-process env (the host process is not isolated). The orchestrator tightens autonomy + the
+ * design/37 policy gate when this is `false` (zero-trust on an un-isolated target). The safe default is
+ * `false` — isolation must be explicitly declared, never assumed.
+ */
+export declare function isIsolated(env: ExecutionEnv): boolean;
+//# sourceMappingURL=remote-env.d.ts.map

package/dist/core/remote-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-env.d.ts","sourceRoot":"","sources":["../../src/core/remote-env.ts"],"names":[],"mappings":"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"}

package/dist/core/remote-env.js

@@ -0,0 +1,77 @@
+/**
+ * Remote execution seam (design/48 §5) — the type-only contract a **remote/containerised** `ExecutionEnv`
+ * implementation (E2B/Firecracker, owned by the service control plane) must satisfy so the agent's "hand"
+ * (design/44) can act inside an isolated, *stateful*, *suspendable* workspace instead of the in-process
+ * `NodeExecutionEnv`.
+ *
+ * **This file is a SEAM, not an implementation.** The real `RemoteContainerExecutionEnv` (E2B SDK, warm
+ * pools, snapshot lifecycle, tier routing) lives in the service and is driven by real integration needs —
+ * exactly like `CheckpointStore` (design/45). Core owns the seam shape; service owns the backend.
+ *
+ * Design rulings folded in (design/48 §10/§11 DeepSeek council):
+ * - **#1 [blocker] interface extension, not capability probing**: `RemoteExecutionEnv extends ExecutionEnv`.
+ *   The base {@link ExecutionEnv} is UNCHANGED — `NodeExecutionEnv`/`StubExecutionEnv` need zero edits, and a
+ *   consumer that only needs buffered fs/shell keeps accepting the base type.
+ * - **#3 [major] do not overload `exec`**: `exec()` stays buffered; streaming is a NEW {@link execStream}.
+ * - **#4 [major] suspend × in-flight exec must not hang**: see {@link suspendVM}.
+ * - **#8 [major] post-resume consistency**: see {@link postResumeInit}.
+ * - **#10 naming**: the isolation level is `sandboxTier` (not `tier`) to avoid clashing with the existing
+ *   timeout-/degradation-"tier" in the codebase.
+ * - **#16 suspend/resume disambiguation**: the VM-lifecycle methods are `suspendVM`/`resumeVM` to keep them
+ *   distinct from the Runner gate-resume and design/45 wake/resume semantics.
+ *
+ * **Deferred (NOT modelled here — they are runtime, not seam):** actually suspending a running task and
+ * persisting the {@link WorkspaceHandle} into a design/45 `Checkpoint`; the `status:"suspended"` orchestrator
+ * mapping; tier *classification* (the static table + Tier1-safe allow-list + fail-closed routing) — all are
+ * service/design-45 implementation-time concerns. Core only declares the seam those will plug into.
+ */
+/**
+ * Error surfaced by {@link RemoteExecutionEnv} lifecycle ops and by {@link RemoteExecutionEnv.execStream}'s
+ * iterator. Mirrors the vendored `ExecutionError` shape but carries the remote-specific code set; it is kept
+ * separate from the vendored `ExecutionErrorCode` union deliberately — those codes only need to widen once the
+ * design/45 suspend/resume *runtime* lands and the Runner/orchestrator layer must thread `"suspended"`.
+ */
+export class RemoteExecutionError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "RemoteExecutionError";
+        this.code = code;
+    }
+}
+/** True when `env` exposes a lifecycle {@link RemoteExecutionEnv.destroy} the Runner should call on task end. */
+export function hasDestroy(env) {
+    return typeof env.destroy === "function";
+}
+/** Structural check that `env` implements the remote seam (lifecycle + streaming surface + declared capabilities). */
+export function isRemoteExecutionEnv(env) {
+    const e = env;
+    return (typeof e.workspaceHandle === "function" &&
+        typeof e.execStream === "function" &&
+        typeof e.suspendVM === "function" &&
+        typeof e.destroy === "function" &&
+        typeof e.capabilities === "object" &&
+        e.capabilities !== null);
+}
+/**
+ * Can this env be durably suspended/snapshotted (design/61 §9 A)? Use this — NOT the structural
+ * {@link isRemoteExecutionEnv} — before calling `suspendVM` (a non-suspendable SSH/ADB env declares
+ * `capabilities.suspendable: false` but still has the method, which returns `"unsupported"`). Non-remote
+ * (in-process) envs are not suspendable.
+ *
+ * A composite type guard (structural AND capability) so a `suspendVM` call site narrowed by THIS predicate
+ * gets the {@link RemoteExecutionEnv} type without a cast — `true` always implies the structural check too.
+ */
+export function isSuspendable(env) {
+    return isRemoteExecutionEnv(env) && env.capabilities.suspendable;
+}
+/**
+ * Is this env an isolated sandbox (design/61 §9 A, design/53)? `false` for a real SSH host / ADB device AND
+ * for any in-process env (the host process is not isolated). The orchestrator tightens autonomy + the
+ * design/37 policy gate when this is `false` (zero-trust on an un-isolated target). The safe default is
+ * `false` — isolation must be explicitly declared, never assumed.
+ */
+export function isIsolated(env) {
+    return isRemoteExecutionEnv(env) ? env.capabilities.isolation : false;
+}
+//# sourceMappingURL=remote-env.js.map

package/dist/core/remote-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-env.js","sourceRoot":"","sources":["../../src/core/remote-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAyLH;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,CAA2B;IAExC,YAAY,IAA8B,EAAE,OAAe,EAAE,KAAa;QACxE,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AA6LD,iHAAiH;AACjH,MAAM,UAAU,UAAU,CAAC,GAAiB;IAC1C,OAAO,OAAQ,GAA6B,CAAC,OAAO,KAAK,UAAU,CAAC;AACtE,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,oBAAoB,CAAC,GAAiB;IACpD,MAAM,CAAC,GAAG,GAAkC,CAAC;IAC7C,OAAO,CACL,OAAO,CAAC,CAAC,eAAe,KAAK,UAAU;QACvC,OAAO,CAAC,CAAC,UAAU,KAAK,UAAU;QAClC,OAAO,CAAC,CAAC,SAAS,KAAK,UAAU;QACjC,OAAO,CAAC,CAAC,OAAO,KAAK,UAAU;QAC/B,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ;QAClC,CAAC,CAAC,YAAY,KAAK,IAAI,CACxB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,GAAiB;IAC7C,OAAO,oBAAoB,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,YAAY,CAAC,WAAW,CAAC;AACnE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAiB;IAC1C,OAAO,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACxE,CAAC"}

package/dist/core/roles.d.ts

@@ -0,0 +1,74 @@
+import type { ThinkingLevel } from "../internal/harness.js";
+import type { Model } from "../internal/llm.js";
+import type { ModelRef, ModelRole, ModelRoles } from "./types.js";
+export type { ModelRole, RoleSpec, ModelRoles } from "./types.js";
+/** Resolve a string ModelRef against the catalog (a Model object passes through). */
+export declare function resolveModel(ref: ModelRef, models?: Record<string, Model>): Model;
+/** 档位降档链(强→弱)。解析某档无绑定时沿链向后找第一个有绑定的档(fail-open 可用性优先;绑定缺口
+ *  在部署 catalog 审计面可见)。`ultra` 预留:排在 `max` 前,今天不绑,未来加档零码改。 */
+export declare const DEFAULT_TIER_ORDER: readonly string[];
+/** CC 档位词 → sema 档位(内置固定,兼容层):fable/mythos→max · opus→pro · sonnet→flash · haiku→lite。 */
+export declare const CC_MODEL_TIER_ALIASES: Readonly<Record<string, string>>;
+export declare function expandTiers(models: Record<string, Model> | undefined, tiers: Record<string, ModelRef> | undefined): Record<string, Model> | undefined;
+export interface ModelMention {
+    /** The matched model name — always one of `allowedNames` — or undefined if none was found. */
+    model?: string;
+    /** The message with the matched `@model` token removed and whitespace tidied. */
+    cleanedText: string;
+}
+/**
+ * Parse a leading/inline `@model` mention out of a user message, restoring the chat "@-model" UX.
+ * Returns the matched model **name** (a catalog ref the caller resolves), never a Model object — and
+ * **only ever a name from `allowedNames`**. This is the security boundary: untrusted end-user text can
+ * pick *which configured model* to use, but can never inject an arbitrary `baseUrl`/`apiKey`/Model
+ * (see design/11). Matches the first allow-listed mention; the rest of the text is returned cleaned.
+ *
+ * Typical use: `const { model, cleanedText } = parseModelMention(userMsg, Object.keys(deps.models));`
+ * then `runTask({ objective: cleanedText, model })` (omit `model` to fall back to the default role).
+ */
+export declare function parseModelMention(text: string, allowedNames: Iterable<string>): ModelMention;
+/**
+ * Role → 档位默认表(clay 拍 2026-07-11:「role 体系用户不感知」)。配了 `RunnerDeps.tiers` 的部署,
+ * 各 role 未显式配置时自动落到语义档位——用户/壳只感知档位,roles 降级为内部路由层:
+ * - `default` → `pro`(主力档兜底;用户/部署 roles.default / TaskSpec.model 恒可覆盖);
+ * - `summarize` → `flash`(压缩本该便宜;flash 未绑沿降档链到 lite);
+ * - `advisor` → 第一档(`ultra` 起,未绑降档到 max/pro——teacher 用最强的);
+ * - `verifier` → `pro`;
+ * - `subagent`/`team`/`synthesize` 无档位默认 = 走 FALLBACK 继承主模型(LLM 可经 model 参数自选档)。
+ * 未配 tiers 的部署:catalog 无 TIERS_ACTIVE 标记 → 表整体 INERT,行为与从前逐字节一致
+ * (即使 catalog 恰有裸模型名 `pro`/`flash` 也不入档位路由——INERT 靠配置成立,不靠键名运气)。
+ */
+export declare const ROLE_TIER_DEFAULTS: Readonly<Partial<Record<ModelRole, string>>>;
+export interface ResolvedRole {
+    model: Model;
+    /** The effective thinking level: explicit `spec.thinking` wins, else the role's default. */
+    thinking?: ThinkingLevel;
+    /** The requested role's preset system prompt, if it set one (independent of model fallback). */
+    systemPrompt?: string;
+}
+/**
+ * Resolve the model (and default thinking) for a task. Explicit `spec.model` wins; otherwise walk the
+ * `modelRole`'s fallback chain over the merged roles (task overrides runner) and use the first role
+ * that supplies a model. Throws a helpful error if nothing resolves.
+ */
+export declare function resolveTaskModel(spec: {
+    model?: ModelRef;
+    modelRole?: ModelRole;
+    roles?: ModelRoles;
+    thinking?: ThinkingLevel;
+}, deps: {
+    models?: Record<string, Model>;
+    roles?: ModelRoles;
+}): ResolvedRole;
+/**
+ * Resolve a role's model **only if that exact role key is configured** (no fallback chain). Used for
+ * the `summarize` compaction model: override only when a summarize-specific model is set, otherwise
+ * let the caller fall back to the main model (unchanged behavior).
+ */
+export declare function roleModelIfSet(role: ModelRole, spec: {
+    roles?: ModelRoles;
+}, deps: {
+    models?: Record<string, Model>;
+    roles?: ModelRoles;
+}): Model | undefined;
+//# sourceMappingURL=roles.d.ts.map

package/dist/core/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/core/roles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAY,MAAM,YAAY,CAAC;AAE5E,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAElE,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,CAWjF;AAUD;6DAC6D;AAC7D,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAA6C,CAAC;AAE9F,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMlE,CAAC;AAuBF,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,SAAS,EACzC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,SAAS,GAC1C,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,SAAS,CAiCnC;AAED,MAAM,WAAW,YAAY;IAC3B,8FAA8F;IAC9F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,YAAY,CAiB5F;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAK3E,CAAC;AA8FF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,QAAQ,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,aAAa,CAAA;CAAE,EAC/F,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,GAC3D,YAAY,CAmCd;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,EAC5B,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,GAC3D,KAAK,GAAG,SAAS,CAKnB"}