@agent-compose/sdk 0.5.2 → 0.5.5

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, } from ".
 export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "./types/protocol.js";
 export type { SandboxProvider, DesktopSandboxProvider, } from "./types/sandbox.js";
 export { AgentComposeClient } from "./client.js";
-export type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, StreamRunLogsOptions, EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse, ApiKey, ApiKeyCreated, UsageRollupRow, UsageResponse, CancelRunResponse, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, AnswerSteerOptions, } from "./client.js";
+export type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, StreamRunLogsOptions, EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse, ApiKey, ApiKeyCreated, UsageRollupRow, UsageResponse, CancelRunResponse, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, AnswerSteerOptions, ResumePauseOptions, ResumePauseResponse, ResumePauseSuccess, ResumePausePending, ResumePauseActor, } from "./client.js";
 export { parseSseStream } from "./sse.js";
 export { AgentComposeError } from "./errors.js";
 export { formatError } from "./utils/errors.js";
@@ -37,8 +37,15 @@ export { AgentStatusSchema } from "./utils/schemas.js";
 export { createClaudeRuntime, ClaudeRunner } from "./runtimes/claude.js";
 export type { ClaudeRuntimeConfig } from "./runtimes/claude.js";
 export { default as claudeRuntime } from "./runtimes/claude.js";
-export { createVercelRuntime, VercelRunner } from "./runtimes/vercel.js";
-export type { VercelRuntimeConfig } from "./runtimes/vercel.js";
+export { createVercelRuntime, VercelRunner, listVercelRuntimeModels } from "./runtimes/vercel.js";
+export type { VercelRuntimeConfig, VercelRuntimeModel } from "./runtimes/vercel.js";
+export type { GatewayModelId } from "ai";
+export { createCodexRuntime } from "./runtimes/codex.js";
+export type { CodexRuntimeConfig } from "./runtimes/codex.js";
+export { default as codexRuntime } from "./runtimes/codex.js";
+export { createAmpRuntime } from "./runtimes/amp.js";
+export type { AmpRuntimeConfig } from "./runtimes/amp.js";
+export { default as ampRuntime } from "./runtimes/amp.js";
 export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/index.js";
 export type { CodingTool } from "./tools/index.js";
 export type { RunEvent } from "./types/events.js";

package/dist/index.js

@@ -18,7 +18,7 @@ var __toESM = (mod, isNodeMode, target) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/runtimes/vercel.ts
-import { streamText, stepCountIs, tool } from "ai";
+import { streamText, stepCountIs, tool, gateway } from "ai";
 
 // src/types/runtime.ts
 function defineRuntime(pkg) {
@@ -387,6 +387,8 @@ class VercelRunner {
   options;
   config;
   supportsToolCallProcessor = true;
+  kind;
+  model;
   tools;
   messages = [];
   constructor(sandbox, options, config) {
@@ -394,6 +396,8 @@ class VercelRunner {
     this.options = options;
     this.config = config;
     this.tools = config.tools ?? codingTools;
+    this.kind = config.kind;
+    this.model = config.modelId;
   }
   async gateToolCall(call, ctx) {
     const verdict = await runProcessorChain(this.options.processors ?? [], (p) => p.processToolCall, call, ctx);
@@ -511,6 +515,10 @@ function createVercelRuntime(config) {
     create: (sandbox, opts) => new VercelRunner(sandbox, opts, config)
   });
 }
+async function listVercelRuntimeModels() {
+  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));
+}
 // src/types/workflow.ts
 import { z as z3 } from "zod";
 
@@ -2368,6 +2376,239 @@ function createClaudeRuntime(config = {}) {
   });
 }
 var claude_default = createClaudeRuntime();
+// src/runtimes/_cli-agent.ts
+function now3() {
+  return new Date().toISOString();
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+class CliAgentRunner {
+  sandbox;
+  options;
+  spec;
+  configModel;
+  kind;
+  constructor(sandbox, options, spec, configModel) {
+    this.sandbox = sandbox;
+    this.options = options;
+    this.spec = spec;
+    this.configModel = configModel;
+    this.kind = spec.kind;
+  }
+  get model() {
+    return this.configModel ?? this.options.model ?? this.spec.defaultModel;
+  }
+  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 {
+      for await (const line of lines) {
+        let parsed;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        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: now3() };
+        return;
+      }
+      if (!sawError)
+        yield { type: "done", sessionId: sessionId ?? "", timestamp: now3() };
+    } catch (err) {
+      yield { type: "error", text: formatError(err), timestamp: now3() };
+    }
+  }
+}
+function createCliAgentRuntime(spec, configModel) {
+  return defineRuntime({
+    create: (sandbox, opts) => new CliAgentRunner(sandbox, opts, spec, configModel)
+  });
+}
+
+// src/runtimes/codex.ts
+function now4() {
+  return new Date().toISOString();
+}
+var codexSpec = {
+  kind: "codex",
+  authEnv: "CODEX_API_KEY",
+  promptPayload: (prompt) => prompt,
+  buildCommand: ({ promptPath, sessionId, model, cwd }) => {
+    const flags = [
+      "--json",
+      "--skip-git-repo-check",
+      "--dangerously-bypass-approvals-and-sandbox",
+      ...model ? ["-m", shellQuote(model)] : [],
+      ...cwd ? ["-C", shellQuote(cwd)] : []
+    ].join(" ");
+    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) => {
+    const ts = now4();
+    switch (p.type) {
+      case "item.started":
+      case "item.completed": {
+        const item = p.item;
+        if (!item)
+          return [];
+        const itype = String(item.type ?? "");
+        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 }] : [];
+        }
+        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 }];
+        }
+        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;
+        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 [];
+    }
+  }
+};
+function createCodexRuntime(config = {}) {
+  return createCliAgentRuntime(codexSpec, config.model);
+}
+var codex_default = createCodexRuntime();
+// src/runtimes/amp.ts
+function now5() {
+  return new Date().toISOString();
+}
+function blocks(msg) {
+  const inner = msg.message?.content ?? msg.content ?? [];
+  return inner;
+}
+var ampSpec = {
+  kind: "amp",
+  authEnv: "AMP_API_KEY",
+  promptPayload: (prompt) => JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text: prompt }] } }) + `
+`,
+  buildCommand: ({ promptPath, sessionId }) => {
+    const cont = sessionId ? `threads continue ${shellQuote(sessionId)} ` : "";
+    return `amp ${cont}-x --stream-json --stream-json-input < ${shellQuote(promptPath)}`;
+  },
+  extractSessionId: (p) => typeof p.session_id === "string" ? p.session_id : undefined,
+  mapEvent: (p) => {
+    const ts = now5();
+    if (p.type === "assistant") {
+      return blocks(p).flatMap((b) => {
+        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 ?? {}, toolUseId: String(b.id ?? ""), timestamp: ts }];
+        return [];
+      });
+    }
+    if (p.type === "user") {
+      return blocks(p).flatMap((b) => 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 = [];
+      const u = p.usage;
+      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 [];
+  }
+};
+function createAmpRuntime(config = {}) {
+  return createCliAgentRuntime(ampSpec, config.model);
+}
+var amp_default = createAmpRuntime();
 // src/sandbox.ts
 import { promises as fs2 } from "node:fs";
 import { dirname as dirname2 } from "node:path";
@@ -3666,6 +3907,7 @@ export {
   parseAgentResponse,
   makeSandboxProvider,
   makeDesktopSandboxProvider,
+  listVercelRuntimeModels,
   listOwnedSandboxes,
   killSandboxById,
   killAllSandboxes,
@@ -3683,8 +3925,11 @@ export {
   defineRuntime,
   createVercelRuntime,
   createSandbox,
+  createCodexRuntime,
   createClaudeRuntime,
+  createAmpRuntime,
   codingTools,
+  codex_default as codexRuntime,
   claude_default as claudeRuntime,
   classifyError,
   bundleWorkflow,
@@ -3692,6 +3937,7 @@ export {
   buildInvokeChild,
   bashTool,
   assertDefaultExportIsDefineWorkflow,
+  amp_default as ampRuntime,
   agentLoop,
   agent,
   WorkflowSourceValidationError,

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

@@ -0,0 +1,72 @@
+/**
+ * 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`.
+ *
+ * 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.
+ */
+import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider } from "../index.js";
+/** Single-quote a value for safe interpolation into a `sh -c` command line. */
+export declare function shellQuote(value: string): string;
+/** 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;
+    /** 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 declare class CliAgentRunner implements ModelExecutionContract {
+    private readonly sandbox;
+    private readonly options;
+    private readonly spec;
+    private readonly configModel?;
+    readonly kind: string;
+    constructor(sandbox: SandboxProvider, options: RuntimeOptions, spec: CliAgentSpec, configModel?: string | undefined);
+    get model(): string | undefined;
+    sendMessage(opts: {
+        prompt: string;
+        sessionId?: string;
+        iteration?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentMessage>;
+}
+export declare function createCliAgentRuntime(spec: CliAgentSpec, configModel?: string): import("../index.js").AgentRuntime<SandboxProvider>;

package/dist/runtimes/amp.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ * 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.
+ *
+ * ⚠️ 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.
+ */
+export interface AmpRuntimeConfig {
+    /** Amp uses its configured model; reserved for forward-compatibility. */
+    model?: string;
+}
+export declare function createAmpRuntime(config?: AmpRuntimeConfig): import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+export default _default;

package/dist/runtimes/codex.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 `CODEX_API_KEY` (or `OPENAI_API_KEY`) in the sandbox env via a
+ * workflow secret. Requires the `codex` CLI installed in the sandbox image.
+ *
+ * ⚠️ 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.
+ */
+export interface CodexRuntimeConfig {
+    /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */
+    model?: string;
+}
+export declare function createCodexRuntime(config?: CodexRuntimeConfig): import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+export default _default;

package/dist/runtimes/openai-desktop.js

@@ -18,7 +18,7 @@ var __toESM = (mod, isNodeMode, target) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/runtimes/vercel.ts
-import { streamText, stepCountIs, tool } from "ai";
+import { streamText, stepCountIs, tool, gateway } from "ai";
 
 // src/types/runtime.ts
 function defineRuntime(pkg) {
@@ -387,6 +387,8 @@ class VercelRunner {
   options;
   config;
   supportsToolCallProcessor = true;
+  kind;
+  model;
   tools;
   messages = [];
   constructor(sandbox, options, config) {
@@ -394,6 +396,8 @@ class VercelRunner {
     this.options = options;
     this.config = config;
     this.tools = config.tools ?? codingTools;
+    this.kind = config.kind;
+    this.model = config.modelId;
   }
   async gateToolCall(call, ctx) {
     const verdict = await runProcessorChain(this.options.processors ?? [], (p) => p.processToolCall, call, ctx);
@@ -511,6 +515,10 @@ function createVercelRuntime(config) {
     create: (sandbox, opts) => new VercelRunner(sandbox, opts, config)
   });
 }
+async function listVercelRuntimeModels() {
+  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));
+}
 // src/types/workflow.ts
 import { z as z3 } from "zod";
 
@@ -2368,6 +2376,239 @@ function createClaudeRuntime(config = {}) {
   });
 }
 var claude_default = createClaudeRuntime();
+// src/runtimes/_cli-agent.ts
+function now3() {
+  return new Date().toISOString();
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+class CliAgentRunner {
+  sandbox;
+  options;
+  spec;
+  configModel;
+  kind;
+  constructor(sandbox, options, spec, configModel) {
+    this.sandbox = sandbox;
+    this.options = options;
+    this.spec = spec;
+    this.configModel = configModel;
+    this.kind = spec.kind;
+  }
+  get model() {
+    return this.configModel ?? this.options.model ?? this.spec.defaultModel;
+  }
+  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 {
+      for await (const line of lines) {
+        let parsed;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        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: now3() };
+        return;
+      }
+      if (!sawError)
+        yield { type: "done", sessionId: sessionId ?? "", timestamp: now3() };
+    } catch (err) {
+      yield { type: "error", text: formatError(err), timestamp: now3() };
+    }
+  }
+}
+function createCliAgentRuntime(spec, configModel) {
+  return defineRuntime({
+    create: (sandbox, opts) => new CliAgentRunner(sandbox, opts, spec, configModel)
+  });
+}
+
+// src/runtimes/codex.ts
+function now4() {
+  return new Date().toISOString();
+}
+var codexSpec = {
+  kind: "codex",
+  authEnv: "CODEX_API_KEY",
+  promptPayload: (prompt) => prompt,
+  buildCommand: ({ promptPath, sessionId, model, cwd }) => {
+    const flags = [
+      "--json",
+      "--skip-git-repo-check",
+      "--dangerously-bypass-approvals-and-sandbox",
+      ...model ? ["-m", shellQuote(model)] : [],
+      ...cwd ? ["-C", shellQuote(cwd)] : []
+    ].join(" ");
+    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) => {
+    const ts = now4();
+    switch (p.type) {
+      case "item.started":
+      case "item.completed": {
+        const item = p.item;
+        if (!item)
+          return [];
+        const itype = String(item.type ?? "");
+        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 }] : [];
+        }
+        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 }];
+        }
+        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;
+        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 [];
+    }
+  }
+};
+function createCodexRuntime(config = {}) {
+  return createCliAgentRuntime(codexSpec, config.model);
+}
+var codex_default = createCodexRuntime();
+// src/runtimes/amp.ts
+function now5() {
+  return new Date().toISOString();
+}
+function blocks(msg) {
+  const inner = msg.message?.content ?? msg.content ?? [];
+  return inner;
+}
+var ampSpec = {
+  kind: "amp",
+  authEnv: "AMP_API_KEY",
+  promptPayload: (prompt) => JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text: prompt }] } }) + `
+`,
+  buildCommand: ({ promptPath, sessionId }) => {
+    const cont = sessionId ? `threads continue ${shellQuote(sessionId)} ` : "";
+    return `amp ${cont}-x --stream-json --stream-json-input < ${shellQuote(promptPath)}`;
+  },
+  extractSessionId: (p) => typeof p.session_id === "string" ? p.session_id : undefined,
+  mapEvent: (p) => {
+    const ts = now5();
+    if (p.type === "assistant") {
+      return blocks(p).flatMap((b) => {
+        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 ?? {}, toolUseId: String(b.id ?? ""), timestamp: ts }];
+        return [];
+      });
+    }
+    if (p.type === "user") {
+      return blocks(p).flatMap((b) => 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 = [];
+      const u = p.usage;
+      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 [];
+  }
+};
+function createAmpRuntime(config = {}) {
+  return createCliAgentRuntime(ampSpec, config.model);
+}
+var amp_default = createAmpRuntime();
 // src/sandbox.ts
 import { promises as fs2 } from "node:fs";
 import { dirname as dirname2 } from "node:path";

package/dist/runtimes/vercel.d.ts

@@ -7,18 +7,38 @@ import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvi
 import { type CodingTool } from "../tools/index.js";
 import type { ProcessorContext, ToolCall } from "../processors/processor.js";
 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;
 }
 export declare class VercelRunner implements ModelExecutionContract {
     private readonly sandbox;
     private readonly options;
     private readonly config;
     supportsToolCallProcessor: boolean;
+    /** 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;
     private readonly messages;
     constructor(sandbox: SandboxProvider, options: RuntimeOptions, config: VercelRuntimeConfig);
@@ -44,3 +64,23 @@ export declare class VercelRunner implements ModelExecutionContract {
     }): AsyncGenerator<AgentMessage>;
 }
 export declare function createVercelRuntime(config: VercelRuntimeConfig): import("../index.js").AgentRuntime<SandboxProvider>;
+/** 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 declare function listVercelRuntimeModels(): Promise<VercelRuntimeModel[]>;

package/dist/runtimes/vercel.js

@@ -18,7 +18,7 @@ var __toESM = (mod, isNodeMode, target) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/runtimes/vercel.ts
-import { streamText, stepCountIs, tool } from "ai";
+import { streamText, stepCountIs, tool, gateway } from "ai";
 
 // src/types/runtime.ts
 function defineRuntime(pkg) {
@@ -387,6 +387,8 @@ class VercelRunner {
   options;
   config;
   supportsToolCallProcessor = true;
+  kind;
+  model;
   tools;
   messages = [];
   constructor(sandbox, options, config) {
@@ -394,6 +396,8 @@ class VercelRunner {
     this.options = options;
     this.config = config;
     this.tools = config.tools ?? codingTools;
+    this.kind = config.kind;
+    this.model = config.modelId;
   }
   async gateToolCall(call, ctx) {
     const verdict = await runProcessorChain(this.options.processors ?? [], (p) => p.processToolCall, call, ctx);
@@ -511,7 +515,12 @@ function createVercelRuntime(config) {
     create: (sandbox, opts) => new VercelRunner(sandbox, opts, config)
   });
 }
+async function listVercelRuntimeModels() {
+  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));
+}
 export {
+  listVercelRuntimeModels,
   createVercelRuntime,
   VercelRunner
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.5.2",
+  "version": "0.5.5",
   "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

@@ -120,6 +120,7 @@ export type {
   RequestAgentPauseOptions, RequestAgentPauseResponse,
   SendAgentMessageOptions, SendAgentMessageResponse,
   AnswerSteerOptions,
+  ResumePauseOptions, ResumePauseResponse, ResumePauseSuccess, ResumePausePending, ResumePauseActor,
 } from "./client.js";
 
 // SSE parser — exposed so tests and downstream callers can reuse it.
@@ -147,8 +148,25 @@ export { AgentStatusSchema } from "./utils/schemas.js";
 export { createClaudeRuntime, ClaudeRunner } from "./runtimes/claude.js";
 export type { ClaudeRuntimeConfig } from "./runtimes/claude.js";
 export { default as claudeRuntime } from "./runtimes/claude.js";
-export { createVercelRuntime, VercelRunner } from "./runtimes/vercel.js";
-export type { VercelRuntimeConfig } from "./runtimes/vercel.js";
+export { createVercelRuntime, VercelRunner, listVercelRuntimeModels } from "./runtimes/vercel.js";
+export type { VercelRuntimeConfig, VercelRuntimeModel } from "./runtimes/vercel.js";
+// There is no per-provider runtime — the model is a parameter, not a runtime.
+// `createVercelRuntime({ model })` drives any provider: pass a gateway model-id
+// string ("openai/gpt-5", "google/gemini-2.5-pro", "anthropic/claude-…") or a
+// LanguageModel object from any @ai-sdk/<provider> package. To DISCOVER which
+// gateway models are available, call `listVercelRuntimeModels()` (live catalog)
+// or browse https://vercel.com/ai-gateway/models. `GatewayModelId` is the
+// string-form model-id type. See docs/custom-runtimes.md.
+export type { GatewayModelId } from "ai";
+// CLI-agent runtimes — drive an external agentic CLI (codex / amp) inside the
+// sandbox and stream-parse its JSONL. No heavy npm deps (the CLI lives in the
+// sandbox image), so these are root-exported like claudeRuntime.
+export { createCodexRuntime } from "./runtimes/codex.js";
+export type { CodexRuntimeConfig } from "./runtimes/codex.js";
+export { default as codexRuntime } from "./runtimes/codex.js";
+export { createAmpRuntime } from "./runtimes/amp.js";
+export type { AmpRuntimeConfig } from "./runtimes/amp.js";
+export { default as ampRuntime } from "./runtimes/amp.js";
 
 // Built-in coding tools for Vercel AI SDK runtime.
 export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/index.js";

package/src/runtimes/_cli-agent.ts

@@ -0,0 +1,161 @@
+/**
+ * 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`.
+ *
+ * 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.
+ */
+
+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;
+  /** 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;
+  }
+
+  // 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> {
+    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 {
+      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,94 @@
+/**
+ * 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.
+ * 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.
+ *
+ * ⚠️ 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.
+ */
+
+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",
+  // `--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,109 @@
+/**
+ * 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 `CODEX_API_KEY` (or `OPENAI_API_KEY`) in the sandbox env via a
+ * workflow secret. Requires the `codex` CLI installed in the sandbox image.
+ *
+ * ⚠️ 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.
+ */
+
+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",
+  // 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));
+}