@agent-compose/cli 0.1.2 → 0.1.3

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 readFileSync3 } from "node:fs";
+import { readFileSync as readFileSync4 } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { program } from "commander";
 
@@ -183,7 +183,7 @@ var registerCommand = new Command("register").description("Register a workflow w
     console.error(`Error: workflow not found at ${workflowPath}`);
     process.exit(1);
   }
-  const { source, networkPolicy, placeholders, snapshot, saveSnapshot } = await bundleWorkflow(workflowPath);
+  const { source, manifest, networkPolicy, placeholders, snapshot, saveSnapshot, memory, workflowPlan } = await bundleWorkflow(workflowPath);
   if (networkPolicy)
     console.log(`[register] Network policy detected — credentials will be brokered via Vercel firewall`);
   if (snapshot)
@@ -195,13 +195,16 @@ var registerCommand = new Command("register").description("Register a workflow w
   const result = await client.register({
     name,
     source,
+    manifest,
+    workflowPlan,
     factorySlug: opts.factory,
     ...opts.version ? { version: opts.version } : {},
     ...opts.schedule ? { schedule: opts.schedule } : {},
     ...networkPolicy ? { networkPolicy } : {},
     ...placeholders ? { placeholders } : {},
     ...snapshot ? { snapshot } : {},
-    ...saveSnapshot !== undefined ? { saveSnapshot } : {}
+    ...saveSnapshot !== undefined ? { saveSnapshot } : {},
+    ...memory !== undefined ? { memory } : {}
   });
   const scheduleNote = opts.schedule ? ` — schedule: ${opts.schedule}` : "";
   console.log(`✓ Workflow:  ${result.name}@${result.version} (${result.id})${scheduleNote}`);
@@ -246,6 +249,37 @@ function extractToolSnippet(toolInput) {
   const raw = toolInput ? String(toolInput) : "";
   return raw.match(/"(?:command|file_path|url|query|pattern)":"([^"]{1,80})/)?.[1] ?? "";
 }
+function printAgentMessage(data) {
+  const message = data.message;
+  if (!message)
+    return;
+  switch (message.type) {
+    case "text": {
+      const text = String(message.text ?? "").replace(/<status>[\s\S]*?<\/status>/g, "").trim();
+      if (text)
+        process.stdout.write(`  ${pc.dim("text")} ${text.slice(0, 160)}
+`);
+      break;
+    }
+    case "thinking": {
+      const text = String(message.text ?? "").trim();
+      if (text)
+        process.stdout.write(`  ${pc.dim("thinking")} ${text.slice(0, 160)}
+`);
+      break;
+    }
+    case "tool_use": {
+      const detail = extractToolSnippet(message.toolInputPreview);
+      process.stdout.write(`  ${pc.cyan("→")} ${pc.bold(String(message.toolName ?? "tool"))}${detail ? `  ${pc.dim(detail)}` : ""}
+`);
+      break;
+    }
+    case "tool_result":
+      process.stdout.write(`  ${message.isError ? pc.red("tool error") : pc.dim("tool result")} ${String(message.output ?? "").slice(0, 160)}
+`);
+      break;
+  }
+}
 function printEvent(event, data, state) {
   switch (event) {
     case "step_started":
@@ -263,6 +297,7 @@ ${pc.dim(`● ${data.step}`)}
       process.stdout.write(`  ${pc.red("✗")} ${data.step}: ${pc.dim(String(data.reason ?? ""))}
 `);
       break;
+    case "agent.spawned":
     case "agent_spawned": {
       const name = String(data.agentName ?? data.label ?? "agent");
       const id = String(data.agentId ?? "");
@@ -275,6 +310,7 @@ ${pc.bold(pc.magenta(`▶ ${name}`))}${tag}
 `);
       break;
     }
+    case "agent.settled":
     case "agent_settled": {
       const ok = data.outcome === "success" || data.outcome === "done";
       const id = String(data.agentId ?? "");
@@ -292,6 +328,16 @@ ${pc.bold(pc.magenta(`▶ ${name}`))}${tag}
       }
       break;
     }
+    case "agent.iteration": {
+      const name = String(data.label ?? "agent");
+      const iteration = data.iteration ? ` ${data.iteration}` : "";
+      process.stdout.write(`  ${pc.dim(`${name} iteration${iteration}`)}
+`);
+      break;
+    }
+    case "agent.message":
+      printAgentMessage(data);
+      break;
     case "agent_event": {
       const { toolName } = data;
       if (toolName) {
@@ -600,7 +646,7 @@ function requireAdminKey(adminKey) {
   process.exit(1);
 }
 var keysCommand = new Command6("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. 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) => {
+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;
   let expiresAt;
@@ -964,8 +1010,122 @@ var cancelCommand = new Command12("cancel").description("Cancel an in-progress r
     await streamLogs(runId, opts);
 });
 
+// src/commands/events.ts
+import { Command as Command13 } from "commander";
+import { readFileSync as readFileSync3 } from "node:fs";
+import pc3 from "picocolors";
+function parseBody(raw) {
+  if (raw === undefined || raw === "")
+    return {};
+  const src = raw.startsWith("@") ? readFileSync3(raw.slice(1), "utf8") : raw;
+  try {
+    return JSON.parse(src);
+  } catch (err) {
+    throw new Error(`--body is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function parseAttribute(raw, prev = {}) {
+  const idx = raw.indexOf("=");
+  if (idx < 0)
+    throw new Error(`--attribute must be key=value, got "${raw}"`);
+  const key = raw.slice(0, idx);
+  const val = raw.slice(idx + 1);
+  if (!key)
+    throw new Error(`--attribute key is empty in "${raw}"`);
+  let parsed;
+  try {
+    parsed = JSON.parse(val);
+  } catch {
+    parsed = val;
+  }
+  return { ...prev, [key]: parsed };
+}
+function parseConfidence(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || n > 1) {
+    throw new Error(`--confidence must be a number in [0, 1], got "${raw}"`);
+  }
+  return n;
+}
+function parseLimit(raw) {
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1)
+    throw new Error(`--limit must be a positive integer, got "${raw}"`);
+  return n;
+}
+function fmtBodyPreview(body) {
+  if (body === null || body === undefined)
+    return pc3.dim("—");
+  if (typeof body === "string")
+    return body.length > 60 ? body.slice(0, 57) + "…" : body;
+  try {
+    const s = JSON.stringify(body);
+    return s.length > 60 ? s.slice(0, 57) + "…" : s;
+  } catch {
+    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) => {
+  let body;
+  try {
+    body = parseBody(opts.body);
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  const client = makeClient(opts);
+  const event = await client.reportEvent(runId, {
+    name,
+    body,
+    ...opts.summary ? { summary: opts.summary } : {},
+    ...opts.confidence !== undefined ? { confidence: opts.confidence } : {},
+    ...opts.timestamp ? { timestamp: opts.timestamp } : {},
+    ...Object.keys(opts.attribute).length ? { attributes: opts.attribute } : {},
+    ...opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {},
+    ...opts.propagate === false ? { propagate: false } : {}
+  }).catch(reportSdkError);
+  if (opts.json) {
+    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)}`)}`);
+});
+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) => {
+  if (!runId && !opts.factory) {
+    console.error("Error: provide either <run-id> or --factory <slug>");
+    process.exit(1);
+  }
+  if (runId && opts.factory) {
+    console.error("Error: <run-id> and --factory are mutually exclusive");
+    process.exit(1);
+  }
+  const client = makeClient(opts);
+  const events = runId ? await client.listRunEvents(runId).catch(reportSdkError) : (await client.listFactoryEvents({
+    factorySlug: opts.factory,
+    ...opts.limit !== undefined ? { limit: opts.limit } : {},
+    ...opts.name ? { name: opts.name } : {}
+  }).catch(reportSdkError)).events;
+  if (opts.json) {
+    console.log(JSON.stringify(events, null, 2));
+    return;
+  }
+  if (events.length === 0) {
+    const scope = runId ? `run ${runId.slice(0, 8)}` : `factory "${opts.factory}"`;
+    console.log(`No events for ${scope}.`);
+    return;
+  }
+  const sorted = [...events].sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+  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}`);
+  }
+});
+var eventsCommand = new Command13("events").description("Send or list run events (Events API)").addCommand(sendCommand).addCommand(listCommand2);
+
 // src/index.ts
-var pkg = JSON.parse(readFileSync3(fileURLToPath2(new URL("../package.json", import.meta.url)), "utf8"));
+var pkg = JSON.parse(readFileSync4(fileURLToPath2(new URL("../package.json", import.meta.url)), "utf8"));
 program.name("agentc").description("CLI for agent-compose — register, invoke, and monitor workflows").version(pkg.version);
 program.addCommand(registerCommand);
 program.addCommand(invokeCommand);
@@ -979,4 +1139,5 @@ program.addCommand(usageCommand);
 program.addCommand(snapshotCommand);
 program.addCommand(factoryCommand);
 program.addCommand(cancelCommand);
+program.addCommand(eventsCommand);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Command-line interface for agent-compose — register, invoke, and monitor workflows from your terminal.",
   "license": "MIT",
   "repository": {

package/skills/ac:demo.md

@@ -34,7 +34,7 @@ for the full version.
 > Owns the run end-to-end: orchestrates phases, kicks off agent loops,
 > writes metadata, returns a structured result.
 
-> **Agent loop** — `runAgent({ runtime, prompt, ... })`. Embedded inside
+> **Agent loop** — `agent({ runtime, prompt, ... })`. Embedded inside
 > the workflow body. Drives one iteration cycle of an LLM agent against
 > the runner sandbox until the model emits `exit_signal: true` (or
 > hits the iteration budget).
@@ -50,7 +50,7 @@ work. Keep it minimal — one phase, no fancy plumbing:
 
 ```ts
 // hello-agent.ts
-import { defineWorkflow, runAgent, claudeRuntime } from "@agent-compose/sdk";
+import { defineWorkflow, agent, claudeRuntime } from "@agent-compose/sdk";
 
 const PROMPT = `
 You're verifying agent-compose is wired up correctly.
@@ -62,7 +62,7 @@ exit_signal: true.
 
 export default defineWorkflow({
   async run(ctx, sandbox) {
-    const result = await runAgent({
+    const result = await agent({
       sandbox,
       runtime: claudeRuntime,
       prompt:  PROMPT,
@@ -76,7 +76,7 @@ export default defineWorkflow({
 ```
 
 Walk the user through the file — point at `ctx`, `sandbox`,
-`runAgent`, the prompt, the tool allowlist, the budget. Confirm before
+`agent`, the prompt, the tool allowlist, the budget. Confirm before
 writing.
 
 ### 3. Register
@@ -96,7 +96,7 @@ agentc invoke hello-agent --follow
 ```
 
 > "The server creates a runner sandbox, drops the bundle in, and starts
-> Node. Inside the sandbox, our workflow runs `runAgent` once — Claude
+> Node. Inside the sandbox, our workflow runs `agent` once — Claude
 > spawns, runs the bash command, emits its `<status>`, and exits.
 > Server marks the run complete; the CLI prints the final outcome and
 > elapsed time."
@@ -123,8 +123,8 @@ artifacts (logs, metadata) the workflow emitted.
 > "That was the simplest possible workflow. To go further:"
 >
 > - `/ac:generate-workflow` — describe a multi-phase workflow in plain
->   English; Claude scaffolds the full file with `runAgent` blocks per phase.
-> - `/ac:generate-agent` — scaffold one phase's prompt + `runAgent` snippet
+>   English; Claude scaffolds the full file with `agent` blocks per phase.
+> - `/ac:generate-agent` — scaffold one phase's prompt + `agent` snippet
 >   to slot into an existing workflow.
 > - `/ac:generate-runtime` — write a custom runtime for a model the SDK
 >   doesn't ship.

package/skills/ac:generate-agent.md

@@ -1,19 +1,19 @@
 ---
 name: ac:generate-agent
-description: Scaffold a `runAgent` block + prompt for one agent loop inside a workflow.
+description: Scaffold an `agent` block + prompt for one agent loop inside a workflow.
 allowed-tools: Read Write Edit Bash(bunx *) Bash(bun *)
 effort: high
 ---
 
 # Generate Agent
 
-Interactively scaffold a single agent loop — a `runAgent({ ... })` call
+Interactively scaffold a single agent loop — an `agent({ ... })` call
 plus its `prompt.md` — to drop into an existing workflow.
 
 > **Mental model.** There is no standalone "agent" resource. Agents live
-> *inside* workflows via `runAgent`. Each `runAgent` call drives one
+> *inside* workflows via `agent`. Each `agent` call drives one
 > iteration loop with a runtime, prompt, tool allowlist, and budget.
-> Multiple `runAgent` calls compose by sequencing (`await`) or by
+> Multiple `agent` calls compose by sequencing (`await`) or by
 > fanning out (`Promise.all`).
 
 ## Steps
@@ -24,12 +24,12 @@ plus its `prompt.md` — to drop into an existing workflow.
    - Runtime? (default: `claudeRuntime`. Use `openAIDesktopRuntime` for desktop / computer-use.)
    - Tools? (e.g. `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `WebFetch`)
    - Budget? Suggest `{ turnsPerIteration: 30-60, maxIterations: 4-8 }` based on complexity.
-   - Typed response? If yes, sketch a zod schema — `runAgent({ responseSchema })`
+   - Typed response? If yes, sketch a zod schema — `agent({ responseSchema })`
      makes the loop demand a `<response>` block that validates against it.
    - Prompt directory? (default: alongside the workflow file)
 
-2. If the user has an existing workflow with a `runAgent` block, read it
-   to match their conventions — prompt template structure, `promptVars`,
+2. If the user has an existing workflow with an `agent` block, read it
+   to match their conventions — prompt structure,
    tool sets, error handling. Otherwise follow the patterns in
    `sdk/src/runtimes/claude.ts` and the SDK's [README](../../sdk/README.md).
 
@@ -40,19 +40,18 @@ plus its `prompt.md` — to drop into an existing workflow.
    - Available tools + when to use each.
    - Step-by-step instructions for the phase.
    - The `<status>` protocol is auto-appended; don't include it manually.
-   - Use `{{VAR}}` placeholders for runtime substitution (`WORKING_DIR`,
-     `DIFF_BASE`, plus any `promptVars` the workflow passes in).
+   - Put runtime values directly in the workflow's prompt string; there is no
+     separate templating layer.
 
    **Snippet to paste into the workflow body:**
 
    ```ts
    import PROMPT from "./<phase>.md" with { type: "text" };
    // …in the workflow's run():
-   const result = await runAgent({
+   const result = await agent({
      sandbox,
      runtime:    claudeRuntime,
-     prompt:     PROMPT,
-     promptVars: { /* … */ },
+     prompt:     `${PROMPT}\n\nContext: ${JSON.stringify(ctx.input ?? {})}`,
      tools:      [/* … */],
      budget:     { turnsPerIteration: 40, maxIterations: 6 },
      // responseSchema: MySchema,   // when typed handoff is needed

package/skills/ac:generate-workflow.md

@@ -12,9 +12,9 @@ Interactively scaffold a new workflow from a plain-English description.
 > **Mental model.** A workflow is `async (ctx, sandbox) => T`. The `ctx`
 > exposes `run`, `input?`, `setMetadata`, and `step` (for named timeline
 > phases). The `sandbox` is the runner's own VM — pass it to
-> `runAgent({ sandbox, ... })` and to any helper that takes a
+> `agent({ sandbox, ... })` and to any helper that takes a
 > `SandboxProvider`. Agent loops live *inside* the workflow body via
-> `runAgent`. There's no `defineAgent` / `spawnAgent` model anymore.
+> `agent`. There's no `defineAgent` / `spawnAgent` model anymore.
 
 ## Steps
 
@@ -29,7 +29,7 @@ Interactively scaffold a new workflow from a plain-English description.
      workflows whose end-state other workflows boot from)
 
 2. If the user has a reference workflow in their project, read it to
-   match their conventions (prompt structure, `promptVars` shape,
+   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).
@@ -37,7 +37,7 @@ Interactively scaffold a new workflow from a plain-English description.
 3. Generate a complete, real implementation:
 
    ```ts
-   import { defineWorkflow, runAgent, claudeRuntime } from "@agent-compose/sdk";
+   import { defineWorkflow, agent, claudeRuntime } from "@agent-compose/sdk";
    import PROMPT from "./prompt.md" with { type: "text" };
 
    export default defineWorkflow({
@@ -48,13 +48,12 @@ Interactively scaffold a new workflow from a plain-English description.
          // pure-server work, fetches, etc.
        });
 
-       // Phase 2 — agent loop. Each `runAgent` is one iteration cycle
+       // Phase 2 — agent loop. Each `agent` is one iteration cycle
        // with its own prompt + tool allowlist + budget.
-       const result = await runAgent({
+       const result = await agent({
          sandbox,
          runtime:    claudeRuntime,
-         prompt:     PROMPT,
-         promptVars: { /* {{VAR}} substitutions */ },
+         prompt:     `${PROMPT}\n\nContext: ${JSON.stringify(data)}`,
          tools:      ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
          budget:     { turnsPerIteration: 40, maxIterations: 6 },
          // responseSchema: MyZodSchema,   // for typed handoffs
@@ -72,7 +71,7 @@ Interactively scaffold a new workflow from a plain-English description.
    ```
 
    - Always declare the return type (or let TS infer + show it on hover).
-   - Use `Promise.all` to fan out independent `runAgent` calls.
+   - Use `Promise.all` to fan out independent `agent` calls.
    - Use `ctx.step("phase-name", () => …)` for any named non-agent phase.
 
 4. Show the complete file plus a separate `prompt.md` (or per-phase