@agent-compose/sdk 0.2.0 → 0.2.2

package/src/agent/run-agent.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 { agentLoop } from "./agent-loop.js";
+import type { AgentLoopResult } from "./agent-loop.js";
+import type { AgentMessage, AgentStatus } from "../types/protocol.js";
+import type { AgentRuntime, RuntimeOptions } from "../types/runtime.js";
+import type { SandboxProvider } from "../types/sandbox.js";
+import type { AgentBudget } from "../types/workflow.js";
+import PROTOCOL_SUFFIX_RAW from "./protocol-suffix.md" with { type: "text" };
+
+const PROTOCOL_SUFFIX = stripFrontmatter(PROTOCOL_SUFFIX_RAW);
+
+function stripFrontmatter(content: string): string {
+  if (!content.startsWith("---")) return content;
+  const end = content.indexOf("\n---", 3);
+  return end === -1 ? content : content.slice(end + 4).trimStart();
+}
+
+function inject(template: string, vars: Record<string, string>): string {
+  return Object.entries(vars).reduce((t, [k, v]) => t.replaceAll(`{{${k}}}`, v), template);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function zodTypeName(schema: any): string {
+  if (schema instanceof z.ZodString)   return "string";
+  if (schema instanceof z.ZodNumber)   return "number";
+  if (schema instanceof z.ZodBoolean)  return "boolean";
+  if (schema instanceof z.ZodArray)    return `${zodTypeName(schema.element)}[]`;
+  if (schema instanceof z.ZodEnum)     return (schema.options as string[]).map((o: string) => `"${o}"`).join(" | ");
+  if (schema instanceof z.ZodOptional) return `${zodTypeName(schema.unwrap())} (optional)`;
+  if (schema instanceof z.ZodNullable) return `${zodTypeName(schema.unwrap())} | null`;
+  if (schema instanceof z.ZodLiteral)  return `"${String(schema.value)}"`;
+  if (schema instanceof z.ZodObject)   return "object";
+  return "any";
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function buildResponseFormatAppendix(schema: z.ZodType<any>): string {
+  const header = ["## Response Format", "", "When you emit `exit_signal: true` in your `<status>` block, also include a `<response>` block containing JSON immediately after `<status>`:", ""];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const shape: Record<string, any> | null =
+    schema instanceof z.ZodObject ? (schema as z.ZodObject<z.ZodRawShape>).shape : null;
+  const body = shape
+    ? (() => {
+      const entries = Object.entries(shape);
+      const example = Object.fromEntries(entries.map(([k, v]) => [k, `<${zodTypeName(v)}>`]));
+      return [
+        "Fields:",
+        ...entries.map(([k, v]) => `- \`${k}\` (${zodTypeName(v)})`),
+        "", "Example:", "<response>",
+        JSON.stringify(example, null, 2),
+        "</response>",
+      ];
+    })()
+    : [
+      "The response must match this schema:",
+      `Expected type: ${zodTypeName(schema)}`,
+      "", "Example:", "<response>",
+      `<${zodTypeName(schema)}>`,
+      "</response>",
+    ];
+  return [...header, ...body].join("\n");
+}
+
+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 async function runAgent<T = unknown>(opts: RunAgentOpts<T>): Promise<AgentLoopResult> {
+  const workingDir = opts.workingDir ?? "";
+  const promptVars = { WORKING_DIR: workingDir, DIFF_BASE: "HEAD~1", ...opts.promptVars };
+
+  return agentLoop({
+    runtime: (runtimeOpts: RuntimeOptions) => opts.runtime.create(opts.sandbox, runtimeOpts),
+    ...(opts.label !== undefined ? { label: opts.label } : {}),
+    ...(opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {}),
+    ...(opts.budget?.maxIterations     !== undefined ? { maxIterations:     opts.budget.maxIterations }     : {}),
+    ...(opts.tools                      !== undefined ? { allowedTools:      opts.tools }                    : {}),
+    ...(opts.responseSchema             !== undefined ? { responseSchema:    opts.responseSchema }           : {}),
+    ...(workingDir                                     ? { cwd: workingDir }                                 : {}),
+    buildPrompt: (_lastStatus, iteration) => {
+      // Mid-loop: session resumes via --resume, model has history; only the
+      // protocol suffix is needed so tool-use + status block grammar stays fresh.
+      if (iteration > 0) return PROTOCOL_SUFFIX;
+      const base = inject(stripFrontmatter(opts.prompt), promptVars);
+      return opts.responseSchema
+        ? `${base}\n\n${PROTOCOL_SUFFIX}\n\n${buildResponseFormatAppendix(opts.responseSchema)}`
+        : `${base}\n\n${PROTOCOL_SUFFIX}`;
+    },
+    ...(opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {}),
+    ...(opts.onIteration  ? { onIteration:  opts.onIteration  } : {}),
+  });
+}

package/src/client.ts

@@ -0,0 +1,446 @@
+/**
+ * AgentComposeClient — HTTP client for the agent-compose server API.
+ *
+ * Templates always live inside a factory (project). Methods that touch a
+ * specific template (`register`, `invoke`, `setSecret`, `listSecrets`,
+ * `deleteSecret`) take an optional `factorySlug`; when omitted, they target
+ * the team's auto-created `default` factory. There is no second URL space
+ * for "templates without a factory" — every workflow belongs to exactly one.
+ *
+ * `register()` accepts pre-built sources — use the CLI (`agent-compose
+ * register`) or build sources yourself and pass them directly.
+ */
+
+import { ofetch } from "ofetch";
+import { AgentComposeError } from "./errors.js";
+import { parseSseStream } from "./sse.js";
+import type { RunEvent } from "./types/events.js";
+import type { SandboxNetworkPolicy } from "./sandbox.js";
+
+/** UUID-v4-ish — matches the server-side predicate. Used to auto-detect
+ *  that `process.env.RUN_ID` was injected by the runner sandbox (rather
+ *  than being set by accident), so we only propagate it when it looks real. */
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Default factory slug — every team gets one auto-created at sign-up.
+ *  Methods that don't take an explicit `factorySlug` resolve to this. */
+const DEFAULT_FACTORY = "default";
+
+/** Read-once cached parentRunId from `process.env.RUN_ID` at module load.
+ *  `null` if unset or malformed. Exported so tests can override-and-reset. */
+function detectAmbientParentRunId(): string | null {
+  const envRunId = (typeof process !== "undefined" ? process.env?.RUN_ID : undefined);
+  return envRunId && UUID_REGEX.test(envRunId) ? envRunId : null;
+}
+
+/** Build the `/api/v1/factories/:slug/templates/...` prefix. Slug + name are
+ *  URL-encoded as defense-in-depth: today's server-side patterns
+ *  (`^[a-z][a-z0-9-]*$`) can't produce reserved characters, but a future
+ *  relaxation would otherwise quietly become an injection vector. */
+function templatePath(factorySlug: string, ...rest: string[]): string {
+  const tail = rest.length > 0
+    ? "/" + rest.map(encodeURIComponent).join("/")
+    : "";
+  return `/api/v1/factories/${encodeURIComponent(factorySlug)}/templates${tail}`;
+}
+
+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" | "canceled";
+  output?: Record<string, unknown>;
+}
+
+/** Row shape returned by `GET /api-keys`. */
+export interface ApiKey {
+  object:           "api_key";
+  id:               string;
+  name:             string | null;
+  last4:            string | null;
+  scopes:           string[];
+  teamId:           string;
+  createdByUserId:  string | null;
+  /** Non-null when the key is restricted to a single factory. */
+  factoryId:        string | null;
+  createdAt:        string;
+  expiresAt:        string | null;
+  lastUsedAt:       string | null;
+  revokedAt:        string | null;
+}
+
+/** Response from `POST /api-keys`. The `key` field is the plaintext token —
+ *  shown once at creation, never retrievable again. */
+export interface ApiKeyCreated extends ApiKey { key: string }
+
+/** Single rollup row from `GET /api/v1/usage`. */
+export interface UsageRollupRow {
+  eventType: string;
+  unit:      string;
+  total:     number;
+  tags:      Record<string, unknown>;
+}
+
+/** Response from `GET /api/v1/usage`. */
+export interface UsageResponse {
+  object:   "list";
+  data:     UsageRollupRow[];
+  has_more: boolean;
+  from:     string | null;
+  to:       string | null;
+}
+
+/** Response from `POST /api/v1/workflows/:id/cancel`. The endpoint is
+ *  idempotent: cancelling a run that's already terminal returns its current
+ *  outcome verbatim (rather than throwing or pretending it just canceled),
+ *  so `status` widens to every terminal value the server might surface. */
+export interface CancelRunResponse {
+  runId:       string;
+  status:      "canceled" | "success" | "failed" | "abandoned";
+  canceledAt:  string;
+}
+
+export interface SnapshotListEntry {
+  runId: string;
+  workflow: string | null;
+  version: string | null;
+  vercelSnapshotId: string;
+  endedAt: string | null;
+}
+
+export class AgentComposeClient {
+  private readonly fetch:   typeof ofetch;
+  private readonly baseUrl: string;
+  private readonly apiKey:  string;
+
+  constructor(baseUrl: string, apiKey: string) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey  = apiKey;
+    this.fetch = ofetch.create({
+      baseURL: this.baseUrl,
+      headers: { Authorization: `Bearer ${apiKey}` },
+      async onResponseError({ response }) {
+        const body = response._data as { error?: string } | undefined;
+        throw new AgentComposeError(response.status, body?.error ?? response.statusText);
+      },
+    });
+  }
+
+  /** Register (or update) a workflow template inside a factory. Defaults to
+   *  the team's `default` factory when `factorySlug` is omitted. */
+  register(payload: {
+    name: string;
+    source: string;
+    version?: string;
+    schedule?: string;
+    runtimes?: Array<{ name: string; source: string }>;
+    networkPolicy?: unknown;
+    placeholders?: Record<string, string>;
+    /** Reference to a snapshot the runner should boot from at run start.
+     *  A run UUID, workflow name, or `name@version`. The referenced
+     *  workflow must have been registered with `--build` (or any prior
+     *  successful run with `saveSnapshot: true`). Per-invocation
+     *  `invoke({ snapshot })` overrides this default. */
+    snapshot?: string;
+    /** If true, runs default to capturing a long-lived sandbox snapshot on
+     *  success. Individual invocations can override via
+     *  `invoke(..., { saveSnapshot })`. */
+    saveSnapshot?: boolean;
+    /** Factory slug. Defaults to `"default"`. */
+    factorySlug?: string;
+  }): Promise<RegisterResult> {
+    const { factorySlug = DEFAULT_FACTORY, ...body } = payload;
+    return this.fetch(templatePath(factorySlug), { method: "POST", body });
+  }
+
+  /** Invoke a workflow. Returns run ID immediately — workflow runs asynchronously.
+   *
+   *  `snapshot`: per-invocation override of the template-level `snapshot`
+   *  field. Same forms — a run UUID, a workflow name, or `name@version`.
+   *  Use this when one template needs to boot from many different
+   *  snapshots (e.g. a benchmark workflow running against a different
+   *  starting state per invocation). Does not change the template's
+   *  registered default; only affects this run.
+   *
+   *  `saveSnapshot`: `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 the `snapshot` field on 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.
+   *
+   *  `factorySlug`: defaults to `"default"`. */
+  invoke(
+    name: string,
+    input?: Record<string, unknown>,
+    opts?: {
+      snapshot?:     string;
+      saveSnapshot?: boolean;
+      parentRunId?:  string | null;
+      factorySlug?:  string;
+      networkPolicy?: SandboxNetworkPolicy;
+      placeholders?: Record<string, string>;
+    },
+  ): Promise<{ id: string }> {
+    const parentRunId = opts?.parentRunId === undefined
+      ? detectAmbientParentRunId()
+      : opts.parentRunId;
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(templatePath(factorySlug, name, "invoke"), {
+      method: "POST",
+      body: {
+        input,
+        ...(opts?.snapshot     !== undefined ? { snapshot:     opts.snapshot }     : {}),
+        ...(opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {}),
+        ...(parentRunId                      ? { parentRunId }                     : {}),
+        ...(opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {}),
+        ...(opts?.placeholders  !== undefined ? { placeholders:  opts.placeholders }  : {}),
+      },
+    });
+  }
+
+  /** 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. */
+  async invokeAndWait(
+    name: string,
+    input?: Record<string, unknown>,
+    opts?: {
+      snapshot?:       string;
+      saveSnapshot?:   boolean;
+      parentRunId?:    string | null;
+      factorySlug?:    string;
+      networkPolicy?:  SandboxNetworkPolicy;
+      placeholders?:   Record<string, string>;
+      timeoutMs?:      number;
+      pollIntervalMs?: number;
+    },
+  ): Promise<RunStatus> {
+    const timeoutMs = opts?.timeoutMs ?? 30 * 60 * 1000;
+    const pollMs    = opts?.pollIntervalMs ?? 1000;
+    const { id: runId } = await this.invoke(name, input, {
+      ...(opts?.snapshot     !== undefined ? { snapshot:     opts.snapshot }     : {}),
+      ...(opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {}),
+      ...(opts?.parentRunId  !== undefined ? { parentRunId:  opts.parentRunId }  : {}),
+      ...(opts?.factorySlug  !== undefined ? { factorySlug:  opts.factorySlug }  : {}),
+      ...(opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {}),
+      ...(opts?.placeholders  !== undefined ? { placeholders:  opts.placeholders }  : {}),
+    });
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const status = await this.getStatus(runId);
+      if (status.status === "success" || status.status === "failed" || status.status === "abandoned") {
+        return status;
+      }
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+    // Use AgentComposeError (not plain Error) so catch-blocks handling SDK
+    // transport failures also handle timeouts uniformly. HTTP 504 is the
+    // closest idiomatic status for "upstream didn't answer in time."
+    throw new AgentComposeError(504, `invokeAndWait: run ${runId} did not settle within ${timeoutMs}ms`);
+  }
+
+  /** List runs this account has captured snapshots for. */
+  async listSnapshots(opts?: { workflow?: string; limit?: number }): Promise<SnapshotListEntry[]> {
+    const q = new URLSearchParams();
+    if (opts?.workflow) q.set("workflow", opts.workflow);
+    if (opts?.limit    != null) q.set("limit", String(opts.limit));
+    const body = await this.fetch<{ object: "list"; data: SnapshotListEntry[]; has_more: boolean }>(
+      `/api/v1/snapshots${q.toString() ? `?${q}` : ""}`,
+    );
+    return body.data;
+  }
+
+  /** Delete the snapshot captured by a specific run. Frees Vercel storage. */
+  deleteSnapshot(runId: string): Promise<void> {
+    return this.fetch(`/api/v1/workflows/${runId}/snapshot`, { method: "DELETE" });
+  }
+
+  /** Poll run status. */
+  getStatus(runId: string): Promise<RunStatus> {
+    return this.fetch(`/api/v1/workflows/${runId}/status`);
+  }
+
+  /** List registered workflow templates. When `factorySlug` is supplied,
+   *  scopes to that factory; otherwise returns every template the team can
+   *  see across every factory in one round trip — each row carries its
+   *  `factorySlug` so callers can route per-template actions to the right
+   *  factory. */
+  async listTemplates(opts?: { factorySlug?: string }): Promise<Array<{ name: string; version: string; factorySlug: string }>> {
+    const path = opts?.factorySlug
+      ? templatePath(opts.factorySlug)
+      : "/api/v1/templates";
+    const body = await this.fetch<{ templates: Array<{ name: string; version: string; factorySlug: string }> }>(path);
+    return body.templates;
+  }
+
+  // ── Factories ──────────────────────────────────────────────────────────────
+  // Projects within a team. Workflows + secrets belong to exactly one factory.
+
+  /** List factories for the caller's team. */
+  async listFactories(): Promise<FactoryRow[]> {
+    const body = await this.fetch<{ factories: FactoryRow[] }>("/api/v1/factories");
+    return body.factories;
+  }
+
+  /** Create a factory. `slug` must be lowercase kebab-case and unique
+   *  within the team. */
+  createFactory(payload: { slug: string; name: string; description?: string }): Promise<FactoryRow> {
+    return this.fetch<FactoryRow>("/api/v1/factories", { method: "POST", body: payload });
+  }
+
+  /** Get a factory by slug. */
+  getFactory(slug: string): Promise<FactoryRow> {
+    return this.fetch<FactoryRow>(`/api/v1/factories/${encodeURIComponent(slug)}`);
+  }
+
+  /** Rename or describe a factory. */
+  updateFactory(slug: string, updates: { name?: string; description?: string }): Promise<FactoryRow> {
+    return this.fetch<FactoryRow>(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "PATCH", body: updates });
+  }
+
+  /** Delete a factory. Refuses `default` and any factory still
+   *  containing workflows. */
+  deleteFactory(slug: string): Promise<void> {
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "DELETE" });
+  }
+
+  // ── Secrets ────────────────────────────────────────────────────────────────
+  // Scoped to (factory, workflow, key). Stored in GCP Secret Manager;
+  // `factorySlug` defaults to `"default"`.
+
+  /** Create or update a workflow secret. Value is stored in GCP Secret Manager. */
+  setSecret(workflowName: string, key: string, value: string, opts?: { factorySlug?: string }): Promise<{ key: string }> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(templatePath(factorySlug, workflowName, "secrets"), {
+      method: "POST",
+      body: { key, value },
+    });
+  }
+
+  /** List secret keys registered for a workflow (metadata only — values are never returned). */
+  async listSecrets(workflowName: string, opts?: { factorySlug?: string }): Promise<Array<{ key: string; createdAt: string; updatedAt: string }>> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const body = await this.fetch<{ secrets: Array<{ secretKey: string; createdAt: string; updatedAt: string }> }>(
+      templatePath(factorySlug, workflowName, "secrets"),
+    );
+    return body.secrets.map(s => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
+  }
+
+  /** Delete a workflow secret. */
+  deleteSecret(workflowName: string, key: string, opts?: { factorySlug?: string }): Promise<void> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(templatePath(factorySlug, workflowName, "secrets", key), { method: "DELETE" });
+  }
+
+  // ── API keys ───────────────────────────────────────────────────────────────
+  // Both endpoints require an admin-scoped key as the bearer token.
+
+  /** Create a new API key on the caller's team. The plaintext `key` is
+   *  returned once — it cannot be retrieved later.
+   *
+   *  When `factorySlug` is set, the new key is restricted to that factory.
+   *  Factory-scoped keys can only mint other keys bound to the same factory. */
+  createApiKey(input: {
+    name?:        string;
+    scopes?:      string[];
+    expiresAt?:   string;
+    factorySlug?: string;
+  }): Promise<ApiKeyCreated> {
+    return this.fetch<ApiKeyCreated>("/api-keys", { method: "POST", body: input });
+  }
+
+  /** List API keys on the caller's team (metadata only — plaintext keys are
+   *  never returned). */
+  async listApiKeys(): Promise<ApiKey[]> {
+    const body = await this.fetch<{ object: "list"; data: ApiKey[]; has_more: boolean }>("/api-keys");
+    return body.data;
+  }
+
+  // ── Usage ──────────────────────────────────────────────────────────────────
+
+  /** Billable usage rollup for the caller's team over the [from, to) window. */
+  getUsage(from: Date, to: Date): Promise<UsageResponse> {
+    const qs = `?from=${encodeURIComponent(from.toISOString())}&to=${encodeURIComponent(to.toISOString())}`;
+    return this.fetch<UsageResponse>(`/api/v1/usage${qs}`);
+  }
+
+  // ── Run control ────────────────────────────────────────────────────────────
+
+  /** Cancel an in-progress run. Idempotent: cancelling an already-terminal
+   *  run returns the current state without throwing. The server stamps the
+   *  run as `canceled` and kills any live sandboxes. */
+  cancelRun(runId: string): Promise<CancelRunResponse> {
+    return this.fetch<CancelRunResponse>(
+      `/api/v1/workflows/${encodeURIComponent(runId)}/cancel`,
+      { method: "POST" },
+    );
+  }
+
+  /** Stream lifecycle events for a run as an async iterable. Yields parsed
+   *  `RunEvent` payloads in order; caller breaks on terminal events
+   *  (`run_complete`, `run_failed`, `run_canceled`).
+   *
+   *  `lastEventId` enables resume — pass the highest `seq` you've already
+   *  processed to receive only events you missed.
+   *
+   *  `signal` can be used to abort the stream from the caller side.
+   *
+   *  Uses raw `fetch` (not ofetch) because SSE requires access to the
+   *  response's `ReadableStream`, which ofetch consumes when parsing. Auth
+   *  + base URL are still sourced from the same constructor inputs, and
+   *  non-2xx responses throw the same `AgentComposeError`. */
+  async *streamRunLogs(
+    runId: string,
+    opts?: { lastEventId?: number; signal?: AbortSignal },
+  ): AsyncGenerator<RunEvent> {
+    const headers: Record<string, string> = { Authorization: `Bearer ${this.apiKey}` };
+    if (opts?.lastEventId && opts.lastEventId > 0) {
+      headers["Last-Event-ID"] = String(opts.lastEventId);
+    }
+    const res = await fetch(`${this.baseUrl}/api/v1/workflows/${encodeURIComponent(runId)}/stream`, {
+      headers,
+      ...(opts?.signal ? { signal: opts.signal } : {}),
+    });
+    if (!res.ok || !res.body) {
+      let message = res.statusText;
+      try {
+        const body = await res.json() as { error?: string };
+        if (body.error) message = body.error;
+      } catch { /* non-JSON error body — fall back to statusText */ }
+      throw new AgentComposeError(res.status, message);
+    }
+    for await (const ev of parseSseStream(res.body)) {
+      // The server's `data` payload already includes `event`, `runId`, `seq`,
+      // `at`, and the per-event payload — so `ev.data` IS the `RunEvent`.
+      // Cast directly; unknown future event names flow through untyped, and
+      // callers using the discriminated union see them via the default branch.
+      yield ev.data as unknown as RunEvent;
+    }
+  }
+}
+
+/** A factory: a project-level grouping of workflows inside a team. */
+export interface FactoryRow {
+  id:          string;
+  teamId:      string;
+  slug:        string;
+  name:        string;
+  description: string | null;
+  createdAt:   string;
+  updatedAt:   string;
+}

package/src/env.d.ts

@@ -0,0 +1,5 @@
+// Allow importing .md files as plain text (via Bun's static text import)
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/src/errors.ts

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