projectinator 0.1.0

package/src/research.ts

@@ -0,0 +1,127 @@
+// Auto-feed the Scout — turn a research report into structured findings.
+//
+// The deep-research harness (or any benchmark write-up) produces prose. This module
+// extracts it into clean Finding[] the Scout can consume: a model reads the report and
+// calls a forced typebox tool. That's reliable because it's reformatting text we give
+// it, not recalling facts from memory.
+//
+// Flow:  research report (text)  ->  extractFindings()  ->  findings.json  ->  scout --from
+
+import {
+  AuthStorage,
+  ModelRegistry,
+  createAgentSession,
+  defineTool,
+  type AgentSession,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import type { Provider } from "./types.js";
+import type { Finding } from "./scout.js";
+import { resolvePiModel } from "./executor.js";
+import { MODELS } from "./models.js";
+
+const FindingsSchema = Type.Object({
+  findings: Type.Array(
+    Type.Object({
+      capability: Type.Union([
+        Type.Literal("plan"), Type.Literal("design"), Type.Literal("code"),
+        Type.Literal("test"), Type.Literal("ops"),
+      ]),
+      tier: Type.Union([Type.Literal("fast"), Type.Literal("mid"), Type.Literal("high")]),
+      backend: Type.Union([Type.Literal("web"), Type.Literal("api")]),
+      provider: Type.Union([Type.Literal("anthropic"), Type.Literal("openai"), Type.Literal("google")]),
+      model: Type.String({ description: "exact model id, e.g. claude-opus-4-8" }),
+      evidence: Type.String({ description: "one-line benchmark/source justification" }),
+    }),
+  ),
+});
+type FindingsRaw = Static<typeof FindingsSchema>;
+
+export interface ValidationIssue {
+  index: number;
+  model: string;
+  problem: string;
+}
+
+/** Pure check: does each finding reference a real model with a matching provider? */
+export function validateFindings(findings: Finding[]): { ok: boolean; issues: ValidationIssue[] } {
+  const issues: ValidationIssue[] = [];
+  findings.forEach((f, index) => {
+    const m = MODELS[f.model];
+    if (!m) {
+      issues.push({ index, model: f.model, problem: "model not in models.ts" });
+    } else if (m.provider !== f.provider) {
+      issues.push({ index, model: f.model, problem: `provider mismatch (models.ts says ${m.provider})` });
+    }
+  });
+  return { ok: issues.length === 0, issues };
+}
+
+function buildFindingsTool() {
+  let captured: Finding[] | undefined;
+  const tool = defineTool({
+    name: "submit_findings",
+    label: "Submit Findings",
+    description: "Submit the extracted model-per-role findings.",
+    parameters: FindingsSchema,
+    execute: async (_id, params: FindingsRaw) => {
+      captured = params.findings as Finding[];
+      return { content: [{ type: "text", text: `Extracted ${params.findings.length} findings.` }], details: {} };
+    },
+  });
+  return { tool, get: () => captured };
+}
+
+export function extractionPrompt(report: string): string {
+  return [
+    "You are a data extractor. From the research report below, extract the single best",
+    "model for each role the report covers, as structured findings.",
+    "",
+    "For each finding set: capability (plan|design|code|test|ops), tier (fast|mid|high),",
+    "backend (usually 'api' for benchmark-driven picks), provider, the EXACT model id,",
+    "and a one-line evidence note. Only include roles the report actually supports.",
+    "Do not invent models. When done, call submit_findings once.",
+    "",
+    "--- REPORT ---",
+    report,
+  ].join("\n");
+}
+
+export interface ExtractOptions {
+  model: { provider: Provider; model: string };
+  authStorage?: AuthStorage;
+  onEvent?: Parameters<AgentSession["subscribe"]>[0];
+}
+
+/** Extract findings from a report via a model. Spends money (one model call). */
+export async function extractFindings(report: string, opts: ExtractOptions): Promise<Finding[]> {
+  const authStorage = opts.authStorage ?? AuthStorage.create();
+  const registry = ModelRegistry.create(authStorage);
+  const model = resolvePiModel(registry, opts.model.provider, opts.model.model);
+
+  const { tool, get } = buildFindingsTool();
+  const { session } = await createAgentSession({
+    model, authStorage, modelRegistry: registry,
+    thinkingLevel: "low",
+    noTools: "all",
+    customTools: [tool],
+    tools: ["submit_findings"],
+  });
+
+  const unsub = opts.onEvent ? session.subscribe(opts.onEvent) : undefined;
+  try {
+    await session.prompt(extractionPrompt(report));
+    let out = get();
+    if (!out) {
+      await session.followUp("Call submit_findings now.");
+      out = get();
+    }
+    if (!out) throw new Error("Extractor did not call submit_findings.");
+    return out;
+  } finally {
+    unsub?.();
+    session.dispose();
+  }
+}
+
+export { FindingsSchema, buildFindingsTool };

package/src/retro.ts

@@ -0,0 +1,99 @@
+// Build retro — a free, data-driven summary of a finished build, computed from
+// build-state: what passed, what the tester flagged, cost per epic and per
+// model, retries, and the priciest tasks. No model call.
+
+import type { BuildState } from "./build-state.js";
+import type { Bug, Difficulty } from "./types.js";
+import { baselineTokens } from "./estimate.js";
+import { estimateCost } from "./cost.js";
+import { getModel } from "./models.js";
+
+export interface RetroReport {
+  idea: string;
+  status: BuildState["status"];
+  totalCost: number;
+  estCost: number; // baseline predicted cost for the tasks that ran
+  taskCount: number;
+  doneCount: number;
+  tests: { passed: number; failed: number };
+  bugs: Bug[]; // everything the tester flagged during the build
+  retries: { taskId: string; title: string; rounds: number }[];
+  byEpic: { epic: string; cost: number; tasks: number }[];
+  byModel: { model: string; cost: number; tasks: number }[];
+  topCost: { taskId: string; title: string; cost: number }[];
+}
+
+const round2 = (n: number) => Math.round(n * 100) / 100;
+
+export function computeRetro(state: BuildState): RetroReport {
+  const titleById = new Map(state.tasks.map((t) => [t.id, t.title]));
+  const epicById = new Map(state.tasks.map((t) => [t.id, t.epic || "General"]));
+  const diffById = new Map(state.tasks.map((t) => [t.id, t.difficulty]));
+  const outcomes = state.outcomes;
+  const doneIds = new Set(outcomes.map((o) => o.taskId));
+
+  // Baseline-predicted cost for each run: static token budget × the model that ran it.
+  let estCost = 0;
+  for (const o of outcomes) {
+    const diff = (diffById.get(o.taskId) ?? "medium") as Difficulty;
+    try {
+      const model = getModel(o.modelId);
+      const tokens = baselineTokens(o.capability, diff);
+      estCost += estimateCost({ input: tokens.input, output: tokens.output, cachedInputFraction: 0.55 }, model);
+    } catch {
+      /* unknown model — skip its estimate */
+    }
+  }
+
+  // Tests: judge each test task by its LAST outcome (final state after retries).
+  const lastTestByTask = new Map<string, (typeof outcomes)[number]>();
+  for (const o of outcomes) if (o.capability === "test") lastTestByTask.set(o.taskId, o);
+  let passed = 0;
+  let failed = 0;
+  for (const o of lastTestByTask.values()) {
+    if (o.verdict?.passed) passed++;
+    else if (o.verdict) failed++;
+  }
+
+  // Bugs the tester flagged anywhere during the build (signal, even if later fixed).
+  const bugs: Bug[] = [];
+  for (const o of outcomes) if (o.verdict?.bugs) bugs.push(...o.verdict.bugs);
+
+  // Retries: any outcome past round 0 means a Tester→Developer rebuild happened.
+  const roundsByTask = new Map<string, number>();
+  for (const o of outcomes) if (o.round > 0) roundsByTask.set(o.taskId, Math.max(roundsByTask.get(o.taskId) ?? 0, o.round));
+  const retries = [...roundsByTask.entries()].map(([taskId, rounds]) => ({ taskId, title: titleById.get(taskId) ?? taskId, rounds }));
+
+  // Cost per epic + per model.
+  const epicCost = new Map<string, { cost: number; tasks: number }>();
+  const modelCost = new Map<string, { cost: number; tasks: number }>();
+  for (const o of outcomes) {
+    const e = epicById.get(o.taskId) ?? "General";
+    const ec = epicCost.get(e) ?? { cost: 0, tasks: 0 };
+    epicCost.set(e, { cost: ec.cost + o.cost, tasks: ec.tasks + 1 });
+    const mc = modelCost.get(o.modelId) ?? { cost: 0, tasks: 0 };
+    modelCost.set(o.modelId, { cost: mc.cost + o.cost, tasks: mc.tasks + 1 });
+  }
+  const byEpic = [...epicCost.entries()].map(([epic, v]) => ({ epic, cost: round2(v.cost), tasks: v.tasks })).sort((a, b) => b.cost - a.cost);
+  const byModel = [...modelCost.entries()].map(([model, v]) => ({ model, cost: round2(v.cost), tasks: v.tasks })).sort((a, b) => b.cost - a.cost);
+
+  const topCost = [...outcomes]
+    .sort((a, b) => b.cost - a.cost)
+    .slice(0, 3)
+    .map((o) => ({ taskId: o.taskId, title: titleById.get(o.taskId) ?? o.taskId, cost: round2(o.cost) }));
+
+  return {
+    idea: state.idea ?? state.id,
+    status: state.status,
+    totalCost: round2(state.totalCost),
+    estCost: round2(estCost),
+    taskCount: state.tasks.length,
+    doneCount: doneIds.size,
+    tests: { passed, failed },
+    bugs,
+    retries,
+    byEpic,
+    byModel,
+    topCost,
+  };
+}

package/src/roles.ts

@@ -0,0 +1,357 @@
+// Phase 4 — role definitions + the real Pi-backed executor.
+//
+// Each capability becomes a role with its own prompt and tool set. The Tester uses
+// a forced typebox verdict tool (like the PM) so its pass/fail is structured, which
+// the orchestrator's feedback loop depends on.
+
+import {
+  AuthStorage,
+  ModelRegistry,
+  createAgentSession,
+  defineTool,
+  type AgentSession,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import type {
+  Backend,
+  Capability,
+  Provider,
+  RegistryEntry,
+  RoleExecutor,
+  RoleResult,
+  Task,
+  Verdict,
+} from "./types.js";
+import { resolvePiModel } from "./executor.js";
+import { renderCheck } from "./preview.js";
+import { estimateCost } from "./cost.js";
+import { getModel } from "./models.js";
+import { addSessionCost } from "./session-cost.js";
+import { recordActual } from "./calibration.js";
+import { readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+// ---- role prompts ----
+
+const ROLE_INTRO: Record<Capability, string> = {
+  plan: "You are the PLANNER. Produce a concise plan or decision for this task as text.",
+  design:
+    "You are the DESIGNER. Produce a clear, concrete design spec (layout, components, colours, states) as text. " +
+    "If the product spans multiple files, also specify the intended FILE STRUCTURE — name each file and say what it holds (e.g. index.html, styles.css, app.js, or a src/ tree). Do not write code files. " +
+    "For a plain static site with no build step, DO NOT spec ES modules with relative imports (`<script type=\"module\">` + `import './x.js'`): browsers block those when the user double-clicks the file (file://), so the app looks dead. Prefer one classic `<script src>` (or a few, loaded in order) so it runs on double-click.",
+  code:
+    "You are the DEVELOPER. Write real, working files into the working directory — minimal, correct, no placeholders, no TODO stubs. " +
+    "This is often a MULTI-FILE project: FIRST inspect what already exists (use ls, then read the relevant files) and BUILD ON it — " +
+    "reuse and extend existing files, follow the file structure the design spec defines, and make sure files reference each other with correct paths " +
+    "(imports/requires, <script src> and <link href>, relative paths). Create only the files this task needs; never delete or clobber files unrelated to your task. " +
+    "MUST-RUN-ON-DOUBLE-CLICK: for a plain static site with no bundler/build step, the app has to work when the user just opens index.html as a file (file://). Do NOT use `<script type=\"module\">` with relative `import`s, and do not `fetch()` local files — browsers block both on file://, leaving a blank page. Split code with several plain `<script src>` tags in dependency order (globals), not ES modules. If the app genuinely needs a server (a real backend, bundler, or framework), write a short README.md with the exact run command.",
+  test: "You are the TESTER. For a web app, FIRST call check_app to actually run it in a headless browser — it reports how the app renders BOTH served over http AND opened directly as a file (double-click / file://). Confirm it renders, shows the expected content, and has no JavaScript/console errors. The app MUST also work on double-click (file://) UNLESS a README documents how to run it — if check_app says double-click is BROKEN and there is no README with a run command, that is a HIGH-severity bug (report it, describe the file:// failure). Then inspect the files against the task and check multi-file wiring (referenced files exist, paths/imports resolve). Then call submit_verdict with pass/fail and any bugs. A blank render or a JS error is a high-severity bug. Do not fix anything yourself.",
+  ops: "You are OPS. Perform the operational task (build, config, deploy prep) using your tools. Report what you did as text.",
+};
+
+export function buildRolePrompt(task: Task, contextText: string): string {
+  const lines = [
+    ROLE_INTRO[task.capability],
+    "",
+    `Task ${task.id}: ${task.title}`,
+    contextText ? `\n${contextText}` : "",
+    "",
+    task.capability === "test"
+      ? "When finished, call submit_verdict exactly once."
+      : "Complete the task, then stop. Do not explain at length.",
+  ];
+  return lines.filter((l) => l !== "").join("\n");
+}
+
+// ---- tester verdict tool (forced structured output) ----
+
+const VerdictSchema = Type.Object({
+  passed: Type.Boolean({ description: "true if the build satisfies the task with no serious bugs" }),
+  bugs: Type.Array(
+    Type.Object({
+      severity: Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high")]),
+      description: Type.String(),
+      file: Type.Optional(Type.String()),
+    }),
+    { description: "empty if passed" },
+  ),
+});
+type VerdictRaw = Static<typeof VerdictSchema>;
+
+// ---- tester "run the app" tool: headless render + error capture ----
+
+function buildCheckTool(workspace: string) {
+  return defineTool({
+    name: "check_app",
+    label: "Run the app",
+    description:
+      "Render a built web page in a headless browser and report its title, the visible text, " +
+      "and any JavaScript/console errors or failed asset requests. Use this on web apps to confirm " +
+      "the app actually RUNS and renders before you judge it — do not rely on reading the code alone.",
+    parameters: Type.Object(
+      { file: Type.Optional(Type.String({ description: "HTML entry file to load; default index.html" })) },
+      { additionalProperties: true },
+    ),
+    execute: async (_id, params: { file?: string }) => {
+      try {
+        const r = await renderCheck(workspace, params.file || "index.html");
+        const doubleClick = r.doubleClickBroken
+          ? "BROKEN — renders behind a server but is blank/erroring when opened directly as a file (double-click). "
+            + "Most likely ES modules + relative imports (or fetch of local files), which browsers block on file://. "
+            + "This is a real defect for a user who just opens the folder. Fix: use a classic non-module <script>, "
+            + "or ship a README with a run command (e.g. `python3 -m http.server`)."
+          : r.fileOk
+            ? "OK (works on double-click too)"
+            : `over file://: ${r.fileErrors.length ? r.fileErrors.join("; ") : "(empty page)"}`;
+        const text = [
+          `rendered (served over http): ${r.ok ? "OK (no JS errors)" : "with errors"}`,
+          `title: ${r.title || "(none)"}`,
+          `errors: ${r.errors.length ? "\n  - " + r.errors.join("\n  - ") : "none"}`,
+          `opened as a file (double-click / file://): ${doubleClick}`,
+          `visible text:\n${r.text || "(empty page — nothing rendered)"}`,
+        ].join("\n");
+        return { content: [{ type: "text", text }], details: {} };
+      } catch (e) {
+        return {
+          content: [{ type: "text", text: `check_app could not run (${e instanceof Error ? e.message : e}). If this isn't a web app with an HTML page, inspect the files directly instead.` }],
+          details: {},
+        };
+      }
+    },
+  });
+}
+
+function buildVerdictTool() {
+  let captured: Verdict | undefined;
+  const tool = defineTool({
+    name: "submit_verdict",
+    label: "Submit Verdict",
+    description: "Submit your pass/fail judgement and any bugs found.",
+    parameters: VerdictSchema,
+    execute: async (_id, params: VerdictRaw) => {
+      captured = { passed: params.passed, bugs: params.bugs };
+      return {
+        content: [{ type: "text", text: `Verdict: ${params.passed ? "PASS" : "FAIL"} (${params.bugs.length} bugs)` }],
+        details: {},
+      };
+    },
+  });
+  return { tool, get: () => captured };
+}
+
+// ---- provider lock: run the whole pipeline on one provider ----
+// Useful when you hold a key for only one provider. Maps each capability+tier to
+// that provider's sensible model, so route() resolves everything to it.
+
+const PROVIDER_MODELS: Record<Provider, { strong: string; mid: string; cheap: string }> = {
+  anthropic: { strong: "claude-opus-4-8", mid: "claude-sonnet-4-6", cheap: "claude-haiku-4-5" },
+  openai: { strong: "gpt-5.6-sol", mid: "gpt-5.6-terra", cheap: "gpt-5.6-luna" },
+  google: { strong: "gemini-3.1-pro-preview", mid: "gemini-3.1-pro-preview", cheap: "gemini-3-flash-preview" },
+};
+
+const CAP_STRENGTH: Record<Capability, "strong" | "mid" | "cheap"> = {
+  plan: "mid",
+  design: "strong",
+  code: "strong",
+  test: "cheap",
+  ops: "strong",
+};
+
+/** A registry where every capability routes to one provider's models. */
+export function lockRegistryToProvider(provider: Provider): RegistryEntry[] {
+  const m = PROVIDER_MODELS[provider];
+  const caps: Capability[] = ["plan", "design", "code", "test", "ops"];
+  const tiers = ["fast", "mid", "high"] as const;
+  const out: RegistryEntry[] = [];
+  for (const capability of caps) {
+    const modelId = m[CAP_STRENGTH[capability]];
+    for (const tier of tiers) {
+      out.push({
+        capability,
+        tier,
+        byBackend: { web: { provider, model: modelId }, api: { provider, model: modelId } },
+        updated: "provider-lock",
+      });
+    }
+  }
+  return out;
+}
+
+// ---- the real Pi executor ----
+
+export interface PiExecutorOptions {
+  workspace: string;
+  backend: Backend;
+  authStorage?: AuthStorage;
+  thinkingLevel?: "off" | "low" | "medium" | "high";
+  onEvent?: Parameters<AgentSession["subscribe"]>[0];
+  /** Called when a task falls back from its routed provider to another one. */
+  onFallback?: (info: { taskId: string; from: Provider; to: Provider; model: string }) => void;
+}
+
+// Env vars that hold each provider's key (mirrors run-build's check).
+const ENV_KEYS: Record<Provider, string[]> = {
+  anthropic: ["ANTHROPIC_API_KEY"],
+  openai: ["OPENAI_API_KEY"],
+  google: ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+};
+
+function providersWithKeys(): Provider[] {
+  return (Object.keys(ENV_KEYS) as Provider[]).filter((p) => ENV_KEYS[p].some((k) => process.env[k]));
+}
+
+/** The routed model first, then the same-strength model on every OTHER provider
+ *  that has a key — so a 0-token / errored provider falls back automatically. */
+function fallbackChain(primary: Provider, primaryModel: string, cap: Capability): { provider: Provider; model: string }[] {
+  const chain: { provider: Provider; model: string }[] = [{ provider: primary, model: primaryModel }];
+  for (const p of providersWithKeys()) {
+    if (p === primary) continue;
+    chain.push({ provider: p, model: PROVIDER_MODELS[p][CAP_STRENGTH[cap]] });
+  }
+  return chain;
+}
+
+/** Extract the last assistant text from a session, tolerant of content shape. */
+function lastAssistantText(session: AgentSession): string {
+  const msgs = session.messages as Array<{ role?: string; content?: unknown }>;
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const m = msgs[i];
+    if (m?.role !== "assistant") continue;
+    const c = m.content;
+    if (typeof c === "string") return c;
+    if (Array.isArray(c)) {
+      return c
+        .map((part: unknown) => {
+          if (typeof part === "string") return part;
+          if (part && typeof part === "object" && "text" in part) return String((part as { text: unknown }).text);
+          return "";
+        })
+        .join("")
+        .trim();
+    }
+  }
+  return "";
+}
+
+function listFiles(dir: string): string[] {
+  const out: string[] = [];
+  const skip = new Set([".pi", ".git", "node_modules"]);
+  const walk = (d: string) => {
+    let entries: string[];
+    try {
+      entries = readdirSync(d);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (skip.has(name)) continue;
+      const full = join(d, name);
+      // Tolerate broken symlinks / files removed mid-build; skip, don't abort the run.
+      let st;
+      try { st = statSync(full); } catch { continue; }
+      if (st.isDirectory()) walk(full);
+      else out.push(relative(dir, full));
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+/** Build a real RoleExecutor backed by Pi. Each call spends money. Falls back to
+ *  another key-holding provider when the routed one errors or returns 0 tokens. */
+export function makePiExecutor(opts: PiExecutorOptions): RoleExecutor {
+  const authStorage = opts.authStorage ?? AuthStorage.create();
+
+  // One attempt on a specific provider/model. Returns the result + total tokens
+  // (0 tokens = the provider call didn't really happen → treat as a failure).
+  const runOnce = async (
+    task: Task,
+    contextText: string,
+    provider: Provider,
+    modelId: string,
+  ): Promise<{ result: RoleResult; tokensTotal: number }> => {
+    const registry = ModelRegistry.create(authStorage);
+    const model = resolvePiModel(registry, provider, modelId);
+
+    const isTest = task.capability === "test";
+    const verdictTool = isTest ? buildVerdictTool() : undefined;
+    const checkTool = isTest ? buildCheckTool(opts.workspace) : undefined;
+
+    const { session } = await createAgentSession({
+      model,
+      cwd: opts.workspace,
+      authStorage,
+      modelRegistry: registry,
+      thinkingLevel: opts.thinkingLevel ?? "medium",
+      ...(isTest
+        ? { customTools: [verdictTool!.tool, checkTool!], tools: ["read", "bash", "ls", "grep", "find", "check_app", "submit_verdict"] }
+        : { tools: ["read", "write", "edit", "bash", "ls", "grep", "find"] }),
+    });
+
+    const unsub = opts.onEvent ? session.subscribe(opts.onEvent) : undefined;
+    try {
+      // Give code/test the WHOLE current file tree (not just direct-dep files), so a
+      // dev building one file knows every other file that already exists to wire into.
+      let fullContext = contextText;
+      if (task.capability === "code" || task.capability === "test") {
+        const existing = listFiles(opts.workspace);
+        if (existing.length) {
+          fullContext = [contextText, `Files already in the working directory:\n${existing.map((f) => `  ${f}`).join("\n")}`]
+            .filter(Boolean)
+            .join("\n\n");
+        }
+      }
+      await session.prompt(buildRolePrompt(task, fullContext));
+
+      let verdict = verdictTool?.get();
+      if (isTest && !verdict) {
+        await session.followUp("Call submit_verdict now with your judgement.");
+        verdict = verdictTool?.get();
+      }
+
+      const stats = session.getSessionStats();
+      addSessionCost(stats.cost);
+      // Feed real usage back to sharpen estimates — but only for a real run.
+      if (stats.tokens.total > 0) {
+        const inputTotal = stats.tokens.input + stats.tokens.cacheRead;
+        recordActual(task.capability, task.difficulty, inputTotal, stats.tokens.output, inputTotal > 0 ? stats.tokens.cacheRead / inputTotal : 0);
+      }
+      const result: RoleResult = {
+        finalText: lastAssistantText(session),
+        files: listFiles(opts.workspace),
+        cost: round2(stats.cost),
+        verdict,
+      };
+      return { result, tokensTotal: stats.tokens.total };
+    } finally {
+      unsub?.();
+      session.dispose();
+    }
+  };
+
+  return async ({ task, decision, contextText }) => {
+    const chain = fallbackChain(decision.provider, decision.model.id, task.capability);
+    let lastErr: unknown;
+    for (let i = 0; i < chain.length; i++) {
+      const cand = chain[i]!;
+      try {
+        const att = await runOnce(task, contextText, cand.provider, cand.model);
+        if (att.tokensTotal > 0) {
+          if (i > 0) opts.onFallback?.({ taskId: task.id, from: decision.provider, to: cand.provider, model: cand.model });
+          return att.result;
+        }
+        lastErr = new Error(`${cand.provider}/${cand.model} returned 0 tokens (key likely can't access this model)`);
+      } catch (e) {
+        lastErr = e;
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error("all providers failed");
+  };
+}
+
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+// exported for tests
+export { buildVerdictTool, VerdictSchema, estimateCost, getModel };