@agent-compose/sdk 0.2.1 → 0.2.3

package/src/sandbox.ts

@@ -0,0 +1,458 @@
+/**
+ * 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 { promises as fs } from "node:fs";
+import { dirname } from "node:path";
+import { spawn } from "node:child_process";
+import { Sandbox } from "e2b";
+import { Sandbox as Desktop } from "@e2b/desktop";
+import pRetry from "p-retry";
+import type { SandboxProvider, DesktopSandboxProvider } from "./types/sandbox.js";
+
+export type { SandboxProvider, DesktopSandboxProvider } from "./types/sandbox.js";
+
+// Fleet-wide tag, NOT machine-scoped. Previously we embedded FLY_MACHINE_ID
+// so each replica scoped its own E2B sandboxes at boot, but that made
+// cross-replica orphan reconciliation impossible: when a replica hard-died,
+// its E2B sandboxes became invisible to every surviving replica and stayed
+// running until E2B's own lifetime cap. With a fleet-wide tag the provider
+// reconciler (`listOwned` + DB cross-ref) handles cleanup correctly across
+// all replicas. Boot-time `killAllSandboxes` was deliberately removed when
+// this changed — killing at boot with a shared tag would nuke live sandboxes
+// owned by other replicas.
+export const AGENT_COMPOSE_TAG = process.env.AGENT_COMPOSE_TAG ??
+  `agent-compose-${process.env.AGENT_COMPOSE_ENV ?? "dev"}`;
+
+/** Upper bound for how old a live Vercel sandbox can be: Pro/Enterprise plan
+ *  cap (5h) + 1h slack for clock skew and `extendTimeout()` calls. */
+const VERCEL_VM_LIFETIME_WINDOW_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * 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>;
+}
+
+// ── E2B helpers ───────────────────────────────────────────────────────────────
+
+export function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider {
+  return { sandboxId: sb.sandboxId, commands: sb.commands, files: sb.files, kill: () => sb.kill() };
+}
+
+export function makeDesktopSandboxProvider(sb: Desktop): DesktopSandboxProvider {
+  return {
+    ...makeSandboxProvider(sb),
+    screenshot:  ()           => sb.screenshot() as Promise<Buffer>,
+    leftClick:   (x, y)       => sb.leftClick(x, y),
+    doubleClick: (x, y)       => sb.doubleClick(x, y),
+    rightClick:  (x, y)       => sb.rightClick(x, y),
+    middleClick: (x, y)       => sb.middleClick(x, y),
+    moveMouse:   (x, y)       => sb.moveMouse(x, y),
+    write:       (text)       => sb.write(text),
+    press:       (key)        => sb.press(key),
+    scroll:      (dir, ticks) => sb.scroll(dir, ticks),
+    drag:        (from, to)   => sb.drag(from, to),
+  };
+}
+
+// ── SSE helper (used by broker clients in runner.ts) ─────────────────────────
+
+type SseEvent = { type: string; data?: string; exitCode?: number };
+
+/**
+ * Parse an SSE exec stream from a ReadableStream.
+ * Used by the agent sandbox broker in runner.ts.
+ */
+export async function parseSseExecStream(
+  body: ReadableStream<Uint8Array>,
+  opts?: { onStdout?: (d: string) => void; onStderr?: (d: string) => void },
+): Promise<{ exitCode: number; stdout: string }> {
+  let stdout = "", exitCode = 0, exited = false;
+  const reader = body.getReader(), decoder = new TextDecoder();
+  let buf = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    const lines = buf.replace(/\r\n/g, "\n").split("\n");
+    buf = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.startsWith("data: ")) continue;
+      let event: SseEvent;
+      try { event = JSON.parse(line.slice(6)) as SseEvent; } catch { continue; }
+      if (event.type === "stdout")       { stdout += event.data ?? ""; opts?.onStdout?.(event.data ?? ""); }
+      else if (event.type === "stderr")  { opts?.onStderr?.(event.data ?? ""); }
+      else if (event.type === "exit")    { exitCode = event.exitCode ?? 0; exited = true; }
+      else if (event.type === "error")   { throw new Error(`Sandbox exec error: ${event.data}`); }
+    }
+    // Stop reading as soon as the exit event is received — don't wait for stream close.
+    // QUIC tunnels can delay the stream-end signal even after all data has arrived.
+    if (exited) break;
+  }
+  return { exitCode, stdout };
+}
+
+// ── Vercel helpers ────────────────────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>): SandboxProvider {
+  // Vercel's Sandbox.create({ env }) does NOT flow to runCommand subprocesses — they start fresh shells.
+  // Capture the sandbox-level envs and merge them into every runCommand call so that env vars like
+  // ANTHROPIC_API_KEY (placeholder for network policy injection) are actually visible to subprocesses.
+  const mergeEnvs = (cmdEnvs?: Record<string, string>) =>
+    globalEnvs ? { ...globalEnvs, ...cmdEnvs } : cmdEnvs;
+
+  return {
+    sandboxId: sb.sandboxId,
+    commands: {
+      async run(cmd, opts) {
+        if (opts?.background) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          void (sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true }) as Promise<any>).catch(() => {});
+          return { exitCode: 0, stdout: "" };
+        }
+        const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
+        let stdout = "";
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const handle: any = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal });
+        // Reconnect to the already-running command on transient stream failures (e.g. BrotliDecompressionError).
+        await pRetry(async (attempt) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const h: any = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
+          for await (const log of h.logs()) {
+            if (log.stream === "stdout") { stdout += log.data; opts?.onStdout?.(log.data); }
+            else { opts?.onStderr?.(log.data); }
+          }
+        }, { retries: 3, minTimeout: 1_000, factor: 2 });
+        const finished = await handle.wait();
+        return { exitCode: finished.exitCode, stdout };
+      },
+    },
+    files: {
+      async write(path: string, content: string) {
+        await sb.writeFiles([{ path, content }]);
+      },
+    },
+    // Propagate errors — `killAllRunSandboxes` relies on kill failures being
+    // observable so it can leave `sandbox_id` set for `findOrphanedSandboxes`
+    // to retry on next boot. Swallowing here makes the orphan retry loop blind.
+    async kill() { await sb.stop(); },
+    // Vercel native snapshot — used by sandbox-environments to capture the
+    // configured VM after the customer's `setup()` completes. `expiration: 0`
+    // is Vercel's "never expires" value; env snapshots are long-lived by
+    // design (they ARE the env) so we always pass it.
+    async snapshot() {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const res: any = await sb.snapshot({ expiration: 0 });
+      return { snapshotId: res.snapshotId as string };
+    },
+  };
+}
+
+// ── Local provider (runner's own VM) ──────────────────────────────────────────
+
+/** 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 function makeLocalSandboxProvider(): SandboxProvider {
+  return {
+    sandboxId: "local",
+    commands: {
+      run(cmd, opts) {
+        return new Promise((resolve, reject) => {
+          const proc = spawn("sh", ["-c", cmd], {
+            ...(opts?.cwd ? { cwd: opts.cwd } : {}),
+            env: { ...process.env, ...(opts?.envs ?? {}) },
+            stdio: ["ignore", "pipe", "pipe"],
+          });
+          let stdout = "";
+          proc.stdout?.setEncoding("utf8");
+          proc.stderr?.setEncoding("utf8");
+          proc.stdout?.on("data", (chunk: string) => { stdout += chunk; opts?.onStdout?.(chunk); });
+          proc.stderr?.on("data", (chunk: string) => { opts?.onStderr?.(chunk); });
+          proc.on("error", reject);
+          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout }));
+        });
+      },
+    },
+    files: {
+      async write(path, content) {
+        await fs.mkdir(dirname(path), { recursive: true });
+        await fs.writeFile(path, content);
+      },
+    },
+    async kill() { /* caller IS the sandbox — killing it is the server's job */ },
+  };
+}
+
+// ── Provider registry ─────────────────────────────────────────────────────────
+
+const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
+  "vercel": {
+    requiredEnv: {
+      VERCEL_ACCESS_TOKEN: "Vercel access token — vercel.com/account/tokens",
+      VERCEL_TEAM_ID:      "Vercel team ID — vercel.com/account/settings",
+      VERCEL_PROJECT_ID:   "Vercel project ID — vercel.com/[team]/[project]/settings",
+    },
+    create: async (opts, env) => {
+      // Dynamic import keeps @vercel/sandbox out of runner.bundle.js (runner never calls this path)
+      const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
+      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+      // `template` is a snapshot id (runtime is baked in); absent → fresh node24.
+      const np = opts.networkPolicy;
+      const sb = await VercelSandbox.create(opts.template
+        ? { source: { type: "snapshot" as const, snapshotId: opts.template }, timeout: opts.timeoutMs, env: opts.envs, ...(np ? { networkPolicy: np } : {}), ...creds }
+        : { runtime: "node24" as const, timeout: opts.timeoutMs, env: opts.envs, ...(np ? { networkPolicy: np } : {}), ...creds },
+      );
+      // Pass envs as globalEnvs so they're injected into every runCommand subprocess.
+      // (Vercel's Sandbox.create env parameter does not flow to runCommand subprocesses.)
+      return makeVercelSandboxProvider(sb, opts.envs);
+    },
+    reconnect: async (sandboxId) => {
+      const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
+      const creds = {
+        token:     process.env.VERCEL_ACCESS_TOKEN ?? "",
+        teamId:    process.env.VERCEL_TEAM_ID ?? "",
+        projectId: process.env.VERCEL_PROJECT_ID ?? "",
+      };
+      return makeVercelSandboxProvider(await VercelSandbox.get({ sandboxId, ...creds }));
+    },
+    getActiveCount: async (env) => (await SANDBOX_PROVIDERS.vercel.listOwned!(env)).length,
+    listOwned: async (env) => {
+      const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
+      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+      // Bounds the scan to `VERCEL_VM_LIFETIME_WINDOW_MS` — Pro/Enterprise caps
+      // VM lifetime at 5h, +1h slack for clock skew and `extendTimeout()`.
+      // Without this, projects with thousands of historical terminal sandboxes
+      // page forever (10k+ in v0.6.28). Truncating silently would hide orphans,
+      // so we throw at the 50-page cap instead. Each page is wrapped in pRetry
+      // so a transient 5xx/429/network blip doesn't cost a reconcile tick.
+      const since = Date.now() - VERCEL_VM_LIFETIME_WINDOW_MS;
+      const out: OwnedSandbox[] = [];
+      let until: number | undefined;
+      for (let page = 0; page < 50; page++) {
+        const { json } = await pRetry(
+          () => VercelSandbox.list({ ...creds, limit: 200, since, ...(until !== undefined ? { until } : {}) }),
+          { retries: 3, minTimeout: 500, factor: 2 },
+        );
+        for (const sb of json.sandboxes) if (sb.status === "running") {
+          out.push({ sandboxId: sb.id, createdAt: new Date(sb.createdAt), metadata: {} });
+        }
+        if (json.pagination.next === null) return out;
+        until = json.pagination.next;
+      }
+      throw new Error("Vercel listSandboxes exceeded 50 pages within the lifetime window — refuse to silently truncate");
+    },
+    deleteSnapshot: async (snapshotId, env) => {
+      const { Snapshot } = await import("@vercel/sandbox");
+      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+      const snap = await Snapshot.get({ snapshotId, ...creds });
+      await snap.delete();
+    },
+  },
+  "e2b": {
+    requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
+    create: async ({ template, ...sandboxOpts }) => {
+      if (!template) throw new Error("E2B provider requires an explicit `template` (Dockerfile-based — no default base image)");
+      return makeSandboxProvider(await Sandbox.create(template, sandboxOpts));
+    },
+    reconnect: async (sandboxId) => makeSandboxProvider(
+      await Sandbox.connect(sandboxId, { apiKey: process.env.E2B_API_KEY ?? "", timeoutMs: 60 * 60 * 1000 }),
+    ),
+    killAll: async () => {
+      const paginator = Sandbox.list({ query: { metadata: { executor: AGENT_COMPOSE_TAG } } });
+      const sandboxes = [];
+      while (paginator.hasNext) sandboxes.push(...await paginator.nextItems());
+      if (sandboxes.length === 0) return;
+      await Promise.all(sandboxes.map(s => Sandbox.kill(s.sandboxId).catch(() => {})));
+      console.info(`[sandbox] killed ${sandboxes.length} stale E2B sandboxes (tag: ${AGENT_COMPOSE_TAG})`);
+    },
+    getActiveCount: async () => (await SANDBOX_PROVIDERS.e2b.listOwned!({})).length,
+    listOwned: async () => {
+      const paginator = Sandbox.list({ query: { metadata: { executor: AGENT_COMPOSE_TAG }, state: ["running"] } });
+      const out: OwnedSandbox[] = [];
+      while (paginator.hasNext) {
+        const items = await pRetry(() => paginator.nextItems(), { retries: 3, minTimeout: 500, factor: 2 });
+        for (const sb of items) {
+          out.push({
+            sandboxId: sb.sandboxId,
+            createdAt: new Date(sb.startedAt),
+            metadata:  sb.metadata ?? {},
+          });
+        }
+      }
+      return out;
+    },
+  },
+  "e2b-desktop": {
+    requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
+    create: async ({ template, ...sandboxOpts }) => {
+      if (!template) throw new Error("E2B Desktop provider requires an explicit `template` (Dockerfile-based — no default base image)");
+      return makeDesktopSandboxProvider(await Desktop.create(template, sandboxOpts));
+    },
+  },
+};
+
+/** Provision a sandbox for the named provider. */
+export async function createSandbox(provider: string, opts: SandboxCreateOpts): Promise<SandboxProvider> {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def) throw new Error(`Unknown sandbox provider: "${provider}". Known: ${Object.keys(SANDBOX_PROVIDERS).join(", ")}`);
+  const missing = Object.entries(def.requiredEnv)
+    .filter(([key]) => !process.env[key])
+    .map(([key, desc]) => `  ${key}  — ${desc}`);
+  if (missing.length > 0) throw new Error(`Sandbox provider "${provider}" requires env vars:\n${missing.join("\n")}`);
+  return def.create(opts, Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!])));
+}
+
+/** Reconnect to an existing sandbox by provider + provider-native sandbox ID. */
+export async function reconnectSandbox(provider: string, sandboxId: string): Promise<SandboxProvider> {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.reconnect) throw new Error(`Provider "${provider}" does not support reconnect`);
+  return def.reconnect(sandboxId);
+}
+
+/** Delete a snapshot by id on the named provider. No live sandbox needed. */
+export async function deleteSandboxSnapshot(provider: string, snapshotId: string): Promise<void> {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.deleteSnapshot) throw new Error(`Provider "${provider}" does not support deleteSnapshot`);
+  const missing = Object.entries(def.requiredEnv)
+    .filter(([k]) => !process.env[k])
+    .map(([k, desc]) => `  ${k} — ${desc}`);
+  if (missing.length > 0) throw new Error(`Sandbox provider "${provider}" requires env vars:\n${missing.join("\n")}`);
+  return def.deleteSnapshot(snapshotId, Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!])));
+}
+
+/**
+ * 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 async function getSandboxQuotas(): Promise<Record<string, number | Error>> {
+  const out: Record<string, number | Error> = {};
+  await Promise.all(
+    Object.entries(SANDBOX_PROVIDERS).map(async ([name, def]) => {
+      if (!def.getActiveCount) return;
+      if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return;
+      const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!]));
+      try { out[name] = await def.getActiveCount(env); }
+      catch (err) { out[name] = err instanceof Error ? err : new Error(String(err)); }
+    }),
+  );
+  return out;
+}
+
+/**
+ * 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 async function listOwnedSandboxes(): Promise<Record<string, OwnedSandbox[] | Error>> {
+  const out: Record<string, OwnedSandbox[] | Error> = {};
+  await Promise.all(
+    Object.entries(SANDBOX_PROVIDERS).map(async ([name, def]) => {
+      if (!def.listOwned) return;
+      if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return;
+      const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!]));
+      try { out[name] = await def.listOwned(env); }
+      catch (err) { out[name] = err instanceof Error ? err : new Error(String(err)); }
+    }),
+  );
+  return out;
+}
+
+/** Kill a sandbox by provider + native ID. Used by the orphan reconciler. */
+export async function killSandboxById(provider: string, sandboxId: string): Promise<void> {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.reconnect) throw new Error(`Provider "${provider}" does not support reconnect (required for kill-by-id)`);
+  const sb = await def.reconnect(sandboxId);
+  await sb.kill();
+}
+
+/** Kill all sandboxes across all registered providers. Call at startup to clean up after crashes. */
+export async function killAllSandboxes(
+  onError?: (provider: string, err: unknown) => void,
+): Promise<void> {
+  await Promise.allSettled(
+    Object.entries(SANDBOX_PROVIDERS)
+      .filter(([, def]) => def.killAll)
+      .map(([name, def]) => {
+        const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k] ?? ""]));
+        if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return Promise.resolve();
+        return def.killAll!(env).catch(err => onError?.(name, err));
+      }),
+  );
+}
+
+export { SANDBOX_PROVIDERS };

package/src/sse.ts

@@ -0,0 +1,56 @@
+/**
+ * Generic Server-Sent Events (SSE) parser.
+ *
+ * Consumes a `ReadableStream<Uint8Array>` and yields parsed events one at a
+ * time. Each event carries:
+ *   - `id`:    numeric (from `id:` line; `0` if absent)
+ *   - `event`: event name (from `event:` line; `""` if absent)
+ *   - `data`:  parsed JSON payload (the SDK's stream events are always JSON)
+ *
+ * Malformed payloads are silently skipped — same behaviour as the previous
+ * CLI-side parser. Caller drives the loop via `for await (...)` and is
+ * responsible for breaking on terminal events.
+ *
+ * Output type stays loose (`Record<string, unknown>`) on purpose: typed
+ * unions like `RunEvent` aren't structurally narrowable from
+ * `Record<string, unknown>`, so callers that want a discriminated union
+ * cast at the consumption site (see `streamRunLogs`). Keeping the parser
+ * payload-agnostic also means it's reusable for future SSE endpoints with
+ * different shapes.
+ */
+export async function* parseSseStream(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<{ id: number; event: string; data: Record<string, unknown> }> {
+  const reader  = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let event  = "";
+  let seq    = 0;
+  let dataLines: string[] = [];
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (line.startsWith("id:"))    { seq   = Number(line.slice(3).trim()); continue; }
+        if (line.startsWith("event:")) { event = line.slice(6).trim();         continue; }
+        if (line.startsWith("data:"))  { dataLines.push(line.slice(5).trim()); continue; }
+        if (line === "" && dataLines.length > 0) {
+          try {
+            const data = JSON.parse(dataLines.join("\n")) as Record<string, unknown>;
+            yield { id: seq, event, data };
+          } catch { /* malformed — skip */ }
+          event = ""; seq = 0; dataLines = [];
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/types/events.ts

@@ -0,0 +1,51 @@
+/**
+ * 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;  // truncated key info: Bash command, file path, URL
+      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: "run_canceled";    runId: string; at: number; seq?: number }
+  | { event: "workflow_log";    runId: string; at: number; seq?: number; level: "info" | "warn" | "error"; msg: string };

package/src/types/protocol.ts

@@ -0,0 +1,74 @@
+/**
+ * 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;
+}