@agent-compose/sdk 0.5.5 → 0.5.6

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export type { WorkflowDefinition } from "./types/workflow.js";
 export { defineSandboxEnvironment } from "./types/sandbox-environment.js";
 export type { SandboxEnvironmentDefinition } from "./types/sandbox-environment.js";
 export type { AgentRuntime, McpServerConfig, ModelExecutionContract, ToolCallGateResult, RuntimeOptions, } from "./types/runtime.js";
-export type { WorkflowFn, WorkflowCtx, WorkflowRun, AgentBudget, WorkflowHooks, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema, WorkflowMemoryConfig, } from "./types/workflow.js";
+export type { WorkflowFn, WorkflowCtx, WorkflowRun, AgentBudget, WorkflowHooks, SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, WorkflowMemoryConfig, } from "./types/workflow.js";
 export type { RunSnapshotEntry } from "./client.js";
 export type { WorkflowPlan, WorkflowStepPlan } from "./types/workflow-plan.js";
 export type { BaseExecutionContext, InvokeChild } from "./types/execution-context.js";

package/dist/index.js

@@ -2400,45 +2400,61 @@ class CliAgentRunner {
   get model() {
     return this.configModel ?? this.options.model ?? this.spec.defaultModel;
   }
+  installed = false;
+  async ensureInstalled() {
+    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: 300000 });
+    if (res.exitCode !== 0) {
+      throw new Error(`failed to install ${this.spec.bin}: ${(res.stderr || res.stdout || "").slice(-500)}`);
+    }
+    this.installed = true;
+  }
   async* sendMessage(opts) {
-    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
-    });
-    const lines = new AsyncQueue;
-    let buf = "";
-    const onStdout = (data) => {
-      buf += data;
-      let nl;
-      while ((nl = buf.indexOf(`
-`)) >= 0) {
-        const line = buf.slice(0, nl).trim();
-        buf = buf.slice(nl + 1);
-        if (line)
-          lines.push(line);
-      }
-    };
-    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: now3() };
     let sessionId = opts.sessionId;
     let sawError = false;
     try {
+      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
+      });
+      const lines = new AsyncQueue;
+      let buf = "";
+      const onStdout = (data) => {
+        buf += data;
+        let nl;
+        while ((nl = buf.indexOf(`
+`)) >= 0) {
+          const line = buf.slice(0, nl).trim();
+          buf = buf.slice(nl + 1);
+          if (line)
+            lines.push(line);
+        }
+      };
+      const runPromise = this.sandbox.commands.run(cmd, {
+        ...this.options.cwd ? { cwd: this.options.cwd } : {},
+        onStdout
+      }).then((res2) => {
+        const tail = buf.trim();
+        if (tail)
+          lines.push(tail);
+        lines.close();
+        return res2;
+      }, (err) => {
+        lines.close();
+        throw err;
+      });
       for await (const line of lines) {
         let parsed;
         try {
@@ -2481,6 +2497,8 @@ function now4() {
 var codexSpec = {
   kind: "codex",
   authEnv: "CODEX_API_KEY",
+  bin: "codex",
+  install: 'sudo npm install -g @openai/codex && (command -v codex >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/codex" /usr/local/bin/codex)',
   promptPayload: (prompt) => prompt,
   buildCommand: ({ promptPath, sessionId, model, cwd }) => {
     const flags = [
@@ -2560,6 +2578,8 @@ function blocks(msg) {
 var ampSpec = {
   kind: "amp",
   authEnv: "AMP_API_KEY",
+  bin: "amp",
+  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)',
   promptPayload: (prompt) => JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text: prompt }] } }) + `
 `,
   buildCommand: ({ promptPath, sessionId }) => {

package/dist/runtimes/_cli-agent.d.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";
 /** Single-quote a value for safe interpolation into a `sh -c` command line. */
@@ -34,6 +36,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). */
@@ -62,6 +73,12 @@ export declare class CliAgentRunner implements ModelExecutionContract {
     readonly kind: string;
     constructor(sandbox: SandboxProvider, options: RuntimeOptions, spec: CliAgentSpec, configModel?: string | undefined);
     get model(): string | undefined;
+    private installed;
+    /** 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 ensureInstalled;
     sendMessage(opts: {
         prompt: string;
         sessionId?: string;

package/dist/runtimes/amp.d.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.
  */
 export interface AmpRuntimeConfig {
     /** Amp uses its configured model; reserved for forward-compatibility. */

package/dist/runtimes/cli-agent.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CliAgentRunner self-provisioning — the runtime installs its CLI on demand
+ * (`command -v <bin>` → install if missing), runs the install at most once per
+ * runner, and surfaces an install failure as an `error` message rather than
+ * blowing up. This is what lets `createCodexRuntime()` work on a bare sandbox
+ * with no image baking, and lets `snapshots: { bootFrom: "reuse" }` collapse
+ * the install to a one-time cost.
+ */
+export {};

package/dist/runtimes/codex.d.ts

@@ -4,12 +4,13 @@
  * Built on the shared CLI-agent base; Codex brings its own loop + tools, so we
  * only stream-parse what it prints.
  *
- * Auth: set `CODEX_API_KEY` (or `OPENAI_API_KEY`) in the sandbox env via a
- * workflow secret. Requires the `codex` CLI installed in the sandbox image.
+ * Auth: set `OPENAI_API_KEY` (or `CODEX_API_KEY`) in the sandbox env via a
+ * workflow secret. The runtime installs the `codex` CLI (`@openai/codex`) on
+ * demand — no image baking needed; pair with `snapshots: { bootFrom: "reuse" }`
+ * to install once and boot from the captured snapshot on every run after.
  *
- * ⚠️ NOT verified against a live `codex` run — the resume flag and the exact
- * item shapes (command_execution / reasoning fields) are mapped from the docs
- * (developers.openai.com/codex/noninteractive). Verify before production use.
+ * Verified against codex-cli 0.124.0: `codex exec --json` + resume-by-thread,
+ * with the command_execution / reasoning / agent_message item shapes below.
  */
 export interface CodexRuntimeConfig {
     /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */

package/dist/runtimes/openai-desktop.js

@@ -2400,45 +2400,61 @@ class CliAgentRunner {
   get model() {
     return this.configModel ?? this.options.model ?? this.spec.defaultModel;
   }
+  installed = false;
+  async ensureInstalled() {
+    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: 300000 });
+    if (res.exitCode !== 0) {
+      throw new Error(`failed to install ${this.spec.bin}: ${(res.stderr || res.stdout || "").slice(-500)}`);
+    }
+    this.installed = true;
+  }
   async* sendMessage(opts) {
-    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
-    });
-    const lines = new AsyncQueue;
-    let buf = "";
-    const onStdout = (data) => {
-      buf += data;
-      let nl;
-      while ((nl = buf.indexOf(`
-`)) >= 0) {
-        const line = buf.slice(0, nl).trim();
-        buf = buf.slice(nl + 1);
-        if (line)
-          lines.push(line);
-      }
-    };
-    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: now3() };
     let sessionId = opts.sessionId;
     let sawError = false;
     try {
+      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
+      });
+      const lines = new AsyncQueue;
+      let buf = "";
+      const onStdout = (data) => {
+        buf += data;
+        let nl;
+        while ((nl = buf.indexOf(`
+`)) >= 0) {
+          const line = buf.slice(0, nl).trim();
+          buf = buf.slice(nl + 1);
+          if (line)
+            lines.push(line);
+        }
+      };
+      const runPromise = this.sandbox.commands.run(cmd, {
+        ...this.options.cwd ? { cwd: this.options.cwd } : {},
+        onStdout
+      }).then((res2) => {
+        const tail = buf.trim();
+        if (tail)
+          lines.push(tail);
+        lines.close();
+        return res2;
+      }, (err) => {
+        lines.close();
+        throw err;
+      });
       for await (const line of lines) {
         let parsed;
         try {
@@ -2481,6 +2497,8 @@ function now4() {
 var codexSpec = {
   kind: "codex",
   authEnv: "CODEX_API_KEY",
+  bin: "codex",
+  install: 'sudo npm install -g @openai/codex && (command -v codex >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/codex" /usr/local/bin/codex)',
   promptPayload: (prompt) => prompt,
   buildCommand: ({ promptPath, sessionId, model, cwd }) => {
     const flags = [
@@ -2560,6 +2578,8 @@ function blocks(msg) {
 var ampSpec = {
   kind: "amp",
   authEnv: "AMP_API_KEY",
+  bin: "amp",
+  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)',
   promptPayload: (prompt) => JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text: prompt }] } }) + `
 `,
   buildCommand: ({ promptPath, sessionId }) => {

package/dist/types/workflow-metadata.d.ts

@@ -22,24 +22,32 @@ import type { Processor } from "../processors/processor.js";
  *  workflow completes. Boolean toggle — custom post-run workflows live
  *  in the separate `postRunHooks` array on `WorkflowMetadata`. */
 export type WorkflowMemoryConfig = boolean;
-/** Where a run boots from. The snapshot id is the unit of identity —
- *  each captured snapshot already records the workflow + version it
- *  came from on the snapshot row, so there's no separate "latest of
- *  workflow X" resolution at dispatch time. Operators pick a snapshot
- *  from the dashboard snapshot list (or `agentc snapshot list`) and
- *  paste the id here.
- *
- *  Omit `bootFrom` entirely to boot a fresh base sandbox. */
+/** Boot from a specific captured snapshot, addressed by its id. Operators
+ *  pick one from the dashboard snapshot list (or `agentc snapshot list`) and
+ *  paste the id here. */
 export type BootSnapshot = {
     snapshotId: string;
 };
+/** Boot from this workflow's OWN most recent snapshot, scoped to its content
+ *  hash. The first run — and the first after a re-register changes the source
+ *  — finds none and boots a fresh base sandbox; `"reuse"` also implies
+ *  `saveLatest`, so that run captures a snapshot and every run after it boots
+ *  from it. This lets a runtime install its tooling once (e.g. a CLI-agent
+ *  runtime `npm i -g`'ing its CLI) and skip the install on every later run,
+ *  with no hardcoded snapshot id to manage. Re-registering with changed
+ *  source rolls the content hash, which transparently invalidates the cache
+ *  and re-installs on the next run. */
+export type ReuseSnapshot = "reuse";
 /** Snapshot configuration — boot source plus capture knobs. One object
  *  per workflow / per invocation; collapsing boot + capture under a
  *  single key reads as "all snapshot config lives here." */
 export interface SnapshotConfig {
-    /** Where the runner restores from at run start. Structured (workflow
-     *  ref or snapshot id) so the intent is explicit at the call site. */
-    bootFrom?: BootSnapshot;
+    /** Where the runner restores from at run start:
+     *  - `{ snapshotId }` — a specific captured snapshot.
+     *  - `"reuse"` — this workflow's own latest snapshot (content-hash scoped);
+     *    fresh on the first run / after a re-register. Implies `saveLatest`.
+     *  - omitted — a fresh base sandbox. */
+    bootFrom?: BootSnapshot | ReuseSnapshot;
     /** Capture the sandbox state on terminal success. The latest pointer
      *  on `workflow_runs.vercel_snapshot_id` always tracks the most
      *  recent capture; without `retainSteps`, prior captures are deleted

package/dist/types/workflow.d.ts

@@ -26,8 +26,8 @@ export type { WorkflowMetadata } from "./workflow-metadata.js";
 export interface AgentEventSink {
     emit(event: AgentLifecycleEvent): void | Promise<void>;
 }
-import type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema } from "./workflow-metadata.js";
-export type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema };
+import type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema } from "./workflow-metadata.js";
+export type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema };
 /** Turn/iteration budget for `agent(opts)`. Re-exported here so authors
  *  can type per-invoke budget overrides they pass as workflow input. */
 export interface AgentBudget {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -38,6 +38,7 @@ export type {
   WorkflowHooks,
   SnapshotConfig,
   BootSnapshot,
+  ReuseSnapshot,
   IOSchema,
   OutputSchema,
   WorkflowMemoryConfig,

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").

package/src/runtimes/codex.ts

@@ -4,12 +4,13 @@
  * Built on the shared CLI-agent base; Codex brings its own loop + tools, so we
  * only stream-parse what it prints.
  *
- * Auth: set `CODEX_API_KEY` (or `OPENAI_API_KEY`) in the sandbox env via a
- * workflow secret. Requires the `codex` CLI installed in the sandbox image.
+ * Auth: set `OPENAI_API_KEY` (or `CODEX_API_KEY`) in the sandbox env via a
+ * workflow secret. The runtime installs the `codex` CLI (`@openai/codex`) on
+ * demand — no image baking needed; pair with `snapshots: { bootFrom: "reuse" }`
+ * to install once and boot from the captured snapshot on every run after.
  *
- * ⚠️ NOT verified against a live `codex` run — the resume flag and the exact
- * item shapes (command_execution / reasoning fields) are mapped from the docs
- * (developers.openai.com/codex/noninteractive). Verify before production use.
+ * 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 { AgentMessage } from "../index.js";
@@ -21,6 +22,10 @@ function now(): string { return new Date().toISOString(); }
 const codexSpec: CliAgentSpec = {
   kind: "codex",
   authEnv: "CODEX_API_KEY",
+  bin: "codex",
+  // 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 @openai/codex && (command -v codex >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/codex" /usr/local/bin/codex)',
   // Codex reads the prompt from stdin when invoked as `codex exec ... -`.
   promptPayload: (prompt) => prompt,
   buildCommand: ({ promptPath, sessionId, model, cwd }) => {

package/src/types/workflow-metadata.ts

@@ -25,23 +25,32 @@ import type { Processor } from "../processors/processor.js";
  *  in the separate `postRunHooks` array on `WorkflowMetadata`. */
 export type WorkflowMemoryConfig = boolean;
 
-/** Where a run boots from. The snapshot id is the unit of identity —
- *  each captured snapshot already records the workflow + version it
- *  came from on the snapshot row, so there's no separate "latest of
- *  workflow X" resolution at dispatch time. Operators pick a snapshot
- *  from the dashboard snapshot list (or `agentc snapshot list`) and
- *  paste the id here.
- *
- *  Omit `bootFrom` entirely to boot a fresh base sandbox. */
+/** Boot from a specific captured snapshot, addressed by its id. Operators
+ *  pick one from the dashboard snapshot list (or `agentc snapshot list`) and
+ *  paste the id here. */
 export type BootSnapshot = { snapshotId: string };
 
+/** Boot from this workflow's OWN most recent snapshot, scoped to its content
+ *  hash. The first run — and the first after a re-register changes the source
+ *  — finds none and boots a fresh base sandbox; `"reuse"` also implies
+ *  `saveLatest`, so that run captures a snapshot and every run after it boots
+ *  from it. This lets a runtime install its tooling once (e.g. a CLI-agent
+ *  runtime `npm i -g`'ing its CLI) and skip the install on every later run,
+ *  with no hardcoded snapshot id to manage. Re-registering with changed
+ *  source rolls the content hash, which transparently invalidates the cache
+ *  and re-installs on the next run. */
+export type ReuseSnapshot = "reuse";
+
 /** Snapshot configuration — boot source plus capture knobs. One object
  *  per workflow / per invocation; collapsing boot + capture under a
  *  single key reads as "all snapshot config lives here." */
 export interface SnapshotConfig {
-  /** Where the runner restores from at run start. Structured (workflow
-   *  ref or snapshot id) so the intent is explicit at the call site. */
-  bootFrom?: BootSnapshot;
+  /** Where the runner restores from at run start:
+   *  - `{ snapshotId }` — a specific captured snapshot.
+   *  - `"reuse"` — this workflow's own latest snapshot (content-hash scoped);
+   *    fresh on the first run / after a re-register. Implies `saveLatest`.
+   *  - omitted — a fresh base sandbox. */
+  bootFrom?: BootSnapshot | ReuseSnapshot;
   /** Capture the sandbox state on terminal success. The latest pointer
    *  on `workflow_runs.vercel_snapshot_id` always tracks the most
    *  recent capture; without `retainSteps`, prior captures are deleted

package/src/types/workflow.ts

@@ -37,8 +37,8 @@ export interface AgentEventSink {
   emit(event: AgentLifecycleEvent): void | Promise<void>;
 }
 
-import type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema } from "./workflow-metadata.js";
-export type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema };
+import type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema } from "./workflow-metadata.js";
+export type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema };
 
 /** Turn/iteration budget for `agent(opts)`. Re-exported here so authors
  *  can type per-invoke budget overrides they pass as workflow input. */