@agent-compose/sdk 0.5.5 → 0.5.7

package/src/agent/agent-loop.ts

@@ -15,7 +15,7 @@ import { PauseManager } from "../pause/manager.js";
 import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
 import { SteerDecisionSchema, type SteerDecision, type SteerPayload } from "./steer-control.js";
 
-export const DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
+export const DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 
 const SAME_BLOCKER_ITERATIONS = 3;
 const STALL_ITERATIONS        = 3;
@@ -152,8 +152,15 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   const label              = opts.label ?? "agent";
   const logLabel           = opts.label ?? "[Agent Loop]";
   const startedAt          = Date.now();
-  const turnsPerIteration  = opts.turnsPerIteration ?? 40;
-  const maxIterations      = opts.maxIterations ?? 8;
+  // No budget ⇒ no turn cap: the harness runtime (Claude Code) decides when it's
+  // done. A numeric budget is an explicit caller choice, not a default we impose.
+  const turnsPerIteration  = opts.turnsPerIteration;
+  const maxIterations      = opts.maxIterations ?? (turnsPerIteration === undefined ? 1 : 8);
+  // A responseSchema is a CONTRACT, not a hope: when the agent's <response> fails
+  // validation, the loop re-prompts with the exact errors until it conforms —
+  // without consuming the caller's iteration budget. The backstop below only
+  // guards against a truly wedged agent (never reached in normal operation).
+  let schemaRetriesLeft    = 10;
   const processors         = opts.processors ?? [];
   const requestContext     = opts.requestContext ?? RequestContext.fromReserved({
     teamId: "", runId: "", workflowId: "",
@@ -171,7 +178,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
 
   if (!opts.runtime) throw new Error("agentLoop: opts.runtime is required");
   const client = opts.runtime({
-    maxTurns:     turnsPerIteration,
+    ...(turnsPerIteration !== undefined ? { maxTurns: turnsPerIteration } : {}),
     allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
     label: logLabel,
     cwd:          opts.cwd,
@@ -342,6 +349,14 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
 
     const procCtx = buildProcCtx(iteration + 1);
     let initialPrompt = opts.buildPrompt(lastStatus, iteration);
+    // CONTRACT FEEDBACK: when the previous turn's <response> failed schema
+    // validation, the violation goes BACK TO THE MODEL as its next turn (the
+    // session carries the prior context). Without this, contract retries
+    // re-run the identical prompt and the model repeats the identical mistake.
+    if (lastResponseValidationError) {
+      initialPrompt = `${initialPrompt}\n\n[response contract violation — fix and re-emit]\nYour previous <response> failed schema validation with these errors:\n${lastResponseValidationError.slice(0, 2000)}\nRe-emit the COMPLETE corrected <response> JSON now: every required field present, correctly named and typed (no omissions, no renames).`;
+      lastResponseValidationError = "";
+    }
     if (steerDecision) {
       // Deliver the human's answer as the agent's next user turn by appending
       // it to the iteration prompt. `sendMessage({ prompt })` is the one input
@@ -364,7 +379,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
 
     // Progress, not an error — write to stdout so dashboards and
     // log viewers don't visually flag it as a warning.
-    process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns\n`);
+    process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration !== undefined ? `${turnsPerIteration} turns` : "harness-decided turns"}\n`);
 
     let responseText = "";
     // The single `opts.inbox` is shared across iterations, but the
@@ -376,7 +391,11 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     // semantics — buffered until consumed).
     for await (const rawMsg of client.sendMessage({
       prompt,
-      sessionId: iteration > 0 ? lastSessionId : undefined,
+      // Resume whenever a session exists — NOT keyed on `iteration > 0`, because a
+      // contract retry rolls `iteration` back to 0 while a session already exists;
+      // keying on the session id keeps the corrective re-prompt in the same session
+      // (otherwise it restarts the task in a fresh session and repeats side effects).
+      sessionId: lastSessionId ?? undefined,
       iteration: iteration + 1,
       ...(opts.inbox ? { inboxStream: opts.inbox } : {}),
     })) {
@@ -447,6 +466,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
           process.stderr.write(`${logLabel} NO <response> BLOCK — response tail: ${responseText.slice(-400)}\n`);
           status = { ...status!, exit_signal: false, blockers: ["No <response> block found — emit a <response> block with the required JSON fields before setting exit_signal: true"] };
           opts.onIteration?.(iteration + 1, status);
+          if (schemaRetriesLeft-- > 0) iteration--; // contract enforcement — free, not billed to the iteration budget
           continue;
         }
         // Status-merged validation — the schema may reference status
@@ -458,6 +478,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
           process.stderr.write(`${logLabel} <response> SCHEMA FAILED: ${parsed.error.message}\nraw: ${JSON.stringify(rawResponse).slice(0, 400)}\n`);
           status = { ...status!, exit_signal: false, blockers: [`<response> schema validation failed: ${parsed.error.message}`] };
           opts.onIteration?.(iteration + 1, status);
+          if (schemaRetriesLeft-- > 0) iteration--; // contract enforcement — free, not billed to the iteration budget
           continue;
         }
         response = parsed.data;
@@ -487,10 +508,24 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       continue;
     }
 
-    if (!status) {
+    if (!status && rawResponse === null) {
       if (++iterationsWithoutStatus >= STALL_ITERATIONS)
         throw new Error(`${logLabel} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
+      // EMPTY-OUTPUT RE-PROMPT: under the unbudgeted default (maxIterations 1)
+      // a single turn that emits neither <status> nor <response> would
+      // otherwise exhaust the budget with ZERO corrective feedback. Treat it
+      // like the contract-violation branches — refund the iteration and
+      // re-prompt with explicit feedback, bounded by the shared retry pool.
+      // The stall counter above still hard-bounds consecutive empty turns.
+      if (opts.responseSchema && schemaRetriesLeft-- > 0) {
+        lastResponseValidationError = "no <response> block found — the turn ended with neither a <status> nor a <response> block; emit the complete <response> JSON";
+        process.stdout.write(`${logLabel} no <status>/<response> emitted — corrective re-prompt (${schemaRetriesLeft} retries left)\n`);
+        iteration--;
+        continue;
+      }
     } else {
+      // A parsed structured response (even one that failed schema validation)
+      // is real output, not a stall — the contract retry below handles it.
       iterationsWithoutStatus = 0;
     }
 
@@ -506,6 +541,20 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       blockerStreak = null;
     }
 
+    // CONTRACT RETRY (catch-all): the agent EMITTED a <response> block this turn,
+    // it failed schema validation, and it didn't go through the <status> branches
+    // above (structured-only output, no <status>). Re-prompt with the validation
+    // errors as feedback, FREE of the iteration budget. Gated on an actual
+    // validation failure this turn AND on the agent not signalling it's still
+    // working (`exit_signal: false`) — an in-progress turn that happens to carry
+    // a draft <response> consumes its budget normally instead of draining the
+    // shared retry pool that genuine contract violations rely on.
+    if (opts.responseSchema && rawResponse !== null && lastResponseValidationError !== "" && status?.exit_signal !== false && schemaRetriesLeft-- > 0) {
+      process.stdout.write(`${logLabel} response contract not yet satisfied — corrective re-prompt (${schemaRetriesLeft} retries left)\n`);
+      iteration--;
+      continue;
+    }
+
     if (iteration + 1 < maxIterations)
       // Loop continuation — progress.
       process.stdout.write(`${logLabel} continuing to iteration ${iteration + 2}/${maxIterations}\n`);

package/src/client.ts

@@ -17,7 +17,7 @@ import { parseSseStream } from "./sse.js";
 import type { SandboxNetworkPolicy } from "./sandbox.js";
 import type { RunEvent } from "./types/events.js";
 import type { WorkflowPlan } from "./types/workflow-plan.js";
-import type { SnapshotConfig, IOSchema } from "./types/workflow-metadata.js";
+import type { SnapshotConfig, IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy } from "./types/workflow-metadata.js";
 import type { WorkflowManifest } from "./utils/bundler.js";
 
 /** UUID-v4-ish — matches the server-side predicate. Used to auto-detect
@@ -52,13 +52,6 @@ export interface RegisterResult {
   name: string;
   version: string;
   runtimes?: RegisteredRuntime[];
-  /** Non-fatal advisories from the server. Surfaced at register time so the
-   *  operator sees them while still in front of the terminal — currently
-   *  covers "memory extraction is configured but its workflow is not
-   *  registered in this factory". Empty/undefined when registration was
-   *  cleanly resolved against everything the workflow declares it
-   *  depends on. */
-  warnings?: string[];
 }
 
 export interface RegisteredRuntime {
@@ -72,6 +65,19 @@ export interface RuntimeSourceInput {
   source: string;
 }
 
+/** GitHub provenance for a registered template's source file — stored as
+ *  `metadata.source` on the registration. `cloud-build` stamps the built
+ *  commit's sha; the dashboard's manual link path writes `sha: "manual"`. */
+export interface TemplateSourceRef {
+  owner:  string;
+  repo:   string;
+  branch: string;
+  /** Repo-relative file path, e.g. `.agentc/workflows/workflow-deploy.ts`. */
+  path:   string;
+  /** Commit sha the version was built from, or `"manual"` for hand-links. */
+  sha:    string;
+}
+
 export interface RegisterWorkflowInput {
   name: string;
   source: string;
@@ -83,6 +89,9 @@ export interface RegisterWorkflowInput {
    *  executed on the server. */
   manifest: WorkflowManifest;
   version?: string;
+  /** Where the source file lives on GitHub — stored as `metadata.source`.
+   *  Named `sourceRef` because `source` is the bundled code itself. */
+  sourceRef?: TemplateSourceRef;
   schedule?: string;
   runtimes?: RuntimeSourceInput[];
   /** Human-readable description declared via
@@ -96,13 +105,16 @@ export interface RegisterWorkflowInput {
   snapshots?: SnapshotConfig;
   /** Provider-neutral execution plan detected by the CLI bundler. */
   workflowPlan?: WorkflowPlan;
-  /** Run the built-in memory extractor after this workflow completes.
-   *  Opt-in; defaults to false when omitted. */
-  memory?: boolean;
-  /** Ordered list of workflow names that run as post-hooks after this
-   *  workflow completes. The memory extractor (when `memory: true`)
-   *  runs as an additional hook alongside these. */
-  postRunHooks?: readonly string[];
+  /** Connector requirements declared via `defineWorkflow({ connectors })`
+   *  (ADR-0007). Validated against the server's provider registry at
+   *  registration; tokens are injected at the network layer at dispatch. */
+  connectors?: ConnectorRequirements;
+  /** Connector-catalogue operation tag — see `ConnectorOperationTag`. */
+  connectorOperation?: ConnectorOperationTag;
+  /** Tier-1 invoke ACL declared via `defineWorkflow({ invokePolicy })`.
+   *  Only meaningful when the workflow also declares `connectors` — the
+   *  server gates dispatch on it before binding any grant. */
+  invokePolicy?: InvokePolicy;
   /** Input schema extracted from the workflow's `input` zod schema. */
   inputSchema?: IOSchema;
   /** Output schema extracted from the workflow's `output` zod schema. */
@@ -127,19 +139,16 @@ export interface InvokeWorkflowOptions {
    *  vars after brokering. Replaces the template-level placeholders for
    *  this run only — registered metadata is not mutated. */
   placeholders?: Record<string, string>;
-  /** Per-invocation memory-extractor override — `false` skips the
-   *  built-in memory hook for this run; omitting leaves the registered
-   *  default in place. */
-  memory?:       boolean;
-  /** Per-invocation post-hook override — replaces the registered
-   *  `postRunHooks` array for this run only. */
-  postRunHooks?:    readonly string[];
   /** Explicit parent run id. Pass `null` to suppress ambient RUN_ID auto-detection. */
   parentRunId?:  string | null;
   /** Agent loop inside the parent run that caused this invoke, when applicable. */
   agentId?:      string | null;
   /** Factory slug. Defaults to `"default"`. */
   factorySlug?:  string;
+  /** Idempotency key — sent as the `Idempotency-Key` header. A repeat invoke
+   *  with the same key inside the server's dedup window returns the original
+   *  run instead of starting a new one (matches `resumePause`'s pattern). */
+  idempotencyKey?: string;
 }
 
 export interface InvokeAndWaitOptions extends InvokeWorkflowOptions {
@@ -234,6 +243,13 @@ export interface RunStatus<TOutput = unknown> {
   id: string;
   status: RunState;
   output?: TOutput;
+  /** The run's latest (`saveLatest`) snapshot id, populated once the run has
+   *  succeeded — the boot source to fork this run's evolved filesystem from
+   *  (pass as `snapshots.bootFrom` on a follow-up invoke). `null` while the run
+   *  is still in flight or when it captured no snapshot. Lets an orchestrator
+   *  fork a child straight off the `invokeChild` result without a separate
+   *  `listRunSnapshots` call. */
+  latestSnapshotId?: string | null;
 }
 
 /** ADR-0006 step 10 — actor record returned on a successful resume.
@@ -380,6 +396,41 @@ export interface EventRow {
   createdAt: string;
 }
 
+// The server emits these rows in snake_case; the client maps them to
+// camelCase at the fetch boundary so the SDK surface stays uniform
+// (`EventRow.createdAt`, `RunStatus.latestSnapshotId`, …).
+export interface RunArtifactRow {
+  path: string;
+  factorySlug: string | null;
+  sizeBytes: number | null;
+  lastWriteAt: string;
+  /** Opening text of the file (≤320 chars) — null for binary/empty. */
+  preview: string | null;
+}
+
+export interface FactoryFileWriteResult {
+  path: string;
+  contentHash: string;
+  sizeBytes: number;
+  created: boolean;
+}
+
+/** Wire shapes — what the server actually emits (snake_case). */
+interface RunArtifactWire {
+  path: string;
+  factory_slug: string | null;
+  size_bytes: number | null;
+  last_write_at: string;
+  preview: string | null;
+}
+
+interface FactoryFileWriteWire {
+  path: string;
+  content_hash: string;
+  size_bytes: number;
+  created: boolean;
+}
+
 export interface ReportEventInput {
   name: string;
   body: unknown;
@@ -395,7 +446,7 @@ export interface ListEventsOptions {
   factorySlug?: string;
   limit?: number;
   /** Case-insensitive substring match. Server uses `ILIKE %name%`, so
-   *  `"mem"` matches `memory.fact`, `memory.usage`, etc. Pass the
+   *  `"site"` matches `site.created`, `site.failed`, etc. Pass the
    *  full event name for an effectively-exact filter (any string is a
    *  substring of itself). */
   name?: string;
@@ -600,15 +651,16 @@ export class AgentComposeClient {
       ? detectAmbientParentRunId()
       : opts.parentRunId;
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const headers: Record<string, string> = {};
+    if (opts?.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
     return this.fetch(templatePath(factorySlug, name, "invoke"), {
       method: "POST",
+      ...(opts?.idempotencyKey ? { headers } : {}),
       body: {
         input,
         ...(opts?.snapshots     !== undefined ? { snapshots:     opts.snapshots }     : {}),
         ...(opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {}),
         ...(opts?.placeholders  !== undefined ? { placeholders:  opts.placeholders }  : {}),
-        ...(opts?.memory        !== undefined ? { memory:        opts.memory }        : {}),
-        ...(opts?.postRunHooks     !== undefined ? { postRunHooks:     opts.postRunHooks }     : {}),
         ...(parentRunId                       ? { parentRunId }                       : {}),
         ...(opts?.agentId                     ? { agentId: opts.agentId }             : {}),
       },
@@ -895,6 +947,73 @@ export class AgentComposeClient {
     return body.events;
   }
 
+  /** Files the run wrote on the factory drive — run-attributed revisions,
+   *  latest write per path, paths the run later deleted excluded. */
+  async listRunArtifacts(runId: string): Promise<RunArtifactRow[]> {
+    const body = await this.fetch<{ artifacts: RunArtifactWire[] }>(
+      `/api/v1/workflows/${encodeURIComponent(runId)}/artifacts`,
+    );
+    return body.artifacts.map((a) => ({
+      path:        a.path,
+      factorySlug: a.factory_slug,
+      sizeBytes:   a.size_bytes,
+      lastWriteAt: a.last_write_at,
+      preview:     a.preview,
+    }));
+  }
+
+  // ── Factory files ──────────────────────────────────────────────────────────
+  // The factory drive: documents surfaced in the dashboard's Files tab.
+  // Writes from inside a sandbox automatically carry the run-callback token
+  // (AGENT_COMPOSE_RUN_TOKEN), so the revision is attributed to the run —
+  // that's what surfaces the doc in the Workbench docs section and the
+  // editor-avatar run hover.
+
+  /** Write (create or overwrite) one file on a factory's drive. */
+  async putFactoryFile(
+    path: string,
+    content: string | Uint8Array,
+    opts?: { factorySlug?: string; contentType?: string },
+  ): Promise<FactoryFileWriteResult> {
+    const factorySlug = opts?.factorySlug
+      ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
+      ?? DEFAULT_FACTORY;
+    const runToken = typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_RUN_TOKEN : undefined;
+    const wire = await this.fetch<FactoryFileWriteWire>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?path=${encodeURIComponent(path)}`,
+      {
+        method: "PUT",
+        body: content,
+        headers: {
+          "content-type": opts?.contentType ?? "text/plain; charset=utf-8",
+          ...(runToken ? { "x-run-token": runToken } : {}),
+        },
+      },
+    );
+    return {
+      path:        wire.path,
+      contentHash: wire.content_hash,
+      sizeBytes:   wire.size_bytes,
+      created:     wire.created,
+    };
+  }
+
+  /** Read one file's current content (or a specific revision) as text. */
+  async getFactoryFile(
+    path: string,
+    opts?: { factorySlug?: string; revision?: number },
+  ): Promise<string> {
+    const factorySlug = opts?.factorySlug
+      ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
+      ?? DEFAULT_FACTORY;
+    const q = new URLSearchParams({ path });
+    if (opts?.revision !== undefined) q.set("revision", String(opts.revision));
+    return this.fetch(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?${q}`,
+      { responseType: "text" },
+    );
+  }
+
   /** List events ingested into a factory, newest first. Supports
    *  case-insensitive substring filter (`name`) and timestamp-cursor
    *  pagination (`before`). Returns `{ events, has_more }` — the

package/src/index.ts

@@ -38,10 +38,11 @@ export type {
   WorkflowHooks,
   SnapshotConfig,
   BootSnapshot,
+  ReuseSnapshot,
   IOSchema,
   OutputSchema,
-  WorkflowMemoryConfig,
 } from "./types/workflow.js";
+export type { ConnectorRequestRules } from "./types/workflow-metadata.js";
 
 // Snapshot entry type re-exported for consumers (dashboard, CLI).
 export type { RunSnapshotEntry } from "./client.js";
@@ -105,7 +106,7 @@ export type {
 // HTTP client
 export { AgentComposeClient } from "./client.js";
 export type {
-  RegisterResult, RegisterWorkflowInput, RuntimeSourceInput,
+  RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, TemplateSourceRef,
   InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult,
   ListSnapshotsOptions, TemplateRow, ListTemplatesOptions,
   CreateFactoryInput, UpdateFactoryInput,
@@ -180,6 +181,7 @@ export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById,
   getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot,
   makeSandboxProvider, makeDesktopSandboxProvider,
   parseSseExecStream, AGENT_COMPOSE_TAG } from "./sandbox.js";
+export { SandboxUnavailableError, SANDBOX_UNAVAILABLE_PREFIX } from "./sandbox-errors.js";
 export type {
   SandboxCreateOpts, SandboxNetworkPolicy, SandboxNetworkHeaderTransform,
   SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxProviderName,

package/src/runtimes/_cli-agent.ts

@@ -12,14 +12,16 @@
  * AsyncQueue bridge → init/usage/done/error lifecycle), parameterised per-CLI
  * by a `CliAgentSpec`.
  *
- * Requirements (per spec): the provider CLI is installed in the sandbox image,
- * and the provider's API key is present in the sandbox environment (see each
- * spec's `authEnv`). `commands.run` inherits the sandbox env, so secrets set via
- * `agentc secrets set` are visible to the CLI.
- *
- * NOTE: the per-CLI command construction + resume flags + exact event shapes in
- * the shipped specs are mapped from each tool's docs and have NOT been verified
- * against a live CLI run — verify before relying on them in production.
+ * Provisioning (per spec): the runtime installs the provider CLI on demand —
+ * `command -v <bin>` before the first turn, falling back to the spec's
+ * `install` command when it's absent — so it works on a bare sandbox with no
+ * manual setup or hardcoded snapshot id. Pair it with
+ * `snapshots: { bootFrom: "reuse" }` on the workflow and the install happens
+ * exactly once: the first run installs the CLI and captures a snapshot, and
+ * every run after boots from that snapshot with the CLI already present (the
+ * probe short-circuits). The provider's API key must be in the sandbox env
+ * (see each spec's `authEnv`); `commands.run` inherits the sandbox env, so
+ * values set via `agentc secrets set` are visible to the CLI.
  */
 
 import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider } from "../index.js";
@@ -44,6 +46,15 @@ export interface CliAgentSpec {
   authEnv: string;
   /** Default model id when none is configured; omit to let the CLI choose. */
   defaultModel?: string;
+  /** Binary the runtime spawns (`codex`, `amp`). Probed with `command -v`
+   *  before the first turn; if absent, `install` provisions it. */
+  bin: string;
+  /** Shell command that installs `bin` when it's missing from the sandbox.
+   *  Runs at most once per runner, and only when the probe fails — so booting
+   *  from a snapshot that already has the CLI (the steady state under
+   *  `snapshots: { bootFrom: "reuse" }`) skips it. Must leave `bin` resolvable
+   *  on a non-login shell's PATH (the runtime spawns via `sh -c`). */
+  install: string;
   /** Serialise the user prompt into the bytes written to the prompt file —
    *  plain text for a CLI that reads the prompt from stdin (codex `-`), or a
    *  JSONL user message for a `--stream-json-input` CLI (amp). */
@@ -76,6 +87,23 @@ export class CliAgentRunner implements ModelExecutionContract {
     return this.configModel ?? this.options.model ?? this.spec.defaultModel;
   }
 
+  private installed = false;
+
+  /** Provision the CLI on demand. A no-op once `bin` is on PATH — the steady
+   *  state under `snapshots: { bootFrom: "reuse" }`, where the first run's
+   *  install is baked into the snapshot every later run boots from. So the
+   *  install command runs exactly once: on the first run of a content hash. */
+  private async ensureInstalled(): Promise<void> {
+    if (this.installed) return;
+    const probe = await this.sandbox.commands.run(`command -v ${this.spec.bin}`);
+    if (probe.exitCode === 0) { this.installed = true; return; }
+    const res = await this.sandbox.commands.run(this.spec.install, { timeoutMs: 300_000 });
+    if (res.exitCode !== 0) {
+      throw new Error(`failed to install ${this.spec.bin}: ${(res.stderr || res.stdout || "").slice(-500)}`);
+    }
+    this.installed = true;
+  }
+
   // No captureCheckpoint/restoreCheckpoint: the CLI persists its thread/rollout
   // on the sandbox filesystem (which round-trips through the pause snapshot),
   // and the loop already carries the session id we emit on init/done and pass
@@ -87,45 +115,50 @@ export class CliAgentRunner implements ModelExecutionContract {
     iteration?: number;
     signal?: AbortSignal;
   }): AsyncGenerator<AgentMessage> {
-    const promptPath = `/tmp/ac-${this.spec.kind}-${this.options.agentId ?? "agent"}-${opts.iteration ?? 0}.in`;
-    await this.sandbox.files.write(promptPath, this.spec.promptPayload(opts.prompt));
-    const cmd = this.spec.buildCommand({
-      promptPath,
-      sessionId: opts.sessionId,
-      model: this.model,
-      cwd: this.options.cwd,
-    });
-
-    // Bridge the streaming stdout callback into an async-iterable of complete
-    // JSONL lines. `onStdout` chunks aren't line-aligned, so buffer + split.
-    const lines = new AsyncQueue<string>();
-    let buf = "";
-    const onStdout = (data: string) => {
-      buf += data;
-      let nl: number;
-      while ((nl = buf.indexOf("\n")) >= 0) {
-        const line = buf.slice(0, nl).trim();
-        buf = buf.slice(nl + 1);
-        if (line) lines.push(line);
-      }
-    };
-
-    // `commands.run` resolves when the process exits. Kick it off (don't await
-    // yet); flush the trailing buffer + close the queue on completion so the
-    // for-await below drains and we can read the exit code.
-    const runPromise = this.sandbox.commands.run(cmd, {
-      ...(this.options.cwd ? { cwd: this.options.cwd } : {}),
-      onStdout,
-    }).then(
-      (res) => { const tail = buf.trim(); if (tail) lines.push(tail); lines.close(); return res; },
-      (err) => { lines.close(); throw err; },
-    );
-
     yield { type: "init", sessionId: opts.sessionId ?? "", timestamp: now() };
 
     let sessionId = opts.sessionId;
     let sawError = false;
     try {
+      // Provision the CLI before the first turn (no-op when it's already
+      // present, e.g. booting from a "reuse" snapshot). A failure here surfaces
+      // as an `error` AgentMessage via the catch below.
+      await this.ensureInstalled();
+
+      const promptPath = `/tmp/ac-${this.spec.kind}-${this.options.agentId ?? "agent"}-${opts.iteration ?? 0}.in`;
+      await this.sandbox.files.write(promptPath, this.spec.promptPayload(opts.prompt));
+      const cmd = this.spec.buildCommand({
+        promptPath,
+        sessionId: opts.sessionId,
+        model: this.model,
+        cwd: this.options.cwd,
+      });
+
+      // Bridge the streaming stdout callback into an async-iterable of complete
+      // JSONL lines. `onStdout` chunks aren't line-aligned, so buffer + split.
+      const lines = new AsyncQueue<string>();
+      let buf = "";
+      const onStdout = (data: string) => {
+        buf += data;
+        let nl: number;
+        while ((nl = buf.indexOf("\n")) >= 0) {
+          const line = buf.slice(0, nl).trim();
+          buf = buf.slice(nl + 1);
+          if (line) lines.push(line);
+        }
+      };
+
+      // `commands.run` resolves when the process exits. Kick it off (don't await
+      // yet); flush the trailing buffer + close the queue on completion so the
+      // for-await below drains and we can read the exit code.
+      const runPromise = this.sandbox.commands.run(cmd, {
+        ...(this.options.cwd ? { cwd: this.options.cwd } : {}),
+        onStdout,
+      }).then(
+        (res) => { const tail = buf.trim(); if (tail) lines.push(tail); lines.close(); return res; },
+        (err) => { lines.close(); throw err; },
+      );
+
       for await (const line of lines) {
         let parsed: Record<string, unknown>;
         try {

package/src/runtimes/amp.ts

@@ -5,13 +5,14 @@
  * own loop + tools, so we only stream-parse what it prints.
  *
  * Auth: set `AMP_API_KEY` (`sgamp_…`) in the sandbox env via a workflow secret.
- * Requires the `amp` CLI (`@ampcode/cli`) installed in the sandbox image. The
- * model is chosen by the AMP_API_KEY account (e.g. a GPT-only token runs GPT);
- * the runtime doesn't pin a model.
+ * The runtime installs the `amp` CLI (`@ampcode/cli`) on demand — no image
+ * baking needed; pair with `snapshots: { bootFrom: "reuse" }` to install once
+ * and boot from the captured snapshot on every run after. The model is chosen
+ * by the AMP_API_KEY account (e.g. a GPT-only token runs GPT); the runtime
+ * doesn't pin a model.
  *
- * ⚠️ NOT verified against a live `amp` run — the thread-continue syntax and the
- * exact assistant/result shapes are mapped from the docs (ampcode.com). Verify
- * before production use.
+ * Verified against a live `amp -x --stream-json` run: the user-message stdin
+ * shape, assistant content blocks, and result usage below all round-trip.
  */
 
 import type { AgentMessage } from "../index.js";
@@ -32,6 +33,10 @@ function blocks(msg: Record<string, unknown>): Array<Record<string, unknown>> {
 const ampSpec: CliAgentSpec = {
   kind: "amp",
   authEnv: "AMP_API_KEY",
+  bin: "amp",
+  // Global npm install; symlink onto PATH only if the global bin dir isn't
+  // already there (so a non-login `sh -c` can find it).
+  install: 'sudo npm install -g @ampcode/cli && (command -v amp >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/amp" /usr/local/bin/amp)',
   // `--stream-json-input` reads JSON Lines user messages from stdin; write one.
   // amp's --stream-json-input wants Claude-shaped content blocks, not a bare
   // string (it rejects a string `content` with "expected array, received string").