@agent-compose/sdk 0.8.0 → 0.8.2

package/dist/index.js

@@ -959,6 +959,8 @@ function extractMetadata(source) {
     out.invokePolicy = freezeMetadataValue(source.invokePolicy);
   if (source.environmentBuild !== undefined)
     out.environmentBuild = source.environmentBuild;
+  if (source.factoryDrive !== undefined)
+    out.factoryDrive = source.factoryDrive;
   return Object.freeze(out);
 }
 function freezeMetadataValue(value) {
@@ -1446,14 +1448,47 @@ class AgentComposeClient {
         ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {},
         ...opts?.size !== undefined ? { size: opts.size } : {},
         ...parentRunId ? { parentRunId } : {},
-        ...opts?.agentId ? { agentId: opts.agentId } : {}
+        ...opts?.agentId ? { agentId: opts.agentId } : {},
+        ...opts?.funding !== undefined ? { funding: opts.funding } : {},
+        ...opts?.fundingSecret !== undefined ? { fundingSecret: opts.fundingSecret } : {}
+      }
+    });
+  }
+  invokeInline(workflow, input, opts) {
+    const parentRunId = opts?.parentRunId === undefined ? detectAmbientParentRunId() : opts.parentRunId;
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const headers = {};
+    if (opts?.idempotencyKey)
+      headers["Idempotency-Key"] = opts.idempotencyKey;
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/invoke`, {
+      method: "POST",
+      ...opts?.idempotencyKey ? { headers } : {},
+      body: {
+        workflow,
+        input,
+        ...opts?.title !== undefined ? { title: opts.title } : {},
+        ...opts?.snapshots !== undefined ? { snapshots: opts.snapshots } : {},
+        ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
+        ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {},
+        ...opts?.size !== undefined ? { size: opts.size } : {},
+        ...parentRunId ? { parentRunId } : {},
+        ...opts?.agentId ? { agentId: opts.agentId } : {},
+        ...opts?.funding !== undefined ? { funding: opts.funding } : {},
+        ...opts?.fundingSecret !== undefined ? { fundingSecret: opts.fundingSecret } : {}
       }
     });
   }
   async invokeAndWait(name, input, opts) {
+    const { id: runId } = await this.invoke(name, input, opts);
+    return this.waitForRun(runId, opts);
+  }
+  async invokeInlineAndWait(workflow, input, opts) {
+    const { id: runId } = await this.invokeInline(workflow, input, opts);
+    return this.waitForRun(runId, opts);
+  }
+  async waitForRun(runId, opts) {
     const timeoutMs = opts?.timeoutMs ?? 30 * 60 * 1000;
     const pollMs = opts?.pollIntervalMs ?? 1000;
-    const { id: runId } = await this.invoke(name, input, opts);
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
       const status = await this.getStatus(runId);
@@ -1462,7 +1497,7 @@ class AgentComposeClient {
       }
       await new Promise((r) => setTimeout(r, pollMs));
     }
-    throw new AgentComposeError(504, `invokeAndWait: run ${runId} did not settle within ${timeoutMs}ms`);
+    throw new AgentComposeError(504, `waitForRun: run ${runId} did not settle within ${timeoutMs}ms`);
   }
   async listSnapshots(opts) {
     const body = await this.listSnapshotsPage(opts);
@@ -1598,6 +1633,11 @@ class AgentComposeClient {
       preview: a.preview
     }));
   }
+  async getRunArtifactBytes(runId, path) {
+    const q2 = new URLSearchParams({ path });
+    const buf = await this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/artifacts/content?${q2}`, { responseType: "arrayBuffer" });
+    return new Uint8Array(buf);
+  }
   async putFactoryFile(path, content, opts) {
     const factorySlug = opts?.factorySlug ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined) ?? DEFAULT_FACTORY;
     const runToken = typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_RUN_TOKEN : undefined;
@@ -1621,12 +1661,28 @@ class AgentComposeClient {
     const q2 = new URLSearchParams({ path });
     if (opts?.revision !== undefined)
       q2.set("revision", String(opts.revision));
+    if (opts?.branch !== undefined)
+      q2.set("branch", opts.branch);
     const buf = await this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?${q2}`, { responseType: "arrayBuffer" });
     return new Uint8Array(buf);
   }
   async getFactoryFile(path, opts) {
     return new TextDecoder().decode(await this.getFactoryFileBytes(path, opts));
   }
+  async createDriveMountSession(opts) {
+    const factorySlug = opts?.factorySlug ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined) ?? DEFAULT_FACTORY;
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files/mount-sessions`, {
+      method: "POST",
+      body: {
+        ...opts?.conversationId ? { conversationId: opts.conversationId } : {},
+        ...opts?.host ? { host: opts.host } : {}
+      }
+    });
+  }
+  async releaseDriveMountSession(conversationId, opts) {
+    const factorySlug = opts?.factorySlug ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined) ?? DEFAULT_FACTORY;
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files/mount-sessions/${encodeURIComponent(conversationId)}/release`, { method: "POST", body: {} });
+  }
   listConversations(opts) {
     const q2 = new URLSearchParams;
     if (opts?.cursor)
@@ -1639,8 +1695,9 @@ class AgentComposeClient {
       q2.set("cursor", opts.cursor);
     return this.fetch(`/api/v1/sessions?${q2}`);
   }
-  getConversation(id) {
-    return this.fetch(`/api/v1/conversations/${encodeURIComponent(id)}`);
+  getConversation(id, opts) {
+    const q2 = opts?.limit !== undefined ? `?limit=${opts.limit}` : "";
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(id)}${q2}`);
   }
   createCloudSession(input) {
     return this.fetch(`/api/v1/sessions/cloud`, {
@@ -1658,7 +1715,10 @@ class AgentComposeClient {
         ...input.templateId ? { templateId: input.templateId } : {},
         ...input.sandboxSize ? { sandboxSize: input.sandboxSize } : {},
         ...input.networkPolicy !== undefined ? { networkPolicy: input.networkPolicy } : {},
-        ...input.connectorProfileId !== undefined ? { connectorProfileId: input.connectorProfileId } : {}
+        ...input.connectorProfileId !== undefined ? { connectorProfileId: input.connectorProfileId } : {},
+        ...input.setupCommand !== undefined ? { setupCommand: input.setupCommand } : {},
+        ...input.handoffOrigin !== undefined ? { handoffOrigin: input.handoffOrigin } : {},
+        ...input.seedFiles !== undefined ? { seedFiles: input.seedFiles } : {}
       }
     });
   }
@@ -1696,6 +1756,13 @@ class AgentComposeClient {
     const body = await this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/preview/${port}`, { method: "DELETE" });
     return body.closed;
   }
+  holdBackgroundWork(conversationId, input) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/background-work`, { method: "POST", body: { ...input?.minutes !== undefined ? { minutes: input.minutes } : {} } });
+  }
+  async releaseBackgroundWork(conversationId) {
+    const body = await this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/background-work`, { method: "DELETE" });
+    return body.released;
+  }
   forkSession(conversationId, input) {
     return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/fork`, { method: "POST", body: input?.title ? { title: input.title } : {} });
   }
@@ -1945,7 +2012,7 @@ class AgentComposeClient {
   async createRepoLink(input, opts) {
     const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
     const body = await this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}/repo-links`, { method: "POST", body: input });
-    return body.link;
+    return body.links;
   }
   deleteRepoLink(linkId, opts) {
     const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
@@ -1969,9 +2036,17 @@ class AgentComposeClient {
   createApiKey(input) {
     return this.fetch("/api-keys", { method: "POST", body: input });
   }
-  async listApiKeys() {
-    const body = await this.fetch("/api-keys");
-    return body.data;
+  async listApiKeys(opts) {
+    const qs = new URLSearchParams;
+    if (opts?.limit !== undefined)
+      qs.set("limit", String(opts.limit));
+    if (opts?.status !== undefined)
+      qs.set("status", opts.status);
+    if (opts?.cursor !== undefined)
+      qs.set("cursor", opts.cursor);
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    const body = await this.fetch(`/api-keys${suffix}`);
+    return { data: body.data, hasMore: body.has_more, nextCursor: body.next_cursor ?? null };
   }
   getUsage(from, to) {
     const qs = `?from=${encodeURIComponent(from.toISOString())}&to=${encodeURIComponent(to.toISOString())}`;
@@ -2466,6 +2541,7 @@ class AcpClientPeer {
 }
 // src/utils/bundler.ts
 import { createHash as createHash2 } from "node:crypto";
+import { dirname as dirname2 } from "node:path";
 import { parse as babelParse } from "@babel/parser";
 
 // src/utils/source-loader.ts
@@ -2495,15 +2571,119 @@ class WorkflowSourceValidationError extends Error {
     this.name = "WorkflowSourceValidationError";
   }
 }
+var SDK_PACKAGE = "@agent-compose/sdk";
+var SDK_SPECIFIER_ALIASES = [
+  "agentc/sdk",
+  "@agentc/sdk",
+  "agentc-sdk",
+  "agent-compose/sdk",
+  "agentcompose/sdk",
+  "@agentcompose/sdk",
+  "agent-compose-sdk"
+];
+var SDK_ALIAS_SET = new Set(SDK_SPECIFIER_ALIASES);
+function resolveSdkAlias(specifier) {
+  return SDK_ALIAS_SET.has(specifier) ? SDK_PACKAGE : null;
+}
+function aliasFilter() {
+  const alternation = SDK_SPECIFIER_ALIASES.map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+  return new RegExp(`^(?:${alternation})$`);
+}
+function sdkAliasPlugin(bun) {
+  return {
+    name: "agent-compose-sdk-alias",
+    setup(build) {
+      build.onResolve({ filter: aliasFilter() }, (args) => {
+        const target = resolveSdkAlias(args.path);
+        if (!target)
+          return;
+        const from = args.importer ? dirname2(args.importer) : args.resolveDir;
+        try {
+          return { path: bun.resolveSync(target, from && from.length > 0 ? from : process.cwd()) };
+        } catch {
+          return;
+        }
+      });
+    }
+  };
+}
+function readUnresolvedSpecifier(diag) {
+  if (!diag || typeof diag !== "object")
+    return null;
+  const d = diag;
+  if (typeof d.specifier === "string" && d.specifier.length > 0)
+    return d.specifier;
+  const message = typeof d.message === "string" ? d.message : "";
+  const m = /Could not resolve:?\s*"([^"]+)"/.exec(message);
+  return m ? m[1] : null;
+}
+function flattenDiagnostics(failure) {
+  const out = [];
+  const seen = new Set;
+  const walk = (node, depth) => {
+    if (!node || depth > 4 || seen.has(node))
+      return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+      for (const sub of node)
+        walk(sub, depth + 1);
+      return;
+    }
+    out.push(node);
+    if (typeof node === "object") {
+      const n = node;
+      if (Array.isArray(n.errors))
+        for (const sub of n.errors)
+          walk(sub, depth + 1);
+      if (n.cause)
+        walk(n.cause, depth + 1);
+    }
+  };
+  walk(failure, 0);
+  return out;
+}
+function diagnosticText(diag) {
+  if (diag instanceof Error)
+    return diag.message || String(diag);
+  if (diag && typeof diag === "object" && typeof diag.message === "string") {
+    return diag.message;
+  }
+  return String(diag);
+}
+function explainBundleFailure(err, label) {
+  const diagnostics = flattenDiagnostics(err);
+  const unresolved = [];
+  for (const diag of diagnostics) {
+    const specifier = readUnresolvedSpecifier(diag);
+    if (specifier && !unresolved.includes(specifier))
+      unresolved.push(specifier);
+  }
+  if (unresolved.length > 0) {
+    const quoted = unresolved.map((s) => `"${s}"`).join(", ");
+    return `Could not resolve ${quoted} — workflow source imports the platform SDK as "${SDK_PACKAGE}". ` + `Fix the import specifier in ${label}; anything that is genuinely a third-party ` + `package must be installed where the source is bundled.`;
+  }
+  const detail = diagnostics.map(diagnosticText).filter((t) => t.length > 0 && t !== "Bundle failed").join(`
+`);
+  return `Failed to bundle ${label}:
+${detail || "the bundler reported no diagnostics"}`;
+}
 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: "node" });
+  let result;
+  try {
+    result = await bun.Bun.build({
+      entrypoints: [path],
+      format: "esm",
+      target: "node",
+      plugins: [sdkAliasPlugin(bun.Bun)]
+    });
+  } catch (err) {
+    throw new WorkflowSourceValidationError(explainBundleFailure(err, label));
+  }
   if (!result.success) {
-    throw new Error(`Failed to bundle ${label}:
-${result.logs.map((l) => l.message).join(`
-`)}`);
+    throw new WorkflowSourceValidationError(explainBundleFailure(result.logs, label));
   }
   return result.outputs[0].text();
 }
@@ -2621,7 +2801,8 @@ async function bundleWorkflow(workflowPath, overrides) {
     ...metadata.connectors !== undefined ? { connectors: metadata.connectors } : {},
     ...metadata.connectorOperation !== undefined ? { connectorOperation: metadata.connectorOperation } : {},
     ...metadata.invokePolicy !== undefined ? { invokePolicy: metadata.invokePolicy } : {},
-    ...metadata.environmentBuild !== undefined ? { environmentBuild: metadata.environmentBuild } : {}
+    ...metadata.environmentBuild !== undefined ? { environmentBuild: metadata.environmentBuild } : {},
+    ...metadata.factoryDrive !== undefined ? { factoryDrive: metadata.factoryDrive } : {}
   };
 }
 function extractIOSchema(zodSchema) {
@@ -3019,7 +3200,8 @@ async function agentLoop(opts) {
       label,
       allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
       ...client.model != null ? { model: client.model } : {},
-      ...client.kind != null ? { runtimeKind: client.kind } : {}
+      ...client.kind != null ? { runtimeKind: client.kind } : {},
+      ...opts.phase != null ? { phase: opts.phase } : {}
     });
   }
   const flushState = async (currentIteration) => {
@@ -3616,6 +3798,29 @@ function wrapJsonlCommand(args) {
 function now4() {
   return new Date().toISOString();
 }
+var TAIL_REATTACH_DELAY_MS = 2000;
+var LAUNCH_EXEC_TIMEOUT_MS = 30000;
+var LAUNCH_PID_RECOVERY_ATTEMPTS = 3;
+var LAUNCH_PID_RECOVERY_DELAY_MS = 1000;
+var INSTALL_PROBE_TIMEOUT_MS = 30000;
+function parsePid(raw) {
+  const pid = Number.parseInt(raw.trim().split(`
+`).pop() ?? "", 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : Number.NaN;
+}
+async function recoverLaunchPid(read, pidPath) {
+  for (let attempt = 0;attempt < LAUNCH_PID_RECOVERY_ATTEMPTS; attempt++) {
+    try {
+      const pid = parsePid(await read(pidPath));
+      if (!Number.isNaN(pid))
+        return pid;
+    } catch {}
+    if (attempt < LAUNCH_PID_RECOVERY_ATTEMPTS - 1) {
+      await new Promise((r) => setTimeout(r, LAUNCH_PID_RECOVERY_DELAY_MS));
+    }
+  }
+  return Number.NaN;
+}
 function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -3701,7 +3906,7 @@ class CliAgentRunner {
   async ensureInstalled() {
     if (this.installed)
       return;
-    const probe = await this.sandbox.commands.run(`command -v ${this.spec.bin}`);
+    const probe = await this.sandbox.commands.run(`command -v ${this.spec.bin}`, { timeoutMs: INSTALL_PROBE_TIMEOUT_MS });
     if (probe.exitCode === 0) {
       this.installed = true;
       return;
@@ -3866,51 +4071,153 @@ class CliAgentRunner {
         keepBytes: JSONL_GUARD_KEEP_BYTES
       });
       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 runOpts = {
-        ...this.options.cwd ? { cwd: this.options.cwd } : {},
-        onStdout,
-        timeoutMs: 0
-      };
-      let exited = false;
-      const settle = (res) => {
-        exited = true;
-        const tail = buf.trim();
-        if (tail)
-          lines.push(tail);
-        lines.close();
-        return res;
-      };
-      const fail = (err) => {
-        exited = true;
-        lines.close();
-        throw err;
-      };
-      let kill;
-      let runPromise;
+      let exitCode = null;
+      let exitStderr = "";
+      let transportError = null;
+      let consumerStopped = false;
+      let reap = () => {};
+      let transport;
+      const durableRead = this.sandbox.files.read?.bind(this.sandbox.files);
       if (this.sandbox.commands.runBackground) {
-        const handle = await this.sandbox.commands.runBackground(guardedCmd, runOpts);
-        kill = () => handle.kill();
-        runPromise = handle.wait().then(settle, fail);
+        const outPath = `${promptPath}.out`;
+        const errPath = `${promptPath}.err`;
+        const detachedScript = `{ ${guardedCmd}; } >> ${shellQuote(outPath)} 2>> ${shellQuote(errPath)} </dev/null; ` + `printf '\\n%s %s\\n' ${shellQuote(sentinel)} "$?" >> ${shellQuote(outPath)}`;
+        const pidPath = `${promptPath}.pid`;
+        const launchCmd = `: > ${shellQuote(outPath)}; : > ${shellQuote(errPath)}; ` + `if command -v setsid >/dev/null 2>&1; then setsid sh -c ${shellQuote(detachedScript)} >/dev/null 2>&1 </dev/null & ` + `else sh -c ${shellQuote(detachedScript)} >/dev/null 2>&1 </dev/null & fi; ` + `echo "$!" > ${shellQuote(pidPath)}; echo "$!"`;
+        let pid = Number.NaN;
+        let launched = null;
+        let launchErr = null;
+        try {
+          launched = await this.sandbox.commands.run(launchCmd, {
+            ...this.options.cwd ? { cwd: this.options.cwd } : {},
+            timeoutMs: LAUNCH_EXEC_TIMEOUT_MS
+          });
+        } catch (err) {
+          launchErr = err;
+        }
+        if (launched) {
+          pid = parsePid(launched.stdout ?? "");
+          if (launched.exitCode !== 0 || Number.isNaN(pid)) {
+            throw new Error(`failed to launch ${this.spec.kind}: ` + `exit ${launched.exitCode}${launched.stderr ? `: ${launched.stderr.slice(-500)}` : ""}`);
+          }
+        } else {
+          pid = durableRead ? await recoverLaunchPid(durableRead, pidPath) : Number.NaN;
+          if (Number.isNaN(pid))
+            throw launchErr;
+          console.warn(`[cli-agent] ${this.spec.kind} launch exec stream died but the detached runner is up ` + `(pid ${pid} via ${pidPath}) — continuing on the durable transport: ${formatError(launchErr)}`);
+        }
+        let offset = 0;
+        let currentTail = null;
+        const consumeLine = (raw) => {
+          offset += Buffer.byteLength(raw, "utf8") + 1;
+          const line = raw.trim();
+          if (!line)
+            return;
+          if (line.startsWith(sentinel)) {
+            const code = Number(line.slice(sentinel.length).trim());
+            exitCode = Number.isFinite(code) ? code : 0;
+            return;
+          }
+          lines.push(line);
+        };
+        reap = () => {
+          this.sandbox.commands.run(`kill -TERM -- -${pid} 2>/dev/null; kill -TERM ${pid} 2>/dev/null; true`, { timeoutMs: 1e4 }).catch(() => {});
+          currentTail?.kill().catch(() => {});
+        };
+        transport = (async () => {
+          while (exitCode === null && !consumerStopped && !opts.signal?.aborted) {
+            let buf = "";
+            let handle = null;
+            const onStdout = (data) => {
+              buf += data;
+              let nl;
+              while ((nl = buf.indexOf(`
+`)) >= 0) {
+                consumeLine(buf.slice(0, nl));
+                buf = buf.slice(nl + 1);
+                if (exitCode !== null) {
+                  handle?.kill().catch(() => {});
+                  return;
+                }
+              }
+            };
+            try {
+              handle = await this.sandbox.commands.runBackground(`tail -c +${offset + 1} -f ${shellQuote(outPath)}`, { timeoutMs: 0, onStdout });
+            } catch {}
+            if (handle) {
+              if (exitCode !== null)
+                handle.kill().catch(() => {});
+              currentTail = handle;
+              await handle.wait().catch(() => {
+                return;
+              });
+              currentTail = null;
+            }
+            if (exitCode !== null || consumerStopped || opts.signal?.aborted)
+              break;
+            if (durableRead) {
+              try {
+                const bytes = Buffer.from(await durableRead(outPath), "utf8");
+                let rest = bytes.subarray(offset).toString("utf8");
+                let nl;
+                while (exitCode === null && (nl = rest.indexOf(`
+`)) >= 0) {
+                  consumeLine(rest.slice(0, nl));
+                  rest = rest.slice(nl + 1);
+                }
+              } catch {}
+            }
+            if (exitCode !== null)
+              break;
+            let alive = null;
+            try {
+              const probe = await this.sandbox.commands.run(`kill -0 ${pid} 2>/dev/null`, { timeoutMs: 1e4 });
+              alive = probe.exitCode === 0;
+            } catch {
+              alive = null;
+            }
+            if (alive === false) {
+              exitCode = JSONL_GUARD_NO_SENTINEL_EXIT;
+              break;
+            }
+            console.warn(`[cli-agent] ${this.spec.kind} turn stream lost with the runner alive — re-tailing ${outPath} from byte ${offset}`);
+            await new Promise((r) => setTimeout(r, TAIL_REATTACH_DELAY_MS));
+          }
+          if (exitCode !== null && exitCode !== 0 && durableRead) {
+            try {
+              exitStderr = (await durableRead(errPath)).slice(-2000);
+            } catch {}
+          }
+        })().finally(() => lines.close());
       } else {
-        runPromise = this.sandbox.commands.run(guardedCmd, runOpts).then(settle, fail);
+        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 runOpts = {
+          ...this.options.cwd ? { cwd: this.options.cwd } : {},
+          onStdout,
+          timeoutMs: 0
+        };
+        transport = this.sandbox.commands.run(guardedCmd, runOpts).then((res) => {
+          const tail = buf.trim();
+          if (tail)
+            lines.push(tail);
+          exitCode = res.exitCode;
+          exitStderr = (res.stderr ?? "").slice(-2000);
+        }, (err) => {
+          transportError = err;
+        }).finally(() => lines.close());
       }
-      runPromise.catch(() => {});
-      const reap = () => {
-        if (!exited)
-          kill?.().catch(() => {});
-      };
+      transport.catch(() => {});
       if (opts.signal) {
         if (opts.signal.aborted)
           reap();
@@ -3934,18 +4241,28 @@ class CliAgentRunner {
             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: now4() };
+        await transport;
+        if (transportError)
+          throw transportError;
+        if (exitCode === null) {
+          if (!sawError) {
+            yield { type: "error", text: `${this.spec.kind} aborted — the in-sandbox runner was terminated`, timestamp: now4() };
+          }
+          return;
+        }
+        if (exitCode !== 0 && !sawError) {
+          const detail = exitCode === JSONL_GUARD_NO_SENTINEL_EXIT ? " (the runner died without reporting an exit code)" : "";
+          yield { type: "error", text: `${this.spec.kind} exited with code ${exitCode}${detail}${exitStderr ? `: ${exitStderr}` : ""}`, timestamp: now4() };
           return;
         }
         if (!sawError)
           yield { type: "done", sessionId: sessionId ?? "", timestamp: now4() };
       } finally {
         opts.signal?.removeEventListener("abort", reap);
-        reap();
-        this.sandbox.commands.run(`rm -f ${shellQuote(promptPath)} ${shellQuote(guardPath)}`, { timeoutMs: 1e4 }).catch(() => {});
+        consumerStopped = true;
+        if (exitCode === null)
+          reap();
+        this.sandbox.commands.run(`rm -f ${shellQuote(promptPath)} ${shellQuote(guardPath)} ${shellQuote(`${promptPath}.out`)} ${shellQuote(`${promptPath}.err`)} ${shellQuote(`${promptPath}.pid`)}`, { timeoutMs: 1e4 }).catch(() => {});
       }
     } catch (err) {
       yield { type: "error", text: formatError(err), timestamp: now4() };
@@ -3986,11 +4303,11 @@ var codexSpec = {
       "--skip-git-repo-check",
       "--dangerously-bypass-approvals-and-sandbox",
       ...model ? ["-m", shellQuote(model)] : [],
-      ...effort ? ["-c", `model_reasoning_effort=${effort}`] : [],
-      ...cwd ? ["-C", shellQuote(cwd)] : []
+      ...effort ? ["-c", `model_reasoning_effort=${effort === "max" ? "xhigh" : effort}`] : []
     ].join(" ");
+    const cd = cwd ? `cd ${shellQuote(cwd)} && ` : "";
     const exec = sessionId ? `codex exec resume ${shellQuote(sessionId)} ${flags}` : `codex exec ${flags}`;
-    return `${exec} - < ${shellQuote(promptPath)}`;
+    return `${cd}${exec} - < ${shellQuote(promptPath)}`;
   },
   extractSessionId: (p) => p.type === "thread.started" && typeof p.thread_id === "string" ? p.thread_id : undefined,
   mapEvent: (p) => {
@@ -4208,7 +4525,7 @@ function toolResultText(content) {
   }
   return content == null ? "" : JSON.stringify(content) ?? "";
 }
-var CLAUDE_CODE_THINKING_TOKENS = { low: 2048, medium: 8192, high: 16384 };
+var CLAUDE_CODE_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 var claudeCodeSpec = {
   kind: "claude-code",
   authEnv: "ANTHROPIC_API_KEY",
@@ -4224,14 +4541,15 @@ var claudeCodeSpec = {
       "--include-partial-messages",
       "--dangerously-skip-permissions",
       ...model ? [`--model ${shellQuote(model)}`] : [],
+      ...effort ? [`--effort ${effort}`] : [],
       ...sessionId ? [`--resume ${shellQuote(sessionId)}`] : []
     ].join(" ");
-    const thinking = effort ? `MAX_THINKING_TOKENS=${CLAUDE_CODE_THINKING_TOKENS[effort]} ` : "";
-    return `${cwd ? `cd ${shellQuote(cwd)} && ` : ""}${thinking}IS_SANDBOX=1 claude ${flags} < ${shellQuote(promptPath)}`;
+    return `${cwd ? `cd ${shellQuote(cwd)} && ` : ""}IS_SANDBOX=1 claude ${flags} < ${shellQuote(promptPath)}`;
   },
   extractSessionId: (p) => typeof p.session_id === "string" ? p.session_id : undefined,
   mapEvent: (p) => {
     const ts = now10();
+    const parent = typeof p.parent_tool_use_id === "string" && p.parent_tool_use_id.length > 0 ? { parentToolUseId: p.parent_tool_use_id } : {};
     switch (p.type) {
       case "assistant": {
         const message = p.message;
@@ -4249,6 +4567,7 @@ var claudeCodeSpec = {
               toolName: String(b.name ?? "tool"),
               toolInput: b.input ?? {},
               toolUseId: String(b.id ?? ""),
+              ...parent,
               timestamp: ts
             }];
           }
@@ -4263,6 +4582,7 @@ var claudeCodeSpec = {
           toolUseId: String(b.tool_use_id ?? ""),
           output: toolResultText(b.content),
           isError: b.is_error === true,
+          ...parent,
           timestamp: ts
         }] : []);
       }
@@ -4382,23 +4702,36 @@ function toE2bNetwork(policy) {
 }
 
 // src/sandbox/sizes.ts
-var SANDBOX_VCPUS = {
-  "2vcpu-4gb": 2,
-  "4vcpu-8gb": 4,
-  "8vcpu-16gb": 8,
-  "32vcpu-64gb": 32
+var SANDBOX_MACHINES = {
+  "1vcpu-2gb": { vcpus: 1, memoryMB: 2048 },
+  "2vcpu-4gb": { vcpus: 2, memoryMB: 4096 },
+  "4vcpu-8gb": { vcpus: 4, memoryMB: 8192 },
+  "8vcpu-8gb": { vcpus: 8, memoryMB: 8192 },
+  "8vcpu-16gb": { vcpus: 8, memoryMB: 16384 },
+  "32vcpu-64gb": { vcpus: 32, memoryMB: 65536 }
 };
+var SANDBOX_SIZES = Object.keys(SANDBOX_MACHINES);
+var SANDBOX_VCPUS = Object.fromEntries(SANDBOX_SIZES.map((s) => [s, SANDBOX_MACHINES[s].vcpus]));
 var DEFAULT_SANDBOX_SIZE = "2vcpu-4gb";
-var E2B_TEMPLATE_SIZES = [
-  "2vcpu-4gb",
-  "4vcpu-8gb"
-];
+var SESSION_DEFAULT_SANDBOX_SIZE = "4vcpu-8gb";
+var E2B_MAX_VCPUS = 8;
+var E2B_MAX_MEMORY_MB = 8192;
+var E2B_TEMPLATE_SIZES = SANDBOX_SIZES.filter((s) => SANDBOX_MACHINES[s].vcpus <= E2B_MAX_VCPUS && SANDBOX_MACHINES[s].memoryMB <= E2B_MAX_MEMORY_MB);
 function isE2bSupportedSize(size) {
   return E2B_TEMPLATE_SIZES.includes(size);
 }
+var VERCEL_MEMORY_MB_PER_VCPU = 2048;
+function isVercelSupportedSize(size) {
+  const m = SANDBOX_MACHINES[size];
+  return m.memoryMB === m.vcpus * VERCEL_MEMORY_MB_PER_VCPU;
+}
 function e2bMachineSpec(size) {
-  const cpuCount = SANDBOX_VCPUS[size];
-  return { cpuCount, memoryMB: cpuCount * 2048 };
+  const m = SANDBOX_MACHINES[size];
+  return { cpuCount: m.vcpus, memoryMB: m.memoryMB };
+}
+function sandboxSizeLabel(size) {
+  const m = SANDBOX_MACHINES[size];
+  return `${m.vcpus} vCPU · ${Math.round(m.memoryMB / 1024)} GB`;
 }
 function e2bBaseTemplate(size) {
   return `agent-compose-base-${size}`;
@@ -4615,7 +4948,7 @@ function makeE2bSandboxProvider(sb) {
       return { resumeHandle: sb.sandboxId };
     },
     async extendLifetime(ms) {
-      await sb.setTimeout(ms);
+      await sb.setTimeout(Math.min(ms, e2bMaxSandboxMs()));
     },
     async updateNetworkPolicy(policy) {
       await sb.updateNetwork(toE2bNetwork(policy));
@@ -4892,7 +5225,7 @@ var vercelProviderDef = {
 
 // src/sandbox/providers/local.ts
 import { promises as fs2 } from "node:fs";
-import { dirname as dirname2 } from "node:path";
+import { dirname as dirname3 } from "node:path";
 import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 function makeLocalSandboxProvider() {
@@ -4958,7 +5291,7 @@ function makeLocalSandboxProvider() {
     },
     files: {
       async write(path, content) {
-        await fs2.mkdir(dirname2(path), { recursive: true });
+        await fs2.mkdir(dirname3(path), { recursive: true });
         await fs2.writeFile(path, content);
       },
       async read(path) {
@@ -5509,6 +5842,15 @@ async function runWorkflow(wf, ctx, opts) {
   }
 }
 // src/workflows/invoke-child.ts
+function deriveInvokeChildIdempotencyKey(parentRunId, childName) {
+  const step = getActiveStep();
+  if (!step)
+    return null;
+  const ordinal = nextPauseOrdinalInActiveStep(`invoke-child:${childName}`);
+  if (ordinal === null)
+    return null;
+  return `invoke-child:${parentRunId}:step${step.stepIndex}:${childName}:${ordinal}`;
+}
 function buildInvokeChild(runId, opts = {}) {
   let childClient = null;
   const getChildClient = () => {
@@ -5522,11 +5864,15 @@ function buildInvokeChild(runId, opts = {}) {
     childClient = new AgentComposeClient({ apiKey, baseUrl });
     return childClient;
   };
-  return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {
-    ...childOpts,
-    parentRunId: runId,
-    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug ?? process.env.AGENT_COMPOSE_FACTORY ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default"
-  });
+  return (name, input, childOpts) => {
+    const idempotencyKey = childOpts?.idempotencyKey ?? deriveInvokeChildIdempotencyKey(runId, name) ?? undefined;
+    return getChildClient().invokeAndWait(name, input, {
+      ...childOpts,
+      ...idempotencyKey !== undefined ? { idempotencyKey } : {},
+      parentRunId: runId,
+      factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug ?? process.env.AGENT_COMPOSE_FACTORY ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default"
+    });
+  };
 }
 // src/workflow-steps/step.ts
 var CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
@@ -6256,38 +6602,49 @@ there is nothing to type, paste, or screenshot a credential from.
 
 ## Recording a demo — the desktop, captured to a video the human can play
 
-"Record a demo of you using X" is a normal ask, and this machine does it:
-start a screen recording, drive the app with \`xdotool\` exactly as in Computer
-Use, stop the recording, and report the file. (For a LIVE view no recording is
-needed — the session header's **Desktop** button already streams this display
-to any teammate watching; a recording is the durable, replayable artifact.
-Both modes exist; say so when it matters.)
+"Record a demo of you using X" is a normal ask, and this machine does it.
+(For a LIVE view no recording is needed — the session header's **Desktop**
+button already streams this display to any teammate watching; a recording is
+the durable, replayable artifact. Both modes exist; say so when it matters.)
 
-**ffmpeg is NOT pre-installed** — install it first, once per machine:
+**Use \`ac-record\` — the platform recorder is already on PATH** (cloud
+sessions; \`command -v ac-record\` to confirm on older machines):
 
-    sudo apt-get update -q && sudo apt-get install -y -q ffmpeg
+    ac-record start     # begins capturing the desktop (display :0)
+    # ... drive the app with xdotool, screenshotting as you go ...
+    ac-record stop      # finishes + saves to recordings/ in your workspace
+    ac-record status    # one JSON line: {"recording":true,...}
 
-(drop \`sudo\` if you are already root). Then the whole recipe:
+It records the whole display (with desktop audio when the machine has a
+PulseAudio monitor), enforces sane caps (5 min / 200 MB — start a fresh
+recording per scene rather than one long take), keeps the file playable even
+if the machine dies mid-take, and \`stop\` prints the saved path — the file
+lands ON THE DRIVE in \`recordings/\`, visible in Files and playable in the
+dashboard. A human watching the Desktop pane sees the recording indicator
+while you record.
+
+If \`ac-record\` is missing (older machine), record by hand.
+**ffmpeg IS pre-installed** on platform images (\`command -v ffmpeg\`; only
+if absent: \`sudo apt-get update -q && sudo apt-get install -y -q ffmpeg\`):
 
     DISPLAY=:0 ffmpeg -f x11grab \\
       -video_size "$(DISPLAY=:0 xdotool getdisplaygeometry | tr ' ' x)" \\
       -framerate 10 -i :0 -c:v libvpx -b:v 1M -deadline realtime -cpu-used 8 \\
       demo.webm &
     FFMPEG_PID=$!
-    # ... drive the app with xdotool, screenshotting as you go ...
+    # ... drive the app with xdotool ...
     kill -INT "$FFMPEG_PID" && wait "$FFMPEG_PID"
 
-The gotchas, each one earned:
+The hand-rolled gotchas, each one earned:
 - **Stop with SIGINT (\`kill -INT\`), never SIGKILL** — ffmpeg finalizes the
   file on SIGINT; a hard kill truncates the encode mid-write.
-- **Record WebM (matroska-family), not MP4** — mp4 writes its moov atom at the
-  END, so a killed or crashed encode leaves an UNPLAYABLE file; webm stays
-  playable up to the last written frame and plays natively in the browser.
-  MP4's only edge is compatibility with some external players — transcode
-  afterwards if you truly need it, never record straight to it.
+- **Record WebM (matroska-family), not plain MP4** — mp4 writes its moov atom
+  at the END, so a killed or crashed encode leaves an UNPLAYABLE file; webm
+  stays playable up to the last written frame and plays natively in the
+  browser. (\`ac-record\` sidesteps this with fragmented mp4.)
 - **\`-video_size\` must match the real screen** — x11grab does not default to
   it; read the geometry from \`xdotool getdisplaygeometry\` as above.
-- **10–12 fps is right for a screen demo** — small files, legible UI motion;
+- **10–15 fps is right for a screen demo** — small files, legible UI motion;
   this is not video production.
 - **Write to the drive, not /tmp** — the recording must land in your working
   directory to persist and show up in Files; a file in /tmp dies with the
@@ -6599,6 +6956,7 @@ async function agent(opts) {
       runtime: (runtimeOpts) => opts.runtime.create(opts.sandbox, { ...runtimeOpts, agentManual: buildAgentContextDoc(process.env) }),
       agentId,
       ...opts.label !== undefined ? { label: opts.label } : {},
+      ...opts.phase !== undefined ? { phase: opts.phase } : {},
       ...opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {},
       ...opts.budget?.maxIterations !== undefined ? { maxIterations: opts.budget.maxIterations } : {},
       ...opts.tools !== undefined ? { allowedTools: opts.tools } : {},
@@ -6669,7 +7027,21 @@ function clampPlanEntries(raw) {
 var TABLE_MAX_COLUMNS = 12;
 var TABLE_MAX_ROWS = 100;
 var TABLE_CELL_MAX_CHARS = 200;
-var IMAGE_PATH_MAX_CHARS = 512;
+var DRIVE_PATH_MAX_CHARS = 512;
+function isPlausibleDrivePath(raw) {
+  if (raw.trim().length === 0 || raw.length > DRIVE_PATH_MAX_CHARS)
+    return false;
+  if (raw.startsWith("-"))
+    return false;
+  if (/[\u0000-\u001f\u007f\\]/.test(raw))
+    return false;
+  if (/[|<>;`]|\$\(/.test(raw))
+    return false;
+  const trimmed = raw.replace(/^\/+|\/+$/g, "");
+  if (trimmed.length === 0)
+    return false;
+  return trimmed.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
+}
 function clampCellString(s) {
   return s.length > TABLE_CELL_MAX_CHARS ? `${s.slice(0, TABLE_CELL_MAX_CHARS - 1)}…` : s;
 }
@@ -6860,7 +7232,7 @@ function parseDisplayMarker(line) {
     }
     case "document": {
       const path = str("path");
-      if (!path)
+      if (!path || !isPlausibleDrivePath(path))
         return null;
       return {
         kind: "document",
@@ -6875,7 +7247,7 @@ function parseDisplayMarker(line) {
     }
     case "image": {
       const path = str("path");
-      if (!path || path.length > IMAGE_PATH_MAX_CHARS)
+      if (!path || !isPlausibleDrivePath(path))
         return null;
       return {
         kind: "image",
@@ -7014,6 +7386,8 @@ function detectAgentcInvocation(command) {
     const w = words[i];
     if (SHELL_STOPPERS.has(w))
       break;
+    if (/^\d*>&\d+$/.test(w))
+      continue;
     if (w.startsWith("--")) {
       if (VALUE_FLAGS.has(w) && i + 1 < words.length && !SHELL_STOPPERS.has(words[i + 1])) {
         flags.set(w, words[i + 1]);
@@ -7026,6 +7400,7 @@ function detectAgentcInvocation(command) {
   const factorySlug = flags.get("--factory");
   const withSlug = factorySlug ? { factorySlug } : {};
   const uuid = (v) => v && UUID_RE.test(v) ? v : null;
+  const drivePath = (v) => v && isPlausibleDrivePath(v) ? v : null;
   if (args[0] === "display") {
     switch (args[1]) {
       case "run": {
@@ -7036,19 +7411,27 @@ function detectAgentcInvocation(command) {
         const runId = uuid(args[2]);
         return runId ? { verb: "display-changes", runId, ...withSlug } : null;
       }
-      case "document":
-        return args[2] ? { verb: "display-document", path: args[2], ...withSlug } : null;
+      case "document": {
+        const path = drivePath(args[2]);
+        return path ? { verb: "display-document", path, ...withSlug } : null;
+      }
       case "plan":
         return { verb: "display-plan" };
-      case "image":
-        return args[2] ? { verb: "display-image", path: args[2], ...withSlug } : null;
-      case "preview":
-        return args[2] ? { verb: "display-preview", path: args[2] } : null;
+      case "image": {
+        const path = drivePath(args[2]);
+        return path ? { verb: "display-image", path, ...withSlug } : null;
+      }
+      case "preview": {
+        const path = drivePath(args[2]);
+        return path ? { verb: "display-preview", path } : null;
+      }
       case "table": {
         const file = flags.get("--file");
         const hasData = flags.has("--data");
-        if (file && !hasData)
-          return { verb: "display-table", source: "file", path: file };
+        if (file && !hasData) {
+          const path = drivePath(file);
+          return path ? { verb: "display-table", source: "file", path } : null;
+        }
         if (hasData && !file)
           return { verb: "display-table", source: "inline" };
         return null;
@@ -7060,11 +7443,12 @@ function detectAgentcInvocation(command) {
       case "diff": {
         const from = flags.get("--from");
         const to = flags.get("--to");
-        if (!args[2] || !from || !to)
+        const path = drivePath(args[2]);
+        if (!path || !from || !to)
           return null;
         if (!REVISION_SELECTOR_RE.test(from) || !REVISION_SELECTOR_RE.test(to))
           return null;
-        return { verb: "display-diff", path: args[2], from, to };
+        return { verb: "display-diff", path, from, to };
       }
       case "ask": {
         const prompt = flags.get("--prompt");
@@ -7095,8 +7479,9 @@ function detectAgentcInvocation(command) {
     const runId = uuid(args[2]);
     return runId ? { verb: "run-get", runId } : null;
   }
-  if (args[0] === "files" && args[1] === "read" && args[2]) {
-    return { verb: "files-read", path: args[2], ...withSlug };
+  if (args[0] === "files" && args[1] === "read") {
+    const path = drivePath(args[2]);
+    return path ? { verb: "files-read", path, ...withSlug } : null;
   }
   return null;
 }
@@ -7335,10 +7720,12 @@ export {
   shellWords,
   serveStep,
   serializeDisplayMarker,
+  sandboxSizeLabel,
   runWorkflowSteps,
   runWorkflowSingleStep,
   runWorkflow,
   runProcessorChain,
+  resolveSdkAlias,
   requireScope,
   requestPauseAndAwait,
   requestContextPath,
@@ -7367,6 +7754,8 @@ export {
   killSandboxById,
   killAllSandboxes,
   isWorkflow,
+  isVercelSupportedSize,
+  isPlausibleDrivePath,
   isPlatformE2bTemplateAlias,
   isE2bSupportedSize,
   invokeStep,
@@ -7375,6 +7764,7 @@ export {
   getSandboxQuotas,
   formatError,
   findDisplayMarker,
+  explainBundleFailure,
   editTool,
   e2bMachineSpec,
   e2bDevboxTemplateRef,
@@ -7431,6 +7821,7 @@ export {
   WorkflowError,
   Verdict,
   VercelRunner,
+  VERCEL_MEMORY_MB_PER_VCPU,
   TMP_DIR,
   TABLE_MAX_ROWS,
   TABLE_MAX_COLUMNS,
@@ -7441,8 +7832,13 @@ export {
   STEP_RESULT_PREFIX,
   STEP_PAUSE_PREFIX,
   STEP_ENV,
+  SESSION_DEFAULT_SANDBOX_SIZE,
+  SDK_SPECIFIER_ALIASES,
+  SDK_PACKAGE,
   SANDBOX_VCPUS,
   SANDBOX_UNAVAILABLE_PREFIX,
+  SANDBOX_SIZES,
+  SANDBOX_MACHINES,
   ReservedKeyError,
   RequestContext,
   RUNNER_COMMAND,
@@ -7459,9 +7855,12 @@ export {
   LATEST_VERSION,
   EngineError,
   E2B_TEMPLATE_SIZES,
+  E2B_MAX_VCPUS,
+  E2B_MAX_MEMORY_MB,
   E2B_DEVBOX_TEMPLATE,
   E2B_DEVBOX_SPEC,
   E2B_DEVBOX_RECIPE_VERSION,
+  DRIVE_PATH_MAX_CHARS,
   DISPLAY_MARKER_VERSION,
   DISPLAY_MARKER_KEY,
   DIRECTIVE_MARKER_SUFFIX,
@@ -7469,7 +7868,7 @@ export {
   DEFAULT_SANDBOX_SIZE,
   DEFAULT_CLAUDE_MODEL,
   ClaudeRunner,
-  CLAUDE_CODE_THINKING_TOKENS,
+  CLAUDE_CODE_EFFORT_LEVELS,
   CLAUDE_CODE_ACP_ADAPTER,
   CHART_MAX_SERIES,
   CHART_MAX_POINTS_PER_SERIES,