@agent-compose/cli 0.3.3 → 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";
 
@@ -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,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)
@@ -205,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…`);
@@ -242,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
@@ -1213,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,
@@ -1227,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) {
@@ -1240,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);
@@ -1296,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";
@@ -1336,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;
@@ -1352,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 {}
 }
@@ -1425,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 {
@@ -1439,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);
@@ -1452,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
@@ -1461,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.3",
+  "version": "0.3.4",
   "description": "Command-line interface for agent-compose — register, invoke, and monitor workflows from your terminal.",
   "license": "MIT",
   "repository": {

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,20 +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 `.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.