@agent-compose/sdk 0.2.0 → 0.2.1

package/README.md

@@ -1,13 +1,10 @@
 # @agent-compose/sdk
 
-TypeScript SDK for [agent-compose](https://github.com/Layr-Labs/agent-compose). Use it to:
+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, 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.
+- **Register, invoke, and observe** workflows via the HTTP API (`AgentComposeClient`)
 
 ---
 
@@ -165,10 +162,9 @@ 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/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:
+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";
@@ -180,11 +176,10 @@ 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
-  factorySlug: "default",                // optional — defaults to "default"
+  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
 });
 ```
@@ -209,7 +204,7 @@ const status = await client.invokeAndWait("my-workflow", { repo: "owner/repo" },
   timeoutMs:      5 * 60_000,
   pollIntervalMs: 2000,
 });
-console.log(status.status);   // "success" | "failed" | "abandoned" | "canceled"
+console.log(status.status);   // "success" | "failed" | "abandoned"
 console.log(status.output);   // workflow's return value
 ```
 
@@ -218,10 +213,6 @@ 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
@@ -230,123 +221,25 @@ 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 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).
+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).
 
 ```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
@@ -402,24 +295,17 @@ programmatic / server-to-server callers.
 | `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 |
-| `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 |
-| `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`,
-`RunAgentOpts`, `SandboxProvider`, `DesktopSandboxProvider`,
-`SandboxNetworkPolicy`, `SandboxCreateOpts`, `OwnedSandbox`,
-`BundledWorkflow`.
+
+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

package/dist/client.d.ts

@@ -11,6 +11,7 @@
  * register`) or build sources yourself and pass them directly.
  */
 import type { RunEvent } from "./types/events.js";
+import type { SandboxNetworkPolicy } from "./sandbox.js";
 export interface RegisterResult {
     id: string;
     name: string;
@@ -136,6 +137,8 @@ export declare class AgentComposeClient {
         saveSnapshot?: boolean;
         parentRunId?: string | null;
         factorySlug?: string;
+        networkPolicy?: SandboxNetworkPolicy;
+        placeholders?: Record<string, string>;
     }): Promise<{
         id: string;
     }>;
@@ -151,6 +154,8 @@ export declare class AgentComposeClient {
         saveSnapshot?: boolean;
         parentRunId?: string | null;
         factorySlug?: string;
+        networkPolicy?: SandboxNetworkPolicy;
+        placeholders?: Record<string, string>;
         timeoutMs?: number;
         pollIntervalMs?: number;
     }): Promise<RunStatus>;

package/dist/index.js

@@ -455,7 +455,9 @@ class AgentComposeClient {
         input,
         ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
         ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
-        ...parentRunId ? { parentRunId } : {}
+        ...parentRunId ? { parentRunId } : {},
+        ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
+        ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {}
       }
     });
   }
@@ -466,7 +468,9 @@ class AgentComposeClient {
       ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
       ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
       ...opts?.parentRunId !== undefined ? { parentRunId: opts.parentRunId } : {},
-      ...opts?.factorySlug !== undefined ? { factorySlug: opts.factorySlug } : {}
+      ...opts?.factorySlug !== undefined ? { factorySlug: opts.factorySlug } : {},
+      ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
+      ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {}
     });
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {

package/dist/runtimes/openai-desktop.js

@@ -455,7 +455,9 @@ class AgentComposeClient {
         input,
         ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
         ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
-        ...parentRunId ? { parentRunId } : {}
+        ...parentRunId ? { parentRunId } : {},
+        ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
+        ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {}
       }
     });
   }
@@ -466,7 +468,9 @@ class AgentComposeClient {
       ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
       ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
       ...opts?.parentRunId !== undefined ? { parentRunId: opts.parentRunId } : {},
-      ...opts?.factorySlug !== undefined ? { factorySlug: opts.factorySlug } : {}
+      ...opts?.factorySlug !== undefined ? { factorySlug: opts.factorySlug } : {},
+      ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
+      ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {}
     });
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {