@agent-compose/sdk 0.8.0 → 0.8.1

package/dist/runtimes/openai-desktop.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 } : {}
       }
     });
   }
@@ -2466,6 +2526,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 +2556,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 +2786,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 +3185,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) => {
@@ -3986,7 +4153,7 @@ var codexSpec = {
       "--skip-git-repo-check",
       "--dangerously-bypass-approvals-and-sandbox",
       ...model ? ["-m", shellQuote(model)] : [],
-      ...effort ? ["-c", `model_reasoning_effort=${effort}`] : [],
+      ...effort ? ["-c", `model_reasoning_effort=${effort === "max" ? "xhigh" : effort}`] : [],
       ...cwd ? ["-C", shellQuote(cwd)] : []
     ].join(" ");
     const exec = sessionId ? `codex exec resume ${shellQuote(sessionId)} ${flags}` : `codex exec ${flags}`;
@@ -4208,7 +4375,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 +4391,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 +4417,7 @@ var claudeCodeSpec = {
               toolName: String(b.name ?? "tool"),
               toolInput: b.input ?? {},
               toolUseId: String(b.id ?? ""),
+              ...parent,
               timestamp: ts
             }];
           }
@@ -4263,6 +4432,7 @@ var claudeCodeSpec = {
           toolUseId: String(b.tool_use_id ?? ""),
           output: toolResultText(b.content),
           isError: b.is_error === true,
+          ...parent,
           timestamp: ts
         }] : []);
       }
@@ -4892,7 +5062,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 +5128,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 +5679,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 +5701,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]/;
@@ -6599,6 +6782,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 +6853,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 +7058,7 @@ function parseDisplayMarker(line) {
     }
     case "document": {
       const path = str("path");
-      if (!path)
+      if (!path || !isPlausibleDrivePath(path))
         return null;
       return {
         kind: "document",
@@ -6875,7 +7073,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 +7212,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 +7226,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 +7237,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 +7269,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 +7305,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;
 }

package/dist/types/api-conversations.d.ts

@@ -157,6 +157,16 @@ export interface ConversationDetail {
         name: string;
         description: string;
     }> | null;
+    /** Where this conversation's UNMERGED work lives: a cloud session writes
+     *  its own private drive branch, and every drive read a client makes for
+     *  THAT factory must carry `?branch=` or it resolves against `main`,
+     *  where session-born files do not exist. Non-null only for a session
+     *  with a drive branch and a resolvable factory; null/absent = main
+     *  only (read loosely — older servers omit it). */
+    sessionDrive?: {
+        factorySlug: string;
+        branch: string;
+    } | null;
     viewerLastReadAt: string | null;
     /** The caller's role in this conversation (ADR-0045) — drives client
      *  affordances only; the server remains the authority on every action.
@@ -226,6 +236,27 @@ export interface CreateCloudSessionInput {
      *  profile ids, or "none" for a bare session. Omitted = the owner's
      *  default profile. */
     connectorProfileId?: string;
+    /** Idempotent dependency-setup command run by every fresh sandbox acquire
+     *  after the drive mounts (`bun install`, `npm ci`, …). Strict charset —
+     *  no shell metacharacters (400). Mutually exclusive with `templateId`
+     *  (a snapshot carries its own installed state). */
+    setupCommand?: string;
+    /** Provenance of a session born by `agentc session import`: where the
+     *  imported local session lived and which harness thread seeded it. */
+    handoffOrigin?: {
+        cwd: string;
+        sourceAcpSessionId: string | null;
+        agentKind: string;
+        mirrorConversationId: string | null;
+    };
+    /** Imported claude memories (session-import spec §memories): guest-home
+     *  seeds re-applied on every fresh acquire. Paths under .claude/ only;
+     *  strict base64; 256KB decoded total (server-capped). */
+    seedFiles?: Array<{
+        path: string;
+        contentB64: string;
+        mode: "write" | "append";
+    }>;
 }
 export interface CloudSessionCreated {
     conversation: ConversationRow;

package/dist/types/api-factory.d.ts

@@ -89,6 +89,11 @@ export interface RegisterWorkflowInput {
      *  server skips the /factory mount for its runs (#13). See
      *  `WorkflowMetadata.environmentBuild`. */
     environmentBuild?: boolean;
+    /** Drive requirement declared via `defineWorkflow({ factoryDrive })`.
+     *  Omitted ⇒ `"required"` on the server (a failed /factory mount fails
+     *  the run); `"none"` = explicit no-drive opt-out. See
+     *  `WorkflowMetadata.factoryDrive`. */
+    factoryDrive?: "required" | "none";
     /** Factory slug. Defaults to `"default"`. */
     factorySlug?: string;
 }
@@ -181,6 +186,26 @@ export interface FactoryFileWriteResult {
     sizeBytes: number;
     created: boolean;
 }
+/** A minted local-mount grant: the user branch, the signed gateway token, and
+ *  where to dial. The backing `conversationId` is the mount's review surface
+ *  (its branch changes list + merge ride the session-changes routes). */
+export interface DriveMountSession {
+    conversationId: string;
+    branch: string;
+    /** Signed gateway mount token (user principal, exclusive mode). Treat as a
+     *  secret: write it to a 0600 token file, never argv/env of children. */
+    token: string;
+    gatewayWsUrl: string;
+    /** Token expiry, unix seconds — re-mint (same `conversationId`) before it. */
+    expiresAtS: number;
+    diskId: string;
+}
+export interface CreateDriveMountSessionInput {
+    /** Re-mint for an existing mount session (remount / token refresh). */
+    conversationId?: string;
+    /** The mounting machine's hostname — carried in the mount's title. */
+    host?: string;
+}
 /** A factory: a project-level grouping of workflows inside a team. */
 export interface FactoryRow {
     id: string;

package/dist/types/api-runs.d.ts

@@ -9,7 +9,18 @@
 import type { SandboxNetworkPolicy, SandboxSize } from "../sandbox.js";
 import type { SnapshotConfig } from "./workflow-metadata.js";
 import type { RunContext } from "./api-scopes.js";
+import type { BundledWorkflow } from "../utils/bundler.js";
 export type RunState = "running" | "success" | "failed" | "abandoned" | "canceled";
+/** INLINE invoke payload (`POST /factories/:slug/invoke`): everything
+ *  `bundleWorkflow` produced — source, the REQUIRED manifest binding the
+ *  bytes, the workflow plan, and the build fields — plus the name the run
+ *  reports as its workflow. The server runs it through the same
+ *  validate/build core as registration but writes NO registry row: the run
+ *  snapshots the validated source (auditable, replayable) and the name
+ *  stays free for real registrations. */
+export type InlineWorkflowPayload = BundledWorkflow & {
+    name: string;
+};
 export interface InvokeWorkflowOptions {
     /** Per-invocation snapshot config override. `snapshots.bootFrom`
      *  replaces the template's boot source; `snapshots.saveLatest` and
@@ -38,11 +49,45 @@ export interface InvokeWorkflowOptions {
      *  with the same key inside the server's dedup window returns the original
      *  run instead of starting a new one (matches `resumePause`'s pattern). */
     idempotencyKey?: string;
-}
+    /** Who pays for this run's model calls:
+     *
+     *    - `"default"` (Auto) — the initiating human's connected subscription
+     *      when one is enabled for workflows, else platform credits;
+     *    - `"platform"` — always platform credits (metered);
+     *    - `"subscription"` — REQUIRE the initiating human's plan. If it
+     *      cannot be honored the invoke FAILS (412) rather than quietly
+     *      spending credits;
+     *    - `"byok"` — a factory secret named by `fundingSecret`, injected as
+     *      the runtime's raw provider key. Never metered.
+     *
+     *  Omitted → the workflow's own default (its `settings.funding`), else
+     *  Auto. */
+    funding?: FundingChoice;
+    /** `funding: "byok"` only — the FACTORY SECRET NAME whose value funds the
+     *  run. Must be a provider key variable (ANTHROPIC_API_KEY,
+     *  OPENAI_API_KEY, CODEX_API_KEY, OPENROUTER_API_KEY) — that is where the
+     *  sandbox's runtimes read it. The name only; the value never leaves the
+     *  server's secret store. */
+    fundingSecret?: string;
+}
+/** Inference-funding choice for a run — a lane the caller PINS, or
+ *  `"default"` (Auto, the automatic ladder). Mirrors the same vocabulary
+ *  cloud sessions use. */
+export type FundingChoice = "default" | "platform" | "subscription" | "byok";
 export interface InvokeAndWaitOptions extends InvokeWorkflowOptions {
     timeoutMs?: number;
     pollIntervalMs?: number;
 }
+/** Options for `invokeInline` — the named-invoke options plus the run-title
+ *  override (an inline run has no registered template to inherit one from). */
+export interface InvokeInlineOptions extends InvokeWorkflowOptions {
+    /** Run title override — defaults to the workflow name. */
+    title?: string;
+}
+export interface InvokeInlineAndWaitOptions extends InvokeInlineOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
 export interface InvokeResult {
     id: string;
 }