@agent-compose/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,1114 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/types/runtime.ts
+function defineRuntime(pkg) {
+  if (typeof pkg.create !== "function")
+    throw new Error("defineRuntime: 'create' is required");
+  return pkg;
+}
+// src/types/workflow.ts
+function defineWorkflow(def) {
+  return Object.assign(def.run, {
+    networkPolicy: def.networkPolicy,
+    placeholders: def.placeholders,
+    sandboxEnvironment: def.sandboxEnvironment,
+    snapshot: def.snapshot
+  });
+}
+// src/sandbox.ts
+import { promises as fs } from "node:fs";
+import { dirname } from "node:path";
+import { spawn } from "node:child_process";
+import { Sandbox } from "e2b";
+import { Sandbox as Desktop } from "@e2b/desktop";
+import pRetry from "p-retry";
+var AGENT_COMPOSE_TAG = process.env.AGENT_COMPOSE_TAG ?? `agent-compose-${process.env.AGENT_COMPOSE_ENV ?? "dev"}`;
+var VERCEL_VM_LIFETIME_WINDOW_MS = 6 * 60 * 60 * 1000;
+function makeSandboxProvider(sb) {
+  return { sandboxId: sb.sandboxId, commands: sb.commands, files: sb.files, kill: () => sb.kill() };
+}
+function makeDesktopSandboxProvider(sb) {
+  return {
+    ...makeSandboxProvider(sb),
+    screenshot: () => sb.screenshot(),
+    leftClick: (x, y) => sb.leftClick(x, y),
+    doubleClick: (x, y) => sb.doubleClick(x, y),
+    rightClick: (x, y) => sb.rightClick(x, y),
+    middleClick: (x, y) => sb.middleClick(x, y),
+    moveMouse: (x, y) => sb.moveMouse(x, y),
+    write: (text) => sb.write(text),
+    press: (key) => sb.press(key),
+    scroll: (dir, ticks) => sb.scroll(dir, ticks),
+    drag: (from, to) => sb.drag(from, to)
+  };
+}
+async function parseSseExecStream(body, opts) {
+  let stdout = "", exitCode = 0, exited = false;
+  const reader = body.getReader(), decoder = new TextDecoder;
+  let buf = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    buf += decoder.decode(value, { stream: true });
+    const lines = buf.replace(/\r\n/g, `
+`).split(`
+`);
+    buf = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.startsWith("data: "))
+        continue;
+      let event;
+      try {
+        event = JSON.parse(line.slice(6));
+      } catch {
+        continue;
+      }
+      if (event.type === "stdout") {
+        stdout += event.data ?? "";
+        opts?.onStdout?.(event.data ?? "");
+      } else if (event.type === "stderr") {
+        opts?.onStderr?.(event.data ?? "");
+      } else if (event.type === "exit") {
+        exitCode = event.exitCode ?? 0;
+        exited = true;
+      } else if (event.type === "error") {
+        throw new Error(`Sandbox exec error: ${event.data}`);
+      }
+    }
+    if (exited)
+      break;
+  }
+  return { exitCode, stdout };
+}
+function makeVercelSandboxProvider(sb, globalEnvs) {
+  const mergeEnvs = (cmdEnvs) => globalEnvs ? { ...globalEnvs, ...cmdEnvs } : cmdEnvs;
+  return {
+    sandboxId: sb.sandboxId,
+    commands: {
+      async run(cmd, opts) {
+        if (opts?.background) {
+          sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true }).catch(() => {});
+          return { exitCode: 0, stdout: "" };
+        }
+        const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
+        let stdout = "";
+        const handle = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal });
+        await pRetry(async (attempt) => {
+          const h = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
+          for await (const log of h.logs()) {
+            if (log.stream === "stdout") {
+              stdout += log.data;
+              opts?.onStdout?.(log.data);
+            } else {
+              opts?.onStderr?.(log.data);
+            }
+          }
+        }, { retries: 3, minTimeout: 1000, factor: 2 });
+        const finished = await handle.wait();
+        return { exitCode: finished.exitCode, stdout };
+      }
+    },
+    files: {
+      async write(path, content) {
+        await sb.writeFiles([{ path, content }]);
+      }
+    },
+    async kill() {
+      await sb.stop();
+    },
+    async snapshot() {
+      const res = await sb.snapshot({ expiration: 0 });
+      return { snapshotId: res.snapshotId };
+    }
+  };
+}
+function makeLocalSandboxProvider() {
+  return {
+    sandboxId: "local",
+    commands: {
+      run(cmd, opts) {
+        return new Promise((resolve, reject) => {
+          const proc = spawn("sh", ["-c", cmd], {
+            ...opts?.cwd ? { cwd: opts.cwd } : {},
+            env: { ...process.env, ...opts?.envs ?? {} },
+            stdio: ["ignore", "pipe", "pipe"]
+          });
+          let stdout = "";
+          proc.stdout?.setEncoding("utf8");
+          proc.stderr?.setEncoding("utf8");
+          proc.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+            opts?.onStdout?.(chunk);
+          });
+          proc.stderr?.on("data", (chunk) => {
+            opts?.onStderr?.(chunk);
+          });
+          proc.on("error", reject);
+          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout }));
+        });
+      }
+    },
+    files: {
+      async write(path, content) {
+        await fs.mkdir(dirname(path), { recursive: true });
+        await fs.writeFile(path, content);
+      }
+    },
+    async kill() {}
+  };
+}
+var SANDBOX_PROVIDERS = {
+  vercel: {
+    requiredEnv: {
+      VERCEL_ACCESS_TOKEN: "Vercel access token — vercel.com/account/tokens",
+      VERCEL_TEAM_ID: "Vercel team ID — vercel.com/account/settings",
+      VERCEL_PROJECT_ID: "Vercel project ID — vercel.com/[team]/[project]/settings"
+    },
+    create: async (opts, env) => {
+      const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
+      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+      const np = opts.networkPolicy;
+      const sb = await VercelSandbox.create(opts.template ? { source: { type: "snapshot", snapshotId: opts.template }, timeout: opts.timeoutMs, env: opts.envs, ...np ? { networkPolicy: np } : {}, ...creds } : { runtime: "node24", timeout: opts.timeoutMs, env: opts.envs, ...np ? { networkPolicy: np } : {}, ...creds });
+      return makeVercelSandboxProvider(sb, opts.envs);
+    },
+    reconnect: async (sandboxId) => {
+      const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
+      const creds = {
+        token: process.env.VERCEL_ACCESS_TOKEN ?? "",
+        teamId: process.env.VERCEL_TEAM_ID ?? "",
+        projectId: process.env.VERCEL_PROJECT_ID ?? ""
+      };
+      return makeVercelSandboxProvider(await VercelSandbox.get({ sandboxId, ...creds }));
+    },
+    getActiveCount: async (env) => (await SANDBOX_PROVIDERS.vercel.listOwned(env)).length,
+    listOwned: async (env) => {
+      const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
+      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+      const since = Date.now() - VERCEL_VM_LIFETIME_WINDOW_MS;
+      const out = [];
+      let until;
+      for (let page = 0;page < 50; page++) {
+        const { json } = await pRetry(() => VercelSandbox.list({ ...creds, limit: 200, since, ...until !== undefined ? { until } : {} }), { retries: 3, minTimeout: 500, factor: 2 });
+        for (const sb of json.sandboxes)
+          if (sb.status === "running") {
+            out.push({ sandboxId: sb.id, createdAt: new Date(sb.createdAt), metadata: {} });
+          }
+        if (json.pagination.next === null)
+          return out;
+        until = json.pagination.next;
+      }
+      throw new Error("Vercel listSandboxes exceeded 50 pages within the lifetime window — refuse to silently truncate");
+    },
+    deleteSnapshot: async (snapshotId, env) => {
+      const { Snapshot } = await import("@vercel/sandbox");
+      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+      const snap = await Snapshot.get({ snapshotId, ...creds });
+      await snap.delete();
+    }
+  },
+  e2b: {
+    requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
+    create: async ({ template, ...sandboxOpts }) => {
+      if (!template)
+        throw new Error("E2B provider requires an explicit `template` (Dockerfile-based — no default base image)");
+      return makeSandboxProvider(await Sandbox.create(template, sandboxOpts));
+    },
+    reconnect: async (sandboxId) => makeSandboxProvider(await Sandbox.connect(sandboxId, { apiKey: process.env.E2B_API_KEY ?? "", timeoutMs: 3600000 })),
+    killAll: async () => {
+      const paginator = Sandbox.list({ query: { metadata: { executor: AGENT_COMPOSE_TAG } } });
+      const sandboxes = [];
+      while (paginator.hasNext)
+        sandboxes.push(...await paginator.nextItems());
+      if (sandboxes.length === 0)
+        return;
+      await Promise.all(sandboxes.map((s) => Sandbox.kill(s.sandboxId).catch(() => {})));
+      console.info(`[sandbox] killed ${sandboxes.length} stale E2B sandboxes (tag: ${AGENT_COMPOSE_TAG})`);
+    },
+    getActiveCount: async () => (await SANDBOX_PROVIDERS.e2b.listOwned({})).length,
+    listOwned: async () => {
+      const paginator = Sandbox.list({ query: { metadata: { executor: AGENT_COMPOSE_TAG }, state: ["running"] } });
+      const out = [];
+      while (paginator.hasNext) {
+        const items = await pRetry(() => paginator.nextItems(), { retries: 3, minTimeout: 500, factor: 2 });
+        for (const sb of items) {
+          out.push({
+            sandboxId: sb.sandboxId,
+            createdAt: new Date(sb.startedAt),
+            metadata: sb.metadata ?? {}
+          });
+        }
+      }
+      return out;
+    }
+  },
+  "e2b-desktop": {
+    requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
+    create: async ({ template, ...sandboxOpts }) => {
+      if (!template)
+        throw new Error("E2B Desktop provider requires an explicit `template` (Dockerfile-based — no default base image)");
+      return makeDesktopSandboxProvider(await Desktop.create(template, sandboxOpts));
+    }
+  }
+};
+async function createSandbox(provider, opts) {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def)
+    throw new Error(`Unknown sandbox provider: "${provider}". Known: ${Object.keys(SANDBOX_PROVIDERS).join(", ")}`);
+  const missing = Object.entries(def.requiredEnv).filter(([key]) => !process.env[key]).map(([key, desc]) => `  ${key}  — ${desc}`);
+  if (missing.length > 0)
+    throw new Error(`Sandbox provider "${provider}" requires env vars:
+${missing.join(`
+`)}`);
+  return def.create(opts, Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k]])));
+}
+async function reconnectSandbox(provider, sandboxId) {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.reconnect)
+    throw new Error(`Provider "${provider}" does not support reconnect`);
+  return def.reconnect(sandboxId);
+}
+async function deleteSandboxSnapshot(provider, snapshotId) {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.deleteSnapshot)
+    throw new Error(`Provider "${provider}" does not support deleteSnapshot`);
+  const missing = Object.entries(def.requiredEnv).filter(([k]) => !process.env[k]).map(([k, desc]) => `  ${k} — ${desc}`);
+  if (missing.length > 0)
+    throw new Error(`Sandbox provider "${provider}" requires env vars:
+${missing.join(`
+`)}`);
+  return def.deleteSnapshot(snapshotId, Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k]])));
+}
+async function getSandboxQuotas() {
+  const out = {};
+  await Promise.all(Object.entries(SANDBOX_PROVIDERS).map(async ([name, def]) => {
+    if (!def.getActiveCount)
+      return;
+    if (Object.keys(def.requiredEnv).some((k) => !process.env[k]))
+      return;
+    const env = Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k]]));
+    try {
+      out[name] = await def.getActiveCount(env);
+    } catch (err) {
+      out[name] = err instanceof Error ? err : new Error(String(err));
+    }
+  }));
+  return out;
+}
+async function listOwnedSandboxes() {
+  const out = {};
+  await Promise.all(Object.entries(SANDBOX_PROVIDERS).map(async ([name, def]) => {
+    if (!def.listOwned)
+      return;
+    if (Object.keys(def.requiredEnv).some((k) => !process.env[k]))
+      return;
+    const env = Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k]]));
+    try {
+      out[name] = await def.listOwned(env);
+    } catch (err) {
+      out[name] = err instanceof Error ? err : new Error(String(err));
+    }
+  }));
+  return out;
+}
+async function killSandboxById(provider, sandboxId) {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.reconnect)
+    throw new Error(`Provider "${provider}" does not support reconnect (required for kill-by-id)`);
+  const sb = await def.reconnect(sandboxId);
+  await sb.kill();
+}
+async function killAllSandboxes(onError) {
+  await Promise.allSettled(Object.entries(SANDBOX_PROVIDERS).filter(([, def]) => def.killAll).map(([name, def]) => {
+    const env = Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k] ?? ""]));
+    if (Object.keys(def.requiredEnv).some((k) => !process.env[k]))
+      return Promise.resolve();
+    return def.killAll(env).catch((err) => onError?.(name, err));
+  }));
+}
+
+// src/types/sandbox-environment.ts
+function defineSandboxEnvironment(env) {
+  if (typeof env.setup !== "function") {
+    throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
+  }
+  return defineWorkflow({
+    snapshot: env.snapshot ?? true,
+    run: () => env.setup(makeLocalSandboxProvider())
+  });
+}
+// src/client.ts
+import { ofetch } from "ofetch";
+
+// src/errors.ts
+class AgentComposeError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AgentComposeError";
+  }
+}
+
+// src/client.ts
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function detectAmbientParentRunId() {
+  const envRunId = typeof process !== "undefined" ? process.env?.RUN_ID : undefined;
+  return envRunId && UUID_REGEX.test(envRunId) ? envRunId : null;
+}
+
+class AgentComposeClient {
+  fetch;
+  constructor(baseUrl, apiKey) {
+    this.fetch = ofetch.create({
+      baseURL: baseUrl.replace(/\/$/, ""),
+      headers: { Authorization: `Bearer ${apiKey}` },
+      async onResponseError({ response }) {
+        const body = response._data;
+        throw new AgentComposeError(response.status, body?.error ?? response.statusText);
+      }
+    });
+  }
+  register(payload) {
+    return this.fetch("/api/v1/templates", { method: "POST", body: payload });
+  }
+  invoke(name, input, opts) {
+    const parentRunId = opts?.parentRunId === undefined ? detectAmbientParentRunId() : opts.parentRunId;
+    return this.fetch(`/api/v1/templates/${name}/invoke`, {
+      method: "POST",
+      body: {
+        input,
+        ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
+        ...parentRunId ? { parentRunId } : {}
+      }
+    });
+  }
+  async invokeAndWait(name, input, opts) {
+    const timeoutMs = opts?.timeoutMs ?? 30 * 60 * 1000;
+    const pollMs = opts?.pollIntervalMs ?? 1000;
+    const { id: runId } = await this.invoke(name, input, {
+      ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
+      ...opts?.parentRunId !== undefined ? { parentRunId: opts.parentRunId } : {}
+    });
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const status = await this.getStatus(runId);
+      if (status.status === "success" || status.status === "failed" || status.status === "abandoned") {
+        return status;
+      }
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+    throw new AgentComposeError(504, `invokeAndWait: run ${runId} did not settle within ${timeoutMs}ms`);
+  }
+  async listSnapshots(opts) {
+    const q = new URLSearchParams;
+    if (opts?.workflow)
+      q.set("workflow", opts.workflow);
+    if (opts?.limit != null)
+      q.set("limit", String(opts.limit));
+    const body = await this.fetch(`/api/v1/snapshots${q.toString() ? `?${q}` : ""}`);
+    return body.data;
+  }
+  deleteSnapshot(runId) {
+    return this.fetch(`/api/v1/workflows/${runId}/snapshot`, { method: "DELETE" });
+  }
+  getStatus(runId) {
+    return this.fetch(`/api/v1/workflows/${runId}/status`);
+  }
+  async listTemplates() {
+    const body = await this.fetch("/api/v1/templates");
+    return body.templates;
+  }
+  setSecret(workflowName, key, value) {
+    return this.fetch(`/api/v1/templates/${workflowName}/secrets`, { method: "POST", body: { key, value } });
+  }
+  async listSecrets(workflowName) {
+    const body = await this.fetch(`/api/v1/templates/${workflowName}/secrets`);
+    return body.secrets.map((s) => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
+  }
+  deleteSecret(workflowName, key) {
+    return this.fetch(`/api/v1/templates/${workflowName}/secrets/${key}`, { method: "DELETE" });
+  }
+}
+// src/utils/errors.ts
+function formatError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+// src/utils/discovery.ts
+function discoverRuntimeName(source) {
+  return source.match(/runtime:\s*["']([^"']+)["']/)?.[1] ?? null;
+}
+// src/utils/source-loader.ts
+import { dirname as dirname2 } from "path";
+import { writeFile, unlink, mkdir } from "node:fs/promises";
+var TMP_DIR = process.env.TMP_DIR ?? "/tmp/agent-compose";
+var LATEST_VERSION = "$LATEST";
+async function importSourceModule(source, tmpPath) {
+  await mkdir(dirname2(tmpPath), { recursive: true });
+  await writeFile(tmpPath, source, "utf8");
+  const mod = await import(tmpPath);
+  const cleanup = () => unlink(tmpPath).catch(() => {});
+  return { mod, cleanup };
+}
+
+// src/utils/bundler.ts
+async function bundle(path, label) {
+  const bun = globalThis;
+  if (!bun.Bun?.build)
+    throw new Error("bundleWorkflow requires the Bun runtime (Bun.build)");
+  const result = await bun.Bun.build({ entrypoints: [path], format: "esm", target: "bun" });
+  if (!result.success) {
+    throw new Error(`Failed to bundle ${label}:
+${result.logs.map((l) => l.message).join(`
+`)}`);
+  }
+  return result.outputs[0].text();
+}
+async function extractFromBundle(source, label, pick) {
+  const tmpPath = `/tmp/agentc-${label}-${Date.now()}-${Math.random().toString(36).slice(2)}.js`;
+  try {
+    const loaded = await importSourceModule(source, tmpPath);
+    try {
+      return pick(loaded.mod.default);
+    } finally {
+      await loaded.cleanup();
+    }
+  } catch {
+    return;
+  }
+}
+async function bundleWorkflow(workflowPath, overrides) {
+  const source = await bundle(workflowPath, `workflow "${workflowPath}"`);
+  const wfBits = await extractFromBundle(source, "workflow", (wf) => wf ? {
+    networkPolicy: wf.networkPolicy,
+    placeholders: wf.placeholders,
+    sandboxEnvironment: wf.sandboxEnvironment,
+    snapshot: wf.snapshot
+  } : undefined);
+  const { networkPolicy, placeholders, sandboxEnvironment, snapshot } = wfBits ?? {};
+  return {
+    source,
+    networkPolicy: overrides?.networkPolicy ?? networkPolicy,
+    placeholders: overrides?.placeholders ?? placeholders,
+    ...sandboxEnvironment ? { sandboxEnvironment } : {},
+    ...snapshot !== undefined ? { snapshot } : {}
+  };
+}
+// src/utils/schemas.ts
+import { z } from "zod";
+var AgentStatusSchema = z.object({
+  summary: z.string(),
+  completed: z.array(z.string()),
+  blockers: z.array(z.string()),
+  exit_signal: z.boolean()
+});
+// src/agent/protocol.ts
+import { z as z2 } from "zod";
+var AgentMessageSchema = z2.object({
+  type: z2.enum(["init", "text", "thinking", "tool_use", "tool_result", "done", "error", "usage"]),
+  timestamp: z2.string()
+}).passthrough();
+function parseAgentResponse(text) {
+  const match = text.match(/<response>([\s\S]*?)<\/response>/);
+  if (!match)
+    return null;
+  try {
+    return JSON.parse(match[1].trim());
+  } catch {
+    return null;
+  }
+}
+
+// src/agent/agent-loop.ts
+var DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
+var SAME_BLOCKER_ITERATIONS = 3;
+var STALL_ITERATIONS = 3;
+function parseAgentStatus(text) {
+  const match = text.match(/<status>([\s\S]*?)<\/status>/);
+  if (!match)
+    return null;
+  try {
+    const result = AgentStatusSchema.safeParse(JSON.parse(match[1].trim()));
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_ALLOWED_TOOLS = ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebFetch"];
+async function agentLoop(opts) {
+  const label = opts.label ?? "[Agent Loop]";
+  const turnsPerIteration = opts.turnsPerIteration ?? 40;
+  const maxIterations = opts.maxIterations ?? 8;
+  if (!opts.runtime)
+    throw new Error("agentLoop: opts.runtime is required");
+  const client = opts.runtime({
+    maxTurns: turnsPerIteration,
+    allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
+    label,
+    cwd: opts.cwd
+  });
+  let lastSessionId = "";
+  let lastStatus = null;
+  let iterationsWithoutStatus = 0;
+  let blockerStreak = null;
+  for (let iteration = 0;iteration < maxIterations; iteration++) {
+    const prompt = opts.buildPrompt(lastStatus, iteration);
+    process.stderr.write(`${label} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns
+`);
+    let responseText = "";
+    for await (const msg of client.sendMessage({ prompt, sessionId: iteration > 0 ? lastSessionId : undefined })) {
+      opts.onAgentEvent?.(iteration, msg);
+      if (msg.type === "init")
+        lastSessionId = msg.sessionId;
+      if (msg.type === "text")
+        responseText += msg.text;
+      if (msg.type === "error")
+        throw new Error(`Agent error: ${msg.text}`);
+    }
+    process.stdout.write(`
+`);
+    let status = parseAgentStatus(responseText);
+    process.stderr.write(`
+${label} iteration ${iteration + 1} status: exit_signal=${status?.exit_signal ?? "(no status)"} blockers=${JSON.stringify(status?.blockers ?? [])}
+`);
+    lastStatus = status ?? lastStatus;
+    opts.onIteration?.(iteration + 1, status);
+    if (status?.exit_signal && (status.blockers?.length ?? 0) === 0) {
+      let response = status;
+      if (opts.responseSchema) {
+        const raw = parseAgentResponse(responseText);
+        if (raw === null) {
+          process.stderr.write(`
+${label} NO <response> BLOCK — response tail: ${responseText.slice(-400)}
+`);
+          status = { ...status, exit_signal: false, blockers: ["No <response> block found — emit a <response> block with the required JSON fields before setting exit_signal: true"] };
+          opts.onIteration?.(iteration + 1, status);
+          continue;
+        }
+        const parsed = opts.responseSchema.safeParse({ ...status, ...raw });
+        if (!parsed.success) {
+          process.stderr.write(`
+${label} <response> SCHEMA FAILED: ${parsed.error.message}
+raw: ${JSON.stringify(raw).slice(0, 400)}
+`);
+          status = { ...status, exit_signal: false, blockers: [`<response> schema validation failed: ${parsed.error.message}`] };
+          opts.onIteration?.(iteration + 1, status);
+          continue;
+        }
+        response = parsed.data;
+      }
+      process.stderr.write(`${label} done after ${iteration + 1}/${maxIterations} iterations
+`);
+      return { sessionId: lastSessionId, lastStatus: status, iterations: iteration + 1, response };
+    }
+    if (!status) {
+      if (++iterationsWithoutStatus >= STALL_ITERATIONS)
+        throw new Error(`${label} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
+    } else {
+      iterationsWithoutStatus = 0;
+    }
+    if (status?.blockers?.length) {
+      const key = status.blockers.join("|");
+      if (blockerStreak !== null && blockerStreak.key === key) {
+        if (++blockerStreak.count >= SAME_BLOCKER_ITERATIONS)
+          throw new Error(`${label} circuit break: same blocker repeated ${blockerStreak.count}x — "${status.blockers[0]}"`);
+      } else {
+        blockerStreak = { key, count: 1 };
+      }
+    } else {
+      blockerStreak = null;
+    }
+    if (iteration + 1 < maxIterations)
+      process.stderr.write(`${label} continuing to iteration ${iteration + 2}/${maxIterations}
+`);
+  }
+  if (opts.responseSchema)
+    throw new Error(`${label} did not produce a valid <response> after ${maxIterations} iterations`);
+  process.stderr.write(`${label} exhausted ${maxIterations} iterations, proceeding with available work
+`);
+  return { sessionId: lastSessionId, lastStatus, iterations: maxIterations };
+}
+
+// src/runtimes/claude.ts
+var NO_TIMEOUT = 0;
+function translateEvent(event) {
+  const msgs = [];
+  const ts = new Date().toISOString();
+  if (event.type === "system" && event.subtype === "init") {
+    msgs.push({ type: "init", sessionId: String(event.session_id ?? ""), timestamp: ts });
+    return msgs;
+  }
+  if (event.type === "assistant") {
+    const message = event.message;
+    for (const block of message?.content ?? []) {
+      const b = block;
+      if (b.type === "text")
+        msgs.push({ type: "text", text: String(b.text ?? ""), timestamp: ts });
+      if (b.type === "thinking")
+        msgs.push({ type: "thinking", text: String(b.thinking ?? ""), timestamp: ts });
+      if (b.type === "tool_use")
+        msgs.push({ type: "tool_use", toolName: String(b.name ?? ""), toolInput: b.input ?? {}, toolUseId: String(b.id ?? ""), timestamp: ts });
+    }
+    return msgs;
+  }
+  if (event.type === "user") {
+    const message = event.message;
+    for (const block of message?.content ?? []) {
+      const b = block;
+      if (b.type === "tool_result") {
+        const raw = b.content;
+        msgs.push({ type: "tool_result", toolUseId: String(b.tool_use_id ?? ""), output: typeof raw === "string" ? raw : JSON.stringify(raw ?? ""), isError: Boolean(b.is_error), timestamp: ts });
+      }
+    }
+    return msgs;
+  }
+  if (event.type === "result") {
+    const usage = event.usage;
+    if (usage) {
+      msgs.push({ type: "usage", inputTokens: usage.input_tokens ?? 0, outputTokens: usage.output_tokens ?? 0, cacheReadTokens: usage.cache_read_input_tokens ?? 0, cacheCreationTokens: usage.cache_creation_input_tokens ?? 0, durationMs: Number(event.duration_ms ?? 0), numTurns: Number(event.num_turns ?? 0), timestamp: ts });
+    }
+    if (event.is_error || event.subtype === "error_during_execution") {
+      const raw = event.error ?? event.result ?? event.message;
+      msgs.push({ type: "error", text: raw == null ? "Unknown error" : typeof raw === "object" ? JSON.stringify(raw) : String(raw), timestamp: ts });
+    } else {
+      msgs.push({ type: "done", sessionId: String(event.session_id ?? ""), timestamp: ts });
+    }
+    return msgs;
+  }
+  return msgs;
+}
+
+class ClaudeRunner {
+  sandbox;
+  options;
+  claudeMdContent;
+  configEnv;
+  configModel;
+  configMcpServers;
+  claudeMdWritten = false;
+  homeDir = null;
+  label;
+  constructor(sandbox, options = {}, claudeMdContent = "", configEnv = {}, configModel, configMcpServers) {
+    this.sandbox = sandbox;
+    this.options = options;
+    this.claudeMdContent = claudeMdContent;
+    this.configEnv = configEnv;
+    this.configModel = configModel;
+    this.configMcpServers = configMcpServers;
+    this.label = options.label ?? "[Agent]";
+  }
+  async getHomeDir() {
+    if (!this.homeDir) {
+      const { stdout } = await this.sandbox.commands.run("echo $HOME", { timeoutMs: 30000 });
+      this.homeDir = stdout.trim() || "/home/user";
+    }
+    return this.homeDir;
+  }
+  async deployGlobalConfig() {
+    if (this.claudeMdWritten)
+      return;
+    const home = await this.getHomeDir();
+    await this.sandbox.commands.run(`mkdir -p "${home}/.claude" && find "${home}/.claude" -name "*.json" -not -name "CLAUDE.md" -delete 2>/dev/null || true`, { timeoutMs: 5000 });
+    await this.sandbox.files.write(`${home}/.claude/CLAUDE.md`, this.claudeMdContent);
+    if (Object.keys(this.configEnv).length) {
+      const settings = JSON.stringify({ env: this.configEnv });
+      const b64 = Buffer.from(settings).toString("base64");
+      await this.sandbox.commands.run(`echo "${b64}" | base64 -d > "${home}/.claude/settings.json"`, { timeoutMs: 5000 });
+    }
+    const mcpServers = this.configMcpServers;
+    if (mcpServers && Object.keys(mcpServers).length) {
+      const b64 = Buffer.from(JSON.stringify({ mcpServers })).toString("base64");
+      await this.sandbox.commands.run(`echo "${b64}" | base64 -d > "${home}/.claude.json"`, { timeoutMs: 5000 });
+      process.stderr.write(`${this.label}[mcp] wrote ${Object.keys(mcpServers).join(",")} to ~/.claude.json
+`);
+    }
+    const placeholderB64 = Buffer.from("x-access-token:placeholder").toString("base64");
+    await this.sandbox.commands.run([
+      `git config --global core.askPass ""`,
+      `git config --global credential.interactive false`,
+      `git config --global credential.helper ""`,
+      `git config --global "http.https://github.com/.extraHeader" "Authorization: Basic ${placeholderB64}"`
+    ].join(" && "), { timeoutMs: 5000 }).catch((e) => console.warn(`${this.label}[init] git config failed (non-fatal): ${formatError(e)}`));
+    try {
+      await this.sandbox.commands.run("rtk init --global --hook-only --auto-patch", { timeoutMs: 1e4 });
+    } catch {
+      console.warn("[Transport] rtk init failed (non-fatal) — token compression disabled");
+    }
+    this.claudeMdWritten = true;
+  }
+  async* _runCli(cmd, label, signal) {
+    const queue = [];
+    let notify = null;
+    function enqueue(items) {
+      queue.push(...items);
+      notify?.();
+      notify = null;
+    }
+    let lineBuffer = "";
+    let stderrBuffer = "";
+    const maxTurns = this.options.maxTurns ?? 40;
+    function handleStdout(data) {
+      lineBuffer += data;
+      const lines = lineBuffer.split(`
+`);
+      lineBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+          continue;
+        try {
+          const event = JSON.parse(trimmed);
+          if (event.type === "assistant") {
+            const content = event.message?.content ?? [];
+            for (const block of content) {
+              const b = block;
+              if (b.type === "text")
+                process.stdout.write(".");
+              if (b.type === "tool_use")
+                process.stderr.write(`
+${label} ${b.name}(${JSON.stringify(b.input).slice(0, 80)})`);
+            }
+          } else if (event.type === "result") {
+            process.stderr.write(`
+${label}[result:${event.num_turns}/${maxTurns}/${event.subtype}]
+`);
+          } else if (event.type === "system") {
+            const ev = event;
+            const mcpSrvs = ev.mcp_servers ?? [];
+            const mcpStr = mcpSrvs.length ? ` mcp=[${mcpSrvs.map((s) => `${s.name}:${s.status}`).join(",")}]` : " mcp=[]";
+            process.stderr.write(`
+${label}[init:${ev.session_id}]${mcpStr}
+`);
+          }
+          enqueue(translateEvent(event));
+        } catch {}
+      }
+    }
+    process.stderr.write(`${label}[cwd:${this.options.cwd ?? "(none)"}]
+`);
+    const runPromise = this.sandbox.commands.run(cmd, {
+      cwd: this.options.cwd,
+      timeoutMs: NO_TIMEOUT,
+      onStdout: handleStdout,
+      onStderr: (data) => {
+        stderrBuffer += data;
+        process.stderr.write(`${label}[stderr] ${data.trimEnd()}
+`);
+      }
+    });
+    runPromise.catch((err) => {
+      const e = err;
+      if (e && typeof e === "object" && "exitCode" in e)
+        process.stderr.write(`${label}[transport] command failed — exitCode=${e.exitCode} error=${JSON.stringify(e.error)} stdout_tail=${String(e.stdout ?? "").slice(-200)} stderr_tail=${String(e.stderr ?? "").slice(-200)}
+`);
+      queue.push({ sentinel: "error", text: stderrBuffer.trim() ? `Agent process failed: ${formatError(err)}
+
+${stderrBuffer.trim()}` : `Agent process failed: ${formatError(err)}` });
+    }).finally(() => {
+      if (lineBuffer.trim()) {
+        try {
+          enqueue(translateEvent(JSON.parse(lineBuffer.trim())));
+        } catch {}
+      }
+      queue.push(null);
+      notify?.();
+      notify = null;
+    });
+    while (true) {
+      while (queue.length > 0) {
+        const item = queue.shift();
+        if (item === null)
+          return;
+        if ("sentinel" in item) {
+          yield { type: "error", text: item.text, timestamp: new Date().toISOString() };
+          return;
+        }
+        if (signal?.aborted)
+          return;
+        const msg = item;
+        yield msg.type === "error" && stderrBuffer.trim() && !msg.text.includes(stderrBuffer.trim()) ? { ...msg, text: `${msg.text}
+
+${stderrBuffer.trim()}` } : msg;
+      }
+      await new Promise((r) => {
+        notify = r;
+      });
+    }
+  }
+  async* sendMessage(opts) {
+    await this.deployGlobalConfig();
+    if (opts.sessionId) {
+      await this.sandbox.commands.run(`pkill -x claude 2>/dev/null || true`, { timeoutMs: 1e4 });
+    }
+    const maxTurns = this.options.maxTurns ?? 40;
+    const model = this.configModel ?? this.options.model ?? DEFAULT_CLAUDE_MODEL;
+    const label = this.label;
+    const promptFile = `/tmp/agent-prompt-${Date.now()}.txt`;
+    await this.sandbox.files.write(promptFile, opts.prompt);
+    const hasMcp = this.configMcpServers && Object.keys(this.configMcpServers).length > 0;
+    const allowedToolsFlag = !hasMcp && this.options.allowedTools?.length ? ["--allowedTools", this.options.allowedTools.join(",")] : [];
+    const buildCmd = (sessionId) => [
+      "claude",
+      "--dangerously-skip-permissions",
+      "--verbose",
+      "--output-format",
+      "stream-json",
+      "--max-turns",
+      String(maxTurns),
+      "--model",
+      model,
+      ...allowedToolsFlag,
+      ...sessionId ? ["--resume", sessionId] : [],
+      "-p",
+      `"$(cat ${promptFile})"`
+    ].join(" ");
+    const MAX_529_RETRIES = 5;
+    const BACKOFF_MS = [60000, 120000, 240000, 480000, 600000];
+    let resumeSessionId = opts.sessionId;
+    for (let attempt = 0;attempt <= MAX_529_RETRIES; attempt++) {
+      let got529 = false;
+      let newSession = "";
+      for await (const msg of this._runCli(buildCmd(resumeSessionId), label, opts.signal)) {
+        if (msg.type === "init")
+          newSession = msg.sessionId;
+        if (msg.type === "error" && msg.text.includes("529")) {
+          got529 = true;
+          break;
+        }
+        yield msg;
+        if (msg.type === "done" || msg.type === "error")
+          return;
+      }
+      if (!got529)
+        return;
+      if (attempt === MAX_529_RETRIES) {
+        yield { type: "error", text: "Agent process failed: Repeated 529 Overloaded errors — all retries exhausted", timestamp: new Date().toISOString() };
+        return;
+      }
+      if (newSession)
+        resumeSessionId = newSession;
+      const wait = BACKOFF_MS[attempt];
+      process.stderr.write(`
+${label}[529] Overloaded — resuming in ${wait / 1000}s (attempt ${attempt + 1}/${MAX_529_RETRIES})${resumeSessionId ? " with session resume" : ""}
+`);
+      await new Promise((r) => setTimeout(r, wait));
+    }
+  }
+}
+function createClaudeRuntime(config = {}) {
+  return defineRuntime({
+    create: (sandbox, opts) => new ClaudeRunner(sandbox, opts, config.claudeMdContent ?? "", config.env ?? {}, config.model, config.mcpServers)
+  });
+}
+var claude_default = createClaudeRuntime();
+// src/workflows/engine.ts
+class WorkflowError extends Error {
+  kind = "workflow";
+  constructor(message, options) {
+    super(message, options);
+    this.name = "WorkflowError";
+  }
+}
+
+class EngineError extends Error {
+  kind = "engine";
+  subsystem;
+  constructor(message, subsystem = "unknown", options) {
+    super(message, options);
+    this.name = "EngineError";
+    this.subsystem = subsystem;
+  }
+}
+function classifyError(err) {
+  if (err instanceof WorkflowError)
+    return "workflow";
+  if (err instanceof EngineError)
+    return "engine";
+  return "engine";
+}
+function parseNameVersion(ref) {
+  const atIdx = ref.lastIndexOf("@");
+  return atIdx > 0 ? { name: ref.slice(0, atIdx), version: ref.slice(atIdx + 1) } : { name: ref, version: undefined };
+}
+async function runWorkflow(wf, ctx, opts) {
+  const hooks = opts?.hooks ?? {};
+  const setMetadata = opts?.setMetadata ?? (async () => {});
+  const sandbox = makeLocalSandboxProvider();
+  let workflowErr;
+  let wfOutput;
+  try {
+    wfOutput = await wf({
+      ...ctx,
+      setMetadata,
+      step: async (name, fn) => {
+        const startedAt = Date.now();
+        hooks.onStepStart?.(name);
+        try {
+          const r = await fn();
+          hooks.onStepComplete?.(name, Date.now() - startedAt);
+          return r;
+        } catch (err) {
+          hooks.onStepFail?.(name, Date.now() - startedAt, formatError(err));
+          throw err;
+        }
+      }
+    }, sandbox);
+  } catch (err) {
+    workflowErr = err;
+  }
+  if (workflowErr !== undefined) {
+    if (workflowErr instanceof WorkflowError)
+      throw workflowErr;
+    throw new WorkflowError(formatError(workflowErr), { cause: workflowErr });
+  }
+  return { response: wfOutput ?? null };
+}
+// src/agent/run-agent.ts
+import { z as z3 } from "zod";
+
+// src/agent/protocol-suffix.md
+var protocol_suffix_default = '## Status Signal\n\nWhen you have finished your work or are blocked, emit a `<status>` block at the end of your response:\n\n```json\n<status>\n{\n  "summary": "one sentence describing what was done or what is blocking",\n  "completed": ["each acceptance criterion that is now fully met"],\n  "blockers": [],\n  "changed_files": ["relative/path/to/file"],\n  "tests_run": true,\n  "exit_signal": true\n}\n</status>\n```\n\n**Field semantics:**\n- `summary`: one sentence — what was accomplished or what is blocking\n- `completed`: acceptance criteria items that are fully done — be specific\n- `blockers`: non-empty when `exit_signal: false` — describe the exact obstacle\n- `changed_files`: relative paths of files you created or modified\n- `tests_run`: `true` if you ran any test suite (pass or fail); `false` if no tests exist or you skipped them\n- `exit_signal: true` — set when ALL acceptance criteria are met and no blockers remain\n- `exit_signal: false` — set when blocked or unfinished; `blockers` must be non-empty\n\n**If you are still actively working** and have not reached a natural stopping point, do NOT emit a `<status>` block — just keep working.\n\n**Example (done):**\n\n```json\n<status>\n{\n  "summary": "Added input validation middleware to /api/tasks with tests",\n  "completed": ["POST /api/tasks validates required fields", "Returns 400 with details on invalid input", "Unit tests passing"],\n  "blockers": [],\n  "changed_files": ["src/middleware/validate.ts", "src/routes/tasks.ts", "tests/validate.test.ts"],\n  "tests_run": true,\n  "exit_signal": true\n}\n</status>\n```\n\n**Example (blocked):**\n\n```json\n<status>\n{\n  "summary": "Implemented middleware but tests are failing due to module resolution",\n  "completed": ["Middleware created and wired into route"],\n  "blockers": ["Tests fail: cannot resolve import \'./validate\' — module resolution config unclear"],\n  "changed_files": ["src/middleware/validate.ts"],\n  "tests_run": true,\n  "exit_signal": false\n}\n</status>\n```\n';
+
+// src/agent/run-agent.ts
+var PROTOCOL_SUFFIX = stripFrontmatter(protocol_suffix_default);
+function stripFrontmatter(content) {
+  if (!content.startsWith("---"))
+    return content;
+  const end = content.indexOf(`
+---`, 3);
+  return end === -1 ? content : content.slice(end + 4).trimStart();
+}
+function inject(template, vars) {
+  return Object.entries(vars).reduce((t, [k, v]) => t.replaceAll(`{{${k}}}`, v), template);
+}
+function zodTypeName(schema) {
+  if (schema instanceof z3.ZodString)
+    return "string";
+  if (schema instanceof z3.ZodNumber)
+    return "number";
+  if (schema instanceof z3.ZodBoolean)
+    return "boolean";
+  if (schema instanceof z3.ZodArray)
+    return `${zodTypeName(schema.element)}[]`;
+  if (schema instanceof z3.ZodEnum)
+    return schema.options.map((o) => `"${o}"`).join(" | ");
+  if (schema instanceof z3.ZodOptional)
+    return `${zodTypeName(schema.unwrap())} (optional)`;
+  if (schema instanceof z3.ZodNullable)
+    return `${zodTypeName(schema.unwrap())} | null`;
+  if (schema instanceof z3.ZodLiteral)
+    return `"${String(schema.value)}"`;
+  if (schema instanceof z3.ZodObject)
+    return "object";
+  return "any";
+}
+function buildResponseFormatAppendix(schema) {
+  const header = ["## Response Format", "", "When you emit `exit_signal: true` in your `<status>` block, also include a `<response>` block containing JSON immediately after `<status>`:", ""];
+  const shape = schema instanceof z3.ZodObject ? schema.shape : null;
+  const body = shape ? (() => {
+    const entries = Object.entries(shape);
+    const example = Object.fromEntries(entries.map(([k, v]) => [k, `<${zodTypeName(v)}>`]));
+    return [
+      "Fields:",
+      ...entries.map(([k, v]) => `- \`${k}\` (${zodTypeName(v)})`),
+      "",
+      "Example:",
+      "<response>",
+      JSON.stringify(example, null, 2),
+      "</response>"
+    ];
+  })() : [
+    "The response must match this schema:",
+    `Expected type: ${zodTypeName(schema)}`,
+    "",
+    "Example:",
+    "<response>",
+    `<${zodTypeName(schema)}>`,
+    "</response>"
+  ];
+  return [...header, ...body].join(`
+`);
+}
+async function runAgent(opts) {
+  const workingDir = opts.workingDir ?? "";
+  const promptVars = { WORKING_DIR: workingDir, DIFF_BASE: "HEAD~1", ...opts.promptVars };
+  return agentLoop({
+    runtime: (runtimeOpts) => opts.runtime.create(opts.sandbox, runtimeOpts),
+    ...opts.label !== undefined ? { label: opts.label } : {},
+    ...opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {},
+    ...opts.budget?.maxIterations !== undefined ? { maxIterations: opts.budget.maxIterations } : {},
+    ...opts.tools !== undefined ? { allowedTools: opts.tools } : {},
+    ...opts.responseSchema !== undefined ? { responseSchema: opts.responseSchema } : {},
+    ...workingDir ? { cwd: workingDir } : {},
+    buildPrompt: (_lastStatus, iteration) => {
+      if (iteration > 0)
+        return PROTOCOL_SUFFIX;
+      const base = inject(stripFrontmatter(opts.prompt), promptVars);
+      return opts.responseSchema ? `${base}
+
+${PROTOCOL_SUFFIX}
+
+${buildResponseFormatAppendix(opts.responseSchema)}` : `${base}
+
+${PROTOCOL_SUFFIX}`;
+    },
+    ...opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {},
+    ...opts.onIteration ? { onIteration: opts.onIteration } : {}
+  });
+}
+export {
+  runWorkflow,
+  runAgent,
+  reconnectSandbox,
+  parseSseExecStream,
+  parseNameVersion,
+  parseAgentStatus,
+  parseAgentResponse,
+  makeSandboxProvider,
+  makeDesktopSandboxProvider,
+  listOwnedSandboxes,
+  killSandboxById,
+  killAllSandboxes,
+  importSourceModule,
+  getSandboxQuotas,
+  formatError,
+  discoverRuntimeName,
+  deleteSandboxSnapshot,
+  defineWorkflow,
+  defineSandboxEnvironment,
+  defineRuntime,
+  createSandbox,
+  createClaudeRuntime,
+  claude_default as claudeRuntime,
+  classifyError,
+  bundleWorkflow,
+  agentLoop,
+  WorkflowError,
+  TMP_DIR,
+  LATEST_VERSION,
+  EngineError,
+  DEFAULT_CLAUDE_MODEL,
+  ClaudeRunner,
+  AgentStatusSchema,
+  AgentMessageSchema,
+  AgentComposeError,
+  AgentComposeClient,
+  AGENT_COMPOSE_TAG
+};