@agent-compose/sdk 0.1.0

package/dist/sandbox.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Sandbox provider registry — creates and manages isolated execution environments.
+ *
+ * Providers: "vercel" (Vercel Sandbox), "e2b" (E2B), "e2b-desktop" (E2B Desktop).
+ * Each provider validates its required env vars at creation time.
+ */
+import { Sandbox } from "e2b";
+import { Sandbox as Desktop } from "@e2b/desktop";
+import type { SandboxProvider, DesktopSandboxProvider } from "./types/sandbox.js";
+export type { SandboxProvider, DesktopSandboxProvider } from "./types/sandbox.js";
+export declare const AGENT_COMPOSE_TAG: string;
+/**
+ * Vercel-compatible network policy for outbound HTTPS requests.
+ * When a sandbox makes a request matching a domain in `allow`, the Vercel
+ * firewall injects the specified headers before forwarding — credentials never
+ * exist inside the VM. E2B ignores this field (future self-hosted mapping TBD).
+ */
+export type SandboxNetworkPolicy = "allow-all" | "deny-all" | {
+    allow?: string[] | Record<string, Array<{
+        transform?: Array<{
+            headers?: Record<string, string>;
+        }>;
+    }>>;
+    subnets?: {
+        allow?: string[];
+        deny?: string[];
+    };
+};
+export interface SandboxCreateOpts {
+    envs: Record<string, string>;
+    metadata: Record<string, string>;
+    timeoutMs: number;
+    /** Provider-specific template/snapshot identifier. E2B: template ID; Vercel: snapshot ID. */
+    template?: string;
+    /** Outbound request policy. Vercel only — E2B silently ignores. */
+    networkPolicy?: SandboxNetworkPolicy;
+}
+/**
+ * What the provider reports as "currently alive" — the single input to orphan
+ * reconciliation. `metadata` is best-effort: E2B populates it from sandbox
+ * labels, Vercel leaves it empty (the API has no metadata field). Callers
+ * that need runId correlation cross-reference `sandboxId` against their own
+ * state (server: `workflow_runs.sandbox_id` + `run_agent_sandboxes.provider_sandbox_id`).
+ */
+export interface OwnedSandbox {
+    sandboxId: string;
+    createdAt: Date;
+    metadata: Record<string, string>;
+}
+interface SandboxProviderDef {
+    requiredEnv: Record<string, string>;
+    create: (opts: SandboxCreateOpts, env: Record<string, string>) => Promise<SandboxProvider>;
+    reconnect?: (sandboxId: string) => Promise<SandboxProvider>;
+    killAll?: (env: Record<string, string>) => Promise<void>;
+    /**
+     * Returns the number of sandboxes currently running against this provider.
+     * Used for quota observability — account-wide, not per-instance.
+     *
+     * E2B scopes by our AGENT_COMPOSE_TAG metadata so each machine only reports
+     * its own sandboxes; DD aggregates across instances with `sum by {provider}`.
+     * Vercel has no user metadata support, so it counts every running sandbox in
+     * the configured project (assumed dedicated to agent-compose).
+     */
+    getActiveCount?: (env: Record<string, string>) => Promise<number>;
+    /**
+     * Provider's view of what's currently alive for our account/fleet.
+     * The reconciliation SoT — a sandbox missing from this list IS dead,
+     * regardless of what our DB says. Implemented by listing the provider's
+     * running sandboxes; E2B filters by metadata tag, Vercel lists the whole
+     * project (it has no metadata search). 200-row cap applies to Vercel.
+     */
+    listOwned?: (env: Record<string, string>) => Promise<OwnedSandbox[]>;
+    /**
+     * Delete a snapshot by id. Called from the customer-initiated
+     * `DELETE /workflows/:runId/snapshot` route. Best-effort — the DB is
+     * source of truth; an orphan on the provider side is benign and cleaned
+     * up eventually by the provider's own retention.
+     */
+    deleteSnapshot?: (snapshotId: string, env: Record<string, string>) => Promise<void>;
+}
+export declare function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider;
+export declare function makeDesktopSandboxProvider(sb: Desktop): DesktopSandboxProvider;
+/**
+ * Parse an SSE exec stream from a ReadableStream.
+ * Used by the agent sandbox broker in runner.ts.
+ */
+export declare function parseSseExecStream(body: ReadableStream<Uint8Array>, opts?: {
+    onStdout?: (d: string) => void;
+    onStderr?: (d: string) => void;
+}): Promise<{
+    exitCode: number;
+    stdout: string;
+}>;
+/** Minimal SandboxProvider that targets the current process's host VM.
+ *  `commands.run` → `child_process.spawn`; `files.write` → `fs.writeFile`;
+ *  `kill` is a no-op because the caller IS the VM. Used by
+ *  `defineSandboxEnvironment` so setup recipes read like imperative
+ *  provisioning scripts. Uses `node:child_process` — works under both Node
+ *  (the runner executes `node /tmp/runner.bundle.js`) and Bun. */
+export declare function makeLocalSandboxProvider(): SandboxProvider;
+declare const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef>;
+/** Provision a sandbox for the named provider. */
+export declare function createSandbox(provider: string, opts: SandboxCreateOpts): Promise<SandboxProvider>;
+/** Reconnect to an existing sandbox by provider + provider-native sandbox ID. */
+export declare function reconnectSandbox(provider: string, sandboxId: string): Promise<SandboxProvider>;
+/** Delete a snapshot by id on the named provider. No live sandbox needed. */
+export declare function deleteSandboxSnapshot(provider: string, snapshotId: string): Promise<void>;
+/**
+ * Current active-sandbox count per configured provider, for quota gauges.
+ * Skips providers whose required env isn't set or which don't implement
+ * `getActiveCount`. Errors are surfaced per-provider so one flaky provider
+ * doesn't silence the rest.
+ */
+export declare function getSandboxQuotas(): Promise<Record<string, number | Error>>;
+/**
+ * List every alive sandbox owned by this fleet, across all configured
+ * providers — the orphan-reconciler SoT. Providers without `listOwned`
+ * or missing env are skipped. Errors propagate per-provider so one flaky
+ * provider doesn't silence the rest.
+ */
+export declare function listOwnedSandboxes(): Promise<Record<string, OwnedSandbox[] | Error>>;
+/** Kill a sandbox by provider + native ID. Used by the orphan reconciler. */
+export declare function killSandboxById(provider: string, sandboxId: string): Promise<void>;
+/** Kill all sandboxes across all registered providers. Call at startup to clean up after crashes. */
+export declare function killAllSandboxes(onError?: (provider: string, err: unknown) => void): Promise<void>;
+export { SANDBOX_PROVIDERS };

package/dist/types/events.d.ts

@@ -0,0 +1,80 @@
+/**
+ * RunEvent — the canonical streaming contract for agent-compose SSE streams.
+ *
+ * Emitted by the server via pg_notify and forwarded to clients over
+ * GET /api/v1/workflows/:id/stream. Every event carries `runId`, `at` (unix ms),
+ * and `seq` (the DB row id for Last-Event-ID resumption).
+ *
+ * The `event` field doubles as the SSE `event:` name.
+ */
+export type RunEvent = {
+    event: "agent_event";
+    runId: string;
+    at: number;
+    seq?: number;
+    msgType: string;
+    toolName?: string;
+    toolDetail?: string;
+    isError?: boolean;
+} | {
+    event: "agent_spawned";
+    runId: string;
+    at: number;
+    seq?: number;
+    agentIndex: number;
+    agentId: string;
+    label: string;
+    sandboxId: string;
+    agentName: string;
+    parentAgentId: string | null;
+} | {
+    event: "agent_settled";
+    runId: string;
+    at: number;
+    seq?: number;
+    agentIndex: number;
+    agentId: string;
+    label: string;
+    outcome: "success" | "failed";
+    durationMs: number;
+    failureReason?: string;
+} | {
+    event: "step_started";
+    runId: string;
+    at: number;
+    seq?: number;
+    step: string;
+} | {
+    event: "step_completed";
+    runId: string;
+    at: number;
+    seq?: number;
+    step: string;
+    durationMs: number;
+} | {
+    event: "step_failed";
+    runId: string;
+    at: number;
+    seq?: number;
+    step: string;
+    durationMs: number;
+    reason: string;
+} | {
+    event: "run_complete";
+    runId: string;
+    at: number;
+    seq?: number;
+} | {
+    event: "run_failed";
+    runId: string;
+    at: number;
+    seq?: number;
+    reason: string;
+} | {
+    event: "workflow_log";
+    runId: string;
+    at: number;
+    seq?: number;
+    level: "info" | "warn" | "error";
+    msg: string;
+};

package/dist/types/protocol.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Agent message protocol — the stream of events emitted by a runtime's ModelExecutionContract.
+ */
+interface AgentMessageBase {
+    timestamp: string;
+}
+export interface AgentMessageInit extends AgentMessageBase {
+    type: "init";
+    sessionId: string;
+}
+export interface AgentMessageText extends AgentMessageBase {
+    type: "text";
+    text: string;
+}
+export interface AgentMessageThinking extends AgentMessageBase {
+    type: "thinking";
+    text: string;
+}
+export interface AgentMessageToolUse extends AgentMessageBase {
+    type: "tool_use";
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+}
+export interface AgentMessageToolResult extends AgentMessageBase {
+    type: "tool_result";
+    toolUseId: string;
+    output: string;
+    isError: boolean;
+}
+export interface AgentMessageDone extends AgentMessageBase {
+    type: "done";
+    sessionId: string;
+}
+export interface AgentMessageError extends AgentMessageBase {
+    type: "error";
+    text: string;
+}
+export interface AgentMessageUsage extends AgentMessageBase {
+    type: "usage";
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    durationMs: number;
+    numTurns: number;
+}
+export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage;
+/** Status block the agent emits to signal iteration completion or blockers. */
+export interface AgentStatus {
+    summary: string;
+    completed: string[];
+    blockers: string[];
+    exit_signal: boolean;
+}
+export {};

package/dist/types/runtime.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Agent runtime types — the execution strategy for driving a model.
+ */
+import type { SandboxProvider } from "./sandbox.js";
+import type { AgentMessage } from "./protocol.js";
+/** Configuration for a single MCP server. */
+export interface McpServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/** Options passed to a runtime when creating a ModelExecutionContract. */
+export interface RuntimeOptions {
+    allowedTools?: string[];
+    maxTurns?: number;
+    model?: string;
+    /** Label prefix for all stderr output. */
+    label?: string;
+    /** Working directory — the claude CLI process starts here so relative paths work correctly. */
+    cwd?: string;
+}
+/**
+ * The execution contract every runtime must satisfy.
+ * Given a prompt, yield a stream of agent events.
+ */
+export interface ModelExecutionContract {
+    sendMessage(opts: {
+        prompt: string;
+        sessionId?: string;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentMessage>;
+}
+/**
+ * An agent runtime — a model execution strategy that drives an agent inside a sandbox.
+ *
+ * The sandbox provider (e.g. "vercel", "e2b") is an infrastructure concern
+ * configured via SANDBOX_PROVIDER — not part of the runtime definition.
+ * For non-sandbox agents (API calls, etc.) make the call directly in the workflow;
+ * spawnAgent is a sandbox concept.
+ */
+export interface AgentRuntime<S extends SandboxProvider = SandboxProvider> {
+    create(sandbox: S, opts: RuntimeOptions): ModelExecutionContract;
+}
+/**
+ * Declare a registerable runtime. Validates required fields at module load time.
+ * Use `export default defineRuntime({...})` as the single export in runtime source files.
+ */
+export declare function defineRuntime<S extends SandboxProvider = SandboxProvider>(pkg: AgentRuntime<S>): AgentRuntime<S>;

package/dist/types/sandbox-environment.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A sandbox environment is a workflow whose job is to leave its VM in a
+ * configured state, then snapshot it so other workflows can boot from that
+ * state. Snapshots are **opt-in**: the wrapper below sets `snapshot: true`
+ * by default (opt out with `snapshot: false` if you only want side effects).
+ *
+ * Once captured, reference the snapshot from another workflow's
+ * `sandboxEnvironment` field by run UUID, workflow name, or `name@version`:
+ *
+ *     sandboxEnvironment: "my-setup"          // most recent successful snapshot
+ *     sandboxEnvironment: "my-setup@v1"       // version-scoped recency
+ *     sandboxEnvironment: "<run-uuid>"        // pinned to an exact run
+ *
+ * `defineSandboxEnvironment` is sugar over `defineWorkflow` — it makes the
+ * setup recipe read like an imperative script by supplying the local
+ * sandbox provider (the runner's own VM) to the callback.
+ *
+ * Typical flow:
+ *   1. Author a setup file with `defineSandboxEnvironment`.
+ *   2. `agentc register setup.ts --build` — registers and invokes once to
+ *      capture the snapshot.
+ *   3. Other workflows declare `sandboxEnvironment: "name"` and boot from it.
+ *   4. `agentc snapshot list` / `delete` to manage the Vercel storage bill.
+ *
+ * @example
+ * ```typescript
+ * import { defineSandboxEnvironment } from "@agent-compose/sdk";
+ *
+ * export default defineSandboxEnvironment({
+ *   name: "python",
+ *   setup: async (sb) => {
+ *     await sb.commands.run("sudo dnf install -y python3-pip");
+ *   },
+ * });
+ * ```
+ */
+import type { SandboxProvider } from "./sandbox.js";
+import type { WorkflowFn } from "./workflow.js";
+export interface SandboxEnvironmentDefinition {
+    name: string;
+    description?: string;
+    setup: (sb: SandboxProvider) => Promise<void>;
+    /** Override the sugar's `snapshot: true` default. Set `false` to opt out
+     *  of snapshot capture (rarely useful — an env with no snapshot can't be
+     *  referenced as `sandboxEnvironment`). */
+    snapshot?: boolean;
+}
+export declare function defineSandboxEnvironment(env: SandboxEnvironmentDefinition): WorkflowFn<void>;

package/dist/types/sandbox.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Sandbox abstraction — the compute environment an agent runs inside.
+ * Provider-agnostic: E2B, Vercel, Docker, or any other backend implements this.
+ */
+/** Base compute interface — pure I/O, no filesystem path or git concerns. */
+export interface SandboxProvider {
+    sandboxId: string;
+    /** Working directory for the agent process. Set by onStart after environment setup. */
+    cwd?: string;
+    commands: {
+        run(cmd: string, opts?: {
+            cwd?: string;
+            timeoutMs?: number;
+            envs?: Record<string, string>;
+            onStdout?: (data: string) => void;
+            onStderr?: (data: string) => void;
+            background?: boolean;
+        }): Promise<{
+            exitCode: number;
+            stdout: string;
+        }>;
+    };
+    files: {
+        write(path: string, content: string): Promise<unknown>;
+    };
+    kill(): Promise<void>;
+    /** Capture the running sandbox's state as a reusable snapshot. Vercel
+     *  supports it natively; E2B's model is Dockerfile-based and doesn't map
+     *  cleanly — `undefined` on providers that don't. Used by the server's
+     *  `--build` flow to stamp the snapshot id on the workflow row. */
+    snapshot?(): Promise<{
+        snapshotId: string;
+    }>;
+}
+/** Stateless provider-level snapshot deletion — no live sandbox needed,
+ *  called from customer-initiated `DELETE /workflows/:runId/snapshot`. */
+export type DeleteSnapshotFn = (snapshotId: string) => Promise<void>;
+/** Extends SandboxProvider with desktop GUI capabilities. */
+export interface DesktopSandboxProvider extends SandboxProvider {
+    screenshot(): Promise<Buffer>;
+    leftClick(x: number, y: number): Promise<void>;
+    doubleClick(x: number, y: number): Promise<void>;
+    rightClick(x: number, y: number): Promise<void>;
+    middleClick(x: number, y: number): Promise<void>;
+    moveMouse(x: number, y: number): Promise<void>;
+    write(text: string): Promise<void>;
+    press(key: string): Promise<void>;
+    scroll(direction: "up" | "down", ticks: number): Promise<void>;
+    drag(from: [number, number], to: [number, number]): Promise<void>;
+}

package/dist/types/workflow.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Workflow types — the context and function signature for authoring workflows.
+ *
+ * A workflow is `async (ctx, sandbox) => T`. Two positional args by design:
+ *
+ *   - `ctx` carries facts + observability about THIS run (id, input,
+ *     setMetadata, step). Metadata bag.
+ *   - `sandbox` is a capability handed to you by the engine for doing work
+ *     (exec commands, write files). Pass it to `runAgent({ sandbox, ... })`
+ *     and to any helper that takes a SandboxProvider (git utilities, file
+ *     writers). Constructed once per run; reuse it.
+ *
+ * LLM agent loops live in `runAgent(opts)` (sdk/src/agent/run-agent.ts).
+ * Invoking other workflows uses `AgentComposeClient.invoke[AndWait](...)`.
+ */
+import type { SandboxNetworkPolicy } from "../sandbox.js";
+import type { SandboxProvider } from "./sandbox.js";
+/** The identity of this workflow run. */
+export interface WorkflowRun {
+    id: string;
+}
+/** Turn/iteration budget for `runAgent(opts)`. Re-exported here so authors
+ *  can type per-invoke budget overrides they pass as workflow input. */
+export interface AgentBudget {
+    turnsPerIteration: number;
+    maxIterations: number;
+}
+/** Context passed to a workflow function — facts + observability for this run. */
+export interface WorkflowCtx {
+    run: WorkflowRun;
+    input?: Record<string, unknown>;
+    /** Persist key-value metadata on the run record (e.g. prUrl, planUrl). */
+    setMetadata: (data: Record<string, unknown>) => Promise<void>;
+    /**
+     * Wrap a named step for observability. Emits step_started / step_completed /
+     * step_failed lifecycle events with duration. Use for long phases you want
+     * visible on the run's timeline (setup, external API calls, submit).
+     */
+    step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+}
+/** A workflow is `async (ctx, sandbox) => T`. */
+export type WorkflowFn<T = unknown> = (ctx: WorkflowCtx, sandbox: SandboxProvider) => Promise<T>;
+/**
+ * Declare a workflow with server-side metadata.
+ * Use `export default defineWorkflow({ run, networkPolicy, ... })` to attach
+ * a runner network policy so the server brokers credentials for the workflow
+ * sandbox.
+ *
+ * Without defineWorkflow, a plain `export default async (ctx) => {...}` still
+ * works — the workflow just runs with secrets passed directly in env.
+ */
+export interface WorkflowDefinition<T = unknown> {
+    run: WorkflowFn<T>;
+    /**
+     * Name (or `name@version`) of another workflow whose built snapshot this
+     * workflow's runner boots into. Any workflow registered with `--build`
+     * can be used as a sandbox environment.
+     */
+    sandboxEnvironment?: string;
+    /**
+     * Capture a snapshot of the sandbox on successful /complete. Snapshots are
+     * long-lived (never auto-expire) — customers list + delete them explicitly
+     * via `agentc snapshot list/delete`. Per-invocation `invoke({ snapshot })`
+     * overrides this default. `defineSandboxEnvironment` sugar sets this to
+     * true by default.
+     */
+    snapshot?: boolean;
+    /**
+     * Outbound network policy for the runner sandbox.
+     * Use "*": [] to allow all traffic while still injecting headers for specific domains.
+     * Secret values are referenced as $VARIABLE and resolved from GCP at dispatch time.
+     * Vercel only — E2B ignores.
+     *
+     * @example
+     * networkPolicy: {
+     *   allow: {
+     *     "*": [],
+     *     "api.github.com": [{ transform: [{ headers: { "Authorization": "basic:$GITHUB_TOKEN" } }] }],
+     *   }
+     * }
+     */
+    networkPolicy?: SandboxNetworkPolicy;
+    /**
+     * Optional placeholder env var values for secrets referenced in the network policy.
+     * By default, brokered secrets are removed from the runner env entirely — the real
+     * values are only ever present inside the Vercel firewall config, never in the VM.
+     * Only set this if a tool or SDK validates the env var format on startup before
+     * making any requests (e.g. some CLIs check that ANTHROPIC_API_KEY looks like a
+     * real key). The placeholder is a syntactically valid but non-functional stand-in.
+     *
+     * @example
+     * placeholders: {
+     *   ANTHROPIC_API_KEY: `sk-ant-api03-${"a".repeat(95)}`,
+     * }
+     */
+    placeholders?: Record<string, string>;
+}
+/**
+ * Attach server-side metadata to a workflow function.
+ * The returned function is a valid WorkflowFn with metadata fields attached
+ * for the bundler / registration layer to read.
+ */
+export declare function defineWorkflow<T = unknown>(def: WorkflowDefinition<T>): WorkflowFn<T> & Pick<WorkflowDefinition, "networkPolicy" | "placeholders" | "sandboxEnvironment" | "snapshot">;
+/** Observability-only lifecycle hooks — passed to the workflow engine, not workflow authors. */
+export interface WorkflowHooks {
+    onStepStart?: (step: string) => void;
+    onStepComplete?: (step: string, durationMs: number) => void;
+    onStepFail?: (step: string, durationMs: number, reason: string) => void;
+}

package/dist/utils/bundler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Bundle a workflow for registration.
+ *
+ * Shared between the CLI (agentc register) and tests. Uses `Bun.build`
+ * to bundle TypeScript sources into a self-contained ESM module.
+ *
+ * Post de-broker there are no agent bundles to produce — workflows embed
+ * their agent loops inline via `runAgent(...)`, and workflows invoke other
+ * workflows via the public SDK client.
+ */
+import type { SandboxNetworkPolicy } from "../sandbox.js";
+export interface BundledWorkflow {
+    source: string;
+    networkPolicy?: SandboxNetworkPolicy;
+    placeholders?: Record<string, string>;
+    /** Name (or `name@version`) of another workflow whose built snapshot this
+     *  workflow boots from, if declared via `sandboxEnvironment`. */
+    sandboxEnvironment?: string;
+    /** Default snapshot-on-success flag from the workflow definition, if any. */
+    snapshot?: boolean;
+}
+/** Bundle a workflow from source. */
+export declare function bundleWorkflow(workflowPath: string, overrides?: {
+    networkPolicy?: SandboxNetworkPolicy;
+    placeholders?: Record<string, string>;
+}): Promise<BundledWorkflow>;

package/dist/utils/discovery.d.ts

@@ -0,0 +1,2 @@
+/** Find the runtime name referenced via runtime: "name" in workflow source. */
+export declare function discoverRuntimeName(source: string): string | null;

package/dist/utils/errors.d.ts

@@ -0,0 +1,2 @@
+/** Convert any thrown value to a string message. */
+export declare function formatError(err: unknown): string;

package/dist/utils/schemas.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+/** Zod schema for the AgentStatus block agents emit to signal iteration completion. */
+export declare const AgentStatusSchema: z.ZodObject<{
+    summary: z.ZodString;
+    completed: z.ZodArray<z.ZodString>;
+    blockers: z.ZodArray<z.ZodString>;
+    exit_signal: z.ZodBoolean;
+}, z.core.$strip>;

package/dist/utils/source-loader.d.ts

@@ -0,0 +1,6 @@
+export declare const TMP_DIR: string;
+export declare const LATEST_VERSION = "$LATEST";
+export declare function importSourceModule<T>(source: string, tmpPath: string): Promise<{
+    mod: T;
+    cleanup: () => Promise<void>;
+}>;

package/dist/workflows/engine.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Workflow engine — runs a workflow function with a minimal ctx.
+ *
+ * Post de-broker there is no agent-spawning primitive here. Workflows that
+ * want to embed an LLM agent call `runAgent(opts)` directly from
+ * `@agent-compose/sdk`. Workflows that want to invoke OTHER workflows use
+ * `AgentComposeClient.invoke[AndWait](...)`. The engine's only job now is:
+ *
+ *   - build the `ctx` the workflow function receives
+ *   - funnel `onStepStart / onStepComplete / onStepFail` hooks
+ *   - classify errors into `WorkflowError` vs `EngineError` for the runner
+ *     harness to emit on /fail
+ */
+import type { WorkflowHooks, WorkflowCtx, WorkflowFn } from "../types/workflow.js";
+/**
+ * Thrown from `runWorkflow` when the authored workflow threw.
+ * User-level; not a bug in the platform.
+ */
+export declare class WorkflowError extends Error {
+    readonly kind: "workflow";
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when the runner harness itself cannot run (or finish) a workflow —
+ * bundle missing, max-runtime exceeded, sandbox provider died, secret
+ * resolution broken. Platform-level; investigate us, not the user's code.
+ *
+ * `subsystem` narrows where the failure originated so monitors + dashboards
+ * can break down alerts without string-matching on messages.
+ */
+export type EngineSubsystem = "bundle" | "timeout" | "sandbox" | "dispatch" | "unknown";
+export declare class EngineError extends Error {
+    readonly kind: "engine";
+    readonly subsystem: EngineSubsystem;
+    constructor(message: string, subsystem?: EngineSubsystem, options?: ErrorOptions);
+}
+/** Classify any thrown value into the wire-level `kind` expected by `/fail`. */
+export declare function classifyError(err: unknown): "workflow" | "engine";
+export declare function parseNameVersion(ref: string): {
+    name: string;
+    version: string | undefined;
+};
+export interface WorkflowResult<T = unknown> {
+    /** The value returned by the workflow function. `null` for void workflows. */
+    response: T | null;
+}
+export declare function runWorkflow<T = unknown>(wf: WorkflowFn<T>, ctx: Pick<WorkflowCtx, "run" | "input">, opts?: {
+    hooks?: WorkflowHooks;
+    setMetadata?: (data: Record<string, unknown>) => Promise<void>;
+}): Promise<WorkflowResult<T>>;