@agent-compose/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Layr Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# @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.
+
+---
+
+## Installation
+
+```bash
+npm install @agent-compose/sdk
+# peer dep:
+npm install zod
+```
+
+---
+
+## Defining an Agent
+
+```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 },
+});
+```
+
+---
+
+## Defining a Runtime
+
+```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),
+});
+```
+
+---
+
+## Writing a Workflow
+
+```typescript
+// my-workflow.ts
+import type { WorkflowFn } from "@agent-compose/sdk";
+
+const myWorkflow: WorkflowFn = async (ctx) => {
+  const planner = await ctx.spawnAgent("planner", {
+    data: { task: ctx.input.task },
+  });
+
+  await ctx.spawnAgent("implementer", {
+    input: planner,                    // chains branch + response
+    data: { task: ctx.input.task },
+  });
+
+  await ctx.setMetadata({ done: true });
+};
+
+export default myWorkflow;
+```
+
+---
+
+## Registration
+
+`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.
+
+```typescript
+import { AgentComposeClient } from "@agent-compose/sdk";
+
+const client = new AgentComposeClient(
+  "http://localhost:8080",
+  process.env.API_KEY!,
+);
+
+// Auto-discovers agents and runtimes from the workflow file
+await client.register({
+  name: "my-workflow",
+  workflowPath: "./my-workflow.ts",
+  // agentPaths and runtimePaths are optional overrides if auto-discovery fails
+});
+```
+
+**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`
+
+---
+
+## Invocation
+
+```typescript
+// Invoke a registered workflow (returns immediately with a run ID)
+const { id } = await client.invoke("my-workflow", {
+  task: "Add rate limiting to the /projects endpoint",
+});
+
+// Poll until done
+let status;
+do {
+  await new Promise(r => setTimeout(r, 5000));
+  status = await client.getStatus(id);
+} while (status.status === "running");
+
+console.log(status.output); // workflow's setMetadata() payload
+```
+
+---
+
+## Exported Types
+
+```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(), ... }
+```

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

@@ -0,0 +1,27 @@
+/**
+ * Agent loop — runner-agnostic iteration driver operating through ModelExecutionContract.
+ * Each iteration: build prompt → sendMessage() → parse <status> → done / continue / circuit-break.
+ */
+import type { RuntimeOptions, ModelExecutionContract } from "../index.js";
+import { z } from "zod";
+import type { AgentStatus, AgentMessage } from "./protocol.js";
+export declare const DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
+export declare function parseAgentStatus(text: string): AgentStatus | null;
+export interface AgentLoopResult {
+    sessionId: string;
+    lastStatus: AgentStatus | null;
+    iterations: number;
+    response?: unknown;
+}
+export declare function agentLoop(opts: {
+    label?: string;
+    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>;
+    runtime?: (opts: RuntimeOptions) => ModelExecutionContract;
+    cwd?: string;
+}): Promise<AgentLoopResult>;

package/dist/agent/protocol.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { AgentStatusSchema } from "../utils/schemas.js";
+import type { AgentMessage } from "../types/protocol.js";
+export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "../types/protocol.js";
+export { AgentStatusSchema };
+export declare const AgentMessageSchema: z.ZodType<AgentMessage>;
+export declare function parseAgentResponse(text: string): unknown;

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

@@ -0,0 +1,58 @@
+/**
+ * runAgent — 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 { 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> {
+    /** 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
+     *  callers can substitute their own. */
+    sandbox: SandboxProvider;
+    /** Runtime definition from `createClaudeRuntime({...})` (or custom). */
+    runtime: AgentRuntime;
+    /** Prompt template. 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
+     *  `agentLoop`. Pass [] to disable tool use entirely. */
+    tools?: string[];
+    /** Turn/iteration caps. Defaults: 40 turns/iteration, 8 iterations. */
+    budget?: AgentBudget;
+    /** If set, the loop demands a `<response>` block when `exit_signal=true`
+     *  and validates it against this schema. The response format appendix is
+     *  appended to the prompt on first iteration. */
+    responseSchema?: z.ZodType<T>;
+    /** Label prefix for runtime stderr ("[sbid][agent]" by default). */
+    label?: string;
+    /** 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;
+}
+/**
+ * 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>;

package/dist/client.d.ts

@@ -0,0 +1,110 @@
+/**
+ * AgentComposeClient — HTTP client for the agent-compose server API.
+ *
+ * register() accepts pre-built sources — use the CLI (agent-compose register)
+ * or build sources yourself and pass them directly.
+ */
+export interface RegisterResult {
+    id: string;
+    name: string;
+    version: string;
+    runtimes?: Array<{
+        name: string;
+        version: string;
+        id: string;
+    }>;
+}
+export interface RunStatus {
+    id: string;
+    status: "running" | "success" | "failed" | "abandoned";
+    output?: Record<string, unknown>;
+}
+export interface SnapshotListEntry {
+    runId: string;
+    workflow: string | null;
+    version: string | null;
+    vercelSnapshotId: string;
+    endedAt: string | null;
+}
+export declare class AgentComposeClient {
+    private readonly fetch;
+    constructor(baseUrl: string, apiKey: string);
+    /** Register a workflow with pre-built sources. */
+    register(payload: {
+        name: string;
+        source: string;
+        version?: string;
+        schedule?: string;
+        runtimes?: Array<{
+            name: string;
+            source: string;
+        }>;
+        networkPolicy?: unknown;
+        placeholders?: Record<string, string>;
+        /** Name (or `name@version`) of another workflow whose snapshot this
+         *  workflow's runner boots from. Must reference a workflow previously
+         *  registered with `--build`. */
+        sandboxEnvironment?: string;
+        /** If true, runs default to capturing a long-lived sandbox snapshot on
+         *  success. Individual invocations can override via `invoke(..., { snapshot })`. */
+        snapshot?: boolean;
+    }): Promise<RegisterResult>;
+    /** Invoke a workflow. Returns run ID immediately — workflow runs asynchronously.
+     *
+     *  `snapshot`: `true` overrides the workflow default; `false` opts out. When
+     *  the run captures a snapshot, its id is stamped on the row and can be
+     *  referenced as `sandboxEnvironment` by other workflows.
+     *
+     *  `parentRunId`: links the new run to another of the same account's
+     *  currently-running runs. When omitted, the client auto-detects from
+     *  `process.env.RUN_ID` — set by the runner sandbox on every dispatch,
+     *  so workflows invoking other workflows get the parent/child tree for
+     *  free. Pass `null` to suppress auto-detection (e.g. invoking a top-level
+     *  sibling workflow from inside a runner for a reason unrelated to the
+     *  current run). Explicit non-null wins over auto-detection. */
+    invoke(name: string, input?: Record<string, unknown>, opts?: {
+        snapshot?: boolean;
+        parentRunId?: string | null;
+    }): Promise<{
+        id: string;
+    }>;
+    /** Invoke a workflow and wait for it to settle (success / failed / abandoned).
+     *  Polls `getStatus` on a fixed interval. Rejects with `AgentComposeError`
+     *  if the run settles non-success, or a plain `Error` on timeout.
+     *
+     *  Defaults: `timeoutMs = 30min`, `pollIntervalMs = 1000ms`. Tune down for
+     *  tests, tune up for long-running workflows. The parent-child auto-
+     *  detection from `invoke()` applies here too. */
+    invokeAndWait(name: string, input?: Record<string, unknown>, opts?: {
+        snapshot?: boolean;
+        parentRunId?: string | null;
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<RunStatus>;
+    /** List runs this account has captured snapshots for. */
+    listSnapshots(opts?: {
+        workflow?: string;
+        limit?: number;
+    }): Promise<SnapshotListEntry[]>;
+    /** Delete the snapshot captured by a specific run. Frees Vercel storage. */
+    deleteSnapshot(runId: string): Promise<void>;
+    /** Poll run status. */
+    getStatus(runId: string): Promise<RunStatus>;
+    /** List registered workflow templates. */
+    listTemplates(): Promise<Array<{
+        name: string;
+        version: string;
+    }>>;
+    /** Create or update a workflow secret. Value is stored in GCP Secret Manager. */
+    setSecret(workflowName: string, key: string, value: string): Promise<{
+        key: string;
+    }>;
+    /** List secret keys registered for a workflow (metadata only — values are never returned). */
+    listSecrets(workflowName: string): Promise<Array<{
+        key: string;
+        createdAt: string;
+        updatedAt: string;
+    }>>;
+    /** Delete a workflow secret. */
+    deleteSecret(workflowName: string, key: string): Promise<void>;
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+/** Thrown by AgentComposeClient when the server returns a non-2xx response. */
+export declare class AgentComposeError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @agent-compose/sdk
+ *
+ * Tools for defining runtimes and workflows, registering/invoking them
+ * against an agent-compose server, and running LLM agent loops inside a
+ * workflow via `runAgent(opts)`.
+ *
+ * @example
+ * ```typescript
+ * import { defineWorkflow, runAgent, AgentComposeClient } from "@agent-compose/sdk";
+ * ```
+ */
+export { defineRuntime } from "./types/runtime.js";
+export { defineWorkflow } from "./types/workflow.js";
+export type { WorkflowDefinition } from "./types/workflow.js";
+export { defineSandboxEnvironment } from "./types/sandbox-environment.js";
+export type { SandboxEnvironmentDefinition } from "./types/sandbox-environment.js";
+export type { AgentRuntime, McpServerConfig, ModelExecutionContract, RuntimeOptions, } from "./types/runtime.js";
+export type { WorkflowFn, WorkflowCtx, WorkflowRun, AgentBudget, WorkflowHooks, } from "./types/workflow.js";
+export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "./types/protocol.js";
+export type { SandboxProvider, DesktopSandboxProvider, } from "./types/sandbox.js";
+export { AgentComposeClient } from "./client.js";
+export type { RegisterResult, RunStatus } from "./client.js";
+export { AgentComposeError } from "./errors.js";
+export { formatError } from "./utils/errors.js";
+export { discoverRuntimeName } from "./utils/discovery.js";
+export { bundleWorkflow } from "./utils/bundler.js";
+export type { BundledWorkflow } from "./utils/bundler.js";
+export { AgentStatusSchema } from "./utils/schemas.js";
+export { createClaudeRuntime, ClaudeRunner } from "./runtimes/claude.js";
+export type { ClaudeRuntimeConfig } from "./runtimes/claude.js";
+export { default as claudeRuntime } from "./runtimes/claude.js";
+export type { RunEvent } from "./types/events.js";
+export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById, getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot, makeSandboxProvider, makeDesktopSandboxProvider, parseSseExecStream, AGENT_COMPOSE_TAG } from "./sandbox.js";
+export type { SandboxCreateOpts, SandboxNetworkPolicy, OwnedSandbox } from "./sandbox.js";
+export { runWorkflow, WorkflowError, EngineError, classifyError, parseNameVersion } from "./workflows/engine.js";
+export type { WorkflowResult, EngineSubsystem } from "./workflows/engine.js";
+export { agentLoop, parseAgentStatus, DEFAULT_CLAUDE_MODEL } from "./agent/agent-loop.js";
+export type { AgentLoopResult } from "./agent/agent-loop.js";
+export { runAgent } from "./agent/run-agent.js";
+export type { RunAgentOpts } from "./agent/run-agent.js";
+export { AgentMessageSchema, parseAgentResponse } from "./agent/protocol.js";
+export { importSourceModule, TMP_DIR, LATEST_VERSION } from "./utils/source-loader.js";