projectinator 0.1.0

package/src/intake.ts

@@ -0,0 +1,129 @@
+// Intake — the PM's clarifying-questions step. Before planning a vague request,
+// the PM asks 2-4 short questions (each with suggested options) to pin down what
+// to build. A clear request returns no questions and skips straight to planning.
+//
+// Forced structured output, same discipline as pm.ts: one tool, permissive
+// schema, coerced/validated in code.
+
+import {
+  AuthStorage,
+  ModelRegistry,
+  createAgentSession,
+  defineTool,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import type { Backend, Provider } from "./types.js";
+import { findEntry } from "./registry.js";
+import { resolvePiModel } from "./executor.js";
+import { addSessionCost } from "./session-cost.js";
+
+const IntakeSchema = Type.Object(
+  {
+    needsClarification: Type.Boolean({ description: "true only if the request is too vague to plan well" }),
+    questions: Type.Array(
+      Type.Object(
+        {
+          question: Type.String({ description: "one short clarifying question" }),
+          options: Type.Array(Type.String(), { description: "2-4 concrete pickable answers; may be empty for free text" }),
+          multi: Type.Boolean({ description: "true if several options can apply at once" }),
+        },
+        { additionalProperties: true },
+      ),
+      { description: "empty when needsClarification is false; at most 4" },
+    ),
+  },
+  { additionalProperties: true },
+);
+type IntakeRaw = Static<typeof IntakeSchema>;
+
+export interface IntakeQuestion {
+  question: string;
+  options: string[];
+  multi: boolean;
+}
+
+function buildIntakeTool() {
+  let captured: IntakeRaw | undefined;
+  const tool = defineTool({
+    name: "submit_intake",
+    label: "Submit Intake",
+    description: "Submit whether clarification is needed and, if so, the clarifying questions. Call exactly once.",
+    parameters: IntakeSchema,
+    execute: async (_id, params) => {
+      captured = params as IntakeRaw;
+      return { content: [{ type: "text", text: `Intake: ${params.needsClarification ? `${params.questions.length} questions` : "clear"}.` }], details: {} };
+    },
+  });
+  return { tool, get: () => captured };
+}
+
+const SYSTEM = [
+  "You are the PROJECT MANAGER doing intake for a build request.",
+  "If the request already has enough detail to plan and build — its purpose and the",
+  "must-have features are clear or reasonably inferable — set needsClarification=false",
+  "and questions=[].",
+  "If it is vague (a bare template like 'landing page', a one-liner missing the",
+  "essentials), set needsClarification=true and produce 2-4 SHORT questions that most",
+  "reduce ambiguity: what the product/business actually is, a name, must-have",
+  "sections/features, and style. For each question give 2-4 concrete pickable options;",
+  "set multi=true when several can apply (e.g. which sections). Never more than 4",
+  "questions. Do not ask what you can reasonably assume. Call submit_intake exactly once.",
+].join("\n");
+
+export interface AssessOptions {
+  backend: Backend;
+  modelOverride?: { provider: Provider; model: string };
+}
+
+/** Ask the PM whether the request needs clarification; returns up to 4 questions
+ *  (empty = clear enough to plan directly). Never throws — returns [] on trouble. */
+export async function assessIntake(idea: string, opts: AssessOptions): Promise<IntakeQuestion[]> {
+  const authStorage = AuthStorage.create();
+  const registry = ModelRegistry.create(authStorage);
+  const { entry } = findEntry("plan", "mid");
+  const pick = opts.modelOverride ?? entry.byBackend[opts.backend];
+
+  try {
+    const model = resolvePiModel(registry, pick.provider, pick.model);
+    const { tool, get } = buildIntakeTool();
+    const { session } = await createAgentSession({
+      model,
+      authStorage,
+      modelRegistry: registry,
+      thinkingLevel: "low",
+      noTools: "all",
+      customTools: [tool],
+      tools: ["submit_intake"],
+    });
+    try {
+      await session.prompt(`${SYSTEM}\n\n--- REQUEST ---\n${idea}`);
+      let raw = get();
+      if (!raw) {
+        await session.prompt("Call submit_intake now.");
+        raw = get();
+      }
+      addSessionCost(session.getSessionStats().cost);
+      if (!raw || !raw.needsClarification) return [];
+      return (raw.questions ?? [])
+        .slice(0, 4)
+        .map((q) => ({
+          question: String(q.question ?? "").trim(),
+          options: (q.options ?? []).map((o) => String(o).trim()).filter(Boolean).slice(0, 6),
+          multi: !!q.multi,
+        }))
+        .filter((q) => q.question);
+    } finally {
+      session.dispose();
+    }
+  } catch {
+    return []; // never block a build on intake — fall through to planning
+  }
+}
+
+/** Fold the collected answers into the brief the PM will plan from. */
+export function enrichBrief(idea: string, answers: { question: string; answer: string }[]): string {
+  const kept = answers.filter((a) => a.answer.trim());
+  if (!kept.length) return idea;
+  const lines = kept.map((a) => `- ${a.question} ${a.answer.trim()}`);
+  return `${idea}\n\nClarifications from the requester:\n${lines.join("\n")}`;
+}

package/src/models.ts

@@ -0,0 +1,92 @@
+// Model pricing table. Rates USD per 1,000,000 tokens (verified July 2026).
+// Shape mirrors Pi's models.json `cost` block so this ports to Pi later.
+// cacheRead ~= 0.1x input, cacheWrite ~= 1.25x input (Anthropic-style; approximations
+// for models whose exact cache rates we haven't pinned — refine against provider docs).
+
+import type { Model } from "./types.js";
+
+export const MODELS: Record<string, Model> = {
+  // ---- OpenAI: GPT-5.6 family ----
+  "gpt-5.6-sol": {
+    id: "gpt-5.6-sol",
+    provider: "openai",
+    name: "GPT-5.6 Sol",
+    contextWindow: 272_000,
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 6.25 },
+  },
+  "gpt-5.6-terra": {
+    id: "gpt-5.6-terra",
+    provider: "openai",
+    name: "GPT-5.6 Terra",
+    contextWindow: 272_000,
+    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 3.125 },
+  },
+  "gpt-5.6-luna": {
+    id: "gpt-5.6-luna",
+    provider: "openai",
+    name: "GPT-5.6 Luna",
+    contextWindow: 272_000,
+    cost: { input: 1, output: 6, cacheRead: 0.1, cacheWrite: 1.25 },
+  },
+
+  // ---- Anthropic: Claude ----
+  "claude-fable-5": {
+    id: "claude-fable-5",
+    provider: "anthropic",
+    name: "Claude Fable 5",
+    contextWindow: 1_000_000,
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+  },
+  "claude-opus-4-8": {
+    id: "claude-opus-4-8",
+    provider: "anthropic",
+    name: "Claude Opus 4.8",
+    contextWindow: 1_000_000,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+  },
+  "claude-sonnet-4-6": {
+    id: "claude-sonnet-4-6",
+    provider: "anthropic",
+    name: "Claude Sonnet 4.6",
+    contextWindow: 1_000_000,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+  },
+  "claude-haiku-4-5": {
+    id: "claude-haiku-4-5",
+    provider: "anthropic",
+    name: "Claude Haiku 4.5",
+    contextWindow: 200_000,
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+  },
+
+  // ---- Google: Gemini ----
+  // NOTE: ids match Pi's built-in registry exactly (provider "google"), so they
+  // resolve directly via ModelRegistry.find() with no alias layer.
+  "gemini-3.1-pro-preview": {
+    id: "gemini-3.1-pro-preview",
+    provider: "google",
+    name: "Gemini 3.1 Pro",
+    contextWindow: 1_000_000,
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      // Google charges more past 200k input tokens.
+      tiers: [{ inputTokensAbove: 200_000, input: 4, output: 18, cacheRead: 0.4, cacheWrite: 5 }],
+    },
+  },
+  "gemini-3-flash-preview": {
+    id: "gemini-3-flash-preview",
+    provider: "google",
+    name: "Gemini 3 Flash",
+    contextWindow: 1_000_000,
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+  },
+};
+
+export function getModel(id: string): Model {
+  const m = MODELS[id];
+  if (!m) throw new Error(`Unknown model id: "${id}". Add it to src/models.ts.`);
+  return m;
+}

package/src/narrate.ts

@@ -0,0 +1,91 @@
+// AI narrative for a build retro. Feeds the data-driven RetroReport to a model
+// and gets back a short "what went well / what to improve" write-up. On-demand
+// (costs a small call) and cached on the build state by the caller.
+
+import {
+  AuthStorage,
+  ModelRegistry,
+  createAgentSession,
+  type AgentSession,
+} from "@earendil-works/pi-coding-agent";
+import type { Backend, Provider } from "./types.js";
+import type { RetroReport } from "./retro.js";
+import { findEntry } from "./registry.js";
+import { resolvePiModel } from "./executor.js";
+import { addSessionCost } from "./session-cost.js";
+
+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((p: unknown) => (typeof p === "string" ? p : p && typeof p === "object" && "text" in p ? String((p as { text: unknown }).text) : ""))
+        .join("")
+        .trim();
+    }
+  }
+  return "";
+}
+
+/** Compact fact sheet the model reasons over — numbers, not prose. */
+function facts(r: RetroReport): string {
+  const lines = [
+    `Idea: ${r.idea}`,
+    `Status: ${r.status}. Tasks done: ${r.doneCount}/${r.taskCount}.`,
+    `Cost: predicted $${r.estCost.toFixed(2)}, actual $${r.totalCost.toFixed(2)}.`,
+    `Tests: ${r.tests.passed} passed, ${r.tests.failed} failed.`,
+    r.retries.length ? `Rebuilds: ${r.retries.map((x) => `${x.taskId}×${x.rounds}`).join(", ")}.` : "Rebuilds: none.",
+    `Cost by epic: ${r.byEpic.map((e) => `${e.epic} $${e.cost}`).join(", ") || "n/a"}.`,
+    `Cost by model: ${r.byModel.map((m) => `${m.model} $${m.cost} (${m.tasks})`).join(", ") || "n/a"}.`,
+    `Priciest tasks: ${r.topCost.map((t) => `${t.taskId} $${t.cost}`).join(", ") || "n/a"}.`,
+    r.bugs.length
+      ? `Tester flags: ${r.bugs.map((b) => `[${b.severity}] ${b.description}`).slice(0, 6).join("; ")}.`
+      : "Tester flags: none.",
+  ];
+  return lines.join("\n");
+}
+
+const PROMPT = [
+  "You are a pragmatic engineering lead writing a SHORT retro for this build.",
+  "Use the facts below — reference the actual numbers. Do not invent anything.",
+  "Write exactly three sections, terse bullets, under 140 words total:",
+  "**What went well** (2-3 bullets)",
+  "**What to improve** (2-3 bullets)",
+  "**Next time** (one line)",
+  "No preamble, no closing remarks.",
+].join("\n");
+
+export interface NarrateOptions {
+  backend: Backend;
+  modelOverride?: { provider: Provider; model: string };
+}
+
+/** Generate the narrative. Throws on failure (caller shows the error). */
+export async function narrateRetro(report: RetroReport, opts: NarrateOptions): Promise<string> {
+  const authStorage = AuthStorage.create();
+  const registry = ModelRegistry.create(authStorage);
+  const { entry } = findEntry("plan", "mid");
+  const pick = opts.modelOverride ?? entry.byBackend[opts.backend];
+  const model = resolvePiModel(registry, pick.provider, pick.model);
+
+  const { session } = await createAgentSession({
+    model,
+    authStorage,
+    modelRegistry: registry,
+    thinkingLevel: "low",
+    noTools: "all",
+  });
+  try {
+    await session.prompt(`${PROMPT}\n\n--- FACTS ---\n${facts(report)}`);
+    const text = lastAssistantText(session);
+    if (!text) throw new Error("The model returned no narrative.");
+    return text;
+  } finally {
+    addSessionCost(session.getSessionStats().cost);
+    session.dispose();
+  }
+}

package/src/orchestrator.ts

@@ -0,0 +1,271 @@
+// Phase 4 — the Orchestrator. Runs a whole backlog end to end.
+//
+// - Topologically orders tasks by dependsOn (respects design->code->test->deploy).
+// - Threads handoff context: a task sees the final output of its dependencies.
+// - Runs a Tester -> Developer feedback loop, bounded by maxFeedbackRounds.
+// - Tracks cost and halts on the budget cap.
+//
+// The executor is INJECTED (RoleExecutor), so this entire control flow is testable
+// offline with a fake — no model, no spend. The real Pi executor lives in roles.ts.
+
+import type {
+  RegistryEntry,
+  RoleExecutor,
+  RoutingPolicy,
+  Task,
+  TaskOutcome,
+} from "./types.js";
+import { route } from "./router.js";
+import { REGISTRY } from "./registry.js";
+
+/** Order tasks so every task comes after its dependencies. Throws on a cycle. */
+export function toposort(tasks: Task[]): Task[] {
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+  const state = new Map<string, "visiting" | "done">();
+  const out: Task[] = [];
+
+  const visit = (t: Task, trail: string[]) => {
+    const s = state.get(t.id);
+    if (s === "done") return;
+    if (s === "visiting") {
+      throw new Error(`Dependency cycle: ${[...trail, t.id].join(" -> ")}`);
+    }
+    state.set(t.id, "visiting");
+    for (const dep of t.dependsOn ?? []) {
+      const d = byId.get(dep);
+      if (d) visit(d, [...trail, t.id]); // unknown deps already stripped by normalize
+    }
+    state.set(t.id, "done");
+    out.push(t);
+  };
+
+  for (const t of tasks) visit(t, []);
+  return out;
+}
+
+export interface RunOptions {
+  policy: RoutingPolicy;
+  execute: RoleExecutor;
+  /** Registry to route against. Swap this to lock every role to one provider. */
+  registry?: RegistryEntry[];
+  onProgress?: (event: OrchestratorEvent) => void;
+  /** Prior outcomes to resume from (append-only record). Their tasks are skipped. */
+  seedOutcomes?: TaskOutcome[];
+  /** Called after each task settles, with the full record + running total, for persistence. */
+  onCheckpoint?: (outcomes: TaskOutcome[], totalCost: number) => void;
+  /** Max tasks to run at once. 1 (default) = sequential. >1 runs independent tasks in parallel. */
+  concurrency?: number;
+  /** Optional human gate before development begins (design done → dev). Resolve "stop" to halt. */
+  onGate?: (info: { stage: string }) => Promise<"continue" | "stop">;
+}
+
+export type OrchestratorEvent =
+  | { type: "task_start"; task: Task; round: number; provider: string; modelId: string }
+  | { type: "task_done"; outcome: TaskOutcome; runningTotal: number }
+  | { type: "task_skipped"; taskId: string }
+  | { type: "test_failed"; taskId: string; bugs: number; round: number }
+  | { type: "retry_dev"; taskId: string; forTest: string; round: number }
+  | { type: "budget_halt"; runningTotal: number; cap: number }
+  | { type: "gate"; stage: string }
+  | { type: "cycle_or_error"; message: string };
+
+export interface RunResult {
+  outcomes: TaskOutcome[];
+  totalCost: number;
+  halted: boolean;
+  haltReason?: string;
+}
+
+/** Build handoff text from a task's dependency outcomes. */
+function gatherContext(task: Task, outcomes: Map<string, TaskOutcome>): string {
+  const deps = task.dependsOn ?? [];
+  if (deps.length === 0) return "";
+  const parts: string[] = [];
+  for (const depId of deps) {
+    const o = outcomes.get(depId);
+    if (!o) continue;
+    const snippet = o.finalText.trim();
+    if (snippet) parts.push(`### From ${depId} (${o.capability}):\n${snippet}`);
+    if (o.files.length) parts.push(`### Files from ${depId}: ${o.files.join(", ")}`);
+  }
+  return parts.length ? `Context from upstream work:\n\n${parts.join("\n\n")}` : "";
+}
+
+function bugReport(bugs: { severity: string; description: string; file?: string }[]): string {
+  return [
+    "The tester found these issues. Fix them, then stop:",
+    ...bugs.map((b) => `- [${b.severity}]${b.file ? ` (${b.file})` : ""} ${b.description}`),
+  ].join("\n");
+}
+
+export async function runBacklog(tasks: Task[], opts: RunOptions): Promise<RunResult> {
+  const { policy, execute } = opts;
+  const registry = opts.registry ?? REGISTRY;
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+  const outcomes = new Map<string, TaskOutcome>();
+  const record: TaskOutcome[] = [];
+  let running = 0;
+
+  // Resume: replay prior outcomes so finished tasks are skipped and cost is restored.
+  const seed = opts.seedOutcomes ?? [];
+  for (const o of seed) {
+    record.push(o);
+    outcomes.set(o.taskId, o); // last wins (retries overwrite)
+    running += o.cost;
+  }
+  running = round2(running);
+  const wasDone = new Set(seed.map((o) => o.taskId));
+
+  const emit = opts.onProgress ?? (() => {});
+  const checkpoint = () => opts.onCheckpoint?.(record, round2(running));
+
+  let ordered: Task[];
+  try {
+    ordered = toposort(tasks);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    emit({ type: "cycle_or_error", message });
+    return { outcomes: [], totalCost: 0, halted: true, haltReason: message };
+  }
+
+  const runOne = async (task: Task, round: number, contextOverride?: string): Promise<TaskOutcome> => {
+    const decision = route(task, { policy, registry, runningTotalBefore: running });
+    emit({ type: "task_start", task, round, provider: decision.provider, modelId: decision.model.id });
+    const contextText = contextOverride ?? gatherContext(task, outcomes);
+    const result = await execute({ task, decision, contextText, round });
+    const outcome: TaskOutcome = {
+      ...result,
+      taskId: task.id,
+      capability: task.capability,
+      provider: decision.provider,
+      modelId: decision.model.id,
+      round,
+    };
+    running += result.cost;
+    outcomes.set(task.id, outcome);
+    record.push(outcome);
+    emit({ type: "task_done", outcome, runningTotal: round2(running) });
+    return outcome;
+  };
+
+  // One task's full lifecycle: run it, then its Tester->Developer feedback loop.
+  const runTaskUnit = async (task: Task): Promise<void> => {
+    let outcome = await runOne(task, 0);
+    if (task.capability === "test" && outcome.verdict && !outcome.verdict.passed) {
+      const codeDeps = (task.dependsOn ?? [])
+        .map((id) => byId.get(id))
+        .filter((t): t is Task => !!t && t.capability === "code");
+
+      let round = 1;
+      while (outcome.verdict && !outcome.verdict.passed && round <= policy.maxFeedbackRounds) {
+        emit({ type: "test_failed", taskId: task.id, bugs: outcome.verdict.bugs.length, round });
+        const fixContext = bugReport(outcome.verdict.bugs);
+        for (const dep of codeDeps) {
+          emit({ type: "retry_dev", taskId: dep.id, forTest: task.id, round });
+          await runOne(dep, round, fixContext);
+        }
+        outcome = await runOne(task, round); // re-test
+        round++;
+      }
+    }
+    checkpoint();
+  };
+
+  // Human gate: pause once before the first development (code) task begins.
+  let gateDone = false;
+  const passGate = async (): Promise<boolean> => {
+    if (gateDone || !opts.onGate) return true;
+    gateDone = true;
+    emit({ type: "gate", stage: "design→dev" });
+    const decision = await opts.onGate({ stage: "design→dev" });
+    return decision !== "stop";
+  };
+
+  const concurrency = Math.max(1, Math.floor(opts.concurrency ?? 1));
+
+  // ---- sequential path (concurrency 1) — unchanged behavior ----
+  if (concurrency === 1) {
+    for (const task of ordered) {
+      if (wasDone.has(task.id)) {
+        emit({ type: "task_skipped", taskId: task.id });
+        continue;
+      }
+      if (task.capability === "code" && !(await passGate())) {
+        checkpoint();
+        return { outcomes: record, totalCost: round2(running), halted: true, haltReason: "stopped at review gate" };
+      }
+      const est = route(task, { policy, registry, runningTotalBefore: running });
+      if (est.overCap) {
+        emit({ type: "budget_halt", runningTotal: round2(running + est.cost), cap: policy.budgetCapUSD });
+        checkpoint();
+        return { outcomes: record, totalCost: round2(running), halted: true, haltReason: "budget cap" };
+      }
+      await runTaskUnit(task);
+    }
+    return { outcomes: record, totalCost: round2(running), halted: false };
+  }
+
+  // ---- parallel path (concurrency > 1) — ready-set scheduler ----
+  // JS is single-threaded, so mutations between awaits are atomic (no locks needed).
+  // Independent tasks (deps satisfied) run concurrently up to `concurrency`. A budget
+  // reservation on in-flight estimates prevents launches that could cross the cap.
+  const remaining = new Set(ordered.filter((t) => !wasDone.has(t.id)).map((t) => t.id));
+  for (const id of wasDone) emit({ type: "task_skipped", taskId: id });
+
+  const inFlight = new Map<string, Promise<void>>();
+  let reserved = 0;
+  let codeInFlight = 0; // code tasks are serialized (they share files) even in parallel mode
+  let halted = false;
+  let haltReason: string | undefined;
+
+  const depsSatisfied = (t: Task) => (t.dependsOn ?? []).every((d) => !remaining.has(d));
+  const readyTasks = () =>
+    ordered.filter((t) => remaining.has(t.id) && !inFlight.has(t.id) && depsSatisfied(t));
+
+  while (remaining.size > 0 && !halted) {
+    // Gate before any development task launches.
+    if (!gateDone && opts.onGate && readyTasks().some((t) => t.capability === "code")) {
+      if (!(await passGate())) {
+        halted = true;
+        haltReason = "stopped at review gate";
+        break;
+      }
+    }
+    for (const task of readyTasks()) {
+      if (inFlight.size >= concurrency) break;
+      // Only one code task builds at a time — they write to the shared workspace.
+      if (task.capability === "code" && codeInFlight >= 1) continue;
+      const est = route(task, { policy, registry, runningTotalBefore: round2(running + reserved) });
+      if (round2(running + reserved + est.cost) > policy.budgetCapUSD) {
+        if (inFlight.size === 0) {
+          emit({ type: "budget_halt", runningTotal: round2(running + est.cost), cap: policy.budgetCapUSD });
+          halted = true;
+          haltReason = "budget cap";
+        }
+        break; // wait for in-flight tasks to free budget/capacity
+      }
+      reserved = round2(reserved + est.cost);
+      const cost = est.cost;
+      const isCode = task.capability === "code";
+      if (isCode) codeInFlight++;
+      const p = runTaskUnit(task).then(() => {
+        if (isCode) codeInFlight--;
+        reserved = round2(reserved - cost);
+        remaining.delete(task.id);
+        inFlight.delete(task.id);
+      });
+      inFlight.set(task.id, p);
+    }
+
+    if (inFlight.size === 0) break; // nothing running and nothing launchable -> done or halted
+    await Promise.race(inFlight.values());
+  }
+
+  await Promise.all(inFlight.values());
+  checkpoint();
+  return { outcomes: record, totalCost: round2(running), halted, haltReason };
+}
+
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}