@agent-compose/sdk 0.5.2 → 0.5.6

package/src/runtimes/_cli-agent.ts

@@ -0,0 +1,194 @@
+/**
+ * CLI-agent runtime base — drive an external agentic coding CLI inside the
+ * sandbox and map its JSON-Lines (JSONL) stream onto the `AgentMessage`
+ * contract.
+ *
+ * This is a different *mechanism* from the other runtimes: `claudeRuntime`
+ * drives the Anthropic Agent SDK and `vercelRuntime` drives the Vercel AI SDK,
+ * but a CLI-agent runtime spawns the provider's own CLI (`codex exec --json`,
+ * `amp -x --stream-json`) — the CLI brings its own agent loop + tools, and we
+ * only stream-parse the events it prints. Codex and Amp are the first two; this
+ * base is the shared machinery (spawn → line-buffer stdout → JSONL parse →
+ * AsyncQueue bridge → init/usage/done/error lifecycle), parameterised per-CLI
+ * by a `CliAgentSpec`.
+ *
+ * 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";
+import { defineRuntime } from "../types/runtime.js";
+import { AsyncQueue } from "../agent/async-queue.js";
+import { formatError } from "../utils/errors.js";
+
+function now(): string { return new Date().toISOString(); }
+
+/** Single-quote a value for safe interpolation into a `sh -c` command line. */
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/** 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 {
+  /** Runtime self-id surfaced on `agent.spawned` (dashboard runtime icon). */
+  kind: string;
+  /** Env var the CLI reads for auth — documentation only (must be set in the
+   *  sandbox env via a workflow secret). */
+  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). */
+  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. */
+  buildCommand(args: { promptPath: string; sessionId?: string; model?: string; cwd?: string }): string;
+  /** Map one parsed JSONL stdout event to `AgentMessage`s. The base emits
+   *  `init`/`done`/`error` lifecycle itself, so a spec maps only content +
+   *  usage (text / thinking / tool_use / tool_result / usage). */
+  mapEvent(parsed: Record<string, unknown>): AgentMessage[];
+  /** Pull a session/thread id out of a parsed event so the next turn can
+   *  resume it (codex `thread.started.thread_id`, amp `session_id`). */
+  extractSessionId(parsed: Record<string, unknown>): string | undefined;
+}
+
+export class CliAgentRunner implements ModelExecutionContract {
+  readonly kind: string;
+
+  constructor(
+    private readonly sandbox: SandboxProvider,
+    private readonly options: RuntimeOptions,
+    private readonly spec: CliAgentSpec,
+    private readonly configModel?: string,
+  ) {
+    this.kind = spec.kind;
+  }
+
+  get model(): string | undefined {
+    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
+  // back as `sessionId` for resume — same model as claudeRuntime.
+
+  async *sendMessage(opts: {
+    prompt: string;
+    sessionId?: string;
+    iteration?: number;
+    signal?: AbortSignal;
+  }): AsyncGenerator<AgentMessage> {
+    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 {
+          parsed = JSON.parse(line) as Record<string, unknown>;
+        } catch {
+          continue; // skip any non-JSON noise that lands on stdout
+        }
+        const sid = this.spec.extractSessionId(parsed);
+        if (sid) sessionId = sid;
+        for (const msg of this.spec.mapEvent(parsed)) {
+          if (msg.type === "error") sawError = true;
+          yield msg;
+        }
+      }
+
+      const res = await runPromise;
+      if (res.exitCode !== 0 && !sawError) {
+        const tail = (res.stderr ?? "").slice(-2000);
+        yield { type: "error", text: `${this.spec.kind} exited with code ${res.exitCode}${tail ? `: ${tail}` : ""}`, timestamp: now() };
+        return;
+      }
+      if (!sawError) yield { type: "done", sessionId: sessionId ?? "", timestamp: now() };
+    } catch (err) {
+      yield { type: "error", text: formatError(err), timestamp: now() };
+    }
+  }
+}
+
+export function createCliAgentRuntime(spec: CliAgentSpec, configModel?: string) {
+  return defineRuntime({
+    create: (sandbox, opts) => new CliAgentRunner(sandbox, opts, spec, configModel),
+  });
+}

package/src/runtimes/amp.ts

@@ -0,0 +1,99 @@
+/**
+ * Amp CLI runtime — drives Sourcegraph's `amp -x --stream-json` agentic CLI
+ * inside the sandbox and maps its (Claude-Code-compatible) JSONL stream onto
+ * the AgentMessage contract. Built on the shared CLI-agent base; Amp brings its
+ * 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.
+ * 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.
+ *
+ * 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";
+import { createCliAgentRuntime, shellQuote, type CliAgentSpec } from "./_cli-agent.js";
+import { formatError } from "../utils/errors.js";
+
+function now(): string { return new Date().toISOString(); }
+
+/** Block array off either `{ message: { content } }` (Claude shape) or a
+ *  top-level `{ content }`, whichever the stream uses. */
+function blocks(msg: Record<string, unknown>): Array<Record<string, unknown>> {
+  const inner = (msg.message as { content?: unknown[] } | undefined)?.content
+    ?? (msg.content as unknown[] | undefined)
+    ?? [];
+  return inner as 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").
+  promptPayload: (prompt) =>
+    JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text: prompt }] } }) + "\n",
+  buildCommand: ({ promptPath, sessionId }) => {
+    // Continue the prior thread by id when we have one; else start fresh.
+    const cont = sessionId ? `threads continue ${shellQuote(sessionId)} ` : "";
+    return `amp ${cont}-x --stream-json --stream-json-input < ${shellQuote(promptPath)}`;
+  },
+  // Amp stamps `session_id` (a "T-…" thread id) on every message.
+  extractSessionId: (p) => (typeof p.session_id === "string" ? p.session_id : undefined),
+  mapEvent: (p): AgentMessage[] => {
+    const ts = now();
+    if (p.type === "assistant") {
+      return blocks(p).flatMap((b): AgentMessage[] => {
+        if (b.type === "text") return [{ type: "text", text: String(b.text ?? ""), timestamp: ts }];
+        if (b.type === "thinking") return [{ type: "thinking", text: String(b.thinking ?? ""), timestamp: ts }];
+        if (b.type === "tool_use") return [{ type: "tool_use", toolName: String(b.name ?? ""), toolInput: (b.input ?? {}) as Record<string, unknown>, toolUseId: String(b.id ?? ""), timestamp: ts }];
+        return [];
+      });
+    }
+    if (p.type === "user") {
+      return blocks(p).flatMap((b): AgentMessage[] =>
+        b.type === "tool_result"
+          ? [{ type: "tool_result", toolUseId: String(b.tool_use_id ?? ""), output: typeof b.content === "string" ? b.content : JSON.stringify(b.content ?? ""), isError: Boolean(b.is_error), timestamp: ts }]
+          : []);
+    }
+    if (p.type === "result") {
+      const out: AgentMessage[] = [];
+      const u = p.usage as Record<string, number> | undefined;
+      if (u) out.push({
+        type: "usage",
+        inputTokens: u.input_tokens ?? 0,
+        outputTokens: u.output_tokens ?? 0,
+        cacheReadTokens: u.cache_read_input_tokens ?? 0,
+        cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
+        durationMs: Number(p.duration_ms ?? 0),
+        numTurns: Number(p.num_turns ?? 0),
+        timestamp: ts,
+      });
+      if (p.is_error || p.subtype === "error") {
+        out.push({ type: "error", text: formatError(p.result ?? p.error), timestamp: ts });
+      }
+      return out;
+    }
+    return []; // "system" → session id captured by extractSessionId; init/done owned by the base
+  },
+};
+
+export interface AmpRuntimeConfig {
+  /** Amp uses its configured model; reserved for forward-compatibility. */
+  model?: string;
+}
+
+export function createAmpRuntime(config: AmpRuntimeConfig = {}) {
+  return createCliAgentRuntime(ampSpec, config.model);
+}
+
+export default createAmpRuntime();

package/src/runtimes/codex.ts

@@ -0,0 +1,114 @@
+/**
+ * Codex CLI runtime — drives OpenAI's `codex exec --json` agentic CLI inside
+ * the sandbox and maps its JSONL event stream onto the AgentMessage contract.
+ * Built on the shared CLI-agent base; Codex brings its own loop + tools, so we
+ * only stream-parse what it prints.
+ *
+ * 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.
+ *
+ * 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";
+import { createCliAgentRuntime, shellQuote, type CliAgentSpec } from "./_cli-agent.js";
+import { formatError } from "../utils/errors.js";
+
+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 }) => {
+    const flags = [
+      "--json",
+      "--skip-git-repo-check",
+      // agent-compose already runs us inside an isolated sandbox VM, so codex
+      // must not try to nest its own seccomp/landlock sandbox or block on
+      // approvals (non-interactive). codex docs: this flag is "intended solely
+      // for running in environments that are externally sandboxed".
+      "--dangerously-bypass-approvals-and-sandbox",
+      ...(model ? ["-m", shellQuote(model)] : []),
+      ...(cwd ? ["-C", shellQuote(cwd)] : []),
+    ].join(" ");
+    // Fresh turn: `codex exec <flags> - < prompt`. Continue a thread:
+    // `codex exec resume <id> <flags> - < prompt`. (`-` = read prompt from stdin.)
+    const exec = sessionId
+      ? `codex exec resume ${shellQuote(sessionId)} ${flags}`
+      : `codex exec ${flags}`;
+    return `${exec} - < ${shellQuote(promptPath)}`;
+  },
+  extractSessionId: (p) =>
+    p.type === "thread.started" && typeof p.thread_id === "string" ? p.thread_id : undefined,
+  mapEvent: (p): AgentMessage[] => {
+    const ts = now();
+    switch (p.type) {
+      case "item.started":
+      case "item.completed": {
+        const item = p.item as Record<string, unknown> | undefined;
+        if (!item) return [];
+        const itype = String(item.type ?? "");
+        // Text + reasoning land on completion (started carries no final text).
+        if (itype === "agent_message") {
+          return p.type === "item.completed" ? [{ type: "text", text: String(item.text ?? ""), timestamp: ts }] : [];
+        }
+        if (itype === "reasoning") {
+          return p.type === "item.completed" ? [{ type: "thinking", text: String(item.text ?? ""), timestamp: ts }] : [];
+        }
+        // Command execution: started → tool_use, completed → tool_result.
+        if (itype === "command_execution") {
+          const id = String(item.id ?? "");
+          if (p.type === "item.started") {
+            return [{ type: "tool_use", toolName: "shell", toolInput: { command: String(item.command ?? "") }, toolUseId: id, timestamp: ts }];
+          }
+          const failed = item.status === "failed" || (typeof item.exit_code === "number" && item.exit_code !== 0);
+          return [{ type: "tool_result", toolUseId: id, output: String(item.aggregated_output ?? item.output ?? ""), isError: failed, timestamp: ts }];
+        }
+        // file_change / mcp_tool_call / web_search / todo: surface once, on completion.
+        if (p.type === "item.completed") {
+          return [{ type: "tool_use", toolName: itype || "item", toolInput: item, toolUseId: String(item.id ?? ""), timestamp: ts }];
+        }
+        return [];
+      }
+      case "turn.completed": {
+        const u = p.usage as Record<string, number> | undefined;
+        if (!u) return [];
+        return [{
+          type: "usage",
+          inputTokens: u.input_tokens ?? 0,
+          outputTokens: u.output_tokens ?? 0,
+          cacheReadTokens: u.cached_input_tokens ?? 0,
+          cacheCreationTokens: 0,
+          durationMs: 0,
+          numTurns: 1,
+          timestamp: ts,
+        }];
+      }
+      case "turn.failed":
+      case "error":
+        return [{ type: "error", text: formatError(p.error ?? p.message ?? p), timestamp: ts }];
+      default:
+        return [];
+    }
+  },
+};
+
+export interface CodexRuntimeConfig {
+  /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */
+  model?: string;
+}
+
+export function createCodexRuntime(config: CodexRuntimeConfig = {}) {
+  return createCliAgentRuntime(codexSpec, config.model);
+}
+
+export default createCodexRuntime();

package/src/runtimes/vercel.ts

@@ -3,7 +3,7 @@
  * owned coding tools over SandboxProvider.
  */
 
-import { streamText, stepCountIs, tool, type LanguageModel } from "ai";
+import { streamText, stepCountIs, tool, gateway, type LanguageModel } from "ai";
 import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider, ToolCallGateResult } from "../index.js";
 import { defineRuntime } from "../types/runtime.js";
 import { codingTools, type CodingTool } from "../tools/index.js";
@@ -15,12 +15,27 @@ import { formatError } from "../utils/errors.js";
 type AiToolSet = Record<string, ReturnType<typeof tool<Record<string, unknown>, string>>>;
 
 export interface VercelRuntimeConfig {
-  /** Vercel AI SDK language model (e.g. openai("gpt-5"), anthropic("claude-sonnet-4-5")). */
+  /** The model to drive — this is the only thing that varies per provider;
+   *  there is no per-provider runtime. `LanguageModel` accepts every provider:
+   *   - a gateway model-id string routed via the Vercel AI Gateway (set
+   *     `AI_GATEWAY_API_KEY`; no provider package needed), e.g. "openai/gpt-5",
+   *     "google/gemini-2.5-pro", "xai/grok-4", "deepseek/deepseek-chat",
+   *     "mistral/mistral-large-latest", "anthropic/claude-sonnet-4-5";
+   *   - or a `LanguageModel` object from a provider package (add the dep + set
+   *     its API-key env), e.g. `openai("gpt-5")`, `google("gemini-2.5-pro")`. */
   model: LanguageModel;
   /** Optional system prompt prepended to every model call. */
   system?: string;
   /** Override/extend the default coding tools. Defaults: Read, Write, Edit, Bash. */
   tools?: readonly CodingTool[];
+  /** Short runtime self-id surfaced on `agent.spawned` so the dashboard can
+   *  show a per-agent runtime icon (e.g. "openai", "gemini"). Provider presets
+   *  set this; bare `createVercelRuntime` callers can leave it unset. */
+  kind?: string;
+  /** Display model id surfaced on `agent.spawned` (the Agent tab labels which
+   *  model each agent ran). `model` above is the AI SDK LanguageModel object;
+   *  this is its human-readable id string. */
+  modelId?: string;
 }
 
 function now(): string { return new Date().toISOString(); }
@@ -71,6 +86,11 @@ function toAgentMessages(part: Record<string, unknown>): AgentMessage[] {
 
 export class VercelRunner implements ModelExecutionContract {
   supportsToolCallProcessor = true;
+  /** Surfaced on `agent.spawned` for the dashboard's per-agent runtime icon +
+   *  model label. Set from the (provider preset's) config; undefined for a
+   *  bare `createVercelRuntime` that didn't label itself. */
+  readonly kind?: string;
+  readonly model?: string;
   private readonly tools: readonly CodingTool[];
   private readonly messages: unknown[] = [];
 
@@ -80,6 +100,8 @@ export class VercelRunner implements ModelExecutionContract {
     private readonly config: VercelRuntimeConfig,
   ) {
     this.tools = config.tools ?? codingTools;
+    this.kind = config.kind;
+    this.model = config.modelId;
   }
 
   async gateToolCall(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult> {
@@ -204,3 +226,31 @@ export function createVercelRuntime(config: VercelRuntimeConfig) {
     create: (sandbox, opts) => new VercelRunner(sandbox, opts, config),
   });
 }
+
+/** One model offered by the Vercel AI Gateway. Pass `id` straight to
+ *  `createVercelRuntime({ model: id })`. */
+export interface VercelRuntimeModel {
+  /** Gateway model id, e.g. "openai/gpt-5". Usable directly as the runtime model. */
+  id: string;
+  /** Human-readable display name. */
+  name: string;
+}
+
+/**
+ * List the models the Vercel runtime accepts as a gateway model-id string — the
+ * LIVE Vercel AI Gateway catalog, so it never goes stale. This is the canonical
+ * answer to "what models can I pass to `createVercelRuntime`?" for the string
+ * form (`createVercelRuntime({ model: "openai/gpt-5" })`).
+ *
+ * Requires `AI_GATEWAY_API_KEY`. The other form — a `LanguageModel` object from
+ * an `@ai-sdk/<provider>` package — supports whatever that provider package
+ * does (see its docs); there's no single cross-form list because the runtime is
+ * model-agnostic. Browse the catalog in a UI at https://vercel.com/ai-gateway/models.
+ */
+export async function listVercelRuntimeModels(): Promise<VercelRuntimeModel[]> {
+  const { models } = await gateway.getAvailableModels();
+  return models
+    .filter((m) => m.modelType == null || m.modelType === "language")
+    .map((m) => ({ id: m.id, name: m.name }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}

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. */