@agent-compose/sdk 0.5.2 → 0.5.6

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,259 @@ 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;
+  }
+  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) {
+    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 {
+          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",
+  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 = [
+      "--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",
+  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 }) => {
+    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/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.2",
+  "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,
@@ -120,6 +121,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 +149,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";