@agent-compose/sdk 0.8.5 → 0.8.7

package/dist/runtimes/opencode.d.ts

@@ -1,20 +1,57 @@
 /**
  * OpenCode CLI runtime — drives sst's `opencode` agentic CLI inside the sandbox.
- * OpenCode speaks ACP natively (`opencode acp`, protocolVersion 1 — verified
- * live on E2B), so the runner drives it over ACP; the JSONL members below are
- * only the version-mismatch fallback (vestigial for a v1 agent).
  *
- * Auth + model via OpenRouter: set OPENROUTER_API_KEY (a factory/workflow
- * secret) and use a model id like `openrouter/z-ai/glm-5.2`. The runtime
- * installs the `opencode-ai` CLI on demand; pair with
- * `snapshots: { bootFrom: "reuse" }` to install once and boot from the capture.
+ * Two transports share this spec:
+ *   - the SDK runner (createCliAgentRuntime) speaks ACP: `opencode acp` is a
+ *     protocolVersion-1 ACP server (verified live on E2B, 2026-06-30) on a
+ *     provider with a duplex-stdin command primitive, and the JSONL members
+ *     below are its version-mismatch fallback;
+ *   - the platform's cloud lane (server turn-workflow/tailer.ts) never speaks
+ *     ACP: it launches `buildCommand` detached, tails the CLI's stdout file
+ *     line by line, JSON-parses every line and maps it through `mapEvent`.
+ *     The dispatch constitution's `fast` lane (google/gemini-3.7-flash on
+ *     opencode) runs there, so the JSONL members are the LIVE path for it.
  *
- * Verified live on E2B (2026-06-30): `npm i -g opencode-ai` (v1.17.12);
- * `opencode run --model openrouter/z-ai/glm-5.2` drove a GLM-5.2 turn through
- * OpenRouter; `opencode acp` answered the ACP `initialize` handshake with
- * protocolVersion 1.
+ * The 2026-10-02 fast-lane failure (prod: 5 of 5 opencode turns settled
+ * `harness_no_output` over ten days) — `opencode run` without `--format json`
+ * prints the reply as human-formatted prose and its tool narration on stderr,
+ * so the tailer parsed zero JSON lines and the turn settled empty while the
+ * work itself had completed (reproduced locally, 2026-10-03). `--format json`
+ * makes `run` print one JSON event per line — `{type, timestamp, sessionID,
+ * part}` for step_start / step_finish / text / reasoning / tool_use, and
+ * `{type: "error", timestamp, sessionID, error}` for a session error
+ * (packages/opencode/src/cli/cmd/run.ts, v1.18.34: text and reasoning parts
+ * fire once, when the part's `time.end` lands; a tool part fires once, at
+ * `state.status` completed or error). Captured real streams:
+ * `__fixtures__/jsonl/opencode`.
+ *
+ * Auth + model: the platform routes opencode through its gateway as the
+ * custom provider `gw` — server session-runtime-config.ts writes
+ * ~/.config/opencode/opencode.json with the gateway base URL and
+ * `{env:OPENROUTER_API_KEY}`, and the model flag is `gw/openrouter/<provider>/
+ * <model>`. Stand-alone SDK use sets OPENROUTER_API_KEY (a factory/workflow
+ * secret) and an `openrouter/<provider>/<model>` id.
+ *
+ * Resume (owner, 2026-10-03: "resume like other workers"): every event
+ * carries the CLI's `sessionID`; `extractSessionId` reads it, the tailer
+ * records it, and a follow-up turn on the same machine launches `run
+ * --session <id>` with only the new messages (renderCloudPrompt). The store
+ * is SQLite under the guest's ~/.local/share/opencode, so a resume target
+ * can be gone (a stale binding, a wiped store): `run --session` then exits 1
+ * with `Error: Session not found` on stderr and nothing on stdout — the
+ * classifier's `resume_target_missing` (turn-failure-class.ts), which the
+ * cloud turn workflow heals by dropping the binding and relaunching the turn
+ * fresh. Verified live on 1.18.34 (fixtures `resume-turn-1/2.jsonl`,
+ * `session-not-found.stderr`).
  */
 import { type CliAgentSpec } from "./_cli-agent.js";
+/** The text of an opencode session error — `{name, data: {message, statusCode?}}`
+ *  (ProviderAuthError / APIError / UnknownError / … in the opencode SDK
+ *  types): name and HTTP status first so the settle's classifier reads the
+ *  cause, then the provider's own words. Captured shapes: a 401 from the
+ *  gateway is `APIError` with statusCode 401; an unknown model id is
+ *  `UnknownError` with the gateway's "Unexpected server error". */
+export declare function opencodeErrorText(error: unknown): string;
 export declare const opencodeSpec: CliAgentSpec;
 export interface OpencodeRuntimeConfig {
     /** OpenRouter-prefixed model id (default `openrouter/z-ai/glm-5.2`). */

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

@@ -0,0 +1,14 @@
+/**
+ * opencodeSpec — the cloud lane's launch and its parse of `opencode run
+ * --format json`, against REAL captured streams (opencode 1.18.34 through the
+ * dev gateway on google/gemini-3.7-flash, 2026-10-03; paths rewritten to
+ * /workspace, a 401's key fragment redacted).
+ *
+ * The 2026-10-02 fast-lane failure: prod's 5 of 5 opencode turns settled
+ * `harness_no_output` because the launch printed prose, which the tailer's
+ * JSON parse skipped line by line. These pins hold the two halves of the
+ * fix — the launch asks for JSON, and the mapper reads every event shape the
+ * CLI emits — so the lane can never again run to a clean exit with nothing
+ * the transcript can show.
+ */
+export {};

package/dist/sandbox/baked-clis.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Harness CLIs the E2B session image bakes, pinned: the SINGLE SOURCE for
+ * each version. `infra/e2b-template/parts.ts` installs exactly this version
+ * into every `agent-env-<size>`, and the runtime spec's on-demand install
+ * fetches the same one on a machine whose image predates the bake. It lives
+ * under `sdk/src/sandbox/` so a bump rebuilds the images: sandbox-images.yml
+ * watches this directory.
+ *
+ * The ruling (owner, 2026-10-02): workers run the NEWEST CLIs, baked and
+ * pinned so every machine runs the same tested version, with no per-machine
+ * self-update — prod workers were running claude 2.1.287 on an image that
+ * baked 2.1.283, because the CLI updated itself inside the machines. Each
+ * release bumps the pins here; the two constants below turn the CLIs' own
+ * updaters off wherever the platform runs them.
+ */
+/** Anthropic's claude CLI (the native installer's versioned binary, copied
+ *  to /usr/local/bin/claude). The floor is the worker model: Opus 5.5 needs
+ *  2.1.280 or newer. 2.1.287 is current on npm (2026-10-02) and is the build
+ *  the rtk `--settings` hook, the `[1m]` window behind a gateway base URL and
+ *  the prompt-cache TTL env were verified against. */
+export declare const CLAUDE_CODE_VERSION = "2.1.287";
+/** OpenAI's codex CLI (`@openai/codex`). 0.160.0 is current on npm
+ *  (2026-10-02); codex.ts's event mapping (command_execution / agent_message
+ *  / turn.completed usage) and the hook trust-hash recipe were re-verified
+ *  live against it, and its plan-tool and hook sources are byte-identical to
+ *  rust-v0.159.2, where the `todo_list` shape was captured. Unbaked, every
+ *  session's first codex turn waited ~13 s in prod for the npm install
+ *  before its launch (2026-09-30), and each machine got whichever version
+ *  npm served that minute. Bump deliberately. */
+export declare const CODEX_CLI_VERSION = "0.160.0";
+/** sst's opencode CLI (`opencode-ai`) — the harness behind the dispatch
+ *  constitution's `fast` lane. 1.18.34 is current on npm (2026-09-30) and
+ *  is the build the cloud lane (runtimes/opencode.ts) was verified against,
+ *  live through the gateway on google/gemini-3.7-flash (2026-10-03): the
+ *  `run --format json` event shapes (runtimes/__fixtures__/jsonl/opencode),
+ *  the prompt on stdin, and the `--auto` permission flag — which 1.15.13
+ *  still spelled `--dangerously-skip-permissions`, the kind of flag drift
+ *  an unpinned install ships straight into prod. Until this pin the spec
+ *  installed whatever npm served that minute, on each machine's first
+ *  opencode turn. Bump deliberately. */
+export declare const OPENCODE_CLI_VERSION = "1.18.34";
+/** rtk (rtk-ai/rtk), the shell-output compressor behind the Bash PreToolUse
+ *  hook every claude and codex session carries (runtimes/claude-code.ts
+ *  RTK_BASH_HOOK_COMMAND, runtimes/codex.ts RTK_CODEX_HOOK_COMMAND). The
+ *  floor is `rtk hook codex`, added in 0.50.0 (2026-09-24); 0.51.0 is the
+ *  current release (2026-10-02) and the build both hooks' exact smoke
+ *  payloads were run against (2026-10-04). Until this pin the image ran
+ *  rtk's installer unpinned, so it baked whatever release the installer
+ *  served on the day its layer was last built — and E2B served that layer
+ *  from cache for six weeks: every 2026-10 image carried rtk 0.45.0, whose
+ *  `rtk hook` had no `codex`, so the codex hook exited 2 with clap's usage
+ *  on stderr and Codex blocked every shell command of every codex session
+ *  from the hook's 2026-10-03 deploy on. The image recipe downloads exactly
+ *  this release (infra parts.ts RTK_INSTALL, sha256-verified); its verify
+ *  layer and the smoke gate assert the baked version. Bump deliberately,
+ *  re-running both hooks' payloads against the new build. */
+export declare const RTK_VERSION = "0.51.0";
+/** Env that turns the claude CLI's updater off — the admin-grade switch
+ *  (verified in the 2.1.287 binary): it disables the background self-update
+ *  AND `claude update`, so a machine runs the baked version until the image
+ *  is rebuilt; `DISABLE_AUTOUPDATER` would stop only the background updater.
+ *  The `autoUpdates: false` config does nothing for the native installer.
+ *  Sessions get it from the session env file, runs from the runner env. */
+export declare const CLAUDE_CODE_NO_SELF_UPDATE_ENV: Readonly<Record<string, string>>;
+/** The config.toml line that turns codex's startup update check off
+ *  (`check_for_update_on_startup`, codex-rs config: "set to false only if
+ *  your Codex updates are centrally managed" — they are: the image). A
+ *  top-level key, so it must come before any `[table]` in the file.
+ *  Accepted by 0.160.0 under `--strict-config` (live, 2026-10-02). */
+export declare const CODEX_NO_SELF_UPDATE_CONFIG_LINE = "check_for_update_on_startup = false\n";
+/** The opencode.json keys that turn opencode's updater off (`autoupdate`
+ *  takes true | false | "notify" in 1.18.34's config schema). Spread into
+ *  the session config the server writes (session-runtime-config.ts), so a
+ *  machine runs the baked version until the image is rebuilt. */
+export declare const OPENCODE_NO_SELF_UPDATE_CONFIG: Readonly<Record<string, boolean>>;

package/dist/sandbox/exec-stream.d.ts

@@ -1,6 +1,5 @@
 /**
- * SSE exec-stream parser — used by the agent sandbox broker clients in
- * runner.ts to consume a streamed command execution.
+ * SSE exec-stream parser — consumes a streamed command execution.
  */
 import type { SandboxCommandResult } from "../types/sandbox.js";
 export interface ParseSseExecStreamOptions {

package/dist/sandbox/network-policy.d.ts

@@ -37,6 +37,15 @@ export type SandboxNetworkPolicy = "allow-all" | "deny-all" | {
     allow?: string[] | Record<string, SandboxNetworkAllowRule[]>;
     subnets?: SandboxNetworkSubnetPolicy;
 };
+/**
+ * OPEN egress save the given CIDRs: every domain and every IPv4 destination,
+ * with `deny` applied ahead of both — "allow-all" spelled out so it can carry
+ * a deny (the server stamps its metadata-endpoint deny on every open policy).
+ * Vercel enforces this shape natively (its subnet denies take precedence
+ * over allowed domains and CIDRs). E2B lets an allow entry win over a deny,
+ * so `toE2bNetwork` recognizes the shape and emits a bare deny list instead.
+ */
+export declare function openEgressExcept(deny: readonly string[]): SandboxNetworkPolicy;
 /** Matches a path containing a dot-dot segment — literal (`/../`) or
  *  percent-encoded (`%2e%2e`, `%2f` boundaries). `DOT_SEGMENT_PATH_RE2` is
  *  the RE2 form handed to Vercel's matcher: wrapped in `.*` so it behaves
@@ -74,17 +83,26 @@ export declare function toVercelNetworkPolicy(policy: SandboxNetworkPolicy): Ver
  * (`SandboxNetworkOpts`) — the E2B analogue of `toVercelNetworkPolicy`.
  *
  *   - `allowOut`: the set of allowed egress targets — every host named in
- *     `allow` PLUS every CIDR in `subnets.allow`. The Archil raw-TCP
- *     data-plane CIDRs ride here as FIRST-CLASS allow entries (E2B has no
- *     root-exemption to lean on, unlike the old in-VM iptables model).
+ *     `allow` PLUS every CIDR in `subnets.allow`.
  *   - `denyOut`: the all-traffic sentinel (`0.0.0.0/0`) so the policy is
- *     DEFAULT-DENY — only `allowOut` targets pass. E2B applies allow before
- *     deny, so a host in both lists is allowed.
+ *     DEFAULT-DENY — only `allowOut` targets pass — plus every CIDR in
+ *     `subnets.deny`. E2B applies allow before deny, so a host in both lists
+ *     is allowed: a `subnets.deny` CIDR bites on E2B only where no allow
+ *     entry covers the destination (E2B's documented precedence; Vercel
+ *     applies its `subnets.deny` ahead of every allow). Whether E2B's `"*"`
+ *     domain wildcard also covers a request addressed to a bare IP is E2B's
+ *     call, so a deny under a `"*"`-plus-rules policy is not relied on here.
  *   - `rules`: per-host header injection. For each host carrying transform(s),
  *     emit one rule per transform with `{ transform: { headers } }`. A host
  *     with a rule MUST also be in `allowOut` (registering a rule does not
  *     grant egress on its own — E2B's API requires the host in `allowOut`).
  *
+ * OPEN egress save some CIDRs (`openEgressExcept`) is the one shape E2B's
+ * allow precedence cannot express as allow + deny lists — its "every IPv4
+ * destination" allow would win over the deny. It becomes a bare `denyOut`
+ * of those CIDRs: no allow list and no domain filtering (so raw TCP keeps
+ * flowing, as under "allow-all"), only the denied destinations refused.
+ *
  * BEHAVIOURAL DIVERGENCE FROM iron-proxy / Vercel — path/method gating is NOT
  * available on E2B native rules. An `SandboxNetworkRule` carries only a
  * `transform` (header injection); there is no method/path matcher. So our

package/dist/sandbox.d.ts

@@ -5,17 +5,19 @@
  *   - `sandbox/network-policy.ts` — egress policy shape + per-provider translators
  *   - `sandbox/sizes.ts`          — machine sizes + E2B template aliases
  *   - `sandbox/devbox.ts`         — the ADR-0038 per-member desktop machine alias
+ *   - `sandbox/baked-clis.ts`     — harness CLI versions the session image bakes
  *   - `sandbox/provider-def.ts`   — provider contract, create opts, fleet tag
- *   - `sandbox/exec-stream.ts`    — SSE exec-stream parser (broker clients)
+ *   - `sandbox/exec-stream.ts`    — SSE exec-stream parser
  *   - `sandbox/providers/*`       — vercel / e2b / e2b-desktop / local providers
  *   - `sandbox/registry.ts`       — provider registry + fleet management
  */
 export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions, SandboxCommandResult, SandboxDuplexProcess, SandboxSpawnDuplexOptions } from "./types/sandbox.js";
 export type { SandboxNetworkHeaderTransform, SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxNetworkPolicy, } from "./sandbox/network-policy.js";
-export { DOT_SEGMENT_PATH_RE2, toVercelNetworkPolicy, toE2bNetwork } from "./sandbox/network-policy.js";
+export { DOT_SEGMENT_PATH_RE2, openEgressExcept, toVercelNetworkPolicy, toE2bNetwork } from "./sandbox/network-policy.js";
 export type { SandboxSize } from "./sandbox/sizes.js";
 export { SANDBOX_SIZES, SANDBOX_MACHINES, SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, SESSION_DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES, E2B_MAX_VCPUS, E2B_MAX_MEMORY_MB, VERCEL_MEMORY_MB_PER_VCPU, isE2bSupportedSize, isVercelSupportedSize, sandboxSizeLabel, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate, isPlatformE2bTemplateAlias, } from "./sandbox/sizes.js";
 export { E2B_DEVBOX_TEMPLATE, E2B_DEVBOX_SPEC, E2B_DEVBOX_RECIPE_VERSION, e2bDevboxTemplateRef, } from "./sandbox/devbox.js";
+export { CLAUDE_CODE_VERSION, CODEX_CLI_VERSION, OPENCODE_CLI_VERSION, RTK_VERSION, CLAUDE_CODE_NO_SELF_UPDATE_ENV, CODEX_NO_SELF_UPDATE_CONFIG_LINE, OPENCODE_NO_SELF_UPDATE_CONFIG, } from "./sandbox/baked-clis.js";
 export { AGENT_COMPOSE_TAG } from "./sandbox/provider-def.js";
 export type { SandboxCreateOpts, OwnedSandbox } from "./sandbox/provider-def.js";
 export { parseSseExecStream } from "./sandbox/exec-stream.js";

package/dist/step-invocation/protocol.d.ts

@@ -29,11 +29,10 @@ export declare function stepResultLinePrefix(token: string): string;
  *  `console.log` can't forge either without knowing the token, and the
  *  invoker can filter both prefixes from captured stdout with one token. */
 export declare function stepPauseLinePrefix(token: string): string;
-/** Sandbox-side path where dispatch writes the compiled runner bundle.
- *  Both modes (full-mode `dispatch.ts` and step-mode `invokeStep`) spawn
- *  the runner from this path; single source of truth. */
+/** Sandbox-side path where the sandbox bootstrap writes the compiled runner
+ *  bundle; `invokeStep` spawns the runner from this path. */
 export declare const RUNNER_BUNDLE_PATH = "/tmp/runner.bundle.js";
-/** Command the invoker (and dispatch) spawns inside the sandbox. */
+/** Command the invoker spawns inside the sandbox. */
 export declare const RUNNER_COMMAND = "node /tmp/runner.bundle.js";
 /** Names of the env vars the invoker stamps onto the runner subprocess.
  *  The runner's serveStep reads from these. Centralising the names lets

package/dist/step-invocation/server.d.ts

@@ -58,7 +58,7 @@ export type StepHandler<TInput = unknown, TOutput = unknown> = (request: ServeSt
  * from process.env so user code (including any workflow module imported
  * inside the handler) cannot read AC_STEP_RESULT_TOKEN — that keeps the
  * result channel uncorruptible by stdout output from anywhere in the
- * workflow's dep tree. RUN_ID remains available to match full-mode
- * runner behaviour.
+ * workflow's dep tree. RUN_ID remains available: SDK code inside the step
+ * (`agent()`, the client's parent-run link) reads it.
  */
 export declare function serveStep<TInput, TOutput>(handler: StepHandler<TInput, TOutput>): Promise<never>;

package/dist/step-invocation/types.d.ts

@@ -55,8 +55,8 @@ export declare const StepPauseRequestSchema: z.ZodObject<{
     reason: z.ZodString;
     kind: z.ZodEnum<{
         event: "event";
-        custom: "custom";
         decision: "decision";
+        custom: "custom";
         sleep: "sleep";
     }>;
     payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;