@agent-compose/cli 0.3.2 → 0.3.4

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";
 
@@ -137,7 +137,8 @@ async function saveLocalSettings(projectDir, settings) {
 var [_project, _projectDir] = findProjectRoot();
 var _local = loadLocalSettings(_projectDir);
 var _global = loadGlobalSettings();
-var _activeEnv = _local.env ?? (_project.envs?.["prod"] ? "prod" : undefined);
+var _candidateEnv = _local.env ?? _project.defaultEnv ?? "prod";
+var _activeEnv = _project.envs?.[_candidateEnv] ? _candidateEnv : undefined;
 var _envUrl = _activeEnv ? _project.envs?.[_activeEnv]?.url : undefined;
 var _envDashboardUrl = _activeEnv ? _project.envs?.[_activeEnv]?.dashboardUrl : undefined;
 var _envKey = _activeEnv ? _local.keys?.[_activeEnv] : undefined;
@@ -146,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";
@@ -154,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
@@ -183,7 +189,9 @@ 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, 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)
@@ -204,18 +212,14 @@ var registerCommand = new Command("register").description("Register a workflow w
     ...networkPolicy ? { networkPolicy } : {},
     ...placeholders ? { placeholders } : {},
     ...snapshots !== undefined ? { snapshots } : {},
-    ...memory !== undefined ? { memory } : {},
-    ...postRunHooks !== undefined ? { postRunHooks } : {},
     ...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…`);
@@ -241,7 +245,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
@@ -257,8 +261,15 @@ function fmt(ms) {
   return `${Math.floor(ms / 60000)}m ${Math.floor(ms % 60000 / 1000)}s`;
 }
 function extractToolSnippet(toolInput) {
-  const raw = toolInput ? String(toolInput) : "";
-  return raw.match(/"(?:command|file_path|url|query|pattern)":"([^"]{1,80})/)?.[1] ?? "";
+  if (!toolInput || typeof toolInput !== "object")
+    return "";
+  const input = toolInput;
+  for (const key of ["command", "file_path", "url", "query", "pattern"]) {
+    const value = input[key];
+    if (typeof value === "string" && value.length > 0)
+      return value.slice(0, 80);
+  }
+  return "";
 }
 function printAgentMessage(data) {
   const message = data.message;
@@ -280,7 +291,7 @@ function printAgentMessage(data) {
       break;
     }
     case "tool_use": {
-      const detail = extractToolSnippet(message.toolInputPreview);
+      const detail = extractToolSnippet(message.toolInput);
       process.stdout.write(`  ${pc.cyan("→")} ${pc.bold(String(message.toolName ?? "tool"))}${detail ? `  ${pc.dim(detail)}` : ""}
 `);
       break;
@@ -291,6 +302,15 @@ function printAgentMessage(data) {
       break;
   }
 }
+function printConsoleLine(line) {
+  const text = line.line.trimEnd();
+  if (!text)
+    return;
+  const label = line.stream === "stderr" ? pc.red("stderr") : pc.dim("stdout");
+  const color = line.stream === "stderr" ? pc.red : pc.dim;
+  process.stdout.write(`${label} ${color(text)}
+`);
+}
 function printEvent(event, data, state) {
   switch (event) {
     case "step_started":
@@ -424,45 +444,81 @@ ${pc.bold(pc.yellow("⊘ Run canceled"))}
   }
 }
 var TERMINAL_EVENTS = new Set(["run_complete", "run_failed", "run_canceled"]);
+var CONSOLE_POLL_MS = 500;
 async function streamLogs(runId, opts) {
   const client = makeClient(opts);
+  const view = opts.view ?? "all";
   const state = {
     agentStart: new Map,
     agentLabel: new Map,
     startedAt: Date.now()
   };
   let lastSeq = 0;
+  let lastLogId = 0;
+  let stopConsole = false;
   const MAX_RETRIES = 5;
-  for (let attempt = 0;attempt <= MAX_RETRIES; attempt++) {
-    let settled = false;
-    try {
-      for await (const ev of client.streamRunLogs(runId, { lastEventId: lastSeq })) {
-        const seq = ev.seq ?? 0;
-        if (seq > 0)
-          lastSeq = seq;
-        printEvent(ev.event, ev, state);
-        if (TERMINAL_EVENTS.has(ev.event)) {
-          settled = true;
-          break;
+  const drainConsole = async () => {
+    const lines = await client.listRunLogs(runId, { afterId: lastLogId, limit: 200, direction: "asc" });
+    for (const line of lines) {
+      if (line.id > lastLogId)
+        lastLogId = line.id;
+      printConsoleLine(line);
+    }
+  };
+  const consoleLoop = view === "agent" ? null : (async () => {
+    while (!stopConsole) {
+      await drainConsole().catch((err) => {
+        if (err instanceof AgentComposeError2 && err.status === 404)
+          return;
+        throw err;
+      });
+      if (!stopConsole)
+        await new Promise((r) => setTimeout(r, CONSOLE_POLL_MS));
+    }
+    await drainConsole().catch(() => {});
+  })();
+  try {
+    for (let attempt = 0;attempt <= MAX_RETRIES; attempt++) {
+      let settled = false;
+      try {
+        for await (const ev of client.streamRunLogs(runId, { lastEventId: lastSeq })) {
+          const seq = ev.seq ?? 0;
+          if (seq > 0)
+            lastSeq = seq;
+          if (view !== "console" || TERMINAL_EVENTS.has(ev.event)) {
+            printEvent(ev.event, ev, state);
+          }
+          if (TERMINAL_EVENTS.has(ev.event)) {
+            settled = true;
+            break;
+          }
         }
+      } catch (err) {
+        if (err instanceof AgentComposeError2) {
+          console.error(`Error: failed to connect to log stream (${err.status})`);
+          process.exit(1);
+        }
+        throw err;
       }
-    } catch (err) {
-      if (err instanceof AgentComposeError2) {
-        console.error(`Error: failed to connect to log stream (${err.status})`);
-        process.exit(1);
-      }
-      throw err;
+      if (settled)
+        return;
+      if (attempt < MAX_RETRIES)
+        await new Promise((r) => setTimeout(r, 200));
     }
-    if (settled)
-      return;
-    if (attempt < MAX_RETRIES)
-      await new Promise((r) => setTimeout(r, 200));
+  } finally {
+    stopConsole = true;
+    await consoleLoop;
   }
   console.error("Error: stream closed without terminal event after retries");
   process.exit(1);
 }
-var logsCommand = new Command2("logs").description("Stream logs for a run").argument("<run-id>", "Run ID").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (runId, opts) => {
-  await streamLogs(runId, opts);
+var logsCommand = new Command2("logs").description("Stream logs for a run").argument("<run-id>", "Run ID").option("--agent", "Show structured agent/lifecycle events only").option("--console", "Show raw runner stdout/stderr only").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (runId, opts) => {
+  if (opts.agent && opts.console) {
+    console.error("Error: choose only one of --agent or --console");
+    process.exit(1);
+  }
+  const view = opts.agent ? "agent" : opts.console ? "console" : "all";
+  await streamLogs(runId, { ...opts, view });
 });
 
 // src/commands/invoke.ts
@@ -1160,11 +1216,38 @@ var listCommand2 = new Command13("list").description("List events for a run, or
 });
 var eventsCommand = new Command13("events").description("Send or list run events (Events API)").addCommand(sendCommand).addCommand(listCommand2);
 
-// src/commands/schedule.ts
+// src/commands/files.ts
+import { readFileSync as readFileSync4, writeFileSync } from "node:fs";
 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) => {
+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 Command14("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);
+  }
+});
+
+// src/commands/schedule.ts
+import { Command as Command15 } 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 Command15("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,
@@ -1174,7 +1257,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) {
@@ -1187,21 +1270,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 Command16 } 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";
 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 Command16("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);
@@ -1243,7 +1326,7 @@ var upgradeCommand = new Command15("upgrade").description("Update the agentc CLI
 
 // 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";
@@ -1283,7 +1366,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;
@@ -1299,7 +1382,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 {}
 }
@@ -1372,7 +1455,7 @@ async function checkForUpdate(currentVersion) {
 }
 
 // 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 {
@@ -1386,6 +1469,7 @@ program.addCommand(cancelCommand);
 program.addCommand(scheduleCommand);
 program.addCommand(logsCommand);
 program.addCommand(eventsCommand);
+program.addCommand(filesCommand);
 program.addCommand(factoryCommand);
 program.addCommand(snapshotCommand);
 program.addCommand(secretsCommand);
@@ -1399,6 +1483,7 @@ Topics:
   Workflows         register, invoke, list, cancel
   Scheduling        schedule
   Run inspection    logs, events
+  Factory drive     files
   Resources         factory, snapshot, secrets
   Account           keys, auth, usage
   Setup             init, upgrade
@@ -1408,6 +1493,7 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/cli",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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.1",
+    "@agent-compose/sdk": "^0.5.2",
     "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?
 
@@ -196,6 +212,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 +223,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 +306,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,22 +365,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 `templates/workflow-memory.ts` (or
-   `.agentc/smoketest/workflows/workflow-memory.ts` for the smoke
-   variant).
-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.