@agent-compose/cli 0.1.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@agent-compose/cli",
+  "version": "0.1.0",
+  "description": "Command-line interface for agent-compose — register, invoke, and monitor workflows from your terminal.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Layr-Labs/agent-compose.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/Layr-Labs/agent-compose/tree/master/cli#readme",
+  "bugs": {
+    "url": "https://github.com/Layr-Labs/agent-compose/issues"
+  },
+  "keywords": [
+    "agent-compose",
+    "cli",
+    "agent",
+    "workflow",
+    "ai",
+    "llm",
+    "sandbox"
+  ],
+  "type": "module",
+  "bin": {
+    "agentc": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "typecheck":      "tsc --noEmit",
+    "test":           "bun test src/__tests__",
+    "build":          "bun run clean && bun run build:js && bun run build:chmod",
+    "build:js":       "bun build src/index.ts --outdir dist --target node --format esm --packages external --banner='#!/usr/bin/env node'",
+    "build:chmod":    "chmod +x dist/index.js",
+    "clean":          "rm -rf dist",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@agent-compose/sdk": "^0.1.0",
+    "commander":          "^12.0.0",
+    "picocolors":         "^1.1.1"
+  },
+  "devDependencies": {
+    "bun-types":  "latest",
+    "typescript": "^5.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/ac:demo.md

@@ -0,0 +1,134 @@
+---
+name: ac:demo
+description: First-run walkthrough — verify auth, scaffold a sample workflow, register it, invoke, and watch the agent run live.
+effort: high
+allowed-tools: Bash(agentc *) Bash(git *) Bash(open *) Read Write Edit
+---
+
+# Demo — agent-compose
+
+A guided first-run walkthrough. Verify auth, generate a tiny sample
+workflow, register it, dispatch it, and watch a single agent loop run
+end-to-end. Should take ~5 minutes against the hosted server (a bit
+longer locally — the runner sandbox boots fresh).
+
+## Context
+
+```
+!`agentc auth status`
+```
+
+If the line above shows no API key, run `/ac:setup` first (sign in to
+the dashboard, mint an `ac_…` key, `agentc auth login <key>`). That
+skill walks the full bootstrap.
+
+## Steps
+
+### 1. Briefly explain the model
+
+Make sure the user understands the three primitives before you start
+typing. Keep it brief — they can read [`docs/how-it-works.md`](../../docs/how-it-works.md)
+for the full version.
+
+> **Workflow** — `async (ctx, sandbox) => T`. The function you author.
+> 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
+> 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).
+
+> **Runtime** — `claudeRuntime` (built-in) wraps the Claude CLI.
+> `openAIDesktopRuntime` wraps OpenAI computer-use. You can write your
+> own with `defineRuntime`.
+
+### 2. Scaffold a sample workflow
+
+Create a temporary `hello-agent.ts` next to where the user wants to
+work. Keep it minimal — one phase, no fancy plumbing:
+
+```ts
+// hello-agent.ts
+import { defineWorkflow, runAgent, claudeRuntime } from "@agent-compose/sdk";
+
+const PROMPT = `
+You're verifying agent-compose is wired up correctly.
+
+Run \`echo "hello from sandbox $(hostname)"\` once, then emit a
+<status> block with summary describing what you observed and
+exit_signal: true.
+`;
+
+export default defineWorkflow({
+  async run(ctx, sandbox) {
+    const result = await runAgent({
+      sandbox,
+      runtime: claudeRuntime,
+      prompt:  PROMPT,
+      tools:   ["Bash"],
+      budget:  { turnsPerIteration: 6, maxIterations: 1 },
+    });
+    await ctx.setMetadata({ summary: result.status?.summary });
+    return { ok: !!result.status?.completed, summary: result.status?.summary };
+  },
+});
+```
+
+Walk the user through the file — point at `ctx`, `sandbox`,
+`runAgent`, the prompt, the tool allowlist, the budget. Confirm before
+writing.
+
+### 3. Register
+
+```bash
+agentc register hello-agent.ts
+```
+
+> "The CLI bundles the workflow source + the runtime source via
+> `bundleWorkflow`, then POSTs to `/api/v1/templates`. Once registered,
+> anyone with an `invoke`-scoped API key can call it."
+
+### 4. Invoke and watch live
+
+```bash
+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
+> spawns, runs the bash command, emits its `<status>`, and exits.
+> Server marks the run complete; the CLI prints the final outcome and
+> elapsed time."
+
+Watch the SSE-streamed events together — point out:
+- `step_started` / `step_completed` (timeline phases).
+- `agent_event` lines (model output streaming live).
+- `run_complete` with elapsed time.
+
+### 5. Browse the run in the dashboard
+
+Once the run finishes, open the run detail page:
+
+```bash
+# pull the dashboard URL from auth status; substitute the run id
+open "$(agentc auth status | awk '/^Dashboard:/ {print $2}')/workflows/<run-id>"
+```
+
+The dashboard shows the same lifecycle events plus the captured
+artifacts (logs, metadata) the workflow emitted.
+
+### 6. What to build next
+
+> "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
+>   to slot into an existing workflow.
+> - `/ac:generate-runtime` — write a custom runtime for a model the SDK
+>   doesn't ship.
+> - Read [`docs/how-it-works.md`](../../docs/how-it-works.md) for the
+>   multi-agent example (plan + parallel implementers).
+
+Clean up: `rm hello-agent.ts` (or keep it as a reference).

package/skills/ac:generate-agent.md

@@ -0,0 +1,70 @@
+---
+name: ac:generate-agent
+description: Scaffold a `runAgent` 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
+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
+> iteration loop with a runtime, prompt, tool allowlist, and budget.
+> Multiple `runAgent` calls compose by sequencing (`await`) or by
+> fanning out (`Promise.all`).
+
+## Steps
+
+1. Ask the user:
+   - What's the agent's role in the workflow? (one phase: plan, implement, review, summarize, …)
+   - Where does this fit — inside an existing workflow file, or scaffold a new one?
+   - 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 })`
+     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`,
+   tool sets, error handling. Otherwise follow the patterns in
+   `sdk/src/runtimes/claude.ts` and the SDK's [README](../../sdk/README.md).
+
+3. Generate two files:
+
+   **`<dir>/<phase>.md`** — the prompt. Write a real, detailed prompt:
+   - Role definition + context the model will receive.
+   - 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).
+
+   **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({
+     sandbox,
+     runtime:    claudeRuntime,
+     prompt:     PROMPT,
+     promptVars: { /* … */ },
+     tools:      [/* … */],
+     budget:     { turnsPerIteration: 40, maxIterations: 6 },
+     // responseSchema: MySchema,   // when typed handoff is needed
+   });
+   if (!result.status?.completed) return { ok: false, blockers: result.status?.blockers };
+   ```
+
+4. Show the prompt + snippet and confirm before writing.
+
+5. Write the prompt file. Show the user the snippet to integrate (don't
+   silently splice into their workflow file — that risks corrupting their
+   pipeline).
+
+6. Suggest the user run `bun run typecheck` (or their project's
+   equivalent) and re-register via `agentc register <workflow.ts>`.

package/skills/ac:generate-runtime.md

@@ -0,0 +1,41 @@
+---
+name: ac:generate-runtime
+description: Scaffold a new agent-compose runtime from a plain-English description.
+allowed-tools: Read Write Edit Bash(bunx *) Bash(bun *)
+effort: high
+---
+
+# Generate Runtime
+
+Scaffold a new runtime that drives a model in a sandbox.
+
+## Context
+
+Existing runtimes:
+```
+!`ls sdk/src/runtimes/ 2>/dev/null`
+```
+
+## Steps
+
+1. Ask the user:
+   - What model or API does this runtime drive?
+   - Runtime name? (camelCase, e.g. `gptRuntime`)
+   - Does it need desktop/GUI access? (determines SandboxProvider type)
+   - Where to create it? (default: `sdk/src/runtimes/`)
+
+2. Read `sdk/src/runtimes/claude.ts` to understand the full pattern — `ModelExecutionContract`, sandbox interaction, stdout parsing.
+
+3. Read `sdk/src/types/runtime.ts` for the `AgentRuntime` interface.
+
+4. Generate the runtime file implementing `ModelExecutionContract.sendMessage()`. It must:
+   - Accept a `SandboxProvider` and `RuntimeOptions`
+   - Run the model (subprocess, API call, or GUI control)
+   - Parse output into `AgentMessage` events
+   - Export a default singleton and a factory function
+
+5. Show the generated file and ask the user to confirm before writing.
+
+6. Write the file, then run `bunx tsc --noEmit` from the repo root to validate.
+
+7. Tell the user to export the runtime from `sdk/src/index.ts`.

package/skills/ac:generate-workflow.md

@@ -0,0 +1,85 @@
+---
+name: ac:generate-workflow
+description: Scaffold a new agent-compose workflow from a plain-English description.
+allowed-tools: Read Write Edit Bash(bunx *) Bash(bun *)
+effort: high
+---
+
+# Generate Workflow
+
+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
+> `SandboxProvider`. Agent loops live *inside* the workflow body via
+> `runAgent`. There's no `defineAgent` / `spawnAgent` model anymore.
+
+## Steps
+
+1. Ask the user:
+   - 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
+     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,
+   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:
+
+   ```ts
+   import { defineWorkflow, runAgent, claudeRuntime } from "@agent-compose/sdk";
+   import PROMPT from "./prompt.md" with { type: "text" };
+
+   export default defineWorkflow({
+     async run(ctx, sandbox) {
+       // Phase 1 — wrap any non-agent setup in ctx.step() so it shows
+       // up on the timeline with its own duration:
+       const data = await ctx.step("fetch-input", async () => {
+         // pure-server work, fetches, etc.
+       });
+
+       // Phase 2 — agent loop. Each `runAgent` is one iteration cycle
+       // with its own prompt + tool allowlist + budget.
+       const result = await runAgent({
+         sandbox,
+         runtime:    claudeRuntime,
+         prompt:     PROMPT,
+         promptVars: { /* {{VAR}} substitutions */ },
+         tools:      ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
+         budget:     { turnsPerIteration: 40, maxIterations: 6 },
+         // responseSchema: MyZodSchema,   // for typed handoffs
+       });
+
+       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
+   });
+   ```
+
+   - Always declare the return type (or let TS infer + show it on hover).
+   - Use `Promise.all` to fan out independent `runAgent` 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
+   prompts) and confirm before writing.
+
+5. Write the files, then suggest the user run `bun run typecheck` (or
+   their project's equivalent) to validate.
+
+6. Tell the user: `agentc register <path>` to register, then
+   `agentc invoke <name> --follow` to test.

package/skills/ac:invoke.md

@@ -0,0 +1,42 @@
+---
+name: ac:invoke
+description: Invoke a registered workflow and stream its live output.
+argument-hint: <workflow-name> [--input '{"key":"value"}']
+allowed-tools: Bash(agentc *)
+---
+
+# Invoke Workflow
+
+## Context
+
+Registered workflows:
+```
+!`agentc list 2>/dev/null`
+```
+
+## Instructions
+
+The user wants to invoke: **$ARGUMENTS**
+
+If the line above is blank, ask which workflow to invoke. Use the registered workflows list above as suggestions.
+
+Once you have the workflow name, dispatch it:
+
+```bash
+agentc invoke <name> --follow
+```
+
+## Output
+
+Stream events as they arrive. When complete, report:
+- Final outcome (success / failed)
+- Final wall time (`run_complete` includes elapsed seconds)
+- Any PR URL, plan URL, or artifact produced (visible in the streamed events
+  or via `agentc logs <run-id>` after the fact)
+
+## Next Steps
+
+- **Success** → Report the outcome and any output.
+- **Failed** → Show the failure reason. Offer to debug: "Run `/ac:logs <run-id>` for the full event log."
+- **Secrets missing** → "Run `/ac:secrets set <workflow> <KEY> <value>` to configure the required secret."
+- **Template not found** → "Run `/ac:register <workflow.ts>` to register it first."

package/skills/ac:logs.md

@@ -0,0 +1,39 @@
+---
+name: ac:logs
+description: Stream live or historical events for a workflow run.
+argument-hint: [run-id]
+allowed-tools: Bash(agentc *)
+---
+
+# Stream Run Logs
+
+## Context
+
+The CLI doesn't ship a "list runs" subcommand — to find a run id, dispatch
+a workflow with `agentc invoke <name>` (it prints the id) or browse the
+dashboard's Workflows page.
+
+## Instructions
+
+The user wants to stream logs for: **$ARGUMENTS**
+
+If `$ARGUMENTS` is blank, ask the user for a run id (UUID).
+
+Once you have the run id, stream it:
+
+```bash
+agentc logs <run-id>
+```
+
+## Output
+
+Show events as they stream — agent turns, tool calls, step transitions,
+and the final `run_complete` (with elapsed wall time) or `run_failed`
+(with reason).
+
+## Next Steps
+
+- **Run still active** → Logs stream live until the run completes.
+- **Run failed** → Identify the failure reason and suggest a fix.
+- **Run not found** → The id may be wrong. Find recent runs from the
+  dashboard's Workflows page or grab the id printed by `agentc invoke`.

package/skills/ac:register-invoke.md

@@ -0,0 +1,28 @@
+---
+name: ac:register-invoke
+description: Register a workflow then immediately invoke it. Useful during development to test changes without separate steps.
+argument-hint: <workflow.ts> [--input '{"key":"value"}']
+allowed-tools: Bash(agentc *)
+---
+
+# Register and Invoke
+
+Register the workflow at `$0`, then invoke it.
+
+## Plan
+
+```bash
+agentc register $0
+agentc invoke $(basename "$0" .ts) --follow $1
+```
+
+If `$ARGUMENTS` is empty, ask for the workflow path first.
+
+## Output
+
+Show register output, then stream the run. When complete, report outcome and any artifacts.
+
+## Next Steps
+
+- **Registration failed** → Fix the error and re-run.
+- **Run failed** → Show failure reason from the final event. Offer `/ac:logs <run-id>`.

package/skills/ac:register.md

@@ -0,0 +1,43 @@
+---
+name: ac:register
+description: Bundle and register a workflow (and its agents) with the agent-compose server.
+argument-hint: <workflow.ts>
+allowed-tools: Bash(agentc *) Bash(bun *)
+---
+
+# Register Workflow
+
+## Context
+
+Registered workflows:
+```
+!`agentc list 2>/dev/null`
+```
+
+Current branch: !`git branch --show-current`
+
+## Instructions
+
+The user wants to register: **$ARGUMENTS**
+
+If the line above is blank, ask the user which workflow file to register before proceeding.
+
+Once you have the path, bundle and register it:
+
+```bash
+agentc register <path>
+```
+
+## Output
+
+Confirm:
+- Workflow name and version registered
+- Which runtime sources were inlined into the bundle
+
+## Next Steps
+
+- **Success** → "Registered. Run `/ac:invoke <name>` to test it."
+- **Bundle failed** → Re-read the bundler error; usually a missing import path
+  or a runtime that couldn't be resolved.
+- **Validation error** → Fix the reported issue in the source file and re-run.
+- **Server not running** → from this repo's root, `bun --cwd server run dev`.

package/skills/ac:secrets.md

@@ -0,0 +1,42 @@
+---
+name: ac:secrets
+description: Manage per-workflow secrets in GCP Secret Manager. Values are injected at the network layer — never readable inside the sandbox.
+argument-hint: <set|list|delete> <workflow> [key] [value]
+allowed-tools: Bash(agentc secrets *)
+---
+
+# Workflow Secrets
+
+Secret values are stored in GCP Secret Manager and injected by the Vercel firewall at runtime — they never exist as readable env vars inside the sandbox.
+
+> **Never echo secret values** back in conversation text or summaries. Show key names and metadata only.
+
+## Context
+
+Registered workflows:
+```
+!`agentc list 2>/dev/null | awk '{print $1}'`
+```
+
+## Plan
+
+Based on `$ARGUMENTS`:
+
+| Arguments | Action |
+|---|---|
+| `set <workflow> <key> <value>` | Create or update a secret |
+| `list <workflow>` | List key names (no values) |
+| `delete <workflow> <key>` | Delete a secret |
+| *(none)* | Ask which workflow and action |
+
+```bash
+agentc secrets $ARGUMENTS
+```
+
+For `delete`: confirm with the user before running — "Delete `<key>` from `<workflow>`? Runs depending on it will fail."
+
+## Next Steps
+
+- **After set** → "Secret saved. Re-register the workflow if the network policy changed."
+- **After delete** → "Secret removed. Any future run will not have `<key>` available."
+- **GCP auth error** → Run `gcloud auth application-default login` and check `GCP_PROJECT_ID` in `server/.env.local`.

package/skills/ac:setup.md

@@ -0,0 +1,91 @@
+---
+name: ac:setup
+description: First-time setup — install the CLI, authenticate, and verify the connection.
+allowed-tools: Bash(agentc *) Bash(bun *) Bash(source *) Bash(curl *)
+---
+
+# Setup — agent-compose
+
+## Pre-check
+
+```
+!`agentc auth status 2>/dev/null`
+```
+
+Use the output above to skip steps that are already done.
+
+## Steps
+
+### 1. Install the CLI (skip if `which agentc` found it)
+
+```bash
+cd cli && bun link
+```
+
+Then reload the shell:
+
+```bash
+source ~/.zshrc
+```
+
+Verify: `agentc --version`
+
+### 2. Install skills
+
+```bash
+agentc init
+```
+
+This installs all `/ac:*` slash commands into Claude Code.
+
+### 3. Authenticate (skip if auth status shows an API key)
+
+Open the dashboard URL from `agentc auth status` in a browser
+(prod: `https://platform.agentcompose.ai`; local dev: `http://localhost:3000`)
+and add `/login`. Enter your email; click the magic-link in the email we
+send. A personal team is auto-created on first sign-in and you become
+its owner. Mint your CLI key from **Settings → API Keys → Create key**:
+
+- Defaults are `read+invoke` — right for the typical CLI / CI caller.
+- Tick `admin` only if this key needs to mint other keys, register templates,
+  or manage workflow secrets.
+- The `ac_…` value is shown once in the reveal dialog. Copy it immediately.
+
+Save the key locally:
+
+```bash
+agentc auth login <pasted-key>
+```
+
+Verify:
+
+```bash
+agentc auth status
+```
+
+Should show the server URL and `API key: set`. (The `Env:` line only
+appears if the project's `.agentc/settings.json` defines a named
+environment — see step below if you want to pin one.)
+
+> Scoped keys (read-only, invoke-only, admin-only) or keys that auto-expire
+> can also be minted from the CLI by anyone with an admin-scoped caller key:
+> `agentc keys create <name> --scopes ... --expires-in ... --admin-key ac_…`.
+> The CLI default with no `--scopes` flag is **full team access**; pass
+> `--scopes read,invoke` for least-privilege CI keys. See `/ac:dev-setup`
+> for the full flag reference.
+
+### 4. Verify the connection
+
+```bash
+agentc list
+```
+
+This lists registered workflows. If it returns without error, setup is complete.
+
+### 5. Done
+
+> "You're all set. Here's what you can do now:"
+>
+> - `/ac:demo` — watch AI agents build a browser game end-to-end
+> - `agentc invoke <workflow> --follow` — run any registered workflow
+> - `/ac:generate-workflow` — build your own workflow from a description