@agent-compose/sdk 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,10 @@
 # @agent-compose/sdk
 
-Client library for building against agent-compose. Provides TypeScript types for defining agents, runtimes, and workflows, plus an HTTP client that auto-discovers dependencies and registers everything with a single call.
+TypeScript SDK for agent-compose. Use it to:
+
+- **Author workflows** that run agentic LLM loops inside isolated sandboxes
+- **Define runtimes** that wrap a coding-CLI tool (Claude Code, OpenAI Desktop, …) into a sandbox-portable agent loop
+- **Register, invoke, and observe** workflows via the HTTP API (`AgentComposeClient`)
 
 ---
 
@@ -14,139 +18,317 @@ npm install zod
 
 ---
 
-## Defining an Agent
+## Authoring a workflow
+
+A workflow is `async (ctx, sandbox) => T`. Two positional args:
+
+- **`ctx`** carries the run identity (`run.id`), the caller's `input`, plus
+  observability helpers (`setMetadata`, `step`).
+- **`sandbox`** is a capability the engine constructs once for the run —
+  pass it to `runAgent({ sandbox, ... })` and to any helper that takes a
+  `SandboxProvider` (file writers, git utilities, command runners).
 
 ```typescript
-// my-agents/planner.ts
-import { defineAgent } from "@agent-compose/sdk";
-
-export default defineAgent({
-  name: "planner",
-  runtime: "claude",                                    // registered runtime name
-  prompt: "Explore the codebase and write a plan...",
-  budget: { turnsPerIteration: 70, maxIterations: 1 },
+// my-workflow.ts
+import { defineWorkflow, runAgent, claudeRuntime } from "@agent-compose/sdk";
+import PROMPT from "./prompt.md" with { type: "text" };
+
+export default defineWorkflow({
+  async run(ctx, sandbox) {
+    const repo = (ctx.input?.repo as string | undefined) ?? "owner/repo";
+
+    const result = await runAgent({
+      sandbox,
+      runtime:    claudeRuntime,
+      prompt:     PROMPT,
+      promptVars: { REPO: repo },
+      tools:      ["Bash", "Read", "Edit", "Write", "Grep", "Glob"],
+      budget:     { turnsPerIteration: 40, maxIterations: 8 },
+    });
+
+    await ctx.setMetadata({ summary: result.status?.summary });
+    return { ok: result.status?.completed ?? false };
+  },
+  // Optional: outbound network rules that the runner sandbox will enforce
+  // (Vercel only — E2B ignores). Use `$VAR` placeholders for secrets that
+  // get resolved from the per-workflow secret store at dispatch time.
+  networkPolicy: {
+    allow: {
+      "*": [],
+      "api.anthropic.com": [{ transform: [{ headers: { "x-api-key": "$ANTHROPIC_API_KEY" } }] }],
+    },
+  },
 });
 ```
 
----
-
-## Defining a Runtime
+`defineWorkflow` is a thin sugar — it returns the bare `run` function with
+`networkPolicy` / `placeholders` / `snapshot` / `saveSnapshot` attached as
+metadata that the bundler picks up at registration time. A plain
+`export default async (ctx, sandbox) => {...}` is also valid; you just lose
+the metadata channel.
+
+### What the workflow can do with `ctx`
+
+```ts
+interface WorkflowCtx {
+  run:         { id: string };
+  input?:      Record<string, unknown>;
+  setMetadata: (data: Record<string, unknown>) => Promise<void>;
+  step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+}
+```
 
-```typescript
-// my-runtimes/claude.ts
-import { defineRuntime } from "@agent-compose/sdk";
-// ClaudeRunner is provided by the server — import from your server package
-import { ClaudeRunner } from "@agent-compose/server/runtimes/claude.js";
-
-export default defineRuntime({
-  provider: "claude-code",  // must match what createAgentSandbox knows about
-  create: (sandbox, opts) => new ClaudeRunner(sandbox, opts),
-});
+`step("phase-name", () => …)` wraps a phase for the run timeline — emits
+`step_started` / `step_completed` / `step_failed` lifecycle events with
+duration. Use it for setup, external API calls, or anything you want
+visible on the dashboard's run detail page.
+
+### The `runAgent` loop
+
+```ts
+runAgent({
+  sandbox,            // the workflow's sandbox arg
+  runtime,            // claudeRuntime, or your own via createClaudeRuntime / defineRuntime
+  prompt,             // raw markdown — `--- frontmatter ---` is auto-stripped
+  promptVars?,        // {{VAR}} substitutions; WORKING_DIR + DIFF_BASE auto-populate
+  tools?,             // model tool allowlist (defaults inside agentLoop)
+  budget?,            // { turnsPerIteration, maxIterations }
+  workingDir?,        // every shell command runs here
+  responseSchema?,    // zod — when set, the loop demands a `<response>` block on exit
+  onAgentEvent?,      // per-message hook (e.g. wire to telemetry)
+  onIteration?,       // per-iteration hook with parsed `<status>` block
+})
+// → AgentLoopResult { status?, response? (when responseSchema set), iterations, … }
 ```
 
+The protocol is simple: the model emits XML-tagged blocks (`<status>` /
+`<response>`) the loop parses. See `sdk/src/agent/protocol-suffix.md` for
+the full instructions appended to every prompt.
+
 ---
 
-## Writing a Workflow
+## Defining a runtime
 
-```typescript
-// my-workflow.ts
-import type { WorkflowFn } from "@agent-compose/sdk";
+A "runtime" wraps an agent's underlying execution model — usually a coding
+CLI like Claude Code or OpenAI Desktop — so `runAgent` can drive it. The SDK
+ships built-ins; you only need a custom one for an exotic provider.
 
-const myWorkflow: WorkflowFn = async (ctx) => {
-  const planner = await ctx.spawnAgent("planner", {
-    data: { task: ctx.input.task },
-  });
+### Built-in runtimes
 
-  await ctx.spawnAgent("implementer", {
-    input: planner,                    // chains branch + response
-    data: { task: ctx.input.task },
-  });
+```ts
+import {
+  createClaudeRuntime,    // factory, takes config
+  claudeRuntime,           // pre-built default (DEFAULT_CLAUDE_MODEL)
+  ClaudeRunner,            // class, if you need to override
+} from "@agent-compose/sdk";
 
-  await ctx.setMetadata({ done: true });
-};
+// openAIDesktopRuntime is NOT in the package root (it pulls in `sharp` for
+// screenshot capture; the native binding can't be cross-compiled). Import
+// directly when you actually want the desktop runtime:
+import openAIDesktopRuntime from "@agent-compose/sdk/runtimes/openai-desktop.js";
+```
 
-export default myWorkflow;
+### Custom runtime
+
+```ts
+import { defineRuntime, type AgentRuntime } from "@agent-compose/sdk";
+
+const myRuntime: AgentRuntime = defineRuntime({
+  create: (sandbox, opts) => {
+    // Return a ModelExecutionContract — see sdk/src/types/runtime.ts
+    return {
+      sendMessage({ prompt, sessionId, signal }) {
+        // Async generator that yields AgentMessage chunks the loop parses.
+        return /* … */;
+      },
+    };
+  },
+});
 ```
 
+`AgentRuntime` is a tagged record with `create(sandbox, RuntimeOptions) →
+ModelExecutionContract`. There is **no `provider` field** on it — the
+runtime is bound to the workflow at author time (you pass it to `runAgent`),
+not selected by the server.
+
 ---
 
-## Registration
+## Registering a workflow
 
-`AgentComposeClient.register()` reads the workflow file, scans for `ctx.spawnAgent("name")` calls, resolves each agent's source file, reads `runtime: "name"` from each agent, resolves runtime sources — then bundles and POSTs everything in one call.
+The `agentc` CLI handles the bundling-and-registration step for you:
 
-```typescript
-import { AgentComposeClient } from "@agent-compose/sdk";
+```bash
+agentc register my-workflow.ts -n my-workflow
+```
+
+Under the hood that calls `bundleWorkflow(workflowPath)` (resolves imports,
+inlines runtime sources via dynamic-require traversal) and `POST /api/v1/templates`
+with the bundled source. If you need to drive registration from your own
+build pipeline, you can do the same thing via the SDK directly:
+
+```ts
+import { AgentComposeClient, bundleWorkflow } from "@agent-compose/sdk";
 
 const client = new AgentComposeClient(
-  "http://localhost:8080",
-  process.env.API_KEY!,
+  "https://your-server.example.com",
+  process.env.AGENT_COMPOSE_API_KEY!,
 );
 
-// Auto-discovers agents and runtimes from the workflow file
+const bundled = await bundleWorkflow("./my-workflow.ts");
 await client.register({
-  name: "my-workflow",
-  workflowPath: "./my-workflow.ts",
-  // agentPaths and runtimePaths are optional overrides if auto-discovery fails
+  name:    "my-workflow",
+  source:  bundled.source,
+  runtimes: bundled.runtimes,         // [{ name, source }] — embedded so the runner has them locally
+  schedule: "*/30 * * * *",            // optional cron
+  // snapshot, saveSnapshot, networkPolicy, placeholders — all optional
 });
 ```
 
-**Auto-discovery convention** — for agent `"planner"`, the client looks for:
-- `./planner.ts`
-- `./planner/index.ts`
-- `./agents/planner.ts`
-- `./agents/planner/index.ts`
-
-For runtime `"claude"`, it looks for:
-- `./claude.ts`
-- `./runtimes/claude.ts`
+`register()` requires the caller's API key to carry the `admin` scope
+(or full team-access for legacy keys without scopes).
 
 ---
 
-## Invocation
+## Invoking a workflow
 
-```typescript
-// Invoke a registered workflow (returns immediately with a run ID)
+Two flavours:
+
+```ts
+// Fire-and-forget — returns the run id immediately.
 const { id } = await client.invoke("my-workflow", {
-  task: "Add rate limiting to the /projects endpoint",
+  repo: "owner/repo",
 });
 
-// Poll until done
-let status;
-do {
-  await new Promise(r => setTimeout(r, 5000));
-  status = await client.getStatus(id);
-} while (status.status === "running");
+// Block until the run settles (default 30min timeout, 1s poll).
+const status = await client.invokeAndWait("my-workflow", { repo: "owner/repo" }, {
+  timeoutMs:      5 * 60_000,
+  pollIntervalMs: 2000,
+});
+console.log(status.status);   // "success" | "failed" | "abandoned"
+console.log(status.output);   // workflow's return value
+```
+
+`output` is the workflow's `run()` return value (whatever `defineWorkflow({
+async run() { return … } })` resolves to). `setMetadata()` writes to a
+separate `metadata` field — useful for "side-channel" facts (PR url, plan
+url) without polluting the structured return.
+
+### Auto parent/child tracing
+
+The SDK detects `process.env.RUN_ID` (set by the runner sandbox on every
+dispatch) and automatically threads it as `parentRunId` on subsequent
+`invoke()` calls. Workflows that fan out to other workflows get a
+parent/child tree in the dashboard for free. Pass `parentRunId: null`
+to opt out.
+
+---
+
+## Per-workflow secrets
+
+Secrets are stored in GCP Secret Manager, one row per `(team, workflow,
+key)`. They're injected as env vars into the runner sandbox at dispatch
+time, never persisted in the VM. Values are write-only — the API only
+returns metadata (key, timestamps).
 
-console.log(status.output); // workflow's setMetadata() payload
+```ts
+await client.setSecret("my-workflow", "ANTHROPIC_API_KEY", process.env.ANTHROPIC_API_KEY!);
+const list = await client.listSecrets("my-workflow"); // [{ key, createdAt, updatedAt }]
+await client.deleteSecret("my-workflow", "STALE_KEY");
 ```
 
+Mutations require `admin` scope.
+
 ---
 
-## Exported Types
+## Snapshots (replay-friendly sandboxes)
 
-```typescript
-// Factory functions
-defineAgent(pkg: AgentDefinition): AgentDefinition
-defineRuntime(pkg: AgentRuntime): AgentRuntime
-
-// Workflow authoring
-type WorkflowFn = (ctx: WorkflowCtx) => Promise<void>
-interface WorkflowCtx { spawnAgent, setMetadata, sendMessage, input, run, cost }
-
-// Agent types
-interface AgentDefinition { name, runtime, prompt, budget?, tools?, onStart?, onFinish? }
-interface AgentOpts { budget?, data?, input?, branch?, onStart?, onFinish? }
-interface AgentResult<T> { response: T; session: AgentSession }
-
-// Runtime types
-interface AgentRuntime<S> { provider: string; create(sandbox: S, opts): ModelExecutionContract }
-interface ModelExecutionContract { sendMessage(opts): AsyncGenerator<AgentMessage> }
-
-// Protocol
-interface AgentStatus { summary, completed, blockers, exit_signal }
-type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageToolUse | ...
-
-// Sandbox
-interface SandboxProvider { sandboxId, cwd?, commands, files, kill() }
-interface DesktopSandboxProvider extends SandboxProvider { screenshot(), leftClick(), ... }
+Long-running workflows can capture the runner sandbox as a Vercel snapshot
+on success (`saveSnapshot: true`). Other workflows reference that snapshot
+via the `snapshot` field to boot into the same prepared VM (deps installed,
+repo cloned, etc.) instead of repeating setup.
+
+```ts
+// Capture per-invocation:
+await client.invoke("my-workflow", input, { saveSnapshot: true });
+
+// Boot from a different snapshot per invocation (per-invocation override):
+await client.invoke("my-workflow", input, { snapshot: "<run-id-or-name>" });
+
+// Or set a default at registration time:
+defineWorkflow({ run, saveSnapshot: true });
+
+// Browse / clean up:
+const snaps = await client.listSnapshots({ workflow: "my-workflow", limit: 50 });
+await client.deleteSnapshot(snaps[0].runId);
+```
+
+CLI equivalents: `agentc snapshot list` / `agentc snapshot delete <run-id>`.
+
+---
+
+## Authentication
+
+The SDK accepts a Bearer API key (`ac_…`). Mint one from the dashboard:
+sign in at `<server-url>/login`, then **Settings → API Keys → Create key**.
+
+Default scopes (`read + invoke`) are right for a CI / dispatch caller. Tick
+`admin` only if this key needs to register templates, mint other keys, or
+manage secrets.
+
+```ts
+const client = new AgentComposeClient(
+  process.env.AGENT_COMPOSE_URL!,
+  process.env.AGENT_COMPOSE_API_KEY!,
+);
 ```
+
+The dashboard itself uses the cookie-bound session path; the SDK is for
+programmatic / server-to-server callers.
+
+---
+
+## Public exports — quick reference
+
+| Export | What |
+|---|---|
+| `defineWorkflow` | Attach metadata to a workflow `run` function |
+| `defineRuntime` | Wrap an agent execution provider as an `AgentRuntime` |
+| `defineSandboxEnvironment` | Sugar for declaring a workflow whose primary purpose is to build a snapshot for others to boot from |
+| `runAgent` / `agentLoop` | Embed an LLM loop inside a workflow |
+| `claudeRuntime` / `createClaudeRuntime` / `ClaudeRunner` | Built-in Claude Code runtime + factory |
+| `AgentComposeClient` | HTTP client (register, invoke, status, snapshots, secrets) |
+| `runWorkflow` | Local engine for running a workflow in-process (test harness) |
+| `bundleWorkflow` | Resolve + inline a workflow's runtime sources for registration |
+| `parseAgentStatus` / `parseAgentResponse` / `AgentStatusSchema` / `AgentMessageSchema` | Protocol parsers |
+
+Type exports: `WorkflowFn`, `WorkflowCtx`, `WorkflowDefinition`, `AgentBudget`,
+`AgentRuntime`, `RuntimeOptions`, `ModelExecutionContract`,
+`AgentMessage` (and its variants), `AgentStatus`, `RunStatus`,
+`RegisterResult`, `RunEvent`, `AgentLoopResult`, `RunAgentOpts`,
+`SandboxProvider`, `SandboxNetworkPolicy`, `BundledWorkflow`.
+
+For the canonical signatures, follow your IDE's go-to-definition into
+`@agent-compose/sdk` — `sdk/src/index.ts` is the public surface and the
+files it re-exports from carry full inline docstrings.
+
+---
+
+## Errors
+
+All non-2xx HTTP responses throw `AgentComposeError(status, message)`. The
+`message` is the server's `{ error: string }` body when present, falling
+back to the HTTP status text:
+
+```ts
+import { AgentComposeError } from "@agent-compose/sdk";
+
+try {
+  await client.invoke("missing-workflow");
+} catch (err) {
+  if (err instanceof AgentComposeError && err.status === 404) {
+    // template not registered
+  }
+}
+```
+
+`invokeAndWait` throws `AgentComposeError(504, …)` on timeout for symmetry.