@agent-compose/sdk 0.2.2 → 0.2.4

package/README.md

@@ -1,10 +1,13 @@
 # @agent-compose/sdk
 
-TypeScript SDK for agent-compose. Use it to:
+TypeScript SDK for [agent-compose](https://github.com/Layr-Labs/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`)
+- **Register, invoke, observe, and cancel** workflows via the HTTP API (`AgentComposeClient`)
+- **Manage factories, secrets, API keys, and snapshots** programmatically
+
+The hierarchy: a **team** owns one or more **factories** (project containers); each factory owns workflow templates, secrets, and runs. Workflows are versioned per `(factory, name, version)`. New code that doesn't care about factories transparently lands in `default` — every team has one.
 
 ---
 
@@ -25,23 +28,22 @@ 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
+  pass it to `agent({ sandbox, ... })` and to any helper that takes a
   `SandboxProvider` (file writers, git utilities, command runners).
 
 ```typescript
 // my-workflow.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({
   async run(ctx, sandbox) {
     const repo = (ctx.input?.repo as string | undefined) ?? "owner/repo";
 
-    const result = await runAgent({
+    const result = await agent({
       sandbox,
       runtime:    claudeRuntime,
-      prompt:     PROMPT,
-      promptVars: { REPO: repo },
+      prompt:     `${PROMPT}\n\nRepository: ${repo}`,
       tools:      ["Bash", "Read", "Edit", "Write", "Grep", "Glob"],
       budget:     { turnsPerIteration: 40, maxIterations: 8 },
     });
@@ -83,14 +85,13 @@ interface WorkflowCtx {
 duration. Use it for setup, external API calls, or anything you want
 visible on the dashboard's run detail page.
 
-### The `runAgent` loop
+### The `agent` loop
 
 ```ts
-runAgent({
+agent({
   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
@@ -110,7 +111,7 @@ the full instructions appended to every prompt.
 ## Defining a runtime
 
 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
+CLI like Claude Code or OpenAI Desktop — so `agent` can drive it. The SDK
 ships built-ins; you only need a custom one for an exotic provider.
 
 ### Built-in runtimes
@@ -148,7 +149,7 @@ const myRuntime: AgentRuntime = defineRuntime({
 
 `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`),
+runtime is bound to the workflow at author time (you pass it to `agent`),
 not selected by the server.
 
 ---
@@ -162,9 +163,10 @@ 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:
+inlines runtime sources via dynamic-require traversal) and `POST
+/api/v1/factories/<slug>/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";
@@ -176,10 +178,11 @@ const client = new AgentComposeClient(
 
 const bundled = await bundleWorkflow("./my-workflow.ts");
 await client.register({
-  name:    "my-workflow",
-  source:  bundled.source,
-  runtimes: bundled.runtimes,         // [{ name, source }] — embedded so the runner has them locally
-  schedule: "*/30 * * * *",            // optional cron
+  name:        "my-workflow",
+  source:      bundled.source,
+  runtimes:    bundled.runtimes,        // [{ name, source }] — embedded so the runner has them locally
+  schedule:    "*/30 * * * *",          // optional cron
+  factorySlug: "default",                // optional — defaults to "default"
   // snapshot, saveSnapshot, networkPolicy, placeholders — all optional
 });
 ```
@@ -204,7 +207,7 @@ 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.status);   // "success" | "failed" | "abandoned" | "canceled"
 console.log(status.output);   // workflow's return value
 ```
 
@@ -213,6 +216,10 @@ 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.
 
+`invoke` and `invokeAndWait` both accept `{ factorySlug, snapshot,
+saveSnapshot, parentRunId }` as the third argument. `factorySlug` defaults
+to `"default"`.
+
 ### Auto parent/child tracing
 
 The SDK detects `process.env.RUN_ID` (set by the runner sandbox on every
@@ -221,25 +228,123 @@ dispatch) and automatically threads it as `parentRunId` on subsequent
 parent/child tree in the dashboard for free. Pass `parentRunId: null`
 to opt out.
 
+### Cancelling a run
+
+```ts
+await client.cancelRun(runId);
+```
+
+Idempotent — cancelling an already-terminal run returns the current state
+without throwing. The server stamps the run as `canceled`, kills any live
+sandboxes, and emits a `run_canceled` event on the stream.
+
+### Streaming live logs
+
+`streamRunLogs` returns an async generator of `RunEvent`s in real time,
+re-attaching via SSE under the hood. Pass `lastEventId` (the highest
+`seq` you've already processed) to resume after a reconnect.
+
+```ts
+for await (const ev of client.streamRunLogs(runId, { lastEventId: 0 })) {
+  console.log(ev.event, ev.seq, ev.data);
+  if (ev.event === "run_complete" || ev.event === "run_failed" || ev.event === "run_canceled") {
+    break;
+  }
+}
+```
+
+`AbortSignal` works too — pass `{ signal }` and call `controller.abort()`
+to tear the stream down from the caller side.
+
+---
+
+## Factories
+
+Factories are project containers within a team. Each factory has its own
+workflow templates, secrets, runs, and (optionally) scoped API keys. New
+projects don't need to think about them — `default` is auto-created per
+team and is what the SDK falls back to when `factorySlug` is omitted.
+
+```ts
+// CRUD on factories
+await client.createFactory({ slug: "ci-bots", name: "CI Bots", description: "…" });
+const factories = await client.listFactories();
+const f         = await client.getFactory("ci-bots");
+await client.updateFactory("ci-bots", { name: "Continuous-Integration Bots" });
+await client.deleteFactory("ci-bots");
+
+// Templates list — flat across factories, or scoped to one
+const all   = await client.listTemplates();
+const scoped = await client.listTemplates({ factorySlug: "ci-bots" });
+
+// Register / invoke / secret operations all accept factorySlug
+await client.register({ name: "scrape", source, factorySlug: "ci-bots", … });
+await client.invoke("scrape", { url: "…" }, { factorySlug: "ci-bots" });
+await client.setSecret("scrape", "GH_TOKEN", "ghp_…", { factorySlug: "ci-bots" });
+```
+
+CLI equivalents: `agentc factory list | create | get | update | delete`,
+plus `--factory <slug>` on every other command.
+
 ---
 
 ## 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).
+Secrets live in GCP Secret Manager, one row per `(factory, 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).
 
 ```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");
+
+// Scope to a non-default factory:
+await client.setSecret("scrape", "GH_TOKEN", "ghp_…", { factorySlug: "ci-bots" });
 ```
 
 Mutations require `admin` scope.
 
 ---
 
+## API keys
+
+Mint and list scoped keys programmatically (requires an `admin`-scoped
+caller key). New keys are returned **once**, in the same response as the
+metadata — copy the `ac_…` value immediately.
+
+```ts
+const created = await client.createApiKey({
+  name:      "ci-dispatcher",
+  scopes:    ["read", "invoke"],
+  expiresAt: new Date(Date.now() + 30 * 86_400_000).toISOString(),  // 30 days
+  // factorySlug: "ci-bots"  // optional — scopes the key to a single factory
+});
+console.log(created.key);   // "ac_…" — the only time you'll see this
+
+const all = await client.listApiKeys();
+```
+
+CLI equivalent: `agentc keys create <name> --scopes read,invoke
+--expires-in 30d`.
+
+---
+
+## Usage
+
+```ts
+const usage = await client.getUsage(
+  new Date(Date.now() - 30 * 86_400_000),
+  new Date(),
+);
+// usage.rows: [{ day, runs, sandbox_seconds, … }]
+```
+
+CLI equivalent: `agentc usage`.
+
+---
+
 ## Snapshots (replay-friendly sandboxes)
 
 Long-running workflows can capture the runner sandbox as a Vercel snapshot
@@ -294,18 +399,25 @@ programmatic / server-to-server callers.
 | `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) |
+| `agent` / `agentLoop` | Embed an LLM loop inside a workflow |
 | `runWorkflow` | Local engine for running a workflow in-process (test harness) |
 | `bundleWorkflow` | Resolve + inline a workflow's runtime sources for registration |
+| `claudeRuntime` / `createClaudeRuntime` / `ClaudeRunner` | Built-in Claude Code runtime + factory |
+| `AgentComposeClient` | HTTP client — register, invoke, cancel, stream logs, factories, snapshots, secrets, API keys, usage |
+| `AgentComposeError` | Thrown by every non-2xx HTTP response |
 | `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`.
+| `parseSseStream` | Generic SSE chunk decoder (used by `streamRunLogs`) |
+| `createSandbox` / `reconnectSandbox` / `killAllSandboxes` / `killSandboxById` / `getSandboxQuotas` / `listOwnedSandboxes` / `deleteSandboxSnapshot` | Sandbox-provider helpers (Vercel + E2B) |
+
+Type exports: `WorkflowFn`, `WorkflowCtx`, `WorkflowDefinition`,
+`WorkflowHooks`, `AgentBudget`, `AgentRuntime`, `RuntimeOptions`,
+`ModelExecutionContract`, `McpServerConfig`, `AgentMessage` (and its
+variants), `AgentStatus`, `RunStatus`, `RegisterResult`, `RunEvent`,
+`FactoryRow`, `SnapshotListEntry`, `ApiKey`, `ApiKeyCreated`,
+`UsageRollupRow`, `UsageResponse`, `CancelRunResponse`, `AgentLoopResult`,
+`AgentOpts`, `SandboxProvider`, `DesktopSandboxProvider`,
+`SandboxNetworkPolicy`, `SandboxCreateOpts`, `OwnedSandbox`,
+`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

package/dist/agent/agent-loop.d.ts

@@ -5,23 +5,101 @@
 import type { RuntimeOptions, ModelExecutionContract } from "../index.js";
 import { z } from "zod";
 import type { AgentStatus, AgentMessage } from "./protocol.js";
+import type { Processor } from "../processors/processor.js";
+import { RequestContext } from "../request-context/request-context.js";
 export declare const DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
 export declare function parseAgentStatus(text: string): AgentStatus | null;
-export interface AgentLoopResult {
+export interface AgentLoopResult<TResponse = unknown> {
+    agentId: string;
+    label: string;
     sessionId: string;
     lastStatus: AgentStatus | null;
     iterations: number;
-    response?: unknown;
+    response?: TResponse;
 }
-export declare function agentLoop(opts: {
+export type AgentMessageSummary = {
+    type: "init";
+    sessionId: string;
+} | {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    text: string;
+} | {
+    type: "tool_use";
+    toolName: string;
+    toolUseId: string;
+    toolInputPreview: string;
+} | {
+    type: "tool_result";
+    toolUseId: string;
+    output: string;
+    isError: boolean;
+} | {
+    type: "usage";
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    durationMs: number;
+    numTurns: number;
+} | {
+    type: "done";
+    sessionId: string;
+} | {
+    type: "error";
+    text: string;
+};
+export declare function summarizeAgentMessage(msg: AgentMessage): AgentMessageSummary;
+export type AgentLifecycleEvent = {
+    event: "agent.spawned";
+    at: number;
+    agentId: string;
+    label: string;
+    allowedTools?: string[];
+} | {
+    event: "agent.message";
+    at: number;
+    agentId: string;
+    label: string;
+    iteration: number;
+    message: AgentMessageSummary;
+} | {
+    event: "agent.iteration";
+    at: number;
+    agentId: string;
+    label: string;
+    iteration: number;
+    status: AgentStatus | null;
+} | {
+    event: "agent.settled";
+    at: number;
+    agentId: string;
+    label: string;
+    outcome: "success" | "failed";
+    iterations: number;
+    durationMs: number;
+    failureReason?: string;
+};
+export interface AgentLoopOpts<TResponse = unknown> {
+    agentId?: string;
     label?: string;
+    onAgentLifecycleEvent?: (event: AgentLifecycleEvent) => void;
     onIteration?: (iteration: number, status: AgentStatus | null) => void;
     turnsPerIteration?: number;
     maxIterations?: number;
     buildPrompt: (lastStatus: AgentStatus | null, iteration: number) => string;
     onAgentEvent?: (iteration: number, msg: AgentMessage) => void;
     allowedTools?: string[];
-    responseSchema?: z.ZodType<unknown>;
+    responseSchema?: z.ZodType<TResponse>;
     runtime?: (opts: RuntimeOptions) => ModelExecutionContract;
     cwd?: string;
-}): Promise<AgentLoopResult>;
+    /** Processor chain — see sdk/src/processors. Runs sequentially around
+     *  prompts and emitted messages. Tool-call gating is a no-op until a
+     *  runtime that exposes a pre-tool-use seam is wired (candidate #1). */
+    processors?: readonly Processor[];
+    /** Per-run typed bag — propagated to every processor as `ctx.requestContext`. */
+    requestContext?: RequestContext;
+}
+export declare function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TResponse>): Promise<AgentLoopResult<TResponse>>;

package/dist/agent/run-agent.d.ts

@@ -1,22 +1,25 @@
 /**
- * runAgent — canonical entry point for embedding an LLM agent inside a
+ * agent — canonical entry point for embedding an LLM agent inside a
  * workflow. The workflow's `run()` body calls it; the loop executes
  * against the runner's own VM.
  *
  * Glue packaged so workflows don't duplicate it:
- *   - Inject `{{VAR}}` placeholders into the prompt template.
  *   - Strip the `--- frontmatter ---` header authors use for IDE hints.
  *   - Append PROTOCOL_SUFFIX (status/response format instructions).
  *   - Append a response-format appendix when `responseSchema` is set.
  *   - Delegate to `agentLoop`.
  */
 import { z } from "zod";
-import type { AgentLoopResult } from "./agent-loop.js";
+import type { AgentLifecycleEvent, AgentLoopResult } from "./agent-loop.js";
 import type { AgentMessage, AgentStatus } from "../types/protocol.js";
 import type { AgentRuntime } from "../types/runtime.js";
 import type { SandboxProvider } from "../types/sandbox.js";
 import type { AgentBudget } from "../types/workflow.js";
-export interface RunAgentOpts<T = unknown> {
+import type { Processor } from "../processors/processor.js";
+import { RequestContext } from "../request-context/request-context.js";
+export interface AgentOpts<T = unknown> {
+    /** Stable system identity for this agent loop. Generated when omitted. */
+    agentId?: string;
     /** Sandbox the runtime executes commands against. Inside a workflow,
      *  always pass `ctx.sandbox` — a pre-constructed local provider for
      *  the runner's own VM. Exposed as a parameter so tests and non-workflow
@@ -24,12 +27,9 @@ export interface RunAgentOpts<T = unknown> {
     sandbox: SandboxProvider;
     /** Runtime definition from `createClaudeRuntime({...})` (or custom). */
     runtime: AgentRuntime;
-    /** Prompt template. Authors can include YAML-style `--- frontmatter ---`
+    /** Prompt text. Authors can include YAML-style `--- frontmatter ---`
      *  at the top for IDE hints; it's stripped before the model sees it. */
     prompt: string;
-    /** Substitution map for `{{VAR}}` placeholders in the prompt. `WORKING_DIR`
-     *  and `DIFF_BASE` auto-populate from `opts.workingDir` unless overridden. */
-    promptVars?: Record<string, string>;
     /** `cwd` forwarded to the runtime — every shell command runs here. */
     workingDir?: string;
     /** Tools the model may use. Defaults to a safe kitchen-sink set inside
@@ -43,16 +43,41 @@ export interface RunAgentOpts<T = unknown> {
     responseSchema?: z.ZodType<T>;
     /** Label prefix for runtime stderr ("[sbid][agent]" by default). */
     label?: string;
+    /** Lifecycle event sink from workflow ctx. Emits agent.spawned / iteration / settled. */
+    events?: {
+        emit: (event: AgentLifecycleEvent) => void | Promise<void>;
+    };
     /** Per-message event callback — wire this to your workflow's event
      *  telemetry if you want per-tool-call observability. */
     onAgentEvent?: (iteration: number, msg: AgentMessage) => void;
     /** Per-iteration status callback — fires after each model turn with the
      *  parsed `<status>` block (or null if the model didn't emit one). */
     onIteration?: (iteration: number, status: AgentStatus | null) => void;
+    /**
+     * Processors run as a typed pre/post pipeline around the agent loop:
+     *   - processInput before each iteration's prompt is sent
+     *   - processOutput on each emitted message
+     *   - processToolCall before each tool call (runtime-driven; dormant
+     *     until a runtime that supports pre-tool gating is wired in)
+     *
+     * Common pattern with workflow-level defaults:
+     *   agent({ processors: [...ctx.processors, mySpecific], ... })
+     */
+    processors?: readonly Processor[];
+    /**
+     * Per-run request context. Passed through to processors as
+     * `ctx.requestContext`; carries tenant identity (teamId, factoryId, scopes)
+     * and the freeform user namespace.
+     *
+     * Inside a workflow, pass `ctx.requestContext`. Tests/non-workflow callers
+     * can omit; a degenerate context is synthesised so processors that don't
+     * read identity (e.g. redactPattern) still work.
+     */
+    requestContext?: RequestContext;
 }
 /**
  * Run an agent loop inside a workflow. Returns the loop's final
  * `AgentLoopResult`, including `response` when a `responseSchema` was
  * supplied and the model validated against it.
  */
-export declare function runAgent<T = unknown>(opts: RunAgentOpts<T>): Promise<AgentLoopResult>;
+export declare function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopResult<T>>;