torus-ai 0.1.0

package/src/providers/anthropic.ts

@@ -0,0 +1,94 @@
+import { latestUserText, selectModel } from "../router.ts";
+import type {
+  ContentBlock,
+  Message,
+  ModelProvider,
+  ModelRequest,
+  ModelResponse,
+} from "../types.ts";
+
+export interface AnthropicOptions {
+  model?: string;
+  apiKey?: string;
+  maxTokens?: number;
+  /**
+   * When true, the model is chosen per-request by the cost router (cheap vs
+   * expensive) based on query complexity, instead of using a fixed `model`.
+   */
+  route?: boolean;
+}
+
+/**
+ * Real provider backed by the Anthropic Messages API. Requires the optional
+ * `@anthropic-ai/sdk` dependency and an ANTHROPIC_API_KEY. The SDK is imported
+ * lazily so the package (and the mock demo) work without it installed.
+ */
+export class AnthropicProvider implements ModelProvider {
+  readonly name = "anthropic";
+  private client: any;
+  private model: string;
+  private maxTokens: number;
+  private apiKey?: string;
+  private route: boolean;
+
+  constructor(opts: AnthropicOptions = {}) {
+    this.model = opts.model ?? "claude-sonnet-4-6";
+    this.maxTokens = opts.maxTokens ?? 2048;
+    this.apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    this.route = opts.route ?? false;
+  }
+
+  private async ensureClient(): Promise<void> {
+    if (this.client) return;
+    const mod = await import("@anthropic-ai/sdk").catch(() => {
+      throw new Error(
+        "AnthropicProvider needs the @anthropic-ai/sdk package: run `npm i @anthropic-ai/sdk`.",
+      );
+    });
+    const Anthropic = (mod as any).default ?? (mod as any).Anthropic;
+    this.client = new Anthropic({ apiKey: this.apiKey });
+  }
+
+  async generate(req: ModelRequest): Promise<ModelResponse> {
+    await this.ensureClient();
+
+    // Cost routing: pick cheap vs expensive per request from the latest user
+    // turn. selectModel never throws — it falls back to the expensive model.
+    const model = this.route
+      ? await selectModel(latestUserText(req.messages), {
+          client: this.client,
+          apiKey: this.apiKey,
+        })
+      : this.model;
+
+    const res = await this.client.messages.create({
+      model,
+      max_tokens: this.maxTokens,
+      system: req.system,
+      tools: req.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema,
+      })),
+      messages: req.messages.map(toApiMessage),
+    });
+
+    const content: ContentBlock[] = res.content.map((b: any): ContentBlock => {
+      if (b.type === "tool_use") return { type: "tool_use", id: b.id, name: b.name, input: b.input };
+      return { type: "text", text: b.type === "text" ? b.text : "" };
+    });
+    const stopReason = res.stop_reason === "tool_use" ? "tool_use" : "end_turn";
+    return { content, stopReason };
+  }
+}
+
+function toApiMessage(m: Message): any {
+  return {
+    role: m.role,
+    content: m.content.map((b) => {
+      if (b.type === "text") return { type: "text", text: b.text };
+      if (b.type === "tool_use") return { type: "tool_use", id: b.id, name: b.name, input: b.input };
+      return { type: "tool_result", tool_use_id: b.toolUseId, content: b.content, is_error: b.isError };
+    }),
+  };
+}

package/src/providers/gemini.ts

@@ -0,0 +1,120 @@
+import { latestUserText, selectGeminiModel } from "../router.ts";
+import type {
+  ContentBlock,
+  Message,
+  ModelProvider,
+  ModelRequest,
+  ModelResponse,
+} from "../types.ts";
+
+export interface GeminiOptions {
+  model?: string;
+  apiKey?: string;
+  /**
+   * When true, the model is chosen per-request by the cost router (cheap vs
+   * expensive Gemini) based on query complexity, instead of a fixed `model`.
+   */
+  route?: boolean;
+}
+
+/**
+ * Provider backed by the Google Gemini API (@google/genai). Requires the
+ * optional `@google/genai` dependency and a GOOGLE_API_KEY (or GEMINI_API_KEY).
+ * The SDK is imported lazily so the package works without it installed.
+ */
+export class GeminiProvider implements ModelProvider {
+  readonly name = "gemini";
+  private client: any;
+  private model: string;
+  private apiKey?: string;
+  private route: boolean;
+
+  constructor(opts: GeminiOptions = {}) {
+    this.model = opts.model ?? "gemini-2.5-flash";
+    this.apiKey = opts.apiKey ?? process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY;
+    this.route = opts.route ?? false;
+  }
+
+  private async ensureClient(): Promise<void> {
+    if (this.client) return;
+    const mod = await import("@google/genai").catch(() => {
+      throw new Error("GeminiProvider needs the @google/genai package: run `npm i @google/genai`.");
+    });
+    const GoogleGenAI = (mod as any).GoogleGenAI;
+    this.client = new GoogleGenAI({ apiKey: this.apiKey });
+  }
+
+  async generate(req: ModelRequest): Promise<ModelResponse> {
+    await this.ensureClient();
+
+    const model = this.route
+      ? await selectGeminiModel(latestUserText(req.messages), {
+          client: this.client,
+          apiKey: this.apiKey,
+        })
+      : this.model;
+
+    const idToName = toolUseNames(req.messages);
+
+    const config: any = {};
+    if (req.system) config.systemInstruction = req.system;
+    if (req.tools.length) {
+      config.tools = [
+        {
+          functionDeclarations: req.tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: t.inputSchema,
+          })),
+        },
+      ];
+    }
+
+    const res = await this.client.models.generateContent({
+      model,
+      contents: req.messages.map((m) => toGeminiContent(m, idToName)),
+      config,
+    });
+
+    const content: ContentBlock[] = [];
+    const text: string | undefined = res.text;
+    if (text && text.trim()) content.push({ type: "text", text });
+
+    const calls: any[] = res.functionCalls ?? [];
+    for (const fc of calls) {
+      content.push({ type: "tool_use", id: fc.id ?? "", name: fc.name, input: fc.args ?? {} });
+    }
+    if (content.length === 0) content.push({ type: "text", text: "" });
+
+    return { content, stopReason: calls.length ? "tool_use" : "end_turn" };
+  }
+}
+
+/** Map tool_use id -> tool name (Gemini matches function responses by name). */
+function toolUseNames(messages: Message[]): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const m of messages) {
+    for (const b of m.content) {
+      if (b.type === "tool_use") map.set(b.id, b.name);
+    }
+  }
+  return map;
+}
+
+/** Translate one of our Messages into a Gemini `Content` (role + parts). */
+function toGeminiContent(m: Message, idToName: Map<string, string>): any {
+  const role = m.role === "assistant" ? "model" : "user";
+  const parts = m.content.map((b) => {
+    if (b.type === "text") return { text: b.text };
+    if (b.type === "tool_use") return { functionCall: { id: b.id, name: b.name, args: b.input } };
+    // tool_result -> functionResponse
+    return {
+      functionResponse: {
+        id: b.toolUseId,
+        name: idToName.get(b.toolUseId) ?? b.toolUseId,
+        response: b.isError ? { error: b.content } : { result: b.content },
+      },
+    };
+  });
+  return { role, parts };
+}

package/src/providers/mock.ts

@@ -0,0 +1,93 @@
+import type {
+  ModelProvider,
+  ModelRequest,
+  ModelResponse,
+  ToolSchema,
+} from "../types.ts";
+
+export interface MockOptions {
+  /** Label stamped into outputs so mock-generated content is unmistakable. */
+  label?: string;
+}
+
+/**
+ * A deterministic, offline provider that exercises the full agent loop with no API
+ * key. Strategy: if tools are offered and none have been used yet, call the first
+ * tool once; otherwise synthesize a final answer from the system context + any tool
+ * results. It is intentionally dumb — its job is to prove the harness wiring, not to
+ * write good prose. Swap in AnthropicProvider for real output.
+ */
+export class MockProvider implements ModelProvider {
+  readonly name = "mock";
+  private opts: MockOptions;
+  constructor(opts: MockOptions = {}) {
+    this.opts = opts;
+  }
+
+  async generate(req: ModelRequest): Promise<ModelResponse> {
+    const alreadyUsedTool = req.messages.some((m) =>
+      m.content.some((b) => b.type === "tool_use"),
+    );
+    if (req.tools.length > 0 && !alreadyUsedTool) {
+      const t = req.tools[0];
+      return {
+        stopReason: "tool_use",
+        content: [{ type: "tool_use", id: "", name: t.name, input: this.sampleInput(t) }],
+      };
+    }
+    return { stopReason: "end_turn", content: [{ type: "text", text: this.synthesize(req) }] };
+  }
+
+  private sampleInput(t: ToolSchema): Record<string, unknown> {
+    const props = (t.inputSchema.properties ?? {}) as Record<string, { type?: string }>;
+    const topic = "the requested topic";
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(props)) {
+      out[k] =
+        v.type === "number"
+          ? 3
+          : v.type === "boolean"
+            ? true
+            : k === "path"
+              ? "shared/notes.md"
+              : topic;
+    }
+    return out;
+  }
+
+  private synthesize(req: ModelRequest): string {
+    const toolData = req.messages
+      .flatMap((m) => m.content)
+      .filter((b) => b.type === "tool_result")
+      .map((b) => (b as { content: string }).content)
+      .join("\n");
+
+    const contract = extractLayer(req.system, "2 contract");
+    const label = this.opts.label ? ` ${this.opts.label}` : "";
+
+    const lines = [
+      `<!-- mock model output${label} -->`,
+      "",
+      "## Result",
+      "",
+      "Produced by the Torus MockProvider — proof that layered context →",
+      "agent loop → output handoff works end to end. Replace with AnthropicProvider",
+      "for real generation.",
+    ];
+    if (toolData) {
+      lines.push("", "### Tool-sourced material", "", "```", toolData.slice(0, 600), "```");
+    }
+    if (contract) {
+      lines.push("", "### Stage focus (read from the Layer 2 contract)", "", firstLines(contract, 6));
+    }
+    return lines.join("\n");
+  }
+}
+
+function extractLayer(system: string, layer: string): string {
+  const m = system.match(new RegExp(`<context layer="${layer}"[^>]*>([\\s\\S]*?)</context>`));
+  return m ? m[1].trim() : "";
+}
+function firstLines(s: string, n: number): string {
+  return s.split("\n").slice(0, n).join("\n");
+}

package/src/router.ts

@@ -0,0 +1,260 @@
+// ─────────────────────────────────────────────────────────────────────────
+// Intelligent LLM router — picks CHEAP vs EXPENSIVE per query to cut API cost.
+//
+// Hybrid strategy (provider-agnostic):
+//   1. Fast heuristics (no API call) for the obvious cases.
+//   2. Otherwise a structured "judge" call to the CHEAP model that classifies
+//      the query as SIMPLE | COMPLEX.
+//   SIMPLE → cheap model, COMPLEX → expensive model.
+//
+// The same mechanism is provided for two provider families:
+//   - Anthropic:  selectModel()        (Claude Haiku judge → Haiku / Sonnet)
+//   - Gemini:     selectGeminiModel()  (Gemini Flash-Lite judge → Flash-Lite / Pro)
+//
+// Safety: the select* functions never throw — on any failure they default to
+// the EXPENSIVE model so the user experience never breaks.
+// ─────────────────────────────────────────────────────────────────────────
+
+import type { Message } from "./types.ts";
+
+// ── Target models ──────────────────────────────────────────────────────────
+// Change these in one place per provider.
+export const CHEAP_MODEL = "claude-haiku-4-5"; // $1 / $5 per MTok
+export const EXPENSIVE_MODEL = "claude-sonnet-4-6"; // current default — $3 / $15 per MTok
+
+// Gemini defaults to the stable 2.5 family. Swap to newer IDs (e.g.
+// "gemini-3.1-flash-lite" / "gemini-3.1-pro-preview") if your key has access.
+export const GEMINI_CHEAP_MODEL = "gemini-2.5-flash-lite";
+export const GEMINI_EXPENSIVE_MODEL = "gemini-2.5-pro";
+
+export type Complexity = "SIMPLE" | "COMPLEX";
+
+export interface RouterOptions {
+  /** Reuse an existing provider SDK client (avoids a second client init). */
+  client?: any;
+  /** API key for a lazily-created client (defaults to the provider's env var). */
+  apiKey?: string;
+  /** Model used as the complexity judge. Defaults to the provider's cheap model. */
+  judgeModel?: string;
+}
+
+// ── 1. Fast heuristics (no API call, provider-agnostic) ─────────────────────
+
+const SIMPLE_KEYWORDS = [
+  "hello", "hi ", "hey", "thanks", "thank you", "yes", "no",
+  "format", "json", "yaml", "uppercase", "lowercase", "capitalize",
+  "translate", "spell", "reverse", "echo", "greeting",
+];
+
+const estimateTokens = (s: string) => Math.ceil(s.length / 4); // ~4 chars/token
+
+/**
+ * Cheap, deterministic pre-classification. Returns a verdict only when it's
+ * confident; otherwise null (defer to the judge).
+ */
+export function fastHeuristic(prompt: string): Complexity | null {
+  const tokens = estimateTokens(prompt);
+  const lower = prompt.toLowerCase();
+
+  // Short prompt that mentions a trivial operation → SIMPLE, route immediately.
+  if (tokens <= 30 && SIMPLE_KEYWORDS.some((k) => lower.includes(k))) return "SIMPLE";
+
+  // Very long prompts are almost always real work → skip the judge call.
+  if (tokens >= 400) return "COMPLEX";
+
+  return null;
+}
+
+// ── 2. LLM judges (structured output on each provider's cheap model) ─────────
+
+const JUDGE_SYSTEM =
+  "You are a routing classifier. Decide whether a user query needs a powerful " +
+  "model or can be handled by a small, fast one. Classify as SIMPLE (greetings, " +
+  "formatting, short factual lookups, simple rewrites, single-step tasks) or " +
+  "COMPLEX (multi-step reasoning, coding, analysis, planning, nuanced judgment). " +
+  'Respond ONLY with the required JSON: {"complexity": "SIMPLE" | "COMPLEX"}.';
+
+const COMPLEXITY_SCHEMA = {
+  type: "object",
+  properties: { complexity: { type: "string", enum: ["SIMPLE", "COMPLEX"] } },
+  required: ["complexity"],
+  additionalProperties: false,
+};
+
+/** Robustly extract SIMPLE/COMPLEX from a judge response. Throws if neither. */
+function parseComplexity(text: string): Complexity {
+  try {
+    const parsed = JSON.parse(text) as { complexity?: string };
+    if (parsed.complexity === "SIMPLE" || parsed.complexity === "COMPLEX") return parsed.complexity;
+  } catch {
+    // fall through to text scan
+  }
+  const m = text.toUpperCase().match(/\b(SIMPLE|COMPLEX)\b/);
+  if (m) return m[1] as Complexity;
+  throw new Error(`judge returned unparseable complexity: ${text.slice(0, 80)}`);
+}
+
+// -- Anthropic judge --
+let sharedAnthropic: any;
+async function getAnthropic(opts: RouterOptions): Promise<any> {
+  if (opts.client) return opts.client;
+  if (sharedAnthropic) return sharedAnthropic;
+  const mod = await import("@anthropic-ai/sdk").catch(() => {
+    throw new Error("Anthropic judge needs @anthropic-ai/sdk (npm i @anthropic-ai/sdk).");
+  });
+  const Anthropic = (mod as any).default ?? (mod as any).Anthropic;
+  sharedAnthropic = new Anthropic({ apiKey: opts.apiKey ?? process.env.ANTHROPIC_API_KEY });
+  return sharedAnthropic;
+}
+
+/** Grade complexity with Claude (structured output). May throw. */
+export async function judgeComplexity(prompt: string, opts: RouterOptions = {}): Promise<Complexity> {
+  const client = await getAnthropic(opts);
+  const res = await client.messages.create({
+    model: opts.judgeModel ?? CHEAP_MODEL,
+    max_tokens: 64,
+    system: JUDGE_SYSTEM,
+    output_config: { format: { type: "json_schema", schema: COMPLEXITY_SCHEMA } },
+    messages: [{ role: "user", content: prompt }],
+  });
+  const text: string = res.content.find((b: any) => b.type === "text")?.text ?? "";
+  return parseComplexity(text);
+}
+
+// -- Gemini judge --
+let sharedGemini: any;
+async function getGemini(opts: RouterOptions): Promise<any> {
+  if (opts.client) return opts.client;
+  if (sharedGemini) return sharedGemini;
+  const mod = await import("@google/genai").catch(() => {
+    throw new Error("Gemini judge needs @google/genai (npm i @google/genai).");
+  });
+  const GoogleGenAI = (mod as any).GoogleGenAI;
+  sharedGemini = new GoogleGenAI({
+    apiKey: opts.apiKey ?? process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY,
+  });
+  return sharedGemini;
+}
+
+/** Grade complexity with Gemini (JSON structured output). May throw. */
+export async function judgeComplexityGemini(prompt: string, opts: RouterOptions = {}): Promise<Complexity> {
+  const client = await getGemini(opts);
+  const res = await client.models.generateContent({
+    model: opts.judgeModel ?? GEMINI_CHEAP_MODEL,
+    contents: prompt,
+    config: {
+      systemInstruction: JUDGE_SYSTEM,
+      responseMimeType: "application/json",
+      responseSchema: {
+        type: "object",
+        properties: { complexity: { type: "string", enum: ["SIMPLE", "COMPLEX"] } },
+        required: ["complexity"],
+      },
+    },
+  });
+  return parseComplexity(res.text ?? "");
+}
+
+// ── 3. Classification + routing ─────────────────────────────────────────────
+
+type Judge = (prompt: string, opts: RouterOptions) => Promise<Complexity>;
+
+async function classifyWith(prompt: string, judge: Judge, opts: RouterOptions): Promise<Complexity> {
+  return fastHeuristic(prompt) ?? judge(prompt, opts);
+}
+
+/** Heuristics first, Claude judge second. May throw. */
+export function classifyComplexity(prompt: string, opts: RouterOptions = {}): Promise<Complexity> {
+  return classifyWith(prompt, judgeComplexity, opts);
+}
+
+/** Heuristics first, Gemini judge second. May throw. */
+export function classifyComplexityGemini(prompt: string, opts: RouterOptions = {}): Promise<Complexity> {
+  return classifyWith(prompt, judgeComplexityGemini, opts);
+}
+
+interface RouteConfig {
+  cheapModel: string;
+  expensiveModel: string;
+  judge: Judge;
+}
+
+async function routeWith(prompt: string, cfg: RouteConfig, opts: RouterOptions): Promise<string> {
+  let model = cfg.expensiveModel;
+  try {
+    const complexity = await classifyWith(prompt, cfg.judge, opts);
+    model = complexity === "SIMPLE" ? cfg.cheapModel : cfg.expensiveModel;
+  } catch (err) {
+    console.warn(
+      `[router] classification failed — defaulting to expensive model. Reason: ${(err as Error).message}`,
+    );
+    model = cfg.expensiveModel;
+  }
+  record(model, model === cfg.cheapModel);
+  return model;
+}
+
+/** Pick a Claude model for a prompt. Never throws (falls back to expensive). */
+export function selectModel(prompt: string, opts: RouterOptions = {}): Promise<string> {
+  return routeWith(prompt, { cheapModel: CHEAP_MODEL, expensiveModel: EXPENSIVE_MODEL, judge: judgeComplexity }, opts);
+}
+
+/** Pick a Gemini model for a prompt. Never throws (falls back to expensive). */
+export function selectGeminiModel(prompt: string, opts: RouterOptions = {}): Promise<string> {
+  return routeWith(
+    prompt,
+    { cheapModel: GEMINI_CHEAP_MODEL, expensiveModel: GEMINI_EXPENSIVE_MODEL, judge: judgeComplexityGemini },
+    opts,
+  );
+}
+
+// ── 4. Observability ─────────────────────────────────────────────────────────
+
+let cheapCount = 0;
+let expensiveCount = 0;
+
+function record(model: string, isCheap: boolean): void {
+  if (isCheap) cheapCount++;
+  else expensiveCount++;
+  const total = cheapCount + expensiveCount;
+  const pct = (n: number) => ((n / total) * 100).toFixed(0);
+  console.log(
+    `[router] → ${isCheap ? "CHEAP" : "EXPENSIVE"} (${model})  |  cheap ${pct(cheapCount)}% / expensive ${pct(expensiveCount)}%  (n=${total})`,
+  );
+}
+
+export interface RoutingStats {
+  cheap: number;
+  expensive: number;
+  total: number;
+  cheapPct: number;
+  expensivePct: number;
+}
+
+export function getRoutingStats(): RoutingStats {
+  const total = cheapCount + expensiveCount;
+  return {
+    cheap: cheapCount,
+    expensive: expensiveCount,
+    total,
+    cheapPct: total ? (cheapCount / total) * 100 : 0,
+    expensivePct: total ? (expensiveCount / total) * 100 : 0,
+  };
+}
+
+// ── Shared message util ──────────────────────────────────────────────────────
+
+/** Extract the most recent user turn's text — what the router classifies on. */
+export function latestUserText(messages: Message[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m.role !== "user") continue;
+    const text = m.content
+      .filter((b): b is Extract<typeof b, { type: "text" }> => b.type === "text")
+      .map((b) => b.text)
+      .join("\n")
+      .trim();
+    if (text) return text;
+  }
+  return "";
+}

package/src/subagents.ts

@@ -0,0 +1,92 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+// A "subagent" in this SDK is a stage: a markdown contract (Layer 2 CONTEXT.md)
+// that declares its Inputs / Process / Outputs / Tools. Parsing the contract turns
+// folder structure into agent architecture — the whole ICM premise.
+
+export interface StageInput {
+  layer: 3 | 4; // 3 = reference (constraints), 4 = working (input to process)
+  path: string; // relative to the stage dir, exactly as the contract names it
+  note?: string;
+}
+
+export interface StageContract {
+  name: string; // "01_research"
+  order: number;
+  stageDir: string;
+  contractPath: string;
+  inputs: StageInput[];
+  process: string;
+  outputs: string[]; // artifact filenames, written to the stage's output/
+  tools: string[]; // allowlist patterns from the optional "## Tools" section
+}
+
+/** Pull the body of a "## <Name>" markdown section (up to the next "## " or EOF). */
+function section(body: string, name: string): string {
+  const re = new RegExp(`(?:^|\\n)##\\s+${name}\\s*\\n([\\s\\S]*?)(?=\\n##\\s|$)`, "i");
+  const m = body.match(re);
+  return m ? m[1].trim() : "";
+}
+
+export function parseContract(
+  name: string,
+  stageDir: string,
+  contractPath: string,
+  body: string,
+): StageContract {
+  const order = parseInt(name.slice(0, 2), 10) || 0;
+
+  // Inputs: "- Layer 3 (reference): ../../_config/voice.md   # optional note"
+  const inputs: StageInput[] = [];
+  for (const line of section(body, "Inputs").split("\n")) {
+    const m = line.match(/Layer\s+([34])\b.*?:\s*([^\s#]+)\s*(?:#\s*(.*))?$/i);
+    if (m) inputs.push({ layer: Number(m[1]) as 3 | 4, path: m[2], note: m[3]?.trim() });
+  }
+
+  // Outputs: "- research-output.md -> output/"
+  const outputs: string[] = [];
+  for (const line of section(body, "Outputs").split("\n")) {
+    const m = line.match(/-\s*([A-Za-z0-9._-]+\.(?:md|json|txt))/);
+    if (m) outputs.push(m[1]);
+  }
+
+  // Tools (optional): the stage declares exactly which tools it may use.
+  const toolsRaw = section(body, "Tools");
+  const tools = toolsRaw
+    ? toolsRaw
+        .split(/[\n,]/)
+        .map((s) => s.replace(/^[-*]\s*/, "").trim())
+        .filter(Boolean)
+    : [];
+
+  return {
+    name,
+    order,
+    stageDir,
+    contractPath,
+    inputs,
+    process: section(body, "Process"),
+    outputs,
+    tools,
+  };
+}
+
+/** Discover and parse every numbered stage folder, in execution order. */
+export async function loadStages(workspaceDir: string): Promise<StageContract[]> {
+  const stagesRoot = join(workspaceDir, "stages");
+  const entries = await readdir(stagesRoot, { withFileTypes: true });
+  const dirs = entries
+    .filter((e) => e.isDirectory() && /^\d{2}_/.test(e.name))
+    .map((e) => e.name)
+    .sort();
+
+  const contracts: StageContract[] = [];
+  for (const name of dirs) {
+    const stageDir = join(stagesRoot, name);
+    const contractPath = join(stageDir, "CONTEXT.md");
+    const body = await readFile(contractPath, "utf8");
+    contracts.push(parseContract(name, stageDir, contractPath, body));
+  }
+  return contracts;
+}