@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/remote-env-e2b.d.ts

@@ -1,6 +1,29 @@
+/**
+ * `RemoteContainerExecutionEnv` — the E2B implementation of core's `RemoteExecutionEnv` seam
+ * (core src/core/remote-env.ts, design/48 §5). The service control plane owns this backend; core
+ * owns the seam shape (exactly like `CheckpointStore` / `SqlExecutor`).
+ *
+ * **Scope = design/48 §0.5 v1 minimal slice**: single worker, E2B managed, **Tier 2 only** (every
+ * op runs in a per-task E2B Firecracker VM — no tiering/classification), and the ~4 live seam methods
+ * `connect` / `execStream` / `workspaceHandle` / `destroy` + the base `ExecutionEnv` (FileSystem + Shell).
+ *
+ * **v1.5 (design/49, core 1.69):** `suspendVM` (E2B `pause()`) / `resumeVM` (`Sandbox.connect(id)` auto-resume)
+ * / `postResumeInit` (reachability + at-rest-encryption red line) are IMPLEMENTED — core orchestrates them when
+ * a task with this remote env hits a durable-approval `ask` (workspaceHandle → Checkpoint.state). `reconnect`
+ * (cross-replica re-attach to a still-running VM) stays deferred to **v2** (v1.5 always snapshots → resumeVM).
+ *
+ * **Provider seam discipline (self-host endgame):** every E2B SDK call is confined to this one class. A
+ * future OSS-self-hosted E2B (clay's "最终自部署" constraint) swaps the backend without touching consumers.
+ *
+ * **never-throw invariant:** the base `ExecutionEnv` contract requires every FileSystem/Shell method to
+ * encode failure in the returned `Result` (never throw). The one exception is `execStream`, whose async
+ * iterator MAY throw `RemoteExecutionError` mid-stream before an `exit` chunk (seam contract, OutputChunk).
+ */
 import { Sandbox, type SandboxOpts, type SandboxConnectOpts } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll } from "@sema-agent/core";
+/** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
+/** Minimal optional observability hooks (kept structural so the adapter stays standalone-testable). */
 export interface RemoteEnvObservers {
     logger?: {
         warn(msg: string, meta?: unknown): void;
@@ -10,43 +33,104 @@ export interface RemoteEnvObservers {
         inc(name: string, labels?: Record<string, string>): void;
     };
 }
+/** Construction config for {@link RemoteContainerExecutionEnv}. Secrets/resolved values are control-plane supplied. */
 export interface RemoteContainerEnvConfig extends RemoteEnvObservers {
+    /** E2B API key. Resolved by the trusted control plane from env — never baked into an image or committed. */
     apiKey: string;
+    /** E2B template id (image). Defaults to the E2B base template. */
     template?: string;
+    /** Sandbox lifetime in ms (E2B billing window). Default {@link DEFAULT_TIMEOUT_MS}. */
     timeoutMs?: number;
+    /** Workspace root inside the VM; remote paths normalize against it. Default {@link DEFAULT_MOUNT_PATH}. */
     mountPath?: string;
+    /** Outbound network for the sandbox (clay: service needs external-network capability). Default `true`. */
     allowInternetAccess?: boolean;
+    /** Sandbox metadata (e.g. sessionId/taskId for fleet observability). */
     metadata?: Record<string, string>;
+    /**
+     * 🔴 Out-of-band secret/config env injected sandbox-WIDE at create (design/48 §5 gap 7, OA Phase-B): every
+     * command + background process in the VM sees these, but the VALUES never enter the model prompt, the tool
+     * `command` string, or the durable event log (which only records the command `args`, redacted). This is the
+     * channel for a credential (e.g. a git token the agent uses via GIT_ASKPASS / a credential helper) WITHOUT
+     * routing it through an MCP server. Resolved from the worker's OWN env by the control plane — the values live
+     * only here in memory, never logged. ⚠️ A command that *echoes* the value to stdout still lands it in the L1
+     * session history (the model reads tool output); the injection keeps it out of the prompt/command, not out of
+     * a deliberate echo — consume it without printing (GIT_ASKPASS, `git -c credential.helper`, etc.).
+     */
     sandboxEnv?: Record<string, string>;
+    /** 🔴 (hang class-fix) Wall-clock bound (ms) for a control-plane provider RPC — create/resume/pause/kill/
+     *  isRunning/files.*. A provider hang is surfaced as a typed retryable `RemoteExecutionError("timeout")` after
+     *  this, instead of pinning the worker for the sandbox lifetime. Default {@link DEFAULT_RPC_TIMEOUT_MS}. */
     rpcTimeoutMs?: number;
+    /** 🔴 (hang class-fix) Idle/liveness bound (ms) for a command (exec/execStream): max time with NO output
+     *  and not yet complete = suspected hang. Also bounds the command-creation RPC. Default {@link DEFAULT_LIVENESS_MS}. */
     livenessMs?: number;
+    /** 🔴 Wall-clock for data-transfer/provisioning RPCs (large file io, snapshot suspend/resume,
+     *  create/connect) — wider than {@link rpcTimeoutMs} so a legit multi-minute transfer is not killed. Default
+     *  {@link DEFAULT_DATA_TIMEOUT_MS}. */
     dataTimeoutMs?: number;
 }
+/** Minimal slice of the E2B `Sandbox` static API the adapter uses — injectable so tests pass a fake. */
 export interface SandboxApi {
     create(opts?: SandboxOpts): Promise<Sandbox>;
     connect(sandboxId: string, opts?: SandboxConnectOpts): Promise<Sandbox>;
 }
+/** Inject the E2B SDK for tests (a fake `Sandbox`). Defaults to the real SDK. */
 export interface RemoteContainerEnvDeps {
     sandboxApi?: SandboxApi;
 }
+/**
+ * E2B-backed remote `ExecutionEnv`. **Lazy by default (v1b):** the VM is provisioned on the
+ * FIRST FileSystem/Shell/execStream call (auto `connect()`), so a task that never touches the hand pays zero
+ * cost. `connect()` may still be called explicitly (idempotent + concurrency-memoized) if the control plane
+ * wants to provision eagerly. `destroy()` on task end (the Runner calls it via `hasDestroy`); a never-used env's
+ * destroy is a no-op (nothing to kill, no bill). One container per task (design/48 §5 §7 Q7).
+ */
 export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
+    /** Current working directory for relative paths (FileSystem contract; mutable, core may reassign). */
     cwd: string;
     private readonly cfg;
     private readonly sandboxApi;
     private sbx?;
+    /** 🔴 BL-31 keep-alive — the E2B sandbox lifetime is hard-capped (≈1h, {@link E2B_SANDBOX_MAX_MS}), but a long
+     *  leader/repair run legitimately exceeds it. This interval RE-extends the sandbox (`setTimeout(timeoutMs)` resets
+     *  the auto-kill window from now) while the env is held, so the sandbox tracks ACTUAL usage rather than dying
+     *  mid-run at the cap (otherwise: a silent dead sandbox at hour 1). Cleared on destroy;
+     *  a no-op while paused/destroyed. `unref`'d so it never holds the process open. */
     private keepAlive?;
     private handle?;
+    /** Terminal once set by {@link destroy} — never reset to false (no resurrection). Guards connect/ensureConnected
+     *  and the post-await re-check in BOTH async-provision paths ({@link doConnect} and {@link doResumeVM}) against
+     *  a destroy that races an in-flight provision/restore. */
     private destroyed;
+    /** In-flight connect/resume, memoized so concurrent lazy first-use OR resume provisions exactly one VM (no double-bill). */
     private connecting?;
+    /** Count of exec/execStream calls in flight — `suspendVM` refuses while > 0 (council #4: never snapshot a running command). */
     private activeCommands;
+    /** True between a `suspendVM` (VM paused, external connection dead) and the next `resumeVM` reconnect. While
+     *  paused, `this.sbx` still points at the (now-dead) handle, so `resumeVM`'s idempotency guard must NOT treat
+     *  it as live — it has to fall through and actually `Sandbox.connect()`. Without this, a suspend→resume on the
+     *  SAME env instance skips the reconnect and every later fs/exec runs against the dead VM. */
     private paused;
     constructor(config: RemoteContainerEnvConfig, deps?: RemoteContainerEnvDeps);
+    /** design/61 §9: E2B is a FULL RemoteExecutionEnv — an isolated, snapshot-suspendable microVM. (SSH/ADB
+     *  adapters declare {isolation:false, suspendable:false} — real machines/devices, not snapshotable.) */
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
     };
     workspaceHandle(): WorkspaceHandle;
+    /**
+     * Public host for a port inside the sandbox (E2B reverse proxy → `<port>-<id>.e2b.app`). The LSP sidecar
+     * (design/64 §13.1) uses this to reach the in-sandbox language-server WS bridge over `wss://`. Lazily
+     * provisions the VM (like exec/fs); `undefined` if it can't connect → the LSP manager degrades.
+     */
     getHost(port: number): Promise<string | undefined>;
+    /**
+     * Launch a long-running process as a TRUE E2B background command (resolves once launched, E2B keeps it alive)
+     * — for the LSP bridge (design/64 §13.1). NOT the same as `exec` with a shell `&`: E2B reaps a foreground
+     * command's process group on completion, which would kill an in-shell `&`/nohup child. Fire-and-forget.
+     */
     startBackground(command: string): Promise<void>;
     connect(config?: RemoteConnectConfig): Promise<{
         ok: true;
@@ -56,6 +140,12 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         error: RemoteExecutionError;
     }>;
     private doConnect;
+    /**
+     * v1.5 (design/49): snapshot the workspace via E2B `pause()` (stores fs+memory+process; the snapshot id IS
+     * the sandbox id — a paused E2B sandbox is resumed by its id). Atomic contract (council): on failure the VM
+     * is left UNTOUCHED (still running) so core can fall back to onAsk. Refuses if a command is in flight
+     * (council #4) — never silently snapshot a running command. `abortSignal` bounds a hung pause (council BUG#2).
+     */
     suspendVM(options?: VmLifecycleOptions): Promise<{
         ok: true;
         value: SnapshotId;
@@ -63,6 +153,12 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /**
+     * v1.5: restore from a snapshot via E2B `Sandbox.connect(snapshotId)` (auto-resumes a paused sandbox).
+     * Idempotent: a no-op if already on that sandbox. Concurrent resume/connect for the same snapshot share ONE
+     * provision (memoized via `connecting`, like {@link connect}) so a racing call never double-creates a billable
+     * VM (council #3). `abortSignal` bounds a hung restore.
+     */
     resumeVM(snapshotId: SnapshotId, options?: VmLifecycleOptions): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -71,6 +167,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         error: RemoteExecutionError;
     }>;
     private doResumeVM;
+    /** Cross-replica re-attach to a still-running VM = v2 (design/49 council #15: v1.5 always snapshots→resumeVM). */
     reconnect(_sessionToken: SessionToken): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -78,6 +175,13 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /**
+     * v1.5: re-establish consistency after resumeVM. The resumed VM is restored to its paused state (fs+memory+
+     * process); this verifies it is reachable. Per-command secrets are re-applied automatically (this adapter
+     * injects envs per command, not persistently). The VM-internal agent rebuilds its own external connections
+     * (git/API don't survive pause). 🔴 At-rest snapshot encryption is the provider's here (E2B managed) — a
+     * self-hosted E2B (v2) MUST guarantee it before any secret injection (remote-env.ts §5 red line).
+     */
     postResumeInit(): Promise<{
         ok: true;
         value: void;
@@ -85,6 +189,9 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** BL-31 — (re)start the periodic sandbox-lifetime extension. `setTimeout(timeoutMs)` resets the auto-kill window
+     *  from now; we re-arm at ~80% of the (clamped, ≤1h) window so a long-held sandbox never expires mid-run. A no-op
+     *  when paused/destroyed; `unref`'d so it never keeps the process alive; cleared on destroy. */
     private startKeepAlive;
     private stopKeepAlive;
     destroy(): Promise<void>;
@@ -128,6 +235,9 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
+    /** 见其余 shell 腿上同名方法的旁注(2026-07-25 六腿补齐):core 的敏感路径门在 `canonicalPath` 失败时退到它;
+     *  缺它 ⇒ 合法的悬空链接让整个工具调用失败。必须返回**原始链接目标**(`readlink` 不带 `-f`)。
+     *  本腿的文件面也走 `exec`(与 canonicalPath 同通道),所以实现方式与 shell 腿一致。 */
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
@@ -147,9 +257,35 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         abortSignal?: AbortSignal;
     }): Promise<Result<string, FileError>>;
     private resolve;
+    /**
+     * 🔴 (hang class-fix) Bound a CONTROL-PLANE provider RPC (create/resume/pause/kill/isRunning/files.*) with a
+     * client-side wall-clock deadline + the caller's AbortSignal. Without this, an E2B RPC that hangs (the original
+     * bug: ESTABLISHED socket, no response) pins the worker for the whole sandbox lifetime. On deadline we abort the
+     * op and throw a typed, retryable {@link RemoteExecutionError} code `"timeout"` (caller retries per idempotency —
+     * the adapter NEVER blind-retries). A caller AbortSignal still aborts independently (op surfaces it / "aborted").
+     */
     private rpc;
+    /**
+     * Per-command wall-clock for the E2B SDK (seconds→ms). 🔴 This is a PHYSICAL CAP, NOT the hang
+     * detector. The old code returned `this.cfg.timeoutMs` (the sandbox lifetime) when no `timeout` was given AND
+     * had no liveness check → a hung command waited the WHOLE lifetime (~30 min, the original hang bug). The fix is
+     * NOT to shorten this cap (that would spuriously kill a long-but-progressing `npm ci`) — it's to add a LIVENESS
+     * bound ({@link cfg.livenessMs}) in exec/execStream that catches a *zero-progress* command in ~livenessMs,
+     * independent of this cap. So: explicit caller `timeout` wins; else the lifetime is the cap (a command can't
+     * outlive its VM) but hang detection no longer depends on it.
+     */
     private commandTimeoutMs;
+    /**
+     * 🔴 Liveness for the buffered exec WAIT phase. `handle.wait()` is a long-poll with no read timeout —
+     * a command that hangs DURING execution (not creation) would otherwise wait the E2B command timeout (= the
+     * lifetime when none is set, the original hang bug). Races wait() against an idle check: if no stdout/stderr for
+     * `livenessMs`, the command is hung → kill + typed retryable "timeout". `lastProgress()` is bumped by the
+     * stdout/stderr callbacks, so a slow-but-PROGRESSING command (long `npm ci`) is never killed. (execStream has
+     * its own chunk-driven idle timer; this is the buffered-exec analogue.)
+     */
     private waitWithLiveness;
+    /** Lazily provision the VM on first use: a task that never touches the hand pays zero cost.
+     *  Concurrent first-calls share one provision via the memoized {@link connect}. */
     private ensureConnected;
     private fsReady;
     private tempResult;
@@ -158,6 +294,16 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private execError;
     private remoteError;
 }
+/**
+ * Build the deployment-level `RunnerDeps.executionEnvFactory` (design/48 v1b). Wiring this onto a
+ * deployment makes it a "code-agent worker": every task's hand runs in a per-task E2B VM. Deployments that do
+ * NOT set this (e.g. OA / review) keep the in-process stub env — routing is **deployment-level** (the factory
+ * ctx carries only sessionId/taskId, never a service scenario; that stays out of the generic core seam).
+ *
+ * The factory returns the env **unconnected** (lazy): the VM is provisioned on first FS/Shell/execStream use,
+ * so a task that never touches the hand (e.g. a leader that only plans) pays zero VM cost. The Runner owns the
+ * lifetime and calls `destroy()` on task end (via `hasDestroy`); a never-used env's destroy is a no-op.
+ */
 export declare function e2bExecutionEnvFactory(config: RemoteContainerEnvConfig, deps?: RemoteContainerEnvDeps): ExecutionEnvFactory;
 export {};
 //# sourceMappingURL=remote-env-e2b.d.ts.map