@agent-compose/sdk 0.2.1 → 0.2.2

package/src/types/runtime.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 function defineRuntime<S extends SandboxProvider = SandboxProvider>(
+  pkg: AgentRuntime<S>,
+): AgentRuntime<S> {
+  if (typeof pkg.create !== "function") throw new Error("defineRuntime: 'create' is required");
+  return pkg;
+}

package/src/types/sandbox-environment.ts

@@ -0,0 +1,64 @@
+/**
+ * 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. Capture is **opt-in**: the wrapper below sets `saveSnapshot: true`
+ * by default (opt out with `saveSnapshot: false` if you only want side
+ * effects).
+ *
+ * Once captured, reference the snapshot from another workflow's `snapshot`
+ * field by run UUID, workflow name, or `name@version`:
+ *
+ *     snapshot: "my-setup"          // most recent successful snapshot
+ *     snapshot: "my-setup@v1"       // version-scoped recency
+ *     snapshot: "<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 `snapshot: "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 { makeLocalSandboxProvider } from "../sandbox.js";
+import { defineWorkflow } from "./workflow.js";
+import type { WorkflowFn } from "./workflow.js";
+
+export interface SandboxEnvironmentDefinition {
+  name: string;
+  description?: string;
+  setup: (sb: SandboxProvider) => Promise<void>;
+  /** Override the sugar's `saveSnapshot: true` default. Set `false` to opt
+   *  out of snapshot capture (rarely useful — an env with no snapshot can't
+   *  be referenced as the `snapshot` field on another workflow). */
+  saveSnapshot?: boolean;
+}
+
+export function defineSandboxEnvironment(
+  env: SandboxEnvironmentDefinition,
+): WorkflowFn<void> {
+  if (typeof env.setup !== "function") {
+    throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
+  }
+  return defineWorkflow({
+    saveSnapshot: env.saveSnapshot ?? true,
+    run: () => env.setup(makeLocalSandboxProvider()),
+  });
+}

package/src/types/sandbox.ts

@@ -0,0 +1,51 @@
+/**
+ * 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/src/types/workflow.ts

@@ -0,0 +1,128 @@
+/**
+ * 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>;
+  /**
+   * Reference to a snapshot the runner should boot from at run start.
+   * Accepts a run UUID, a workflow name, or `name@version` — any workflow
+   * registered with `--build` produces a snapshot you can name here. The
+   * runner VM starts in that pre-configured state. Per-invocation
+   * `invoke({ snapshot })` overrides this default.
+   */
+  snapshot?: 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({ saveSnapshot })` overrides this default.
+   * `defineSandboxEnvironment` sugar sets this to true by default.
+   */
+  saveSnapshot?: 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 function defineWorkflow<T = unknown>(
+  def: WorkflowDefinition<T>,
+): WorkflowFn<T> & Pick<WorkflowDefinition, "networkPolicy" | "placeholders" | "snapshot" | "saveSnapshot"> {
+  return Object.assign(def.run, {
+    networkPolicy: def.networkPolicy,
+    placeholders:  def.placeholders,
+    snapshot:      def.snapshot,
+    saveSnapshot:  def.saveSnapshot,
+  });
+}
+
+/** 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/src/utils/bundler.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 { importSourceModule } from "./source-loader.js";
+import type { WorkflowFn, WorkflowDefinition } from "../types/workflow.js";
+import type { SandboxNetworkPolicy } from "../sandbox.js";
+
+export interface BundledWorkflow {
+  source: string;
+  networkPolicy?: SandboxNetworkPolicy;
+  placeholders?: Record<string, string>;
+  /** Run UUID, workflow name, or `name@version` referencing the snapshot
+   *  this workflow's runner boots from, if declared via the `snapshot`
+   *  field on `defineWorkflow`. */
+  snapshot?: string;
+  /** Default capture-on-success flag from the workflow definition. */
+  saveSnapshot?: boolean;
+}
+
+async function bundle(path: string, label: string): Promise<string> {
+  // Use globalThis to access Bun without a compile-time dependency on @types/bun.
+  const bun = globalThis as unknown as { Bun?: { build(opts: { entrypoints: string[]; format: string; target: string }): Promise<{ success: boolean; outputs: { text(): Promise<string> }[]; logs: { message: string }[] }> } };
+  if (!bun.Bun?.build) throw new Error("bundleWorkflow requires the Bun runtime (Bun.build)");
+  const result = await bun.Bun.build({ entrypoints: [path], format: "esm", target: "bun" });
+  if (!result.success) {
+    throw new Error(`Failed to bundle ${label}:\n${result.logs.map((l) => l.message).join("\n")}`);
+  }
+  return result.outputs[0].text();
+}
+
+/** Dynamically import a bundled source in-process and extract fields from its
+ *  default export. Safe for CLI/test contexts. Returns `undefined` on
+ *  resolver failure (missing deps) so callers fall through. */
+async function extractFromBundle<T>(
+  source: string,
+  label: string,
+  pick: (defaultExport: unknown) => T | undefined,
+): Promise<T | undefined> {
+  const tmpPath = `/tmp/agentc-${label}-${Date.now()}-${Math.random().toString(36).slice(2)}.js`;
+  try {
+    const loaded = await importSourceModule<Record<string, unknown>>(source, tmpPath);
+    try { return pick(loaded.mod.default); }
+    finally { await loaded.cleanup(); }
+  } catch { return undefined; }
+}
+
+/** Bundle a workflow from source. */
+export async function bundleWorkflow(
+  workflowPath: string,
+  overrides?: { networkPolicy?: SandboxNetworkPolicy; placeholders?: Record<string, string> },
+): Promise<BundledWorkflow> {
+  const source = await bundle(workflowPath, `workflow "${workflowPath}"`);
+
+  type Wf = WorkflowFn & Pick<WorkflowDefinition, "networkPolicy" | "placeholders" | "snapshot" | "saveSnapshot">;
+  const wfBits = await extractFromBundle<Pick<Wf, "networkPolicy" | "placeholders" | "snapshot" | "saveSnapshot">>(
+    source, "workflow",
+    (wf) => wf ? {
+      networkPolicy: (wf as Wf).networkPolicy,
+      placeholders:  (wf as Wf).placeholders,
+      snapshot:      (wf as Wf).snapshot,
+      saveSnapshot:  (wf as Wf).saveSnapshot,
+    } : undefined,
+  );
+  const { networkPolicy, placeholders, snapshot, saveSnapshot } = wfBits ?? {};
+
+  return {
+    source,
+    networkPolicy: overrides?.networkPolicy ?? networkPolicy,
+    placeholders:  overrides?.placeholders  ?? placeholders,
+    ...(snapshot     !== undefined ? { snapshot }     : {}),
+    ...(saveSnapshot !== undefined ? { saveSnapshot } : {}),
+  };
+}

package/src/utils/discovery.ts

@@ -0,0 +1,4 @@
+/** Find the runtime name referenced via runtime: "name" in workflow source. */
+export function discoverRuntimeName(source: string): string | null {
+  return source.match(/runtime:\s*["']([^"']+)["']/)?.[1] ?? null;
+}

package/src/utils/errors.ts

@@ -0,0 +1,4 @@
+/** Convert any thrown value to a string message. */
+export function formatError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/utils/schemas.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { AgentStatus } from "../types/protocol.js";
+
+/** Zod schema for the AgentStatus block agents emit to signal iteration completion. */
+export const AgentStatusSchema = z.object({
+  summary:      z.string(),
+  completed:    z.array(z.string()),
+  blockers:     z.array(z.string()),
+  exit_signal:  z.boolean(),
+}) satisfies z.ZodType<AgentStatus>;

package/src/utils/source-loader.ts

@@ -0,0 +1,16 @@
+import { dirname } from "path";
+import { writeFile, unlink, mkdir } from "node:fs/promises";
+
+export const TMP_DIR       = process.env.TMP_DIR ?? "/tmp/agent-compose";
+export const LATEST_VERSION = "$LATEST";
+
+export async function importSourceModule<T>(
+  source: string,
+  tmpPath: string,
+): Promise<{ mod: T; cleanup: () => Promise<void> }> {
+  await mkdir(dirname(tmpPath), { recursive: true });
+  await writeFile(tmpPath, source, "utf8");
+  const mod     = await import(tmpPath) as T;
+  const cleanup = () => unlink(tmpPath).catch(() => {});
+  return { mod, cleanup };
+}

package/src/workflows/engine.ts

@@ -0,0 +1,110 @@
+/**
+ * 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";
+import { makeLocalSandboxProvider } from "../sandbox.js";
+import { formatError } from "../utils/errors.js";
+
+// ── Error classification ─────────────────────────────────────────────────────
+
+/**
+ * Thrown from `runWorkflow` when the authored workflow threw.
+ * User-level; not a bug in the platform.
+ */
+export class WorkflowError extends Error {
+  readonly kind = "workflow" as const;
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "WorkflowError";
+  }
+}
+
+/**
+ * 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 class EngineError extends Error {
+  readonly kind = "engine" as const;
+  readonly subsystem: EngineSubsystem;
+  constructor(message: string, subsystem: EngineSubsystem = "unknown", options?: ErrorOptions) {
+    super(message, options);
+    this.name = "EngineError";
+    this.subsystem = subsystem;
+  }
+}
+
+/** Classify any thrown value into the wire-level `kind` expected by `/fail`. */
+export function classifyError(err: unknown): "workflow" | "engine" {
+  if (err instanceof WorkflowError) return "workflow";
+  if (err instanceof EngineError)   return "engine";
+  // Anything uncategorised defaults to engine — safer to over-alert on our
+  // side than miss a real infra issue that escaped the typed catch.
+  return "engine";
+}
+
+export function parseNameVersion(ref: string): { name: string; version: string | undefined } {
+  const atIdx = ref.lastIndexOf("@");
+  return atIdx > 0 ? { name: ref.slice(0, atIdx), version: ref.slice(atIdx + 1) } : { name: ref, version: undefined };
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+export interface WorkflowResult<T = unknown> {
+  /** The value returned by the workflow function. `null` for void workflows. */
+  response: T | null;
+}
+
+export async 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>> {
+  const hooks = opts?.hooks ?? {};
+  const setMetadata = opts?.setMetadata ?? (async () => {});
+  // Single SandboxProvider for the whole run — handed to the workflow as
+  // its second positional arg. Stateless wrapper over child_process.spawn
+  // + fs.writeFile, so reuse is purely a matter of shape consistency.
+  const sandbox = makeLocalSandboxProvider();
+
+  let workflowErr: unknown;
+  let wfOutput: unknown;
+  try {
+    wfOutput = await wf(
+      {
+        ...ctx,
+        setMetadata,
+        step: async <S>(name: string, fn: () => Promise<S>): Promise<S> => {
+          const startedAt = Date.now();
+          hooks.onStepStart?.(name);
+          try   { const r = await fn(); hooks.onStepComplete?.(name, Date.now() - startedAt); return r; }
+          catch (err) { hooks.onStepFail?.(name, Date.now() - startedAt, formatError(err)); throw err; }
+        },
+      },
+      sandbox,
+    );
+  } catch (err) {
+    workflowErr = err;
+  }
+
+  if (workflowErr !== undefined) {
+    if (workflowErr instanceof WorkflowError) throw workflowErr;
+    throw new WorkflowError(formatError(workflowErr), { cause: workflowErr });
+  }
+  return { response: (wfOutput ?? null) as T | null };
+}