@agent-compose/sdk 0.6.0 → 0.8.0

package/dist/pause/wrappers.d.ts

@@ -1,26 +1,29 @@
 /**
- * The two opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
- * closure over `ctx.pause`:
+ * The three opinionated pause wrappers (ADR-0006 §"SDK surface", ADR-0042),
+ * each a thin closure over `ctx.pause`:
  *
  *   - `sleep`           — a lightweight timed pause; resolves on its own TTL,
  *                         skips the snapshot, returns void.
  *   - `waitForEvent`    — pause until an event resumes by correlation key.
- *
- * A typed human/agent decision is NOT a wrapper — it's a plain `ctx.pause`
- * with a `schema` (and `payload.options` for the dashboard's answer UI). The
- * pause primitive carries the reason (the ask) and the resume value (the
- * resolution); there is no separate `requestDecision`.
+ *   - `requestDecision` — a typed human/agent decision (wire `kind:
+ *                         "decision"`): the prompt/options/approvers ride
+ *                         `payload` for the dashboard's answer UI, and the
+ *                         resume value is the frozen `{ decision: string }`
+ *                         convention. `approvers` travel as RAW member refs
+ *                         (user ids or emails) — the SERVER resolves them
+ *                         against the team roster at pause-insert time and
+ *                         stamps the gate-bearing snapshots (ADR-0042 §2).
  *
  * Built from a `PauseFn` so the wrapper logic lives in one place and the step
  * runner just spreads them onto the context next to `pause`.
  */
-import type { z } from "zod";
+import { z } from "zod";
 import type { StepPauseRequest } from "../step-invocation/types.js";
 import type { PauseRequest } from "./pause-core.js";
 /** The public `ctx.pause` callable (always `kind: "custom"`). */
 export type PauseFn = <T = unknown>(req: PauseRequest<T>) => Promise<T>;
 /** Internal: pause with an explicit wire `kind`. The wrappers stamp
- *  `sleep`/`event` through this; the public `ctx.pause` is always
+ *  `decision`/`sleep`/`event` through this; the public `ctx.pause` is always
  *  `custom` and never exposes it. */
 export type KindedPauseFn = <T = unknown>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]) => Promise<T>;
 export interface WaitForEventRequest<T> {
@@ -30,8 +33,27 @@ export interface WaitForEventRequest<T> {
     schema?: z.ZodType<T>;
     ttlMs?: number;
 }
+export interface DecisionRequest {
+    prompt: string;
+    /** Choices the decision UI offers as buttons; free text is always open. */
+    options?: Array<string | {
+        label: string;
+        value: string;
+    }>;
+    /** Team member refs (user ids or emails, ≤ 10) — with any named, ONLY a
+     *  named approver may resolve the decision, and each gets an Activity
+     *  ping. Resolution is server-side at pause creation. */
+    approvers?: string[];
+    /** DecisionDraft artifact rendered alongside the prompt. */
+    draft?: Record<string, unknown>;
+    ttlMs?: number;
+    correlationKey?: string;
+}
 export interface PauseWrappers {
     sleep(durationMs: number): Promise<void>;
     waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
+    requestDecision(req: DecisionRequest): Promise<{
+        decision: string;
+    }>;
 }
 export declare function buildPauseWrappers(pause: KindedPauseFn): PauseWrappers;

package/dist/processors/ask-human.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ask-human processor (ADR-0028).
+ *
+ * Makes "ask a human" a FIRST-CLASS agent affordance: when the agent calls the
+ * built-in `AskUserQuestion` tool, this short-circuits it into a SERVER pause
+ * (`requestPauseAndAwait`) — the run freezes (compute stops), the question +
+ * options land on the human's pause feed, and the human's answer comes back as
+ * the tool result. No `agentc pause` CLI for the model to remember, and no
+ * dependency on prompt discipline: the moment the agent asks, the run pauses.
+ *
+ * Loud by construction — the danger this fixes is a pause that SILENTLY doesn't
+ * happen (a stale in-sandbox CLI, a non-E2B substrate, an auth error) letting
+ * the agent proceed as if it had an answer:
+ *   - pause cannot be created (server reject) → `Verdict.abort` ENDS the agent
+ *     loop with a WorkflowError. The run fails loud; it never guesses an answer.
+ *   - pause expires / is cancelled → the tool result says NO answer came and to
+ *     not assume one.
+ *
+ * Lives in the shared `gateToolCall` chain, so one implementation covers every
+ * runtime (the Claude Agent SDK `PreToolUse` hook and the ACP permission path).
+ * No run credential in the env (local / non-sandbox) → no-op: `AskUserQuestion`
+ * passes through untouched so a dev invocation isn't hard-failed.
+ */
+import type { Processor } from "./processor.js";
+import type { GatePauseConnection } from "./gate-pause.js";
+/** The Claude built-in tool an agent uses to ask the user a question. */
+export declare const ASK_USER_QUESTION_TOOL = "AskUserQuestion";
+export declare function createAskHumanProcessor(opts?: {
+    connection?: GatePauseConnection;
+}): Processor;

package/dist/processors/ask-human.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/processors/index.d.ts

@@ -4,3 +4,4 @@ export { runProcessorChain } from "./runner.js";
 export { denyTools, humanApproval, requireScope, redactPattern, } from "./builtins.js";
 export { createGatePauseProcessor } from "./gate-pause.js";
 export type { GatePausePolicy, GatePauseApproval, GatePauseConnection } from "./gate-pause.js";
+export { createAskHumanProcessor, ASK_USER_QUESTION_TOOL } from "./ask-human.js";

package/dist/runtimes/_acp-client.d.ts

@@ -37,6 +37,26 @@ import type { ToolCallGateResult } from "../types/runtime.js";
  *  ACP wire change — never silently. The package version is pinned separately
  *  in package.json; this integer is the real compatibility gate (ADR-0020). */
 export declare const ACP_PROTOCOL_VERSION = 1;
+/** Session-lifecycle capabilities the agent advertised at `initialize`,
+ *  surfaced (not discarded) so callers can pick a resume strategy
+ *  (ADR-0037 §3). The in-sandbox CLI-agent runtimes ignore both — they
+ *  resume via the CLI's own on-disk rollout (ADR-0020 Q4); the bridge
+ *  daemon attempts `session/resume` only when `resume` is true. */
+export interface AcpSessionCaps {
+    /** Agent supports `session/load` — full-history replay as
+     *  `agent_message_chunk`s. Deliberately NOT used for resume: replaying
+     *  history would re-emit the transcript as new parts and duplicate the
+     *  conversation (ADR-0037 alternative D). */
+    loadSession: boolean;
+    /** Agent supports `session/resume` — context restore with NO replay. */
+    resume: boolean;
+}
+/** One entry of the agent's slash-command palette, as announced by the ACP
+ *  `available_commands_update` session notification. */
+export interface AcpAvailableCommand {
+    name: string;
+    description: string;
+}
 /** Collaborators `AcpClientPeer` needs from `CliAgentRunner`, kept as a small
  *  injected surface so the peer stays transport-agnostic and unit-testable. */
 export interface AcpClientPeerDeps {
@@ -57,6 +77,14 @@ export interface AcpClientPeerDeps {
     /** Turn-scoped abort signal from `sendMessage`. On abort the peer sends
      *  `session/cancel` for the live session. */
     signal?: AbortSignal;
+    /** The agent announced (or changed) its slash-command palette — an ACP
+     *  `available_commands_update` session NOTIFICATION, which can arrive at
+     *  any time (typically right after session/new, outside any prompt), so
+     *  it rides a callback rather than the per-turn message stream. Each call
+     *  carries the ENTIRE palette (replace semantics). Optional: the
+     *  in-sandbox runtimes ignore it; the bridge daemon reports it to the
+     *  server for composer autocomplete. */
+    onAvailableCommands?: (commands: AcpAvailableCommand[]) => void;
 }
 /**
  * Map ONE ACP `session/update` to zero-or-more `AgentMessage`s. The single
@@ -100,10 +128,14 @@ export declare class AcpClientPeer {
      * Negotiate the wire protocol at `initialize`. Pins `protocolVersion` to
      * integer 1 and advertises NO fs / terminal capabilities. Returns the
      * version the agent negotiated — `CliAgentRunner` compares it to
-     * `ACP_PROTOCOL_VERSION` to decide ACP-path vs. legacy-JSONL fallback.
+     * `ACP_PROTOCOL_VERSION` to decide ACP-path vs. legacy-JSONL fallback —
+     * plus the agent's advertised session-lifecycle capabilities (`caps`),
+     * which the bridge daemon caches as `agent_sessions.resume_supported`
+     * (ADR-0037 §3). Absent capability blocks mean "not supported".
      */
     initialize(): Promise<{
         protocolVersion: number;
+        caps: AcpSessionCaps;
     }>;
     /**
      * Start a session and return its id (threaded back onto the synthesised
@@ -113,6 +145,19 @@ export declare class AcpClientPeer {
      * in the manual live step).
      */
     startSession(cwd: string): Promise<string>;
+    /**
+     * Resume an existing session by id — ACP `session/resume` (ADR-0037 §3).
+     * ADDITIVE and opt-in: the in-sandbox CLI-agent runtimes never call this
+     * (their resume path is the CLI's own persisted rollout, see
+     * `startSession`); the bridge daemon calls it only when `initialize`
+     * advertised `caps.resume`. Unlike `session/load` there is NO history
+     * replay — the agent restores its internal context and returns nothing,
+     * so nothing is re-emitted through the caller's part sink. Throws on an
+     * unknown/expired session id (JSON-RPC error from the agent) — the caller
+     * marks the durable row stale and falls back to `startSession` + full
+     * re-render. `this.sessionId` is only adopted on success.
+     */
+    resumeSession(cwd: string, acpSessionId: string): Promise<void>;
     /**
      * Drive one `session/prompt` turn, yielding `AgentMessage`s as the agent
      * streams `session/update` notifications. Resolves the generator when the

package/dist/runtimes/_cli-agent.d.ts

@@ -27,6 +27,21 @@ import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvi
 import type { ProcessorContext, ToolCall } from "../processors/processor.js";
 /** Single-quote a value for safe interpolation into a `sh -c` command line. */
 export declare function shellQuote(value: string): string;
+/**
+ * A UNIQUE per-turn prompt path. Uniqueness is load-bearing, not cosmetic:
+ * E2B's envd cannot overwrite an existing non-root file in /tmp — it opens
+ * with O_CREAT as root (then chowns to the user), and the sandbox kernel's
+ * `fs.protected_regular` policy denies O_CREAT opens by a non-owner of an
+ * existing file in a sticky world-writable directory — so ANY reused path
+ * fails with "error opening file: … permission denied" on every turn after
+ * the first (same boot or across suspend/resume; reproduced against e2b
+ * 2.30.5). Cloud sessions construct a fresh runner per turn, so an
+ * iteration counter alone reuses `…-0.in` per conversation — the exact
+ * production failure. The timestamp+counter+random suffix is collision-proof
+ * across runner instances AND concurrent turns in one sandbox; the readable
+ * prefix (kind/agent/iteration) stays for debugging.
+ */
+export declare function uniquePromptPath(kind: string, agentId: string, iteration: number): string;
 /** Hard deadline (ms) for the ACP `initialize` handshake AND the prompt turn.
  *  `peer.initialize()` resolves only when the agent answers; a real CLI that
  *  never speaks ACP (or blocks on stdin) would otherwise hang forever and the
@@ -34,6 +49,15 @@ export declare function shellQuote(value: string): string;
  *  route to JSONL exactly like a handshake error. Overridable via the env for
  *  ops tuning; defaults sane. */
 export declare const ACP_HANDSHAKE_TIMEOUT_MS: number;
+/** Idle deadline for a PROMPT TURN (distinct from the handshake gate above). A
+ *  turn is killed only if it goes fully SILENT for this long — the deadline is
+ *  re-armed on every streamed message, so a long, *streaming* turn never trips
+ *  it. This must be generous: a reasoning model (GLM, gpt-5-codex) can think for
+ *  tens of seconds between tool calls with no wire activity, which is NOT a hang.
+ *  The 10s handshake timeout was far too tight here and killed live GLM turns
+ *  mid-report. Only a genuinely wedged CLI (the Gemini-style hang) should trip
+ *  this. Overridable via the env for ops tuning. */
+export declare const ACP_TURN_IDLE_TIMEOUT_MS: number;
 /** Readiness gate for the LIVE ACP attempt. The duplex-stdin transport in
  *  `spawnAcpProcess` is now real (`commands.spawnDuplex` on the local provider),
  *  so the agent's `initialize` request bytes are delivered and the handshake can
@@ -45,6 +69,13 @@ export declare const ACP_HANDSHAKE_TIMEOUT_MS: number;
  *  implements duplex) falls back to JSONL cleanly via the capability check in
  *  `sendMessage`. */
 export declare const ACP_TRANSPORT_READY = true;
+/** Reasoning-effort level a CLI turn may carry (T2 session effort). The
+ *  per-CLI mapping lives in each spec's `buildCommand` — Claude Code takes a
+ *  thinking-token budget via `MAX_THINKING_TOKENS`, codex takes
+ *  `-c model_reasoning_effort=<level>`. Specs without a real knob
+ *  (opencode/droid/cursor) never receive one: the server hides + rejects
+ *  effort for those runtimes. */
+export type CliReasoningEffort = "low" | "medium" | "high";
 /** Per-CLI behaviour. The base owns the lifecycle (init/done/error) and the
  *  transport (spawn + JSONL parse); a spec owns the CLI-specific bits. */
 export interface CliAgentSpec {
@@ -69,12 +100,15 @@ export interface CliAgentSpec {
      *  JSONL user message for a `--stream-json-input` CLI (amp). */
     promptPayload(prompt: string): string;
     /** Build the one-shot shell command for a turn. `promptPath` is a file in the
-     *  sandbox holding `promptPayload(prompt)`; `sessionId` continues a thread. */
+     *  sandbox holding `promptPayload(prompt)`; `sessionId` continues a thread.
+     *  `effort` is present only when the caller configured a reasoning effort
+     *  AND the spec has a real knob for it (see `CliReasoningEffort`). */
     buildCommand(args: {
         promptPath: string;
         sessionId?: string;
         model?: string;
         cwd?: string;
+        effort?: CliReasoningEffort;
     }): string;
     /** Map one parsed JSONL stdout event to `AgentMessage`s. The base emits
      *  `init`/`done`/`error` lifecycle itself, so a spec maps only content +
@@ -105,6 +139,7 @@ export declare class CliAgentRunner implements ModelExecutionContract {
     private readonly options;
     private readonly spec;
     private readonly configModel?;
+    private readonly configEffort?;
     readonly kind: string;
     /** Whether the live ACP path will actually run for this runner: the spec
      *  declares an `acp` invocation, the transport is ready, AND the live provider
@@ -146,7 +181,7 @@ export declare class CliAgentRunner implements ModelExecutionContract {
      *  exercising the real `sendMessageAcp` even while the production default is
      *  dormant. Not a public API. */
     private acpTransportReady;
-    constructor(sandbox: SandboxProvider, options: RuntimeOptions, spec: CliAgentSpec, configModel?: string | undefined);
+    constructor(sandbox: SandboxProvider, options: RuntimeOptions, spec: CliAgentSpec, configModel?: string | undefined, configEffort?: CliReasoningEffort | undefined);
     /** TEST-ONLY: flip the live-ACP readiness gate on for this runner instance so
      *  the ACP lifecycle / fallback tests can exercise `sendMessageAcp` while the
      *  production default (`ACP_TRANSPORT_READY`) stays dormant. Not part of the
@@ -231,11 +266,30 @@ export declare class CliAgentRunner implements ModelExecutionContract {
     private spawnAcpProcess;
     /**
      * Legacy JSONL transport (the version-mismatch fallback, ADR-0020 increment
-     * 5 retires it). Unchanged behaviour: write the prompt to a file, run the
+     * 5 retires it) — and the ONLY transport on server→sandbox providers (no
+     * `spawnDuplex`, so ACP never engages). Write the prompt to a file, run the
      * one-shot command, line-buffer stdout, `mapEvent` each parsed line, and cap
      * with the runner-synthesised `done`. Does NOT re-yield `init` (the caller
      * already did).
+     *
+     * Deadline + termination semantics (both load-bearing on the server→E2B
+     * cloud-session path):
+     *   - `timeoutMs: 0` disables the PROVIDER's own command deadline. E2B's
+     *     `CommandStartOpts` defaults to 60s — a fraction of a real coding
+     *     turn — and connect-web normalises `<= 0` to "no deadline" (the same
+     *     idiom `launchStep` uses for the hours-long step runner). The local
+     *     and Vercel providers already treat 0/absent as "no deadline". The
+     *     turn's deadline belongs to the CALLER: the abort signal here, the
+     *     bridge waiter's idle/absolute caps, or the in-VM step deadline.
+     *   - Abort and early generator exit KILL the in-sandbox CLI process via
+     *     the provider's kill-capable background handle (`runBackground` —
+     *     present on E2B, the provider every server-driven turn runs on), so a
+     *     cancelled/timed-out/superseded turn can never leave an orphan agent
+     *     mutating the working tree. Providers without `runBackground` (local
+     *     child_process, Vercel) fall back to `commands.run`: no kill handle,
+     *     abort only stops consumption — the pre-ACP behaviour of the in-VM
+     *     JSONL fallback, bounded by the sandbox VM's own lifetime.
      */
     private sendMessageJsonl;
 }
-export declare function createCliAgentRuntime(spec: CliAgentSpec, configModel?: string): import("../index.js").AgentRuntime<SandboxProvider>;
+export declare function createCliAgentRuntime(spec: CliAgentSpec, configModel?: string, configEffort?: CliReasoningEffort): import("../index.js").AgentRuntime<SandboxProvider>;

package/dist/runtimes/_jsonl-guard.d.ts

@@ -0,0 +1,103 @@
+/**
+ * JSONL frame guard — keeps oversized lines OFF the server→sandbox command
+ * stream.
+ *
+ * The live failure this exists for: a cloud session's turn stream rides
+ * `sandbox.commands.run` over E2B's connect-web gRPC command stream, and that
+ * transport dies at the wire on large payloads — connect-web throws
+ * `13: [internal] protocol error: received unsupported compressed output`
+ * the moment an envelope arrives with the compressed flag set
+ * (@connectrpc/connect-web connect-transport.js), which is what E2B's edge
+ * does to it on big frames. A single `claude` stream-json event echoing a
+ * whole Read file (hundreds of KB on ONE JSONL line) is exactly such a
+ * payload: the stream faults mid-turn, the platform classifies it as a
+ * protocol transport fault (server cloud-executor.ts), recycles the VM, and
+ * the turn's work is lost.
+ *
+ * The structural fix: the full content is already durable INSIDE the sandbox
+ * (the file on disk, the CLI's own session transcript), so the wire never
+ * needs it. A tiny dependency-free node filter runs in-sandbox, piped after
+ * the CLI, and rewrites any oversized JSONL line before it can reach the
+ * vulnerable stream: long strings inside the event are truncated with an
+ * EXPLICIT elision marker (a silent cut is how models and humans end up
+ * trusting hallucinated file contents), and a line that cannot be capped
+ * structurally is hard-truncated so the stream survives at the cost of that
+ * one event. The prompt travels the other direction over `files.write` —
+ * E2B's envd HTTP API, a different transport documented immune to this
+ * failure (see the `files.read` comment in sandbox/providers/e2b.ts) — and
+ * the guard script itself is delivered the same immune way.
+ *
+ * Exit codes: piping would normally replace the CLI's exit code with the
+ * filter's, so the wrapper prints a per-turn random sentinel line carrying
+ * `$?` after the CLI exits and the filter re-raises it as its own exit code.
+ * EOF without a sentinel means the producer died abnormally (killed
+ * mid-pipe) — the filter exits JSONL_GUARD_NO_SENTINEL_EXIT so a crashed CLI
+ * can never masquerade as a clean turn.
+ *
+ * `capJsonlLine` is deliberately SELF-CONTAINED (no imports, no captured
+ * helpers): `jsonlGuardScript()` embeds it via `Function.prototype.toString`
+ * so the exact logic the unit tests pin is the logic that runs in-sandbox —
+ * one implementation, two call sites.
+ */
+/** Trigger threshold: a JSONL line at or under this many bytes passes
+ *  through byte-identical; over it, the guard rewrites. Chosen well under
+ *  whatever E2B's edge chokes on (the observed kills were multi-hundred-KB
+ *  single lines) while comfortably above any sane tool result. */
+export declare const JSONL_GUARD_LINE_CAP_BYTES: number;
+/** How many bytes of an oversized string survive elision (the head — tool
+ *  output fronts-loads the signal: file starts, command output starts). */
+export declare const JSONL_GUARD_KEEP_BYTES: number;
+/** The guard's exit code when its stdin hit EOF WITHOUT the exit sentinel:
+ *  the producer pipeline died abnormally (killed / crashed sh), so the turn
+ *  must surface as an error, never a clean done. */
+export declare const JSONL_GUARD_NO_SENTINEL_EXIT = 121;
+/** Stable prefix of the elision marker appended to every truncated string.
+ *  Exported so consumers/tests can detect an elided payload; a unit test
+ *  pins that `capJsonlLine`'s embedded copy matches this constant. */
+export declare const JSONL_ELISION_MARKER_PREFIX = "[agent-compose: PAYLOAD ELIDED IN TRANSIT";
+/**
+ * Cap one JSONL line to at most `maxBytes` bytes.
+ *
+ *  - At or under `maxBytes`: returned byte-identical (never re-serialized).
+ *  - Over it and parseable as a JSON object/array: every string longer than
+ *    `keepBytes` is truncated to its first `keepBytes` bytes plus an honest
+ *    elision marker telling the reader the full content still exists in the
+ *    sandbox and how to get it. If the result still exceeds `maxBytes`
+ *    (many big strings), the per-string budget shrinks 8× and then 64× before
+ *    giving up.
+ *  - Unparseable, or uncappable even at the smallest budget: hard byte
+ *    truncation to `maxBytes`. The line stops being valid JSON, so the
+ *    consumer's parse skips it — one event lost, stream alive (strictly
+ *    better than the whole turn dying).
+ *
+ * SELF-CONTAINED by contract: no imports, no outer-scope references except
+ * globals (`Buffer`, `JSON`) — `jsonlGuardScript()` ships `this.toString()`
+ * into the sandbox. Keep it that way.
+ */
+export declare function capJsonlLine(line: string, maxBytes: number, keepBytes: number): string;
+/**
+ * The in-sandbox filter's source: a dependency-free node script that
+ * line-buffers stdin, re-emits every line through `capJsonlLine`, and turns
+ * the exit sentinel into its own exit code.
+ *
+ *   node <script> <sentinel> <maxBytes> <keepBytes>
+ */
+export declare function jsonlGuardScript(): string;
+/**
+ * Wrap a turn command so its stdout crosses the command stream through the
+ * guard. Self-deciding in-sandbox: when `node` is absent (a bare sandbox a
+ * self-provisioned CLI runs on), the command runs unguarded — the pre-guard
+ * status quo — instead of failing every turn.
+ *
+ * The command runs in a SUBSHELL so a `$?`-carrying sentinel line always
+ * prints after it exits, however it exits (a brace group would let a shell
+ * `exit` skip the printf). stderr stays un-piped — the provider's stderr
+ * accumulation is unchanged.
+ */
+export declare function wrapJsonlCommand(args: {
+    cmd: string;
+    guardPath: string;
+    sentinel: string;
+    maxBytes: number;
+    keepBytes: number;
+}): string;

package/dist/runtimes/amp.d.ts

@@ -18,6 +18,6 @@ export interface AmpRuntimeConfig {
     /** Amp uses its configured model; reserved for forward-compatibility. */
     model?: string;
 }
-export declare function createAmpRuntime(config?: AmpRuntimeConfig): import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
-declare const _default: import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+export declare function createAmpRuntime(config?: AmpRuntimeConfig): import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
 export default _default;

package/dist/runtimes/claude-code.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Claude Code CLI runtime — drives the `claude` coding CLI headless INSIDE
+ * the sandbox (`claude -p --output-format stream-json`) and maps its JSONL
+ * event stream onto the AgentMessage contract.
+ *
+ * This is a different mechanism from `claudeRuntime` (claude.ts): that one
+ * drives the Anthropic Agent SDK in the CALLING process, which makes it
+ * unusable wherever the caller is the server (a cloud session's turns) —
+ * "never execute user-provided source in the server process". This runtime
+ * is a CLI-agent spec like codex/opencode: the agent loop runs entirely
+ * in-sandbox and we only stream-parse the events it prints, so the
+ * server→sandbox cloud-executor path can host it (CLOUD_SESSION_RUNTIMES).
+ *
+ * Transports, mirroring codexSpec exactly:
+ *   - ACP: the Zed adapter (`npx @zed-industries/claude-code-acp`) — the SAME
+ *     pinned adapter the local bridge daemon launches (cli/src/bridge/acp.ts
+ *     imports the pin from here). Engages only where the provider exposes
+ *     `commands.spawnDuplex` (the in-VM/local view); the server→sandbox
+ *     E2B/Vercel view has no duplex, so cloud-session turns always drive the
+ *     JSONL path below. Cold start: the adapter is npx-fetched on first
+ *     launch (~10-30s once per sandbox lifetime; node/npm are in the
+ *     agent-env image).
+ *   - JSONL: `claude -p --output-format stream-json --verbose`, resume via
+ *     `--resume <session_id>`. The `claude` binary is BAKED into the
+ *     `agent-env-<size>` E2B image at /usr/local/bin/claude
+ *     (infra/e2b-template/build.ts), so there is no install cold-start on the
+ *     platform path; the `install` below is the bare-sandbox fallback.
+ *
+ * Auth (in-sandbox env, in the CLI's own precedence order):
+ *   - `CLAUDE_CODE_OAUTH_TOKEN` — a user subscription (BYOS setup-token /
+ *     OAuth grant); rides the user's plan directly against Anthropic.
+ *   - `ANTHROPIC_API_KEY` (+ `ANTHROPIC_BASE_URL`) — an API key; for cloud
+ *     sessions this is the gateway-minted session virtual key pointed at the
+ *     token-metering gateway's Anthropic passthrough (ADR-0039).
+ */
+import { type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
+/** Pinned Claude Code ACP adapter (Zed's npm shim — `claude` has no native
+ *  ACP mode). Pinned EXACT, not a range: the adapter's README warns of
+ *  breaking changes; bump deliberately and re-verify a live turn. The local
+ *  bridge daemon (cli/src/bridge/acp.ts) imports this same pin so both
+ *  executors launch the identical adapter. Verified against 0.16.2. */
+export declare const CLAUDE_CODE_ACP_ADAPTER = "@zed-industries/claude-code-acp@0.16.2";
+/** Extended-thinking token budget per effort level — Claude Code's real knob
+ *  is the `MAX_THINKING_TOKENS` env var (its documented settings env), set
+ *  per invocation below. Values mirror the platform turn loop's
+ *  `EFFORT_BUDGET_TOKENS` (server model-client) so "high" means the same
+ *  thing in a channel and in a claude-code session. */
+export declare const CLAUDE_CODE_THINKING_TOKENS: Record<CliReasoningEffort, number>;
+export declare const claudeCodeSpec: CliAgentSpec;
+export interface ClaudeCodeRuntimeConfig {
+    /** Claude model id (`--model`). Omit to use the CLI's configured default. */
+    model?: string;
+    /** Extended-thinking effort (`MAX_THINKING_TOKENS`). Omit for the CLI's
+     *  default behaviour (no forced budget). */
+    effort?: CliReasoningEffort;
+}
+export declare function createClaudeCodeRuntime(config?: ClaudeCodeRuntimeConfig): import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+export default _default;

package/dist/runtimes/claude-code.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * claude-code CLI-agent spec — the in-sandbox `claude -p --output-format
+ * stream-json` transport for cloud sessions (the cloud-hostable counterpart
+ * of the in-process `claudeRuntime`).
+ *
+ *   - buildCommand: headless stream-json invocation, stdin prompt, resume
+ *     via --resume, cwd via `cd`, IS_SANDBOX=1 (root-user permission skip);
+ *   - mapEvent: assistant content blocks → text/thinking/tool_use, user
+ *     tool_result echoes → tool_result, result → usage on success and an
+ *     honest STRING error on failure;
+ *   - the ACP invocation pins the SAME Zed adapter the local bridge daemon
+ *     launches, so both executors drive one adapter version.
+ */
+export {};

package/dist/runtimes/claude.d.ts

@@ -30,6 +30,22 @@ export interface ClaudeRuntimeConfig {
      *  `agentc init`; default `"all"` makes them usable. Pass `[]` to disable. */
     skills?: string[] | "all";
 }
+/** Bounded tail of the Claude Code process's stderr. The Agent SDK's
+ *  process-exit error carries ONLY the exit code ("Claude Code process
+ *  exited with code 1") — the CLI's actual complaint goes to stderr, which
+ *  query() surfaces exclusively through the `stderr` callback. Without
+ *  capturing it, a startup failure (bad flag, root refusal, dead config)
+ *  reaches the run card as an uninformative exit code. Same 2000-char cap
+ *  as the CLI-agent runtimes' exit-code tail (_cli-agent.ts). */
+export declare const STDERR_TAIL_CAP = 2000;
+export declare class StderrTail {
+    private buf;
+    append(data: string): void;
+    /** The captured tail, trimmed — empty string when nothing was written. */
+    get text(): string;
+    /** Suffix an error message with the tail (no-op when stderr was silent). */
+    decorate(message: string): string;
+}
 export declare class ClaudeRunner implements ModelExecutionContract {
     private readonly options;
     private readonly config;

package/dist/runtimes/claude.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ClaudeRunner stderr-tail capture — the Agent SDK's process-exit error
+ * ("Claude Code process exited with code 1") carries no detail; the CLI's
+ * actual complaint goes to stderr, surfaced only through query()'s `stderr`
+ * callback. The runner must capture a bounded tail and attach it to the
+ * error message so a startup failure is diagnosable from the run card.
+ */
+export {};

package/dist/runtimes/codex.d.ts

@@ -12,7 +12,10 @@
  * Verified against codex-cli 0.124.0: `codex exec --json` + resume-by-thread,
  * with the command_execution / reasoning / agent_message item shapes below.
  */
-import { type CliAgentSpec } from "./_cli-agent.js";
+import { type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
+/** True when an error-item message is a known codex advisory (log-level
+ *  noise), not a real error. Exported for tests. */
+export declare function isCodexAdvisoryNoise(text: string): boolean;
 /** Exported for the fixture-based parity tests (ADR-0020): the legacy JSONL
  *  `mapEvent` is the golden the ACP normaliser is asserted equal to. Not part
  *  of the public runtime surface — `createCodexRuntime` stays the entry point. */
@@ -20,7 +23,10 @@ export declare const codexSpec: CliAgentSpec;
 export interface CodexRuntimeConfig {
     /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */
     model?: string;
+    /** Reasoning effort (`-c model_reasoning_effort=<level>`). Omit to use the
+     *  codex CLI's configured default. */
+    effort?: CliReasoningEffort;
 }
-export declare function createCodexRuntime(config?: CodexRuntimeConfig): import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
-declare const _default: import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+export declare function createCodexRuntime(config?: CodexRuntimeConfig): import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
 export default _default;

package/dist/runtimes/cursor.d.ts

@@ -0,0 +1,9 @@
+import { type CliAgentSpec } from "./_cli-agent.js";
+export declare const cursorSpec: CliAgentSpec;
+export interface CursorRuntimeConfig {
+    /** Cursor model id; ACP mode ignores it (account default) — applies to the `-p` fallback. */
+    model?: string;
+}
+export declare function createCursorRuntime(config?: CursorRuntimeConfig): import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+export default _default;

package/dist/runtimes/droid.d.ts

@@ -0,0 +1,9 @@
+import { type CliAgentSpec } from "./_cli-agent.js";
+export declare const droidSpec: CliAgentSpec;
+export interface DroidRuntimeConfig {
+    /** `custom:<displayName>-<index>` matching the provisioned settings.json. */
+    model?: string;
+}
+export declare function createDroidRuntime(config?: DroidRuntimeConfig): import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+export default _default;

package/dist/runtimes/jsonl-guard.test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * JSONL frame guard — the canary for the session-machine recycling failure.
+ *
+ * The live incident: a cloud session's turn stream rides `commands.run` over
+ * E2B's connect-web gRPC command stream, and a single multi-hundred-KB JSONL
+ * line (a `claude` stream-json event echoing a whole Read file) kills that
+ * stream with `13: [internal] protocol error: received unsupported compressed
+ * output` — the platform recycles the VM and the turn's work is lost.
+ *
+ * These tests pin the fix at three altitudes:
+ *   1. `capJsonlLine` (unit) — the shared cap logic.
+ *   2. The GENERATED guard script, executed by a REAL `node` subprocess —
+ *      the exact bytes that run in-sandbox, including the exit-code sentinel.
+ *   3. The runner end-to-end through `makeLocalSandboxProvider` — a real
+ *      `sh` pipeline: a synthetic oversized tool_result crosses the command
+ *      boundary UN-FATALLY, arrives with the elision marker, and the turn
+ *      completes with `done`.
+ */
+export {};