projectinator 0.1.0

package/src/router.ts

@@ -0,0 +1,123 @@
+// The Router — deterministic dispatch. No LLM, no network. Given a tagged task
+// and a policy, it resolves backend -> model -> cost, and flags budget overruns.
+//
+// User prompts (which backend? which model on API?) are injected as callbacks so
+// the router stays pure and unit-testable. In the CLI they wrap real prompts;
+// in tests they're stubs.
+
+import type {
+  Backend,
+  RegistryEntry,
+  RouteDecision,
+  RoutingPolicy,
+  Task,
+} from "./types.js";
+import { estimateCost } from "./cost.js";
+import { getModel } from "./models.js";
+import { findEntry, REGISTRY } from "./registry.js";
+
+export interface RouterPrompts {
+  /** Ask the user which backend to use. Called only when backendMode === "ask". */
+  chooseBackend?: (task: Task) => Backend;
+  /** Ask the user which model on API. Called only when entry.ask && backend === "api".
+   *  Return a model id, or undefined to accept the registry default. */
+  chooseModel?: (task: Task, entry: RegistryEntry, backend: Backend) => string | undefined;
+}
+
+export interface RouteContext {
+  policy: RoutingPolicy;
+  registry?: RegistryEntry[];
+  prompts?: RouterPrompts;
+  /** Cumulative spend before this task, USD. */
+  runningTotalBefore?: number;
+}
+
+/** Resolve which backend to use from the policy (and a prompt, if "ask"). */
+export function resolveBackend(policy: RoutingPolicy, task: Task, prompts?: RouterPrompts): Backend {
+  switch (policy.backendMode) {
+    case "api":
+      return "api";
+    case "web":
+      return "web";
+    case "cost-first":
+      // Web-login rides the user's existing subscription -> effectively free.
+      return "web";
+    case "ask":
+      if (!prompts?.chooseBackend) {
+        throw new Error('backendMode "ask" requires prompts.chooseBackend');
+      }
+      return prompts.chooseBackend(task);
+  }
+}
+
+export function route(task: Task, ctx: RouteContext): RouteDecision {
+  const { policy } = ctx;
+  const registry = ctx.registry ?? REGISTRY;
+  const reasons: string[] = [];
+
+  // 1. Backend.
+  const backend = resolveBackend(policy, task, ctx.prompts);
+  reasons.push(`backend=${backend} (mode=${policy.backendMode})`);
+
+  // 2. Difficulty -> tier.
+  const tier = policy.difficultyToTier[task.difficulty];
+  reasons.push(`difficulty=${task.difficulty} -> tier=${tier}`);
+
+  // 3. Registry lookup (with tier fallback).
+  const { entry, exactTier } = findEntry(task.capability, tier, registry);
+  if (!exactTier) reasons.push(`no ${task.capability}/${tier} entry, fell back to ${entry.tier}`);
+
+  // 4. Backend-conditional model, with optional per-role prompt on API.
+  let modelId = entry.byBackend[backend].model;
+  if (backend === "api" && entry.ask && ctx.prompts?.chooseModel) {
+    const picked = ctx.prompts.chooseModel(task, entry, backend);
+    if (picked && picked !== modelId) {
+      reasons.push(`user overrode model ${modelId} -> ${picked}`);
+      modelId = picked;
+    }
+  }
+  const model = getModel(modelId);
+  reasons.push(`model=${model.id} (${model.provider})`);
+
+  // 5. Cost.
+  const cost = estimateCost(task.estTokens, model);
+  const runningTotal = round2((ctx.runningTotalBefore ?? 0) + cost);
+  const overCap = runningTotal > policy.budgetCapUSD;
+  if (overCap) reasons.push(`OVER CAP: running $${runningTotal} > cap $${policy.budgetCapUSD}`);
+
+  return {
+    taskId: task.id,
+    backend,
+    provider: model.provider,
+    model,
+    tier: entry.tier,
+    cost,
+    runningTotal,
+    overCap,
+    reasons,
+  };
+}
+
+/** Route a whole backlog in order, threading the running total. */
+export function routeBacklog(tasks: Task[], ctx: RouteContext): RouteDecision[] {
+  const out: RouteDecision[] = [];
+  let running = ctx.runningTotalBefore ?? 0;
+  for (const task of tasks) {
+    const decision = route(task, { ...ctx, runningTotalBefore: running });
+    running = decision.runningTotal;
+    out.push(decision);
+  }
+  return out;
+}
+
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+/** A sensible default policy. */
+export const DEFAULT_POLICY: RoutingPolicy = {
+  backendMode: "cost-first",
+  budgetCapUSD: 15,
+  difficultyToTier: { trivial: "fast", low: "mid", medium: "mid", high: "high" },
+  maxFeedbackRounds: 3,
+};

package/src/run-bakeoff.ts

@@ -0,0 +1,77 @@
+// Model bake-off CLI — run one task across models, compare cost/latency/quality.
+//
+//   npm run bakeoff -- --capability design "Design a pricing page with 3 tiers"
+//   npm run bakeoff -- --capability plan "Plan an MVP task list for a URL shortener"
+//   npm run bakeoff -- --models claude-opus-4-8,claude-sonnet-4-6,claude-haiku-4-5 "..."
+//
+// Defaults to the three Anthropic tiers (what most people hold a key for). Add
+// --models to compare any model ids; --provider to set their provider.
+
+import type { Capability, Difficulty, Provider } from "./types.js";
+import { runBakeoff, bakeoffTask, type Candidate } from "./bakeoff.js";
+
+const args = process.argv.slice(2);
+function opt(name: string): string | undefined {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+const capability = (opt("--capability") ?? "design") as Capability;
+const difficulty = (opt("--difficulty") ?? "medium") as Difficulty;
+const provider = (opt("--provider") ?? "anthropic") as Provider;
+const modelsArg = opt("--models");
+const consumed = new Set(["--capability", capability, "--difficulty", difficulty, "--provider", provider, "--models", modelsArg ?? ""].filter(Boolean));
+const prompt = args.filter((a) => !consumed.has(a)).join(" ").trim();
+
+if (!prompt) {
+  console.log('\n  Usage: npm run bakeoff -- --capability design "your task"\n');
+  process.exit(1);
+}
+if (capability === "code") {
+  console.log("\n  Code bake-off isn't supported yet (needs a sandbox + real test scoring per model).");
+  console.log("  Try --capability design or plan for now.\n");
+  process.exit(1);
+}
+
+const models = (modelsArg ?? "claude-opus-4-8,claude-sonnet-4-6,claude-haiku-4-5").split(",").map((s) => s.trim()).filter(Boolean);
+const candidates: Candidate[] = models.map((model) => ({ provider, model }));
+
+console.log(`\n  Bake-off — ${capability}/${difficulty}   ${candidates.length} models\n  Task: ${prompt}\n`);
+
+const result = await runBakeoff(bakeoffTask(prompt, capability, difficulty), candidates, {
+  onProgress: (m) => console.log("  " + m),
+});
+
+// ---- report ----
+const scoreOf = new Map(result.scores.map((s) => [s.model, s]));
+const money = (n: number) => `$${n.toFixed(4)}`;
+console.log("\n  --- RESULTS ---");
+console.log("  model".padEnd(30) + "score".padEnd(8) + "cost".padEnd(12) + "time".padEnd(8) + "tokens");
+for (const e of result.entries) {
+  const key = `${e.provider}/${e.model}`;
+  const sc = scoreOf.get(key);
+  const scoreStr = e.error ? "ERR" : sc ? `${sc.score}/10` : "—";
+  const line =
+    ("  " + e.model).padEnd(30) +
+    scoreStr.padEnd(8) +
+    (e.error ? "—" : money(e.cost)).padEnd(12) +
+    (e.error ? "—" : `${(e.ms / 1000).toFixed(1)}s`).padEnd(8) +
+    (e.error ? "" : String(e.outputTokens));
+  console.log(line);
+  if (e.error) console.log(`      ↳ ${e.error}`);
+}
+
+if (result.winner) {
+  const w = result.entries.find((e) => `${e.provider}/${e.model}` === result.winner);
+  const wc = w?.cost ?? 0;
+  const cheapest = result.entries.filter((e) => !e.error).sort((a, b) => a.cost - b.cost)[0];
+  console.log(`\n  🏆 Best quality: ${result.winner}  (judge: ${result.judge})`);
+  if (cheapest && `${cheapest.provider}/${cheapest.model}` !== result.winner) {
+    console.log(`  💸 Cheapest: ${cheapest.provider}/${cheapest.model} at ${money(cheapest.cost)} (winner cost ${money(wc)})`);
+  }
+  for (const s of result.scores.sort((a, b) => b.score - a.score)) {
+    console.log(`      ${s.score}/10  ${s.model} — ${s.reason}`);
+  }
+}
+console.log("");
+process.exit(0);

package/src/run-build.ts

@@ -0,0 +1,190 @@
+// Phase 4 entry — run a whole build end to end.
+//
+//   npm run build -- "an idea"                 dry: decompose + toposort + routing plan, NO spend
+//   npm run build -- --mini                     dry: tiny fixed 3-task backlog (design->code->test)
+//   npm run build -- --live --mini              LIVE: run the mini backlog (cheap end-to-end)
+//   npm run build -- --live --lock anthropic "an idea"   LIVE: full pipeline on one provider
+//
+// --lock <provider> routes every role to one provider (use the one you hold a key for).
+// Default lock is anthropic.
+
+import { mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { AuthStorage } from "@earendil-works/pi-coding-agent";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { Provider, Task } from "./types.js";
+import { DEFAULT_POLICY } from "./router.js";
+import { toposort, runBacklog, type OrchestratorEvent } from "./orchestrator.js";
+import { lockRegistryToProvider, makePiExecutor } from "./roles.js";
+import { estimateTokens } from "./estimate.js";
+import { route } from "./router.js";
+import { decomposeIdea } from "./pm.js";
+import { newBuildState, saveState, loadState, type BuildState } from "./build-state.js";
+import { initRepo, commitTask } from "./git.js";
+
+const args = process.argv.slice(2);
+const live = args.includes("--live");
+const mini = args.includes("--mini");
+const fan = args.includes("--fan");
+const resume = args.includes("--resume");
+const lockIdx = args.indexOf("--lock");
+const lockProvider = (lockIdx >= 0 ? args[lockIdx + 1] : "anthropic") as Provider;
+const concIdx = args.indexOf("--concurrency");
+const concurrency = Math.max(1, parseInt((concIdx >= 0 ? args[concIdx + 1] : "1") ?? "1", 10) || 1);
+const consumed = new Set(
+  ["--live", "--mini", "--fan", "--resume", "--lock", lockIdx >= 0 ? args[lockIdx + 1] : "",
+    "--concurrency", concIdx >= 0 ? args[concIdx + 1] : ""].filter(Boolean),
+);
+const idea = args.filter((a) => !consumed.has(a)).join(" ").trim() ||
+  "A one-page site with a headline and a contact form.";
+
+const money = (n: number) => `$${n.toFixed(2)}`;
+const registry = lockRegistryToProvider(lockProvider);
+const policy = { ...DEFAULT_POLICY, backendMode: "api" as const, budgetCapUSD: mini ? 10 : 25 };
+
+// --- a tiny fixed backlog for cheap end-to-end proof ---
+function miniBacklog(): Task[] {
+  const mk = (id: string, cap: Task["capability"], diff: Task["difficulty"], title: string, deps: string[] = []): Task => ({
+    id, title, capability: cap, difficulty: diff, dependsOn: deps, estTokens: estimateTokens(cap, diff),
+  });
+  return [
+    mk("D-1", "design", "low", "Write a short design spec for a centered card that says 'Hello from Projectinator' on a soft gradient background."),
+    mk("C-1", "code", "low", "Create index.html implementing the design spec exactly. Single self-contained file with embedded CSS.", ["D-1"]),
+    mk("T-1", "test", "trivial", "Open/read index.html and verify it is valid HTML and matches the design spec (centered card, the headline text, a gradient).", ["C-1"]),
+  ];
+}
+
+// A fan-out backlog with independent branches, to show parallel execution:
+// two design tasks (independent) -> two code tasks -> one test that joins them.
+function fanBacklog(): Task[] {
+  const mk = (id: string, cap: Task["capability"], diff: Task["difficulty"], title: string, deps: string[] = []): Task => ({
+    id, title, capability: cap, difficulty: diff, dependsOn: deps, estTokens: estimateTokens(cap, diff),
+  });
+  return [
+    mk("DA", "design", "low", "Design spec for a 'Newsletter signup' card (email input + button)."),
+    mk("DB", "design", "low", "Design spec for an 'FAQ' accordion (3 questions)."),
+    mk("CA", "code", "low", "Create newsletter.html from the newsletter design spec.", ["DA"]),
+    mk("CB", "code", "low", "Create faq.html from the FAQ design spec.", ["DB"]),
+    mk("TJ", "test", "trivial", "Verify newsletter.html and faq.html are valid and match their specs.", ["CA", "CB"]),
+  ];
+}
+
+async function getTasks(): Promise<Task[]> {
+  if (fan) return fanBacklog();
+  if (mini) return miniBacklog();
+  if (!live) {
+    // Dry + full idea: we can't call the PM without spending, so show the mini path.
+    console.log("  (Full-idea decomposition needs the PM model. Use --mini for a dry preview, or add --live.)\n");
+    return miniBacklog();
+  }
+  console.log("  Decomposing idea with PM...\n");
+  const res = await decomposeIdea(idea, {
+    backend: "api",
+    modelOverride: { provider: lockProvider, model: lockRegistryToProvider(lockProvider).find((e) => e.capability === "plan")!.byBackend.api.model },
+  });
+  console.log(`  PM produced ${res.tasks.length} tasks.\n`);
+  return res.tasks;
+}
+
+const variant = fan ? " / fan" : mini ? " / mini" : "";
+console.log(`\n  Projectinator — Phase 4 full build   [${live ? "LIVE" : "DRY"}${variant}]   lock=${lockProvider}   concurrency=${concurrency}\n`);
+if (!mini && !fan) console.log(`  Idea: ${idea}\n`);
+
+let tasks = await getTasks();
+
+// Dry: show plan only.
+if (!live) {
+  const ordered = toposort(tasks);
+  console.log("  Execution order (toposorted):");
+  let est = 0;
+  for (const t of ordered) {
+    const d = route(t, { policy, registry, runningTotalBefore: est });
+    est = d.runningTotal;
+    const dep = t.dependsOn?.length ? ` <- ${t.dependsOn.join(",")}` : "";
+    console.log(`    ${t.id.padEnd(6)} [${t.capability}/${t.difficulty}] -> ${d.model.name.padEnd(20)} ${money(d.cost)}${dep}`);
+  }
+  console.log(`\n  Estimated total: ${money(est)}   (cap ${money(policy.budgetCapUSD)})`);
+  console.log("  Dry run. Add --live to actually build.\n");
+  process.exit(0);
+}
+
+// Live: key check.
+const envKey: Record<Provider, string[]> = {
+  anthropic: ["ANTHROPIC_API_KEY"],
+  openai: ["OPENAI_API_KEY"],
+  google: ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+};
+if (!(envKey[lockProvider] ?? []).some((k) => process.env[k])) {
+  console.error(`  No API key for ${lockProvider}. Set: ${(envKey[lockProvider] ?? []).join(", ")}\n`);
+  process.exit(1);
+}
+
+const projectRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const workspace = join(projectRoot, ".workspace", fan ? "fan-build" : mini ? "mini-build" : "build");
+mkdirSync(workspace, { recursive: true });
+const statePath = join(workspace, "build-state.json");
+
+// Resume: load prior state, reuse its saved backlog, seed finished outcomes.
+let state: BuildState;
+let seedOutcomes = undefined;
+const prior = resume ? loadState(statePath) : undefined;
+if (prior) {
+  state = prior;
+  state.status = "running";
+  tasks = prior.tasks; // authoritative backlog from the interrupted run
+  seedOutcomes = prior.outcomes;
+  const doneCount = new Set(prior.outcomes.map((o) => o.taskId)).size;
+  console.log(`  Resuming: ${doneCount} task(s) already done, restored ${money(prior.totalCost)}.`);
+} else {
+  if (resume) console.log("  (No prior state found — starting fresh.)");
+  state = newBuildState(fan ? "fan-build" : mini ? "mini-build" : "build", tasks);
+}
+console.log(`  Workspace: ${workspace}\n  Building...\n`);
+
+// Version the workspace + commit after each task.
+initRepo(workspace);
+const titleById = new Map(tasks.map((t) => [t.id, t.title]));
+
+const onEvent = (_e: AgentSessionEvent) => {};
+const executor = makePiExecutor({
+  workspace,
+  backend: "api",
+  onEvent,
+  onFallback: (info) => console.log(`    ↪ ${info.taskId}: ${info.from} failed — fell back to ${info.to}/${info.model}`),
+});
+
+const onProgress = (e: OrchestratorEvent) => {
+  if (e.type === "task_start") console.log(`  ▶ ${e.task.id} [${e.task.capability}] -> ${e.provider}/${e.modelId} (round ${e.round})`);
+  else if (e.type === "task_done") {
+    const hash = commitTask(workspace, e.outcome.taskId, titleById.get(e.outcome.taskId) ?? e.outcome.taskId);
+    console.log(`    ✓ ${e.outcome.taskId} ${money(e.outcome.cost)}  running ${money(e.runningTotal)}${e.outcome.verdict ? `  verdict=${e.outcome.verdict.passed ? "PASS" : "FAIL"}` : ""}${hash ? `  [${hash}]` : ""}`);
+  }
+  else if (e.type === "task_skipped") console.log(`    · ${e.taskId} skipped (already done)`);
+  else if (e.type === "test_failed") console.log(`    ✗ ${e.taskId} FAILED (${e.bugs} bugs) — round ${e.round}`);
+  else if (e.type === "retry_dev") console.log(`    ↻ re-running ${e.taskId} to fix ${e.forTest}`);
+  else if (e.type === "budget_halt") console.log(`    ⚠ BUDGET HALT at ${money(e.runningTotal)} (cap ${money(e.cap)})`);
+};
+
+// Checkpoint after every task so a crash/cancel loses at most one task.
+const onCheckpoint = (outcomes: typeof state.outcomes, totalCost: number) => {
+  state.outcomes = outcomes;
+  state.totalCost = totalCost;
+  saveState(state, statePath);
+};
+
+const result = await runBacklog(tasks, { policy, execute: executor, registry, onProgress, seedOutcomes, onCheckpoint, concurrency });
+
+state.outcomes = result.outcomes;
+state.totalCost = result.totalCost;
+state.status = result.halted ? "halted" : "complete";
+state.haltReason = result.haltReason;
+saveState(state, statePath);
+
+console.log(`\n  --- BUILD ${result.halted ? "HALTED" : "COMPLETE"} ---`);
+console.log(`  Steps run: ${result.outcomes.length}`);
+console.log(`  Total cost: ${money(result.totalCost)}`);
+if (result.haltReason) console.log(`  Halt reason: ${result.haltReason}  (re-run with --resume to continue)`);
+const finalFiles = result.outcomes.at(-1)?.files ?? [];
+console.log(`  Files in workspace: ${finalFiles.join(", ") || "(none)"}`);
+console.log(`  State saved: ${statePath}\n`);

package/src/run-dev.ts

@@ -0,0 +1,83 @@
+// Phase 2 entry — route ONE developer task and (optionally) run it on a real Pi agent.
+//
+//   npm run dev:task            dry run: resolve model + print plan/prompt, NO api call, NO spend
+//   npm run dev:task -- --live  actually run the agent (spends money, needs an API key)
+//
+// Dry mode proves the whole wiring offline. Live mode is opt-in and key-gated.
+
+import { mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { Task } from "./types.js";
+import { DEFAULT_POLICY, route } from "./router.js";
+import { buildDeveloperPrompt, executeTask, resolvePiModel } from "./executor.js";
+
+const TASK: Task = {
+  id: "T-DEV1",
+  story: "S-1",
+  title: "Create a single-file landing page (index.html) for 'Projectinator' with a hero headline, one-line pitch, and a contact form (name, email, message) styled with embedded CSS. No external assets.",
+  capability: "code",
+  difficulty: "high",
+  estTokens: { input: 40_000, output: 12_000, cachedInputFraction: 0.3 },
+};
+
+const live = process.argv.includes("--live");
+
+// Route it. Web-login backend isn't built yet -> use API.
+const policy = { ...DEFAULT_POLICY, backendMode: "api" as const };
+const decision = route(TASK, { policy });
+
+const auth = AuthStorage.create();
+const registry = ModelRegistry.create(auth);
+const piModel = resolvePiModel(registry, decision.provider, decision.model.id); // offline, free
+
+const money = (n: number) => `$${n.toFixed(2)}`;
+
+console.log(`\n  Projectinator — Phase 2 developer run   [${live ? "LIVE" : "DRY"}]\n`);
+console.log(`  Task     ${TASK.id}: ${TASK.title.slice(0, 64)}...`);
+console.log(`  Routed   ${decision.provider}/${decision.model.id}  (tier=${decision.tier}, backend=${decision.backend})`);
+console.log(`  Pi model resolved: ${piModel.id}  ctx=${piModel.contextWindow}  in/out=${piModel.cost?.input}/${piModel.cost?.output}`);
+console.log(`  Est cost ${money(decision.cost)}\n`);
+
+if (!live) {
+  console.log("  --- developer prompt (not sent) ---");
+  console.log(buildDeveloperPrompt(TASK).split("\n").map((l) => "  | " + l).join("\n"));
+  console.log("\n  Dry run only. Wiring verified: task routed, Pi model resolved, prompt built.");
+  console.log("  Re-run with --live (and an API key) to actually build.\n");
+  process.exit(0);
+}
+
+// --- LIVE PATH: spends money ---
+const envKey: Record<string, string[]> = {
+  anthropic: ["ANTHROPIC_API_KEY"],
+  openai: ["OPENAI_API_KEY"],
+  google: ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+};
+const keyPresent = (envKey[decision.provider] ?? []).some((k) => !!process.env[k]);
+if (!keyPresent) {
+  console.error(
+    `  No API key for ${decision.provider}. Set one of: ${(envKey[decision.provider] ?? []).join(", ")}\n`,
+  );
+  process.exit(1);
+}
+
+// fileURLToPath decodes %20/%7E etc. — URL.pathname would leave them encoded and
+// create a literally-named "Mobile%20Documents" directory.
+const projectRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const workspace = join(projectRoot, ".workspace", TASK.id);
+mkdirSync(workspace, { recursive: true });
+console.log(`  Workspace: ${workspace}\n  Running agent...\n`);
+
+const onEvent = (e: AgentSessionEvent) => {
+  process.stdout.write(`  · ${e.type}\n`);
+};
+
+const result = await executeTask(TASK, decision, { workspace, onEvent });
+
+console.log(`\n  --- done ---`);
+console.log(`  Files:   ${result.files.join(", ") || "(none)"}`);
+console.log(`  Tokens:  in=${result.actual.input} out=${result.actual.output} cacheRead=${result.actual.cacheRead} total=${result.actual.total}`);
+console.log(`  Est:     ${money(result.estCost)}`);
+console.log(`  Actual:  ${money(result.actualCost)}   (delta ${money(result.costDelta)})\n`);

package/src/run-pm.ts

@@ -0,0 +1,92 @@
+// Phase 3 entry — decompose an idea into a routed backlog.
+//
+//   npm run pm -- "your idea here"            dry: show PM model + prompt, NO spend
+//   npm run pm -- --live "your idea here"     live: decompose + route the backlog
+//
+// Live decomposition needs an API key (PM routes to an OpenAI model by default).
+
+import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_POLICY, routeBacklog } from "./router.js";
+import { findEntry } from "./registry.js";
+import { resolvePiModel } from "./executor.js";
+import { decomposeIdea, pmSystemPrompt } from "./pm.js";
+
+const args = process.argv.slice(2);
+const live = args.includes("--live");
+
+// Optional PM model override: --pm <provider/id> (e.g. anthropic/claude-sonnet-4-6).
+// Lets you decompose with whichever provider you hold a key for.
+const pmIdx = args.indexOf("--pm");
+const pmOverride = pmIdx >= 0 ? args[pmIdx + 1] : undefined;
+const consumed = new Set<string>(["--live", "--pm", pmOverride].filter(Boolean) as string[]);
+const idea = args.filter((a) => !consumed.has(a)).join(" ").trim() ||
+  "A simple personal task tracker web app: add tasks, mark them done, filter by status.";
+
+const backend = "api" as const; // web-login backend not built yet
+const money = (n: number) => `$${n.toFixed(2)}`;
+
+const auth = AuthStorage.create();
+const registry = ModelRegistry.create(auth);
+const { entry } = findEntry("plan", "mid");
+const pick = pmOverride
+  ? { provider: pmOverride.split("/")[0] as typeof entry.byBackend[typeof backend]["provider"], model: pmOverride.split("/").slice(1).join("/") }
+  : entry.byBackend[backend];
+const pm = resolvePiModel(registry, pick.provider, pick.model); // offline
+
+console.log(`\n  Projectinator — Phase 3 PM decomposer   [${live ? "LIVE" : "DRY"}]\n`);
+console.log(`  Idea:    ${idea}`);
+console.log(`  PM model: ${pick.provider}/${pm.id}  (tier=${entry.tier}, backend=${backend})\n`);
+
+if (!live) {
+  console.log("  --- PM system prompt (not sent) ---");
+  console.log(pmSystemPrompt().split("\n").map((l) => "  | " + l).join("\n"));
+  console.log("\n  Dry run. Re-run with --live (and an API key) to actually decompose.\n");
+  process.exit(0);
+}
+
+const envKey: Record<string, string[]> = {
+  anthropic: ["ANTHROPIC_API_KEY"],
+  openai: ["OPENAI_API_KEY"],
+  google: ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+};
+if (!(envKey[pick.provider] ?? []).some((k) => process.env[k])) {
+  console.error(`  No API key for ${pick.provider}. Set: ${(envKey[pick.provider] ?? []).join(", ")}\n`);
+  process.exit(1);
+}
+
+console.log("  Decomposing...\n");
+const onEvent = (e: AgentSessionEvent) => {
+  if (e.type === "tool_execution_end" || e.type === "agent_end") process.stdout.write(`  · ${e.type}\n`);
+};
+
+const result = await decomposeIdea(idea, {
+  backend,
+  onEvent,
+  modelOverride: pmOverride ? { provider: pick.provider, model: pick.model } : undefined,
+});
+
+console.log(`\n  --- BACKLOG (${result.provider}/${result.modelId}) ---`);
+for (const t of result.backlog.tasks) {
+  const dep = (t.dependsOn ?? []).length ? `  <- ${(t.dependsOn ?? []).join(",")}` : "";
+  const grp = t.epic ? `${t.epic}${t.story ? "/" + t.story : ""}  ` : "";
+  console.log(`  ${t.id.padEnd(6)} [${t.capability}/${t.difficulty}] ${grp}${t.title}${dep}`);
+}
+if (result.diagnostics.length) {
+  console.log(`\n  Normalizer notes:`);
+  for (const d of result.diagnostics) console.log(`    ! ${d}`);
+}
+
+// Route the whole backlog and total the cost.
+const decisions = routeBacklog(result.tasks, { policy: { ...DEFAULT_POLICY, backendMode: backend } });
+console.log(`\n  --- ROUTING PLAN ---`);
+console.log("  " + "TASK".padEnd(7) + "CAP/DIFF".padEnd(16) + "MODEL".padEnd(22) + "COST");
+for (const d of decisions) {
+  const t = result.tasks.find((x) => x.id === d.taskId)!;
+  console.log(
+    "  " + d.taskId.padEnd(7) +
+      `${t.capability}/${t.difficulty}`.padEnd(16) +
+      d.model.name.padEnd(22) + money(d.cost),
+  );
+}
+console.log(`\n  Tasks: ${result.tasks.length}   Estimated total: ${money(decisions.at(-1)?.runningTotal ?? 0)}\n`);

package/src/run-research.ts

@@ -0,0 +1,74 @@
+// Research entry — extract findings from a report, ready for the Scout.
+//
+//   npm run research -- report.txt                    dry: show the extraction plan
+//   npm run research -- report.txt --live             extract via a model, write findings.json
+//   npm run research -- report.txt --live --out f.json --model anthropic/claude-sonnet-4-6
+//
+// Then:  npm run scout -- --from findings.json
+//
+// The report is any benchmark write-up — e.g. save the deep-research harness output to a
+// text file and point this at it.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import type { Provider } from "./types.js";
+import { extractFindings, validateFindings, extractionPrompt } from "./research.js";
+
+const args = process.argv.slice(2);
+const live = args.includes("--live");
+const outIdx = args.indexOf("--out");
+const modelIdx = args.indexOf("--model");
+const modelArg = (modelIdx >= 0 ? args[modelIdx + 1] : undefined) ?? "anthropic/claude-sonnet-4-6";
+const outArg = outIdx >= 0 ? args[outIdx + 1] : undefined;
+
+const consumed = new Set(["--live", "--out", outArg, "--model", modelArg].filter(Boolean) as string[]);
+const reportPath = args.filter((a) => !consumed.has(a))[0];
+
+if (!reportPath) {
+  console.error("\n  Usage: npm run research -- <report.txt> [--live] [--out findings.json] [--model provider/id]\n");
+  process.exit(1);
+}
+
+const projectRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const outPath = outArg ?? join(projectRoot, "findings.json");
+const [provider, ...rest] = modelArg.split("/");
+const modelSpec = { provider: provider as Provider, model: rest.join("/") };
+
+const report = readFileSync(reportPath, "utf-8");
+
+console.log(`\n  Projectinator — Research extractor   [${live ? "LIVE" : "DRY"}]`);
+console.log(`  Report:  ${reportPath} (${report.length} chars)`);
+console.log(`  Model:   ${modelSpec.provider}/${modelSpec.model}`);
+console.log(`  Output:  ${outPath}\n`);
+
+if (!live) {
+  console.log("  --- extraction prompt (not sent, report truncated) ---");
+  console.log(extractionPrompt(report.slice(0, 400) + "\n...[truncated]").split("\n").map((l) => "  | " + l).join("\n"));
+  console.log("\n  Dry run. Add --live (and an API key) to extract.\n");
+  process.exit(0);
+}
+
+const envKey: Record<string, string[]> = {
+  anthropic: ["ANTHROPIC_API_KEY"], openai: ["OPENAI_API_KEY"],
+  google: ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+};
+if (!(envKey[modelSpec.provider] ?? []).some((k) => process.env[k])) {
+  console.error(`  No API key for ${modelSpec.provider}. Set: ${(envKey[modelSpec.provider] ?? []).join(", ")}\n`);
+  process.exit(1);
+}
+
+console.log("  Extracting...\n");
+const findings = await extractFindings(report, { model: modelSpec });
+const { ok, issues } = validateFindings(findings);
+
+console.log(`  Extracted ${findings.length} findings:`);
+for (const f of findings) console.log(`    ${f.capability}/${f.tier} [${f.backend}] -> ${f.provider}/${f.model}`);
+
+if (!ok) {
+  console.log(`\n  Validation issues (fix models.ts or the report before applying):`);
+  for (const i of issues) console.log(`    ! finding ${i.index} (${i.model}): ${i.problem}`);
+}
+
+writeFileSync(outPath, JSON.stringify({ findings }, null, 2) + "\n");
+console.log(`\n  Wrote ${outPath}. Next: npm run scout -- --from ${outPath}\n`);