@agent-compose/cli 0.3.3 → 0.3.5

package/dist/index.js

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/index.ts
-import { readFileSync as readFileSync6 } from "node:fs";
+import { readFileSync as readFileSync7 } from "node:fs";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { program } from "commander";
 
@@ -147,6 +147,7 @@ function fallbackDashboardUrl(env) {
   return env === "local" ? "http://localhost:3000" : "https://platform.agentcompose.ai";
 }
 var defaultUrl = process.env.AGENT_COMPOSE_URL ?? _envUrl ?? _global.url ?? "https://api.agentcompose.ai";
+var urlIsBuiltinFallback = !process.env.AGENT_COMPOSE_URL && !_envUrl && !_global.url;
 var defaultDashboardUrl = process.env.AGENT_COMPOSE_DASHBOARD_URL ?? _envDashboardUrl ?? _global.dashboardUrl ?? fallbackDashboardUrl(_activeEnv);
 var defaultApiKey = process.env.AGENT_COMPOSE_API_KEY ?? _envKey ?? _global.apiKey ?? "";
 var defaultFactory = process.env.AGENT_COMPOSE_FACTORY ?? _envFactory ?? "default";
@@ -155,6 +156,10 @@ var projectSettings = _project;
 var localSettings = _local;
 var activeEnv = _activeEnv;
 function makeClient({ url, apiKey }) {
+  if (urlIsBuiltinFallback && url === "https://api.agentcompose.ai") {
+    console.error(`[agentc] No server configured here — targeting https://api.agentcompose.ai (built-in default).
+` + "         If you meant another environment: pass --url, set AGENT_COMPOSE_URL, or run from a repo with .agentc settings.");
+  }
   if (!apiKey) {
     console.error(`API key required. Provide via:
 ` + `  • Project:     .agentc/settings.local.json
@@ -184,13 +189,17 @@ var registerCommand = new Command("register").description("Register a workflow w
     console.error(`Error: workflow not found at ${workflowPath}`);
     process.exit(1);
   }
-  const { source, manifest, description, networkPolicy, placeholders, snapshots, memory, postRunHooks, inputSchema, outputSchema, workflowPlan } = await bundleWorkflow(workflowPath);
+  const { source, manifest, description, networkPolicy, placeholders, snapshots, resources, inputSchema, outputSchema, workflowPlan, connectors, connectorOperation, invokePolicy } = await bundleWorkflow(workflowPath);
+  if (connectors)
+    console.log(`[register] Connectors required: ${Object.keys(connectors).join(", ")} — tokens are injected at the network layer at dispatch`);
   if (networkPolicy)
     console.log(`[register] Network policy detected — credentials will be brokered via Vercel firewall`);
   if (snapshots?.bootFrom)
     console.log(`[register] Boots from: ${formatBootFrom(snapshots.bootFrom)}`);
   if (snapshots?.saveLatest)
     console.log(`[register] Captures snapshot per step${snapshots.retainSteps ? " (retain: every step)" : ""}`);
+  if (resources?.size)
+    console.log(`[register] Sandbox size: ${resources.size}`);
   const client = makeClient(opts);
   console.log(`[register] Registering "${name}" → factory "${opts.factory}"…`);
   const result = await client.register({
@@ -205,18 +214,15 @@ var registerCommand = new Command("register").description("Register a workflow w
     ...networkPolicy ? { networkPolicy } : {},
     ...placeholders ? { placeholders } : {},
     ...snapshots !== undefined ? { snapshots } : {},
-    ...memory !== undefined ? { memory } : {},
-    ...postRunHooks !== undefined ? { postRunHooks } : {},
+    ...resources !== undefined ? { resources } : {},
     ...inputSchema !== undefined ? { inputSchema } : {},
-    ...outputSchema !== undefined ? { outputSchema } : {}
+    ...outputSchema !== undefined ? { outputSchema } : {},
+    ...connectors !== undefined ? { connectors } : {},
+    ...connectorOperation !== undefined ? { connectorOperation } : {},
+    ...invokePolicy !== undefined ? { invokePolicy } : {}
   });
   const scheduleNote = opts.schedule ? ` — schedule: ${opts.schedule}` : "";
   console.log(`✓ Workflow:  ${result.name}@${result.version} (${result.id})${scheduleNote}`);
-  if (result.warnings && result.warnings.length > 0) {
-    for (const w of result.warnings) {
-      console.warn(`! warning: ${w}`);
-    }
-  }
   if (!opts.build)
     return;
   console.log(`[build] Invoking "${name}" with snapshots:{ saveLatest: true } to capture a snapshot…`);
@@ -242,7 +248,7 @@ var registerCommand = new Command("register").description("Register a workflow w
   process.exit(1);
 });
 function formatBootFrom(b) {
-  return `snapshot ${b.snapshotId}`;
+  return b === "reuse" ? "reuse (this workflow's own latest snapshot)" : `snapshot ${b.snapshotId}`;
 }
 
 // src/commands/invoke.ts
@@ -519,7 +525,8 @@ var logsCommand = new Command2("logs").description("Stream logs for a run").argu
 });
 
 // src/commands/invoke.ts
-var invokeCommand = new Command3("invoke").description("Invoke a registered workflow template").argument("<template>", "Template name").option("-i, --input <json>", "Input as JSON string").option("-f, --follow", "Stream logs after invoking").option("--factory <slug>", `Factory the template lives in (default: ${defaultFactory})`, defaultFactory).option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (template, opts) => {
+var SANDBOX_SIZES = ["2vcpu-4gb", "4vcpu-8gb", "8vcpu-16gb", "32vcpu-64gb"];
+var invokeCommand = new Command3("invoke").description("Invoke a registered workflow template").argument("<template>", "Template name").option("-i, --input <json>", "Input as JSON string").option("-f, --follow", "Stream logs after invoking").option("--factory <slug>", `Factory the template lives in (default: ${defaultFactory})`, defaultFactory).option("--size <size>", `Sandbox machine size for this run: ${SANDBOX_SIZES.join(" | ")} (overrides the template default)`).option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (template, opts) => {
   let input;
   if (opts.input) {
     try {
@@ -529,8 +536,15 @@ var invokeCommand = new Command3("invoke").description("Invoke a registered work
       process.exit(1);
     }
   }
+  if (opts.size && !SANDBOX_SIZES.includes(opts.size)) {
+    console.error(`Error: --size must be one of: ${SANDBOX_SIZES.join(", ")}`);
+    process.exit(1);
+  }
   const client = makeClient(opts);
-  const { id } = await client.invoke(template, input, { factorySlug: opts.factory });
+  const { id } = await client.invoke(template, input, {
+    factorySlug: opts.factory,
+    ...opts.size ? { size: opts.size } : {}
+  });
   console.log(`Run started: ${id}`);
   if (opts.follow)
     await streamLogs(id, opts);
@@ -550,8 +564,108 @@ var listCommand = new Command4("list").description("List registered workflow tem
     console.log(`${t.name}  ${t.version}`);
 });
 
+// src/commands/pause.ts
+import { Command as Command5, InvalidArgumentError as InvalidArgumentError2 } from "commander";
+import pc2 from "picocolors";
+function readPauseEnv() {
+  const runId = process.env.RUN_ID;
+  const url = process.env.AGENT_COMPOSE_URL;
+  const apiKey = process.env.AGENT_COMPOSE_API_KEY;
+  const agentId = process.env.AGENT_COMPOSE_AGENT_ID || undefined;
+  const missing = [
+    !runId && "RUN_ID",
+    !url && "AGENT_COMPOSE_URL",
+    !apiKey && "AGENT_COMPOSE_API_KEY"
+  ].filter(Boolean);
+  if (missing.length) {
+    console.error(`Error: agentc pause only works inside a run sandbox — missing ${missing.join(", ")}.`);
+    process.exit(1);
+  }
+  return { runId, url, apiKey, agentId };
+}
+function parseMs(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new InvalidArgumentError2(`expected a positive number of milliseconds, got "${raw}".`);
+  }
+  return n;
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var pauseCommand = new Command5("pause").description("Ask the human a question and block until they answer (run-sandbox only)").requiredOption("--reason <text>", "The question / ask to show the human").option("--option <value>", "A typed choice (repeatable; omit for a free-form answer)", (v, acc) => [...acc, v], []).option("--ttl <ms>", "Auto-expire the pause after this many milliseconds", parseMs).option("--poll-interval <ms>", "How often to poll for an answer", parseMs, 3000).action(async (opts) => {
+  const env = readPauseEnv();
+  const base = env.url.replace(/\/+$/, "");
+  const createBody = { reason: opts.reason };
+  if (opts.option.length)
+    createBody.options = opts.option;
+  if (env.agentId)
+    createBody.agentId = env.agentId;
+  if (opts.ttl !== undefined)
+    createBody.ttlMs = opts.ttl;
+  let createRes;
+  try {
+    createRes = await fetch(`${base}/api/v1/runs/${env.runId}/pauses`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${env.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(createBody)
+    });
+  } catch (err) {
+    console.error(`Error: failed to create pause: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  if (!createRes.ok) {
+    const text = await createRes.text().catch(() => "");
+    console.error(`Error: create pause returned ${createRes.status}${text ? `: ${text}` : ""}`);
+    process.exit(1);
+  }
+  const { id } = await createRes.json();
+  console.error(`${pc2.yellow("⏸")} paused for human input (pause ${id}) — waiting…`);
+  for (;; ) {
+    await sleep(opts.pollInterval);
+    let pause;
+    let terminalError;
+    try {
+      const res = await fetch(`${base}/api/v1/runs/${env.runId}/pauses/${id}`, {
+        headers: { Authorization: `Bearer ${env.apiKey}` }
+      });
+      if (res.ok) {
+        pause = await res.json();
+      } else {
+        const text = await res.text().catch(() => "");
+        const retryable = res.status >= 500 || res.status === 408 || res.status === 429;
+        if (retryable) {
+          console.error(`${pc2.dim(`poll ${id} returned ${res.status}${text ? `: ${text}` : ""} — retrying…`)}`);
+        } else {
+          terminalError = `poll ${id} returned ${res.status}${text ? `: ${text}` : ""} — giving up.`;
+        }
+      }
+    } catch (err) {
+      console.error(`${pc2.dim(`poll ${id} failed (${err instanceof Error ? err.message : String(err)}) — retrying…`)}`);
+    }
+    if (terminalError) {
+      console.error(`Error: ${terminalError}`);
+      process.exit(1);
+    }
+    if (!pause)
+      continue;
+    if (pause.status === "pending")
+      continue;
+    if (pause.status === "resolved") {
+      const payload = pause.resumePayload;
+      const decision = payload && typeof payload.decision === "string" ? payload.decision : undefined;
+      process.stdout.write(`${decision ?? JSON.stringify(payload)}
+`);
+      process.exit(0);
+    }
+    console.error(`Error: pause ${id} ${pause.status} before it was answered.`);
+    process.exit(1);
+  }
+});
+
 // src/commands/init.ts
-import { Command as Command5 } from "commander";
+import { Command as Command6 } from "commander";
 import {
   existsSync as existsSync3,
   mkdirSync,
@@ -630,7 +744,7 @@ function loadSource(dir) {
   const files = readdirSync(dir).filter((f) => f.endsWith(".md"));
   return { dir, files };
 }
-var initCommand = new Command5("init").description("Install agentc Claude Code skills and ensure PATH is configured").option("--dev", "Also install dev-only skills from cli/skills-dev/ (clone install only)").action((opts) => {
+var initCommand = new Command6("init").description("Install agentc Claude Code skills and ensure PATH is configured").option("--dev", "Also install dev-only skills from cli/skills-dev/ (clone install only)").action((opts) => {
   ensureBunInPath();
   const publicSrc = loadSource(locateSkillsDir("skills"));
   if (!publicSrc) {
@@ -683,7 +797,7 @@ ${wanted.length} skill(s) installed to ${targetRoot}${note}`);
 });
 
 // src/commands/keys.ts
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 import { AgentComposeClient as AgentComposeClient2 } from "@agent-compose/sdk";
 var DURATION_UNITS = {
   s: 1000,
@@ -709,7 +823,7 @@ function requireAdminKey(adminKey) {
 ` + "Mint your first admin key by signing into the dashboard.");
   process.exit(1);
 }
-var keysCommand = new Command6("keys").description("Manage API keys");
+var keysCommand = new Command7("keys").description("Manage API keys");
 keysCommand.command("create <name>").description("Create a new API key (requires admin-scoped ac_… key)").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--admin-key <key>", "Admin-scoped ac_… key (or AGENT_COMPOSE_ADMIN_KEY env var)", process.env.AGENT_COMPOSE_ADMIN_KEY ?? "").option("--scopes <list>", "Comma-separated scope list: read, invoke, admin, events:read, events:write. Default (empty) = full team access.").option("--expires-in <duration>", `Expire the key after this duration — e.g. "30d", "2h", "7d12h", "1w", "90m". Default: never.`).option("--factory <slug>", "Restrict the key to a single factory (slug). Default: team-wide.").action(async (name, opts) => {
   requireAdminKey(opts.adminKey);
   const scopes = opts.scopes ? opts.scopes.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
@@ -763,8 +877,8 @@ keysCommand.command("list").description("List API keys for your team (requires a
 });
 
 // src/commands/auth.ts
-import { Command as Command7 } from "commander";
-var authCommand = new Command7("auth").description("Manage authentication");
+import { Command as Command8 } from "commander";
+var authCommand = new Command8("auth").description("Manage authentication");
 authCommand.command("login <key>").description("Save an API key for the active environment").action(async (key) => {
   if (projectDir && activeEnv) {
     if (!projectSettings.envs?.[activeEnv]) {
@@ -845,9 +959,9 @@ Run: agentc auth login YOUR_KEY`);
 });
 
 // src/commands/secrets.ts
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 var sharedOpts = (cmd) => cmd.option("--factory <slug>", `Factory the workflow lives in (default: ${defaultFactory})`, defaultFactory).option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey);
-var secretsCommand = new Command8("secrets").description("Manage workflow secrets stored in GCP Secret Manager");
+var secretsCommand = new Command9("secrets").description("Manage workflow secrets stored in GCP Secret Manager");
 sharedOpts(secretsCommand.command("set <workflow> <key> <value>").description("Create or update a secret for a workflow")).action(async (workflow, key, value, opts) => {
   const client = makeClient(opts);
   await client.setSecret(workflow, key, value, { factorySlug: opts.factory });
@@ -872,7 +986,7 @@ sharedOpts(secretsCommand.command("delete <workflow> <key>").description("Delete
 });
 
 // src/commands/usage.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 function parseMonth(s) {
   const m = /^(\d{4})-(\d{1,2})$/.exec(s);
   if (!m)
@@ -891,7 +1005,7 @@ function fmtSeconds(s) {
   const h = Math.floor(s / 3600);
   return `${h}h ${Math.floor(s % 3600 / 60)}m`;
 }
-var usageCommand = new Command9("usage").description("Show billable usage — runs + sandbox seconds — for the current team").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).option("--month <yyyy-mm>", "Calendar month to report (default: current month, UTC)").option("--from <iso>", "Window start (ISO 8601) — overrides --month").option("--to <iso>", "Window end (ISO 8601)   — overrides --month").action(async (opts) => {
+var usageCommand = new Command10("usage").description("Show billable usage — runs + sandbox seconds — for the current team").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).option("--month <yyyy-mm>", "Calendar month to report (default: current month, UTC)").option("--from <iso>", "Window start (ISO 8601) — overrides --month").option("--to <iso>", "Window end (ISO 8601)   — overrides --month").action(async (opts) => {
   let from, to;
   if (opts.from || opts.to) {
     if (!opts.from || !opts.to) {
@@ -946,8 +1060,8 @@ Usage ${from.toISOString().slice(0, 10)} → ${to.toISOString().slice(0, 10)}
 });
 
 // src/commands/snapshot.ts
-import { Command as Command10 } from "commander";
-var snapshotCommand = new Command10("snapshot").description("Manage captured sandbox snapshots");
+import { Command as Command11 } from "commander";
+var snapshotCommand = new Command11("snapshot").description("Manage captured sandbox snapshots");
 snapshotCommand.command("list").description("List captured sandbox snapshots in a factory").option("-w, --workflow <name>", "Filter to a single workflow").option("--limit <n>", "Max rows to show (default 50, max 500)", (v) => parseInt(v, 10)).option("--before <cursor>", "Pagination cursor from a previous page").option("--factory <slug>", "Factory slug", defaultFactory).option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (opts) => {
   const page = await makeClient(opts).listSnapshotsPage({
     factorySlug: opts.factory,
@@ -994,9 +1108,9 @@ snapshotCommand.command("show").description("List every snapshot held for a run
 });
 
 // src/commands/factory.ts
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 import { AgentComposeError as AgentComposeError3 } from "@agent-compose/sdk";
-var factoryCommand = new Command11("factory").description("Manage factories (projects within your team)");
+var factoryCommand = new Command12("factory").description("Manage factories (projects within your team)");
 var SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
 var SLUG_MAX_LEN = 64;
 function validateSlugOrExit(slug) {
@@ -1084,25 +1198,79 @@ factoryCommand.command("show").description("Show the active factory + how it's r
   console.log(`Active factory: ${defaultFactory}  (default fallback)`);
 });
 
+// src/commands/members.ts
+import { Command as Command13 } from "commander";
+var membersCommand = new Command13("members").description("List teammates and flag them for attention (@-mentions)");
+membersCommand.command("list").description("List the human members of your team (name, email, role, user id)").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (opts) => {
+  const client = makeClient(opts);
+  const members = await client.listMembers().catch(reportSdkError);
+  if (members.length === 0) {
+    console.log("No members found.");
+    return;
+  }
+  const nameW = Math.max(4, ...members.map((m) => (m.name || "").length));
+  const emailW = Math.max(5, ...members.map((m) => m.email.length));
+  const roleW = Math.max(4, ...members.map((m) => m.role.length));
+  console.log(`${"NAME".padEnd(nameW)}  ${"EMAIL".padEnd(emailW)}  ${"ROLE".padEnd(roleW)}  USER ID`);
+  for (const m of members) {
+    console.log(`${(m.name || "—").padEnd(nameW)}  ${m.email.padEnd(emailW)}  ${m.role.padEnd(roleW)}  ${m.userId}`);
+  }
+});
+var collect = (val, acc) => [...acc ?? [], val];
+membersCommand.command("notify").description("Flag teammates for attention — a ping in their Workbench").requiredOption("-u, --user <id-or-email>", "Teammate to flag (repeatable)", collect).requiredOption("-m, --text <message>", "What to flag them about").option("-k, --context-kind <kind>", "doc | comment | plan | run", "plan").option("--context-path <path>", "Factory-relative file path or thread id").option("--context-url <url>", "Dashboard URL the Workbench card links to").option("--factory <slug>", `Factory the ping belongs to (default: ${defaultFactory})`, defaultFactory).option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (opts) => {
+  const kind = opts.contextKind;
+  if (!["doc", "comment", "plan", "run"].includes(kind)) {
+    console.error(`Error: --context-kind must be one of doc | comment | plan | run (got "${kind}")`);
+    process.exit(1);
+  }
+  const client = makeClient(opts);
+  const members = await client.listMembers().catch(reportSdkError);
+  const byEmail = new Map(members.map((m) => [m.email.toLowerCase(), m.userId]));
+  const ids = new Set(members.map((m) => m.userId));
+  const resolved = [];
+  const unknown = [];
+  for (const u of opts.user) {
+    if (ids.has(u))
+      resolved.push(u);
+    else if (byEmail.has(u.toLowerCase()))
+      resolved.push(byEmail.get(u.toLowerCase()));
+    else
+      unknown.push(u);
+  }
+  if (unknown.length > 0) {
+    console.error(`Error: not on this team: ${unknown.join(", ")}. Run \`agentc members list\`.`);
+    process.exit(1);
+  }
+  const mentions = await client.createMentions({
+    mentionedUserIds: [...new Set(resolved)],
+    text: opts.text,
+    contextKind: kind,
+    ...opts.contextPath ? { contextPath: opts.contextPath } : {},
+    ...opts.contextUrl ? { contextUrl: opts.contextUrl } : {},
+    factorySlug: opts.factory
+  }).catch(reportSdkError);
+  console.log(`✓ Flagged ${mentions.length} teammate${mentions.length === 1 ? "" : "s"} in factory "${opts.factory}".`);
+});
+
 // src/commands/cancel.ts
-import { Command as Command12 } from "commander";
-import pc2 from "picocolors";
-var cancelCommand = new Command12("cancel").description("Cancel an in-progress run").argument("<run-id>", "Run ID").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).option("--wait", "Stream the run's events until it terminates").action(async (runId, opts) => {
+import { Command as Command14 } from "commander";
+import pc3 from "picocolors";
+var cancelCommand = new Command14("cancel").description("Cancel an in-progress run").argument("<run-id>", "Run ID").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).option("--wait", "Stream the run's events until it terminates").action(async (runId, opts) => {
   const client = makeClient(opts);
   const res = await client.cancelRun(runId).catch(reportSdkError);
   if (res.status === "canceled") {
-    console.log(`${pc2.yellow("⊘")} canceled ${runId} at ${new Date(res.canceledAt).toISOString()}`);
+    console.log(`${pc3.yellow("⊘")} canceled ${runId} at ${new Date(res.canceledAt).toISOString()}`);
   } else {
-    console.log(`${pc2.dim("⊘")} run ${runId} already ${res.status} at ${new Date(res.canceledAt).toISOString()}`);
+    console.log(`${pc3.dim("⊘")} run ${runId} already ${res.status} at ${new Date(res.canceledAt).toISOString()}`);
   }
   if (opts.wait)
     await streamLogs(runId, opts);
 });
 
 // src/commands/events.ts
-import { Command as Command13 } from "commander";
+import { Command as Command15 } from "commander";
 import { readFileSync as readFileSync3 } from "node:fs";
-import pc3 from "picocolors";
+import pc4 from "picocolors";
 function parseBody(raw) {
   if (raw === undefined || raw === "")
     return {};
@@ -1144,7 +1312,7 @@ function parseLimit(raw) {
 }
 function fmtBodyPreview(body) {
   if (body === null || body === undefined)
-    return pc3.dim("—");
+    return pc4.dim("—");
   if (typeof body === "string")
     return body.length > 60 ? body.slice(0, 57) + "…" : body;
   try {
@@ -1154,7 +1322,7 @@ function fmtBodyPreview(body) {
     return String(body);
   }
 }
-var sendCommand = new Command13("send").description("Send an event to an existing run (requires events:write or invoke scope)").argument("<run-id>", "Target run id (uuid)").argument("<name>", "Event name (e.g. quality.accepted, deploy.completed)").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).option("--body <json>", "Event body — inline JSON or @file (default: {})").option("--summary <s>", "One-line summary (≤2000 chars)").option("--confidence <0..1>", "Confidence score, [0, 1]", parseConfidence).option("-a, --attribute <key=value>", "Attribute (repeatable; value parsed as JSON if possible)", parseAttribute, {}).option("--idempotency-key <k>", "Replay-safe key: identical (run, name, key) returns the original event").option("--no-propagate", "Mark event as non-propagating").option("--timestamp <iso>", "Event timestamp (ISO 8601, defaults to server-now)").option("--json", "Output the raw event JSON instead of the one-line summary").action(async (runId, name, opts) => {
+var sendCommand = new Command15("send").description("Send an event to an existing run (requires events:write or invoke scope)").argument("<run-id>", "Target run id (uuid)").argument("<name>", "Event name (e.g. quality.accepted, deploy.completed)").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).option("--body <json>", "Event body — inline JSON or @file (default: {})").option("--summary <s>", "One-line summary (≤2000 chars)").option("--confidence <0..1>", "Confidence score, [0, 1]", parseConfidence).option("-a, --attribute <key=value>", "Attribute (repeatable; value parsed as JSON if possible)", parseAttribute, {}).option("--idempotency-key <k>", "Replay-safe key: identical (run, name, key) returns the original event").option("--no-propagate", "Mark event as non-propagating").option("--timestamp <iso>", "Event timestamp (ISO 8601, defaults to server-now)").option("--json", "Output the raw event JSON instead of the one-line summary").action(async (runId, name, opts) => {
   let body;
   try {
     body = parseBody(opts.body);
@@ -1177,9 +1345,9 @@ var sendCommand = new Command13("send").description("Send an event to an existin
     console.log(JSON.stringify(event, null, 2));
     return;
   }
-  console.log(`${pc3.green("✓")} event ${pc3.bold(event.id.slice(0, 8))}  ${event.name}  ${pc3.dim(`run ${runId.slice(0, 8)}`)}`);
+  console.log(`${pc4.green("✓")} event ${pc4.bold(event.id.slice(0, 8))}  ${event.name}  ${pc4.dim(`run ${runId.slice(0, 8)}`)}`);
 });
-var listCommand2 = new Command13("list").description("List events for a run, or factory-wide with --factory <slug>").argument("[run-id]", "Run id (uuid). If omitted, requires --factory.").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).option("--factory <slug>", "List events across a factory instead of a single run").option("--limit <n>", "Max rows (factory mode only; server clamps)", parseLimit).option("--name <pattern>", "Filter by event name (factory mode only)").option("--json", "Output raw JSON instead of the columnar view").action(async (runId, opts) => {
+var listCommand2 = new Command15("list").description("List events for a run, or factory-wide with --factory <slug>").argument("[run-id]", "Run id (uuid). If omitted, requires --factory.").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).option("--factory <slug>", "List events across a factory instead of a single run").option("--limit <n>", "Max rows (factory mode only; server clamps)", parseLimit).option("--name <pattern>", "Filter by event name (factory mode only)").option("--json", "Output raw JSON instead of the columnar view").action(async (runId, opts) => {
   if (!runId && !opts.factory) {
     console.error("Error: provide either <run-id> or --factory <slug>");
     process.exit(1);
@@ -1207,17 +1375,44 @@ var listCommand2 = new Command13("list").description("List events for a run, or
   for (const ev of sorted) {
     const ts = ev.timestamp.replace(/\.\d+Z$/, "Z");
     const detail = ev.summary ?? fmtBodyPreview(ev.body);
-    const runHint = runId ? "" : pc3.dim(`  run ${(ev.runId ?? "—").slice(0, 8)}`);
-    console.log(`${pc3.dim(ts)}  ${pc3.bold(ev.name.padEnd(28))}  ${detail}${runHint}`);
+    const runHint = runId ? "" : pc4.dim(`  run ${(ev.runId ?? "—").slice(0, 8)}`);
+    console.log(`${pc4.dim(ts)}  ${pc4.bold(ev.name.padEnd(28))}  ${detail}${runHint}`);
+  }
+});
+var eventsCommand = new Command15("events").description("Send or list run events (Events API)").addCommand(sendCommand).addCommand(listCommand2);
+
+// src/commands/files.ts
+import { readFileSync as readFileSync4, writeFileSync } from "node:fs";
+import { Command as Command16 } from "commander";
+var sharedOpts2 = (cmd) => cmd.option("--factory <slug>", `Factory whose drive to target (default: ${defaultFactory})`, defaultFactory).option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey);
+var filesCommand = new Command16("files").description("Read/write documents on a factory's drive");
+sharedOpts2(filesCommand.command("put <local-file> <drive-path>").description("Upload a local file to the factory drive (creates or overwrites)").option("--content-type <mime>", "Content type", "text/plain; charset=utf-8")).action(async (localFile, drivePath, opts) => {
+  const client = makeClient(opts);
+  const result = await client.putFactoryFile(drivePath, readFileSync4(localFile), {
+    factorySlug: opts.factory,
+    contentType: opts.contentType
+  });
+  console.log(`✓ ${result.created ? "created" : "updated"} ${result.path} (${result.sizeBytes} bytes)`);
+});
+sharedOpts2(filesCommand.command("get <drive-path>").description("Print a drive file's content (or save with -o)").option("-o, --out <local-file>", "Write to a local file instead of stdout").option("--revision <n>", "Read a specific revision id")).action(async (drivePath, opts) => {
+  const client = makeClient(opts);
+  const content = await client.getFactoryFile(drivePath, {
+    factorySlug: opts.factory,
+    ...opts.revision !== undefined ? { revision: Number(opts.revision) } : {}
+  });
+  if (opts.out) {
+    writeFileSync(opts.out, content);
+    console.log(`✓ ${drivePath} → ${opts.out}`);
+  } else {
+    process.stdout.write(content);
   }
 });
-var eventsCommand = new Command13("events").description("Send or list run events (Events API)").addCommand(sendCommand).addCommand(listCommand2);
 
 // src/commands/schedule.ts
-import { Command as Command14 } from "commander";
-var sharedOpts2 = (cmd) => cmd.option("--factory <slug>", `Factory the schedule lives in (default: ${defaultFactory})`, defaultFactory).option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey);
-var scheduleCommand = new Command14("schedule").description("Manage cron schedules attached to registered workflows");
-sharedOpts2(scheduleCommand.command("create <name>").description("Create a new schedule for a workflow").requiredOption("--workflow <name>", "The registered workflow this schedule should fire").requiredOption("--cron <expr>", "Cron expression (UTC) — e.g. '0 9 * * *'")).action(async (name, opts) => {
+import { Command as Command17 } from "commander";
+var sharedOpts3 = (cmd) => cmd.option("--factory <slug>", `Factory the schedule lives in (default: ${defaultFactory})`, defaultFactory).option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey);
+var scheduleCommand = new Command17("schedule").description("Manage cron schedules attached to registered workflows");
+sharedOpts3(scheduleCommand.command("create <name>").description("Create a new schedule for a workflow").requiredOption("--workflow <name>", "The registered workflow this schedule should fire").requiredOption("--cron <expr>", "Cron expression (UTC) — e.g. '0 9 * * *'")).action(async (name, opts) => {
   const client = makeClient(opts);
   const created = await client.createSchedule({
     name,
@@ -1227,7 +1422,7 @@ sharedOpts2(scheduleCommand.command("create <name>").description("Create a new s
   });
   console.log(`✓ Schedule "${created.name}" → workflow "${created.workflow}" @ "${created.cron}" (${created.id})`);
 });
-sharedOpts2(scheduleCommand.command("list").description("List schedules in a factory")).action(async (opts) => {
+sharedOpts3(scheduleCommand.command("list").description("List schedules in a factory")).action(async (opts) => {
   const client = makeClient(opts);
   const rows = await client.listSchedules(opts.factory);
   if (rows.length === 0) {
@@ -1240,21 +1435,21 @@ sharedOpts2(scheduleCommand.command("list").description("List schedules in a fac
     console.log(`  ${s.name.padEnd(24)} ${s.workflowName.padEnd(20)} ${s.cron.padEnd(16)} next: ${next}  ${s.id}`);
   }
 });
-sharedOpts2(scheduleCommand.command("delete <id>").description("Delete a schedule by id")).action(async (id, opts) => {
+sharedOpts3(scheduleCommand.command("delete <id>").description("Delete a schedule by id")).action(async (id, opts) => {
   const client = makeClient(opts);
   await client.deleteSchedule(id, opts.factory);
   console.log(`✓ Schedule ${id} deleted from factory "${opts.factory}"`);
 });
 
 // src/commands/upgrade.ts
-import { Command as Command15 } from "commander";
+import { Command as Command18 } from "commander";
 import { spawnSync } from "node:child_process";
-import { readFileSync as readFileSync4 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import pc4 from "picocolors";
+import pc5 from "picocolors";
 var PACKAGE_NAME = "@agent-compose/cli";
-var upgradeCommand = new Command15("upgrade").description("Update the agentc CLI to the latest published version").option("--check", "Check for updates without installing", false).action(async (opts) => {
-  const pkg = JSON.parse(readFileSync4(fileURLToPath2(new URL("../../package.json", import.meta.url)), "utf8"));
+var upgradeCommand = new Command18("upgrade").description("Update the agentc CLI to the latest published version").option("--check", "Check for updates without installing", false).action(async (opts) => {
+  const pkg = JSON.parse(readFileSync5(fileURLToPath2(new URL("../../package.json", import.meta.url)), "utf8"));
   const current = pkg.version;
   const controller = new AbortController;
   const timeout = setTimeout(() => controller.abort(), 5000);
@@ -1273,34 +1468,34 @@ var upgradeCommand = new Command15("upgrade").description("Update the agentc CLI
     clearTimeout(timeout);
   }
   if (!latest) {
-    console.error(`${pc4.red("✗")} Couldn't reach the npm registry. Check your connection and try again.`);
+    console.error(`${pc5.red("✗")} Couldn't reach the npm registry. Check your connection and try again.`);
     process.exit(1);
   }
   if (latest === current) {
-    console.log(`${pc4.green("✓")} You're on the latest version (${pc4.bold(current)}).`);
+    console.log(`${pc5.green("✓")} You're on the latest version (${pc5.bold(current)}).`);
     return;
   }
-  console.log(`${pc4.yellow("●")} agentc ${pc4.bold(latest)} is available (you have ${current}).`);
+  console.log(`${pc5.yellow("●")} agentc ${pc5.bold(latest)} is available (you have ${current}).`);
   if (opts.check) {
-    console.log(`  Run ${pc4.cyan("agentc upgrade")} to install, or ${pc4.cyan("npm install -g " + PACKAGE_NAME + "@latest")} manually.`);
+    console.log(`  Run ${pc5.cyan("agentc upgrade")} to install, or ${pc5.cyan("npm install -g " + PACKAGE_NAME + "@latest")} manually.`);
     return;
   }
-  console.log(`  Running ${pc4.cyan("npm install -g " + PACKAGE_NAME + "@latest")} …`);
+  console.log(`  Running ${pc5.cyan("npm install -g " + PACKAGE_NAME + "@latest")} …`);
   const result = spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], { stdio: "inherit" });
   if (result.status !== 0) {
-    console.error(`${pc4.red("✗")} Install failed. Run the command above manually, or check for permission issues (npm prefix / sudo).`);
+    console.error(`${pc5.red("✗")} Install failed. Run the command above manually, or check for permission issues (npm prefix / sudo).`);
     process.exit(1);
   }
-  console.log(`${pc4.green("✓")} Installed ${pc4.bold(`agentc ${latest}`)}.`);
+  console.log(`${pc5.green("✓")} Installed ${pc5.bold(`agentc ${latest}`)}.`);
 });
 
 // src/update-check.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync5, writeFileSync } from "node:fs";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import { join as join3 } from "node:path";
 import { createInterface } from "node:readline/promises";
-import pc5 from "picocolors";
+import pc6 from "picocolors";
 var PACKAGE_NAME2 = "@agent-compose/cli";
 var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 var FETCH_TIMEOUT_MS = 2000;
@@ -1336,7 +1531,7 @@ function isNewer(latest, current) {
 }
 function readCache() {
   try {
-    const raw = readFileSync5(cachePath(), "utf8");
+    const raw = readFileSync6(cachePath(), "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.checkedAt !== "number")
       return null;
@@ -1352,7 +1547,7 @@ function writeCache(entry) {
   try {
     const path = cachePath();
     mkdirSync2(join3(path, ".."), { recursive: true });
-    writeFileSync(path, JSON.stringify(entry, null, 2) + `
+    writeFileSync2(path, JSON.stringify(entry, null, 2) + `
 `, "utf8");
   } catch {}
 }
@@ -1398,34 +1593,34 @@ async function checkForUpdate(currentVersion) {
   const latest = await resolveLatest();
   if (!latest || !isNewer(latest, currentVersion))
     return;
-  const headline = `${pc5.yellow("●")} agentc ${pc5.bold(latest)} is available (you have ${currentVersion}).`;
+  const headline = `${pc6.yellow("●")} agentc ${pc6.bold(latest)} is available (you have ${currentVersion}).`;
   process.stderr.write(`${headline}
 `);
   if (!process.stdin.isTTY) {
-    process.stderr.write(`  Run ${pc5.cyan("npm install -g " + PACKAGE_NAME2 + "@latest")} to update.
+    process.stderr.write(`  Run ${pc6.cyan("npm install -g " + PACKAGE_NAME2 + "@latest")} to update.
 `);
     return;
   }
-  const confirm = await promptYesNo(`  Install now? [y/${pc5.bold("N")}] `);
+  const confirm = await promptYesNo(`  Install now? [y/${pc6.bold("N")}] `);
   if (!confirm)
     return;
-  process.stderr.write(`  Running ${pc5.cyan("npm install -g " + PACKAGE_NAME2 + "@latest")} …
+  process.stderr.write(`  Running ${pc6.cyan("npm install -g " + PACKAGE_NAME2 + "@latest")} …
 `);
   const result = spawnSync2("npm", ["install", "-g", `${PACKAGE_NAME2}@latest`], {
     stdio: "inherit"
   });
   if (result.status !== 0) {
-    process.stderr.write(`${pc5.red("✗")} Install failed. Run the command above manually.
+    process.stderr.write(`${pc6.red("✗")} Install failed. Run the command above manually.
 `);
     return;
   }
-  process.stderr.write(`${pc5.green("✓")} Installed ${pc5.bold(`agentc ${latest}`)}. ` + `Re-run your command to use the new version.
+  process.stderr.write(`${pc6.green("✓")} Installed ${pc6.bold(`agentc ${latest}`)}. ` + `Re-run your command to use the new version.
 `);
   process.exit(0);
 }
 
 // src/index.ts
-var pkg = JSON.parse(readFileSync6(fileURLToPath3(new URL("../package.json", import.meta.url)), "utf8"));
+var pkg = JSON.parse(readFileSync7(fileURLToPath3(new URL("../package.json", import.meta.url)), "utf8"));
 program.name("agentc").description("Coordinate agent production lines.").version(pkg.version);
 program.hook("preAction", async () => {
   try {
@@ -1436,10 +1631,13 @@ program.addCommand(registerCommand);
 program.addCommand(invokeCommand);
 program.addCommand(listCommand);
 program.addCommand(cancelCommand);
+program.addCommand(pauseCommand);
 program.addCommand(scheduleCommand);
 program.addCommand(logsCommand);
 program.addCommand(eventsCommand);
+program.addCommand(filesCommand);
 program.addCommand(factoryCommand);
+program.addCommand(membersCommand);
 program.addCommand(snapshotCommand);
 program.addCommand(secretsCommand);
 program.addCommand(keysCommand);
@@ -1452,7 +1650,8 @@ Topics:
   Workflows         register, invoke, list, cancel
   Scheduling        schedule
   Run inspection    logs, events
-  Resources         factory, snapshot, secrets
+  Factory drive     files
+  Resources         factory, members, snapshot, secrets
   Account           keys, auth, usage
   Setup             init, upgrade
 
@@ -1461,8 +1660,9 @@ Examples:
   $ agentc invoke pipeline --follow
   $ agentc schedule create nightly --workflow pipeline --cron '0 9 * * *'
   $ agentc logs <run-id>
+  $ agentc files put report.md runs/abc123/report.md
 
 Docs:
   https://github.com/Layr-Labs/agent-compose
 `);
-program.parse();
+await program.parseAsync();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Command-line interface for agent-compose — register, invoke, and monitor workflows from your terminal.",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@agent-compose/sdk": "^0.5.2",
+    "@agent-compose/sdk": "^0.5.8",
     "commander": "^12.0.0",
     "picocolors": "^1.1.1"
   },

package/skills/ac:files.md

@@ -0,0 +1,84 @@
+---
+name: ac:files
+description: Read and write documents on a factory's drive from the CLI.
+allowed-tools: Bash(agentc *)
+effort: low
+---
+
+# Files
+
+Put files onto a factory's shared drive and read them back — all through
+`agentc`, no raw HTTP. The drive is where agent-written documents, briefs,
+and run artifacts live; the dashboard's **Files** tab renders them, and
+writes are indexed (revisions, search, attribution). Two subcommands:
+`agentc files put` and `agentc files get`.
+
+The primary consumer is an **agent working inside a run sandbox**: publishing
+work to the dashboard while the run is going. Inside a sandbox the env already
+carries `AGENT_COMPOSE_URL` / `AGENT_COMPOSE_API_KEY` / `AGENT_COMPOSE_FACTORY`,
+and the CLI attaches the run-callback token automatically so the write is
+**attributed to the run** (it shows on the file and in the run's Artifacts
+card). Works identically from a dev machine with saved credentials.
+
+> Requires an API key with `invoke` (writes) / `read` (reads). See `/ac:setup`.
+
+## When to use
+
+- **Publish run output** — an agent saves a report/brief so a human sees it
+  in the dashboard mid-run.
+- **Share between runs** — write a file other runs of the same factory read.
+- **Pull a file locally** — fetch a drive document to inspect or edit.
+
+## Upload a file
+
+```bash
+# Create or overwrite a drive file from a local file.
+# Convention: agents write under runs/<short-run-id>/...
+agentc files put report.md runs/abc123/report.md
+
+# Override the content type (default text/plain; charset=utf-8):
+agentc files put index.html sites/demo/index.html --content-type "text/html; charset=utf-8"
+
+# Target a non-default factory:
+agentc files put notes.md briefs/notes.md --factory my-factory
+```
+
+## Download / read a file
+
+```bash
+# Print a drive file to stdout:
+agentc files get briefs/site-7b7954fc.md
+
+# Save to a local file:
+agentc files get runs/abc123/report.md -o ./report.md
+
+# Read a specific historical revision:
+agentc files get briefs/notes.md --revision 12
+```
+
+## Browsing the drive
+
+There is no `agentc files list` — browse via the dashboard's **Files** tab,
+or (inside a sandbox whose factory has a provisioned Archil disk)
+`ls /factory` on the POSIX mount.
+
+## Authoring from inside a workflow
+
+The CLI is for agents + ad-hoc use. Workflow code uses the SDK, which attaches
+the run token the same way:
+
+```ts
+import { AgentComposeClient } from "@agent-compose/sdk";
+const client = new AgentComposeClient({ apiKey, baseUrl });
+await client.putFactoryFile("runs/abc123/report.md", contents, {
+  contentType: "text/markdown; charset=utf-8",
+});
+```
+
+## The drive vs. /factory mount
+
+If the factory has a provisioned Archil disk, the drive is also POSIX-mounted
+at `/factory` inside sandboxes — fine for reading and for scratch shared
+between sibling runs. But a direct `/factory` write is **not indexed** (no
+revision/attribution), so to make a file appear in the dashboard Files tab use
+`agentc files put` (or the SDK), which goes through the indexed files API.

package/skills/ac:generate-workflow.md

@@ -60,7 +60,7 @@ about "step-form vs run-form" — that's an internal call.
 - step-form vs run-form
 - sandbox environments / dependency installation
 - snapshots: `saveLatest`, `retainSteps`, `bootFrom`
-- `memory` / `postRunHooks` / `processors`
+- `processors`
 
 Decide those internally based on what they described (see the
 "Internal decisions" section below).
@@ -69,28 +69,44 @@ Decide those internally based on what they described (see the
 
 After answering the questions above, decide the shape WITHOUT asking:
 
-### Pick the workflow shape
-
-- **Step-form** (`defineWorkflow({...}).step(s1).step(s2).build()` with
-  `defineStep(...)` objects) — pick this when the body decomposes
-  cleanly into named phases with typed handoffs. Each step's output
-  threads into the next step's input. The dashboard renders each step
-  as a typed phase with its own duration. Examples: ETL pipelines,
-  classification → enrichment → publish, fetch → score → rank.
-
-- **Run-form** (one `async (ctx, sandbox)` body with `agent({...})`
-  calls inside) — pick this when the body is dominated by one or more
-  agent loops. Decomposing an LLM iteration into typed engine steps is
-  the wrong shape. Use `ctx.step("phase-name", () => …)` inside the
-  body for observability sub-events when there's pre-agent setup
-  worth tracing on the run timeline.
-
-When the user's description says "agent", "LLM", "the model decides",
-"reasons through", "writes a summary based on", "navigates the
-website" — that's run-form. When they describe deterministic phases
-that each transform structured data — that's step-form. If genuinely
-mixed, default to run-form and use `ctx.step` for the deterministic
-phases.
+### Pick the workflow shape — DEFAULT TO STEP-FORM
+
+**Default to step-form, even for agent-driven workflows.** Each meaningful
+phase — including an agent pass — becomes a `defineStep(...)`, and
+`snapshots: { saveLatest: true }` makes the engine capture a snapshot AFTER
+EACH step (latest-only). That durability is the whole point: if a later step's
+sandbox dies, or a step needs retrying, the engine resumes from the last
+completed step's snapshot instead of re-running the entire (often expensive,
+multi-agent) pipeline from the top.
+
+A multi-phase agent pipeline written **run-form is ONE engine step** — a single
+snapshot at the very end — so ANY failure throws away all the work and restarts
+at phase one. That's the brittleness step-form avoids.
+
+- **Step-form** (`defineWorkflow({ id, input, output, snapshots: { saveLatest: true } }).step(s1).step(s2).build()`
+  with `defineStep(...)` objects) — the default. Each phase (fetch, an agent
+  pass, a transform, a deploy) is a step. **Steps DO receive a `sandbox`** and
+  run `agent({ sandbox: ctx.sandbox, … })`, `ctx.sandbox.commands.run(…)`, etc.
+  — they are NOT limited to pure data transforms. Each step's output threads
+  into the next step's input. The dashboard renders each as a typed,
+  separately-timed, separately-snapshotted phase. Examples: content → imagery →
+  polish → verify → deploy; fetch → score → rank → publish.
+
+- **Run-form** (one `async (ctx, sandbox)` body) — LEGACY; being phased out in
+  favor of step-form everywhere. Only acceptable when the work is a SINGLE
+  indivisible agent loop with no meaningful phase boundaries. You give up
+  per-step snapshots (one capture at the very end). Use `ctx.step("phase", () => …)`
+  inside for timeline observability — it is NOT a snapshot boundary.
+  ⚠️ Replay semantics: a paused run-form workflow RESUMES BY RE-EXECUTING the
+  whole function from the top — only `ctx.requestDecision` results are
+  memoized. Every pre-pause side effect re-fires on resume, so writes must be
+  create-only/non-clobbering (an unconditional re-write destroyed a human's
+  pause-time edits in production testing). If the workflow pauses at all,
+  author it step-form: completed steps structurally never replay.
+
+If the work has more than one phase — especially multiple agent passes, or any
+step whose work you'd hate to lose on a failure — it's step-form. Each such
+phase is its own step.
 
 ### Should it have a sandbox environment?
 
@@ -126,6 +142,21 @@ Most workflows DO NOT need this. Default to no sandbox env.
   IO panels; without them, fields show only their type.
 - `.describe("...")` on the root schema too where helpful — surfaces
   at the panel header.
+- **Persist outputs to the factory drive — `$AGENT_COMPOSE_RUN_DIR`.**
+  Anything the workflow produces that should survive the run (the
+  deliverable, agent artifacts, reports) MUST be written under the run's
+  factory directory, exposed in the sandbox as `$AGENT_COMPOSE_RUN_DIR`
+  (`/factory/files/<workflow>/<version>/<run-id>/`). Files written only
+  to `/workspace` are **ephemeral** — they vanish when the sandbox is
+  reclaimed, never appear in the factory's files, and aren't available
+  as prior-run context to future runs. Read the dir from the sandbox
+  shell (it's injected there), not at module top-level (the workflow VM
+  has no `process.env`): e.g. in a step,
+  `const runDir = (await ctx.sandbox.commands.run('printf %s "${AGENT_COMPOSE_RUN_DIR:-/workspace}"')).stdout.trim()`,
+  then write the deliverable to `${runDir}/...` and tell any agents to do
+  the same. Use `/workspace` only for throwaway scratch. Sibling dirs
+  under `$AGENT_COMPOSE_FACTORY_DIR/<workflow>/` hold prior runs' outputs —
+  read them for continuity instead of re-deriving.
 
 ## Templates
 
@@ -196,6 +227,7 @@ export default defineWorkflow({
   description: "Pulls open PRs from a GitHub repo, scores each one by review urgency, surfaces the top five.",
   input:       InputSchema,
   output:      OutputSchema,
+  snapshots:   { saveLatest: true }, // snapshot after each step → resume from the last one, not the top
 })
   .step(fetchStep)
   .step(scoreStep)
@@ -206,10 +238,18 @@ export default defineWorkflow({
 Notes:
 - Each step's `output` schema must satisfy the next step's `input`
   schema (the SDK enforces this at `defineWorkflow().step(...)` time
-  via TS inference). Reshape inside the upstream step's `run` body,
-  not at the boundary.
-- Step bodies don't receive a `sandbox`. If a step needs to run code
-  inside the runner VM, that's the agent-driven shape — use run-form.
+  via TS inference), and the FINAL step's `output` must be the same
+  zod instance as the workflow's declared `output`. Reshape inside the
+  upstream step's `run` body, not at the boundary.
+- **Step bodies DO receive a `sandbox`** — `ctx.sandbox` is present
+  whenever the run executes in a sandbox-backed workspace. Run
+  `agent({ sandbox: ctx.sandbox, … })`, `ctx.sandbox.commands.run(…)`,
+  `ctx.sandbox.files.write(…)` inside any step. (The example above uses
+  pure transforms, but an agent pass is a perfectly good step — and the
+  preferred shape, because each step is independently snapshotted.)
+- `snapshots: { saveLatest: true }` captures the sandbox after EACH
+  step (latest-only); add `retainSteps: true` only if you need every
+  step's snapshot kept for fork/replay (linear storage cost).
 
 ### Template B — run-form (agent-driven body)
 
@@ -281,13 +321,6 @@ export default defineWorkflow({
   //     saveLatest:  true,
   //     retainSteps: false,
   //   },
-  //
-  // memory — opt-in. Requires `workflow-memory` to be registered in
-  // this factory.
-  //   memory: true,
-  //
-  // postRunHooks — workflows that run after this one completes:
-  //   postRunHooks: ["audit-trail", "notify-slack"],
 });
 ```
 
@@ -347,20 +380,3 @@ export default defineWorkflow({
      "To run it on the schedule: `agentc schedule create pr-triage-daily
      --workflow pr-triage --cron '<expr>'` — the cron pattern we
      worked out earlier.")
-
-## When the user asks for memory extraction
-
-The built-in memory extractor (`workflow-memory`) is a separate
-workflow that must be registered in the same factory. Walk them
-through it in user terms:
-
-1. "I'll add the `workflow-memory` recipe to your project."
-   Copy from `.agentc/templates/workflow-memory.ts`.
-2. "Run `agentc register ./workflow-memory.ts` once to install it."
-3. "Now any workflow with `memory: true` will trigger it after each
-   successful run."
-
-For custom post-run workflows (analytics, audit, notifications)
-without the built-in extractor, use `postRunHooks: [...]` instead.
-Each post-hook runs in declaration order with the source run's full
-context.