@agent-compose/cli 0.1.4 → 0.2.0

package/dist/index.js

@@ -162,7 +162,7 @@ function makeClient({ url, apiKey }) {
 ` + "  • Flag:        --api-key YOUR_KEY");
     process.exit(1);
   }
-  return new AgentComposeClient(url, apiKey);
+  return new AgentComposeClient({ apiKey, baseUrl: url });
 }
 function reportSdkError(err) {
   const msg = err instanceof AgentComposeError ? err.message : err instanceof Error ? err.message : String(err);
@@ -183,13 +183,13 @@ var registerCommand = new Command("register").description("Register a workflow w
     console.error(`Error: workflow not found at ${workflowPath}`);
     process.exit(1);
   }
-  const { source, manifest, networkPolicy, placeholders, snapshot, saveSnapshot, memory, workflowPlan } = await bundleWorkflow(workflowPath);
+  const { source, manifest, networkPolicy, placeholders, snapshots, memory, postRunHooks, inputSchema, outputSchema, workflowPlan } = await bundleWorkflow(workflowPath);
   if (networkPolicy)
     console.log(`[register] Network policy detected — credentials will be brokered via Vercel firewall`);
-  if (snapshot)
-    console.log(`[register] Boots from snapshot: ${snapshot}`);
-  if (saveSnapshot)
-    console.log(`[register] Captures snapshot on success (saveSnapshot: true)`);
+  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)" : ""}`);
   const client = makeClient(opts);
   console.log(`[register] Registering "${name}" → factory "${opts.factory}"…`);
   const result = await client.register({
@@ -202,16 +202,23 @@ var registerCommand = new Command("register").description("Register a workflow w
     ...opts.schedule ? { schedule: opts.schedule } : {},
     ...networkPolicy ? { networkPolicy } : {},
     ...placeholders ? { placeholders } : {},
-    ...snapshot ? { snapshot } : {},
-    ...saveSnapshot !== undefined ? { saveSnapshot } : {},
-    ...memory !== undefined ? { memory } : {}
+    ...snapshots !== undefined ? { snapshots } : {},
+    ...memory !== undefined ? { memory } : {},
+    ...postRunHooks !== undefined ? { postRunHooks } : {},
+    ...inputSchema !== undefined ? { inputSchema } : {},
+    ...outputSchema !== undefined ? { outputSchema } : {}
   });
   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 saveSnapshot:true to capture a snapshot…`);
-  const { id: runId } = await client.invoke(name, {}, { saveSnapshot: true, factorySlug: opts.factory });
+  console.log(`[build] Invoking "${name}" with snapshots:{ saveLatest: true } to capture a snapshot…`);
+  const { id: runId } = await client.invoke(name, {}, { snapshots: { saveLatest: true }, factorySlug: opts.factory });
   console.log(`[build] Run: ${runId} — waiting for completion…`);
   const pollIntervalMs = 2000;
   const timeoutMinutes = opts.buildTimeout ?? 30;
@@ -220,7 +227,7 @@ var registerCommand = new Command("register").description("Register a workflow w
   while (Date.now() < deadline) {
     const { status } = await client.getStatus(runId);
     if (status === "success") {
-      console.log(`✓ Snapshot ready — other workflows can now reference \`snapshot: "${name}"\``);
+      console.log(`✓ Snapshot ready — other workflows can now reference \`snapshots: { bootFrom: { workflow: "${name}" } }\``);
       return;
     }
     if (status === "failed" || status === "abandoned") {
@@ -232,6 +239,13 @@ var registerCommand = new Command("register").description("Register a workflow w
   console.error(`✗ Build timed out after ${timeoutMs / 60000}m (run ${runId} still running)`);
   process.exit(1);
 });
+function formatBootFrom(b) {
+  if (b.snapshotId)
+    return `snapshot ${b.snapshotId}`;
+  if (b.workflow)
+    return b.version ? `${b.workflow}@${b.version}` : `${b.workflow} (latest)`;
+  return "(unknown)";
+}
 
 // src/commands/invoke.ts
 import { Command as Command3 } from "commander";
@@ -658,7 +672,7 @@ keysCommand.command("create <name>").description("Create a new API key (requires
       process.exit(1);
     }
   }
-  const client = new AgentComposeClient2(opts.url, opts.adminKey);
+  const client = new AgentComposeClient2({ apiKey: opts.adminKey, baseUrl: opts.url });
   const created = await client.createApiKey({
     name,
     ...scopes && { scopes },
@@ -682,7 +696,7 @@ API key created for "${name}":
 });
 keysCommand.command("list").description("List API keys for your team (requires admin-scoped ac_… key)").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--admin-key <key>", "Admin-scoped ac_… key", process.env.AGENT_COMPOSE_ADMIN_KEY ?? "").action(async (opts) => {
   requireAdminKey(opts.adminKey);
-  const client = new AgentComposeClient2(opts.url, opts.adminKey);
+  const client = new AgentComposeClient2({ apiKey: opts.adminKey, baseUrl: opts.url });
   const data = await client.listApiKeys().catch(reportSdkError);
   if (!data.length) {
     console.log("No API keys.");
@@ -884,24 +898,49 @@ 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");
-snapshotCommand.command("list").description("List runs that have a captured sandbox snapshot").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("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (opts) => {
-  const rows = await makeClient(opts).listSnapshots({
+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,
     ...opts.workflow ? { workflow: opts.workflow } : {},
-    ...opts.limit != null ? { limit: opts.limit } : {}
+    ...opts.limit != null ? { limit: opts.limit } : {},
+    ...opts.before ? { before: opts.before } : {}
   });
+  const rows = page.data;
   if (rows.length === 0) {
     console.log("No captured snapshots.");
     return;
   }
   for (const r of rows) {
     const wfRef = r.workflow ? `${r.workflow}${r.version ? `@${r.version}` : ""}` : "-";
-    const when = r.endedAt ?? "-";
-    console.log(`${r.runId}  ${wfRef}  ${when}  ${r.vercelSnapshotId}`);
+    const label = r.kind === "step" ? `step ${r.stepIndex}` : "latest";
+    const when = r.createdAt ?? "-";
+    console.log(`${r.runId}  ${label.padEnd(8)}  ${wfRef}  ${when}  ${r.snapshotId}`);
+  }
+  if (page.has_more && page.next_cursor) {
+    console.log(`next_cursor: ${page.next_cursor}`);
+  }
+});
+snapshotCommand.command("delete").description("Delete a captured snapshot. With <snapshot-id>, deletes that specific snapshot from the run; without, clears the run's latest snapshot pointer.").argument("<run-id>", "Run ID (UUID)").argument("[snapshot-id]", "Optional provider snapshot id (Vercel snapshot id)").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (runId, snapshotId, opts) => {
+  const client = makeClient(opts);
+  if (snapshotId) {
+    await client.deleteRunSnapshot(runId, snapshotId);
+    console.log(`Deleted snapshot ${snapshotId} from run ${runId}`);
+  } else {
+    await client.deleteSnapshot(runId);
+    console.log(`Deleted snapshot for run ${runId}`);
   }
 });
-snapshotCommand.command("delete").description("Delete the snapshot captured by a specific run").argument("<run-id>", "Run ID (UUID)").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (runId, opts) => {
-  await makeClient(opts).deleteSnapshot(runId);
-  console.log(`✓ Deleted snapshot for run ${runId}`);
+snapshotCommand.command("show").description("List every snapshot held for a run (latest + retained step snapshots)").argument("<run-id>", "Run ID (UUID)").option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey).action(async (runId, opts) => {
+  const rows = await makeClient(opts).listRunSnapshots(runId);
+  if (rows.length === 0) {
+    console.log(`No snapshots for run ${runId}.`);
+    return;
+  }
+  for (const r of rows) {
+    const label = r.kind === "step" ? `step ${r.stepIndex}` : "latest";
+    const when = r.createdAt ?? "-";
+    console.log(`${label.padEnd(10)}  ${when}  ${r.snapshotId}`);
+  }
 });
 
 // src/commands/factory.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/cli",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "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.2.5",
+    "@agent-compose/sdk": "^0.3.0",
     "commander":          "^12.0.0",
     "picocolors":         "^1.1.1"
   },

package/skills/ac:events.md

@@ -0,0 +1,98 @@
+---
+name: ac:events
+description: Send, list, and inspect events on agent-compose runs.
+allowed-tools: Bash(agentc *)
+effort: low
+---
+
+# Events
+
+Send events into an in-flight run, or list events from any run / the
+whole factory. Events are structured, idempotent, propagating signals
+authors emit alongside the agent loop — the dashboard's run timeline
+renders them, downstream workflows subscribe to them, and analytics
+queries scan them.
+
+> Requires an API key with the `events:write` scope (or `invoke` for
+> writes; reads are un-gated beyond authn). See `/ac:setup` to mint one.
+
+## When to use
+
+- **Test a deployed workflow** — send a synthetic event to verify a
+  downstream subscriber fires.
+- **Inspect what a run emitted** — list a run's full event stream when
+  the dashboard isn't open.
+- **Audit factory traffic** — list factory-wide events filtered by name
+  or time range when debugging cross-workflow contracts.
+
+## Send an event
+
+```bash
+# Simplest form — empty body, idempotent on (run, name) when --idempotency-key is set.
+agentc events send <run-id> quality.accepted
+
+# With body + summary + a single attribute:
+agentc events send <run-id> deploy.completed \
+  --body '{"env":"prod","sha":"abc123"}' \
+  --summary "deploy to prod succeeded" \
+  -a region=us-east-1 \
+  -a duration_ms=42000
+
+# Body from file:
+agentc events send <run-id> review.done --body @review.json
+
+# Replay-safe — re-running with the same key returns the original event id:
+agentc events send <run-id> milestone --idempotency-key milestone:phase-2
+```
+
+Useful flags:
+
+| Flag                    | Notes                                                              |
+|-------------------------|--------------------------------------------------------------------|
+| `--body @file`          | Inline JSON OR `@path/to/file`                                      |
+| `--summary "<text>"`    | One-line human description (≤2000 chars)                            |
+| `--confidence 0..1`     | Useful for verification events                                      |
+| `-a key=value` (repeat) | Attributes. Values JSON-parsed when possible (`-a count=3` → number) |
+| `--idempotency-key <k>` | (run, name, key) collapses to a single event                        |
+| `--no-propagate`        | Mark this event as terminal — don't fan out to subscribers          |
+| `--timestamp <iso>`     | Override event time (defaults to server-now)                        |
+| `--json`                | Print the raw event JSON instead of the one-line summary            |
+
+## List events
+
+```bash
+# All events for a run:
+agentc events list <run-id>
+
+# Factory-wide (omit run id, add --factory):
+agentc events list --factory default
+
+# Filter by event name pattern:
+agentc events list <run-id> --name "deploy.*"
+
+# Page with --limit (default 50, max 500):
+agentc events list <run-id> --limit 200
+```
+
+## Authoring events from inside a workflow
+
+The CLI is for ad-hoc / testing use. Production workflows emit events via
+`ctx.reportEvent(...)` (SDK):
+
+```ts
+await ctx.reportEvent("deploy.completed", {
+  body:        { env: "prod", sha },
+  summary:     `deploy to prod (${sha.slice(0, 7)})`,
+  confidence:  1.0,
+  attributes:  { region: "us-east-1" },
+});
+```
+
+## Verify the events scope
+
+```bash
+agentc keys list                              # confirm the active key has events:write
+agentc events send <test-run> ping            # if 403, the key is missing the scope
+```
+
+Suggest `/ac:setup` if the key needs minting / rotating.

package/skills/ac:generate-workflow.md

@@ -19,20 +19,26 @@ Interactively scaffold a new workflow from a plain-English description.
 ## Steps
 
 1. Ask the user:
-   - What should this workflow do? (plain English — describe the
-     phases, their inputs/outputs, and any external calls.)
+   - What should this workflow do? (plain English — describe the phases,
+     their inputs/outputs, and any external calls.)
    - Workflow name? (kebab-case, e.g. `code-review`)
    - Where to create it? (project-relative path, e.g. `src/workflows/`)
    - Runtime for agent loops? (default `claudeRuntime`)
-   - Network policy needed? (which domains + which secrets to inject?)
-   - Snapshot on success? (default off; on for setup/environment
+   - Network policy needed? (which domains + which brokered secrets to inject?)
+   - Capture a snapshot on success? (default off; on for setup/environment
      workflows whose end-state other workflows boot from)
+   - Boot this run from another workflow's snapshot? (default no — fresh
+     `node24` base sandbox)
+   - Enable the built-in memory extractor? (default off — opt in only when
+     this workflow's events are worth memorising AND the `workflow-memory`
+     template is registered in the same factory)
+   - Additional post-hooks? (ordered list of workflow names that fan out
+     after this run completes)
 
-2. If the user has a reference workflow in their project, read it to
-   match their conventions (prompt structure,
-   error handling). Otherwise follow the patterns in
-   [`sdk/README.md`](../../sdk/README.md) and the example in
-   [`docs/how-it-works.md`](../../docs/how-it-works.md).
+2. If the user has a reference workflow in their project, read it to match
+   their conventions (prompt structure, error handling). Otherwise follow
+   the patterns in [`sdk/README.md`](../../sdk/README.md) and the example
+   in [`docs/how-it-works.md`](../../docs/how-it-works.md).
 
 3. Generate a complete, real implementation:
 
@@ -62,11 +68,43 @@ Interactively scaffold a new workflow from a plain-English description.
        await ctx.setMetadata({ summary: result.status?.summary });
        return { ok: !!result.status?.completed };
      },
-     // Optional metadata picked up by the bundler at registration time:
-     // networkPolicy: { allow: { /* … */ } },
-     // placeholders:  { /* env-var formats for brokered secrets */ },
-     // snapshot: "<other-workflow>",   // boot from a snapshot
-     // snapshot: true,                           // capture-on-success default
+
+     // ── Optional metadata picked up by the bundler at registration ──
+     //
+     // networkPolicy / placeholders — outbound traffic + brokered secrets:
+     //
+     //   networkPolicy: {
+     //     allow: {
+     //       "api.github.com": [{ transform: [{ headers: {
+     //         Authorization: "basic:$GITHUB_TOKEN",
+     //       } }] }],
+     //       "*.openai.com":   [{ transform: [{ headers: {
+     //         "OpenAI-Beta":  "$OPENAI_BETA_HEADER",
+     //       } }] }],
+     //     },
+     //   },
+     //   // Placeholder values the runner sees in env vars AFTER brokering.
+     //   // The real secret never enters the VM — Vercel's firewall
+     //   // substitutes it on the way out. Only needed when a tool /
+     //   // SDK validates the env-var format on startup.
+     //   placeholders: { GITHUB_TOKEN: "ghp_" + "x".repeat(36) },
+     //
+     // snapshots — all snapshot config in one object:
+     //
+     //   snapshots: {
+     //     // Boot from a specific captured snapshot. Pick the id from
+     //     // `agentc snapshot list` or the factory snapshots page.
+     //     bootFrom:    { snapshotId: "snap_abc…" },
+     //     saveLatest:  true,    // capture sandbox on success
+     //     retainSteps: false,   // keep one snapshot per successful step
+     //   },
+     //
+     // memory — opt-in (default false). Requires `workflow-memory` to
+     //          be registered in this factory.
+     //   memory: true,
+     //
+     // postRunHooks — ordered list of workflow names that run after this:
+     //   postRunHooks: ["audit-trail", "notify-slack"],
    });
    ```
 
@@ -82,3 +120,18 @@ Interactively scaffold a new workflow from a plain-English description.
 
 6. Tell the user: `agentc register <path>` to register, then
    `agentc invoke <name> --follow` to test.
+
+## 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:
+
+1. Copy the reference recipe from `templates/workflow-memory.ts` (or
+   `.agentc/smoketest/workflows/workflow-memory.ts` for the smoke
+   variant) into their project.
+2. `agentc register ./workflow-memory.ts` to install it.
+3. Set `memory: true` on the source workflow(s) — done.
+
+If they want to skip the built-in and run custom post-run workflows,
+use `postRunHooks: [...]` instead. Each post-hook is dispatched in order
+with the source run's full context.

package/skills/ac:snapshots.md

@@ -0,0 +1,128 @@
+---
+name: ac:snapshots
+description: List, inspect, and delete captured sandbox snapshots.
+allowed-tools: Bash(agentc *)
+effort: low
+---
+
+# Snapshots
+
+Sandbox snapshots are paid Vercel storage that does **not** auto-expire —
+operators manage them by hand. This skill walks list/inspect/delete
+through `agentc snapshot ...` for captured snapshots in one factory.
+
+> **Mental model.** A snapshot is the on-disk state of a runner VM,
+> captured at the end of a successful step. Other workflows boot from
+> it via `snapshots: { bootFrom: { snapshotId: "snap_…" } }` — the
+> snapshot id is the unit of identity. Operators pick a snapshot from
+> the dashboard snapshot list (or `agentc snapshot list`), copy the id,
+> and use it.
+
+## When to use
+
+- **Find out what you're paying for** — list everything captured and
+  spot stale workflows nobody references.
+- **Surface a snapshot id** to pin a workflow to a specific captured
+  state across deploys.
+- **Free storage** by deleting snapshots you no longer need.
+
+## List captured snapshots
+
+```bash
+# Everything captured by the active/default factory:
+agentc snapshot list
+
+# A specific factory:
+agentc snapshot list --factory my-factory
+
+# Filter to a single workflow:
+agentc snapshot list --workflow my-setup
+
+# Trim the page (default 50, max 500):
+agentc snapshot list --limit 200
+
+# Continue from a previous page:
+agentc snapshot list --before <next_cursor>
+```
+
+Output is one row per captured snapshot:
+
+```
+<run-id>  <capture>  <workflow>@<version>  <captured-at>  <snapshot-id>
+```
+
+The dashboard has a richer view at `/factories/<slug>/snapshots` — same
+data plus size in bytes, capture kind (`latest` vs retained step), and
+delete buttons. Use the CLI for scripting / quick triage.
+
+## Inspect a single run's snapshots
+
+A run that opted into `snapshots: { saveLatest: true, retainSteps: true }`
+ends up with one snapshot per successful step plus the latest pointer.
+List them with:
+
+```bash
+# All snapshots attached to a single run (latest + retained per-step):
+agentc snapshot show <run-id>
+```
+
+Each row shows step index (or "latest"), capture time, snapshot id, and
+size.
+
+## Delete
+
+```bash
+# Delete the run's latest snapshot pointer (legacy shorthand):
+agentc snapshot delete <run-id>
+
+# Delete a specific snapshot id from a run:
+agentc snapshot delete <run-id> <snapshot-id>
+```
+
+Once deleted, any workflow referencing that snapshot via
+`bootFrom: { snapshotId }` gets a 503 at dispatch time. There's no
+"latest of workflow X" fallback — the reference is to a specific
+snapshot id, so it has to exist. Re-register the consuming workflow
+with a different snapshot id (or re-capture).
+
+## Reference a snapshot from another workflow
+
+```ts
+import { defineWorkflow } from "@agent-compose/sdk";
+
+export default defineWorkflow({
+  // Boot from a captured snapshot. Pick the id from
+  // `agentc snapshot list` or the factory snapshots page.
+  snapshots: { bootFrom: { snapshotId: "snap_abc…" } },
+
+  async run(ctx, sandbox) {
+    // Sandbox boots in the captured state — no setup re-runs.
+  },
+});
+```
+
+## Capture a snapshot from a workflow
+
+```ts
+// On every successful run — captures the sandbox VM after the last step:
+defineWorkflow({ snapshots: { saveLatest: true }, run: ... });
+
+// Retain one per step (storage scales with step count):
+defineWorkflow({ snapshots: { saveLatest: true, retainSteps: true }, run: ... });
+```
+
+Per-invocation override:
+
+```bash
+# Force capture for one specific run (overrides the registered default):
+agentc invoke my-workflow --follow            # no override
+# (no CLI flag yet for snapshot capture; use the SDK or dashboard
+# playground for per-invocation overrides.)
+```
+
+## Costs
+
+Vercel snapshots: ~$0.08/GB-month (Pro/Enterprise pricing — confirm in
+your plan). A 3 GB rootfs diff captured every 30s would burn ~$20k/month
+in storage if every run kept one. Use `retainSteps` carefully on
+high-frequency workflows.