pi-orchestrator-config 4.1.5

package/extensions/orchestrator/promotion-queue.ts

@@ -0,0 +1,311 @@
+/**
+ * Promotion queue — structured candidates for graduating memories into
+ * skills, enforcement, or project rules.
+ *
+ * Storage: `.pi/memory/promotions.md` (human + agent readable).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+
+export type PromotionDestination =
+  | "memory"
+  | "skill"
+  | "enforcement"
+  | "project_rule"
+  | "discard";
+
+export type PromotionStatus = "proposed" | "applied" | "rejected";
+
+export interface PromotionCandidate {
+  id: string;
+  destination: PromotionDestination;
+  text: string;
+  category: string;
+  reason: string;
+  evidenceCount?: number;
+  status: PromotionStatus;
+  trigger?: string;
+  action?: string;
+  verifier?: string;
+  skillName?: string;
+  skillCreated?: boolean;
+  createdAt: string;
+}
+
+const DESTINATIONS: PromotionDestination[] = [
+  "memory",
+  "skill",
+  "enforcement",
+  "project_rule",
+  "discard",
+];
+
+const STATUSES: PromotionStatus[] = ["proposed", "applied", "rejected"];
+
+export function getPromotionsPath(cwd: string): string {
+  return join(cwd, ".pi", "memory", "promotions.md");
+}
+
+/** Stable id from destination + category + text (dedup key). */
+export function promotionId(
+  destination: PromotionDestination,
+  category: string,
+  text: string,
+): string {
+  return createHash("sha256")
+    .update(`${destination}|${category}|${text}`)
+    .digest("hex")
+    .slice(0, 12);
+}
+
+export function formatPromotionBlock(c: PromotionCandidate): string {
+  const lines = [
+    `### ${c.id}`,
+    `- destination: ${c.destination}`,
+    `- status: ${c.status}`,
+    `- category: ${c.category}`,
+    `- text: ${c.text}`,
+    `- reason: ${c.reason}`,
+    `- created: ${c.createdAt}`,
+  ];
+  if (c.evidenceCount !== undefined) {
+    lines.push(`- evidence_count: ${c.evidenceCount}`);
+  }
+  if (c.trigger) lines.push(`- trigger: ${c.trigger}`);
+  if (c.action) lines.push(`- action: ${c.action}`);
+  if (c.verifier) lines.push(`- verifier: ${c.verifier}`);
+  if (c.skillName) lines.push(`- skill_name: ${c.skillName}`);
+  if (c.skillCreated !== undefined) {
+    lines.push(`- skill_created: ${c.skillCreated ? "true" : "false"}`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+function parseField(block: string, key: string): string | undefined {
+  const re = new RegExp(`^- ${key}: (.+)$`, "m");
+  const m = block.match(re);
+  return m?.[1]?.trim();
+}
+
+export function parsePromotionsMarkdown(content: string): PromotionCandidate[] {
+  if (!content.trim()) return [];
+
+  const chunks = content.split(/^### /m).filter((c) => c.trim());
+  const results: PromotionCandidate[] = [];
+
+  for (const chunk of chunks) {
+    const lines = chunk.trim().split("\n");
+    const id = lines[0]?.trim();
+    if (!id) continue;
+
+    const body = chunk;
+    const destination = parseField(body, "destination") as PromotionDestination | undefined;
+    const status = parseField(body, "status") as PromotionStatus | undefined;
+    const category = parseField(body, "category");
+    const text = parseField(body, "text");
+    const reason = parseField(body, "reason");
+    const createdAt = parseField(body, "created");
+
+    if (!destination || !DESTINATIONS.includes(destination)) continue;
+    if (!status || !STATUSES.includes(status)) continue;
+    if (!category || !text || !reason || !createdAt) continue;
+
+    const evidenceRaw = parseField(body, "evidence_count");
+    const skillCreatedRaw = parseField(body, "skill_created");
+
+    results.push({
+      id,
+      destination,
+      status,
+      category,
+      text,
+      reason,
+      createdAt,
+      evidenceCount: evidenceRaw !== undefined ? Number(evidenceRaw) : undefined,
+      trigger: parseField(body, "trigger"),
+      action: parseField(body, "action"),
+      verifier: parseField(body, "verifier"),
+      skillName: parseField(body, "skill_name"),
+      skillCreated:
+        skillCreatedRaw === undefined
+          ? undefined
+          : skillCreatedRaw === "true",
+    });
+  }
+
+  return results;
+}
+
+export function loadPromotions(cwd: string): PromotionCandidate[] {
+  const path = getPromotionsPath(cwd);
+  if (!existsSync(path)) return [];
+  try {
+    return parsePromotionsMarkdown(readFileSync(path, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+
+export function writePromotions(cwd: string, candidates: PromotionCandidate[]): void {
+  const path = getPromotionsPath(cwd);
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const header =
+    "# Memory Promotion Queue\n\n" +
+    "Candidates for graduating memories into skills, enforcement, or project rules.\n" +
+    "Statuses: `proposed` → `applied` | `rejected`.\n" +
+    "Never auto-write package or project rules — `project_rule` stays proposed until a human applies it.\n\n";
+
+  const body = candidates.map(formatPromotionBlock).join("\n");
+  writeFileSync(path, header + body, "utf-8");
+}
+
+/**
+ * Append new candidates, skipping ids that already exist.
+ * Returns how many were newly added.
+ */
+export function appendPromotions(
+  cwd: string,
+  incoming: PromotionCandidate[],
+): number {
+  const existing = loadPromotions(cwd);
+  const seen = new Set(existing.map((c) => c.id));
+  let added = 0;
+  for (const c of incoming) {
+    if (seen.has(c.id)) continue;
+    existing.push(c);
+    seen.add(c.id);
+    added += 1;
+  }
+  if (added > 0) writePromotions(cwd, existing);
+  return added;
+}
+
+export function updatePromotionStatus(
+  cwd: string,
+  id: string,
+  status: PromotionStatus,
+): boolean {
+  return updatePromotionStatuses(cwd, [{ id, status }]) === 1;
+}
+
+/** Batch status updates — one load/write cycle. Returns how many ids were updated. */
+export function updatePromotionStatuses(
+  cwd: string,
+  updates: { id: string; status: PromotionStatus }[],
+): number {
+  return updatePromotionCandidates(
+    cwd,
+    updates.map((u) => ({ id: u.id, patch: { status: u.status } })),
+  );
+}
+
+/** Mutable fields only — identity keys cannot be patched. */
+export type PromotionCandidatePatch = Partial<
+  Omit<PromotionCandidate, "id" | "destination" | "text" | "category" | "createdAt">
+>;
+
+const IMMUTABLE_PROMOTION_KEYS = new Set([
+  "id",
+  "destination",
+  "text",
+  "category",
+  "createdAt",
+]);
+
+const STRING_PATCH_KEYS = new Set([
+  "reason",
+  "trigger",
+  "action",
+  "verifier",
+  "skillName",
+]);
+
+/** Normalize one patch entry; returns undefined to leave the stored field unchanged. */
+function normalizePatchValue(
+  key: string,
+  value: unknown,
+): unknown | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (key === "status") {
+    return typeof value === "string" && STATUSES.includes(value as PromotionStatus)
+      ? value
+      : undefined;
+  }
+  if (key === "evidenceCount") {
+    return typeof value === "number" && Number.isFinite(value)
+      ? value
+      : undefined;
+  }
+  if (key === "skillCreated") {
+    return typeof value === "boolean" ? value : undefined;
+  }
+  if (STRING_PATCH_KEYS.has(key)) {
+    return typeof value === "string" ? value : undefined;
+  }
+  return undefined;
+}
+
+/** Batch patch promotion candidates — one load/write. Returns how many ids were updated. */
+export function updatePromotionCandidates(
+  cwd: string,
+  updates: { id: string; patch: PromotionCandidatePatch }[],
+): number {
+  if (updates.length === 0) return 0;
+  const existing = loadPromotions(cwd);
+  const byId = new Map(existing.map((c) => [c.id, c]));
+  let n = 0;
+  for (const u of updates) {
+    const entry = byId.get(u.id);
+    if (!entry) continue;
+    const safePatch: PromotionCandidatePatch = {};
+    for (const [key, value] of Object.entries(u.patch)) {
+      if (IMMUTABLE_PROMOTION_KEYS.has(key)) continue;
+      const normalized = normalizePatchValue(key, value);
+      if (normalized === undefined) continue;
+      (safePatch as Record<string, unknown>)[key] = normalized;
+    }
+    if (Object.keys(safePatch).length === 0) continue;
+    Object.assign(entry, safePatch);
+    entry.id = u.id;
+    n += 1;
+  }
+  if (n > 0) writePromotions(cwd, [...byId.values()]);
+  return n;
+}
+
+export function listProposedPromotions(cwd: string): PromotionCandidate[] {
+  return loadPromotions(cwd).filter((c) => c.status === "proposed");
+}
+
+/** Compact section for situation-report injection (~150 tokens). */
+export function formatPromotionsForReport(
+  cwd: string,
+  maxItems: number = 5,
+): string {
+  const proposed = listProposedPromotions(cwd).slice(0, maxItems);
+  if (proposed.length === 0) return "";
+
+  const lines = proposed.map((c) => {
+    const dest =
+      c.destination === "project_rule"
+        ? "project_rule (propose only)"
+        : c.destination;
+    return `- [${dest}] ${c.text}`;
+  });
+
+  const omitted = listProposedPromotions(cwd).length - proposed.length;
+  if (omitted > 0) {
+    lines.push(`- ... ${omitted} more proposed`);
+  }
+
+  return (
+    `## Promotion Candidates\n` +
+    `Open promotions in \`.pi/memory/promotions.md\` — apply safe ones; never auto-write package rules.\n` +
+    lines.join("\n") +
+    "\n"
+  );
+}

package/extensions/orchestrator/resolve-agent-model.ts

@@ -0,0 +1,32 @@
+/**
+ * Resolve effective model/provider for an agent.
+ * Priority: agent_overrides[name] > agent frontmatter > agent_provider/agent_model setting > parent
+ * null in overrides = skip settings, use parent directly.
+ */
+
+import { getSetting } from "./project-settings.js";
+
+export function resolveAgentModelProvider(
+  agentName: string,
+  agent: { model?: string; provider?: string },
+  parentModelId: string | undefined,
+  parentProvider: string | undefined,
+  cwd: string
+): { model: string | undefined; provider: string | undefined } {
+  const overrides = getSetting(cwd, "agent_overrides");
+  const override = overrides[agentName];
+
+  if (override) {
+    // null = explicitly use parent (skip agent frontmatter AND global settings)
+    // Model and provider resolve independently on purpose: a partial override
+    // (e.g. only model) still lets provider fall through frontmatter → settings → parent.
+    const model = override.model === null ? parentModelId : (override.model || agent.model || getSetting(cwd, "agent_model") || parentModelId);
+    const provider = override.provider === null ? parentProvider : (override.provider || agent.provider || getSetting(cwd, "agent_provider") || parentProvider);
+    return { model: model || undefined, provider: provider || undefined };
+  }
+
+  // No override: agent frontmatter > global setting > parent
+  const model = agent.model || getSetting(cwd, "agent_model") || parentModelId;
+  const provider = agent.provider || getSetting(cwd, "agent_provider") || parentProvider;
+  return { model: model || undefined, provider: provider || undefined };
+}

package/extensions/orchestrator/review-ui.ts

@@ -0,0 +1,204 @@
+/**
+ * Review loop status — status bar indicator + transcript cards.
+ *
+ * Status bar: persistent "6-review" key (last in bar, after git).
+ * Cards: durable entry renderers via pi.appendEntry (persist across reload,
+ * no LLM context cost).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { onStateTransition, readReviewState, type ReviewState } from "./pi-config-review-state.js";
+import { ICON_REVIEW_CLEAN, ICON_REVIEW_NEEDED, ICON_REVIEW_PROGRESS, ICON_REVIEW_FINDINGS } from "./icons.js";
+import { getSetting } from "./project-settings.js";
+import { setSlot, clearSlot } from "./status-bar.js";
+
+interface ReviewStatusData {
+  status: ReviewState["status"];
+  cycle: number;
+  findings_count: number;
+  tests_passed: boolean;
+  reviewers_pending: string[];
+  reviewers_total: number;
+  timestamp: number;
+}
+
+// Deduplication — skip append if status+cycle hasn't changed
+let lastAppendedKey = "";
+
+/** Dedup key shared by status bar and transcript cards. */
+function stateKey(s: { status: string; cycle: number; findings_count: number; tests_passed: boolean; reviewers_pending: { length: number } }): string {
+  return `${s.status}:${s.cycle}:${s.findings_count}:${s.tests_passed}:${s.reviewers_pending.length}`;
+}
+
+export function registerReviewUI(pi: ExtensionAPI): void {
+  // Register the entry renderer for "review-status" custom type
+  pi.registerEntryRenderer<ReviewStatusData>("review-status", (entry, { expanded }, theme) => {
+    const data = entry.data ?? {
+      status: "none" as const,
+      cycle: 0,
+      findings_count: 0,
+      tests_passed: false,
+      reviewers_pending: [],
+      reviewers_total: 0,
+      timestamp: Date.now(),
+    };
+
+    if (data.status === "none") {
+      return new Box(0, 0, (text) => text);
+    }
+
+    const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+
+    let line: string;
+    switch (data.status) {
+      case "in_progress": {
+        const testsIcon = data.tests_passed ? "✅" : "⏳";
+        const waiting = data.reviewers_pending.length > 0
+          ? ` — waiting: ${data.reviewers_pending.join(", ")}`
+          : "";
+        line = `🔄 Review cycle ${data.cycle} — ${data.findings_count} findings — tests ${testsIcon}${waiting}`;
+        break;
+      }
+      case "clean": {
+        const testsLabel = data.tests_passed ? "tests passed" : "tests pending";
+        line = `✅ Review clean — cycle ${data.cycle} — ${testsLabel} — ${data.tests_passed ? "ready to commit" : "awaiting tests"}`;
+        break;
+      }
+      case "needs_review":
+        line = `⚠️ Code changed — review needed`;
+        break;
+      case "has_findings":
+        line = `🔍 Review cycle ${data.cycle} — ${data.findings_count} finding${data.findings_count !== 1 ? "s" : ""} — needs fixes`;
+        break;
+      default:
+        line = `📋 Review: ${data.status}`;
+    }
+
+    const colorMap: Record<string, string> = {
+      in_progress: "accent",
+      clean: "success",
+      needs_review: "warning",
+      has_findings: "error",
+    };
+    const color = colorMap[data.status] || "dim";
+    box.addChild(new Text(theme.fg(color, line), 0, 0));
+
+    if (expanded && data.timestamp) {
+      box.addChild(new Text(theme.fg("dim", new Date(data.timestamp).toLocaleString()), 0, 1));
+    }
+
+    return box;
+  });
+
+  // ── Status bar indicator ─────────────────────────────────────────────
+
+  let lastCtx: ExtensionContext | null = null;
+  let lastBarKey = "";
+
+  function updateStatusBar(state: ReviewState): void {
+    if (!lastCtx?.hasUI) return;
+    try {
+      const ctx = lastCtx;
+
+      let label: string;
+      let color: string;
+      switch (state.status) {
+        case "none":
+          clearSlot("review", ctx);
+          lastBarKey = "";
+          return;
+        case "needs_review":
+          label = `${ICON_REVIEW_NEEDED} review needed`;
+          color = "warning";
+          break;
+        case "in_progress": {
+          const pending = state.reviewers_pending.length;
+          const total = state.reviewers_total;
+          label = `${ICON_REVIEW_PROGRESS} review ${total - pending}/${total}`;
+          color = "accent";
+          break;
+        }
+        case "has_findings":
+          label = `${ICON_REVIEW_FINDINGS} ${state.findings_count} finding${state.findings_count !== 1 ? "s" : ""}`;
+          color = "error";
+          break;
+        case "clean":
+          label = state.tests_passed ? `${ICON_REVIEW_CLEAN} ready` : `${ICON_REVIEW_CLEAN} review clean`;
+          color = "success";
+          break;
+        default:
+          label = `${ICON_REVIEW_PROGRESS} ${state.status}`;
+          color = "dim";
+      }
+
+      const barKey = stateKey(state);
+      if (barKey === lastBarKey) return;
+      lastBarKey = barKey;
+      setSlot("review", ctx.ui.theme.fg(color, label), ctx);
+    } catch { /* stale ctx after session replacement */ }
+  }
+
+  // Capture ctx and show current state on load
+  pi.on("session_start", (_event, ctx) => {
+    lastCtx = ctx;
+    if (getSetting(ctx.cwd, "review_loop_enforcement")) {
+      updateStatusBar(readReviewState(ctx.cwd));
+    } else if (ctx.hasUI) {
+      clearSlot("review", ctx);
+      lastBarKey = "";
+    }
+  });
+  pi.on("agent_end", (_event, ctx) => { lastCtx = ctx; });
+
+  // Poll pi-config-review-state.json for cross-process updates (subagents write state too)
+  const reviewPoller = setInterval(() => {
+    if (!lastCtx) return;
+    // Access a ctx property to detect stale/disposed context (throws if invalidated)
+    try { void lastCtx.ui.theme; } catch { lastCtx = null; return; }
+    try {
+      if (!getSetting(lastCtx.cwd, "review_loop_enforcement")) {
+        if (lastCtx.hasUI) clearSlot("review", lastCtx);
+        lastBarKey = "";
+        return;
+      }
+      updateStatusBar(readReviewState(lastCtx.cwd));
+    } catch (e: any) {
+      console.debug("[review-ui] poller error:", e?.message);
+    }
+  }, 5000);
+  if (reviewPoller.unref) reviewPoller.unref();
+
+  pi.on("session_shutdown", () => {
+    clearInterval(reviewPoller);
+  });
+
+  // ── Hook into review state transitions ───────────────────────────────
+
+  onStateTransition((state: ReviewState) => {
+    // Always update status bar (even for "none" — clears it)
+    // Only show if enforcement is enabled
+    if (lastCtx && getSetting(lastCtx.cwd, "review_loop_enforcement")) {
+      updateStatusBar(state);
+    }
+
+    if (state.status === "none") return;
+
+    const data: ReviewStatusData = {
+      status: state.status,
+      cycle: state.cycle,
+      findings_count: state.findings_count,
+      tests_passed: state.tests_passed,
+      reviewers_pending: [...state.reviewers_pending],
+      reviewers_total: state.reviewers_total,
+      timestamp: Date.now(),
+    };
+
+    // Deduplicate transcript cards — skip if nothing meaningful changed
+    const key = stateKey(data);
+    if (key === lastAppendedKey) return;
+    lastAppendedKey = key;
+
+    pi.appendEntry<ReviewStatusData>("review-status", data);
+  });
+}

package/extensions/orchestrator/rule-placeholders.ts

@@ -0,0 +1,12 @@
+/**
+ * Pure placeholder substitution for rules/*.md prompt text.
+ *
+ * Kept in its own module (no heavy imports) so it can be unit tested without
+ * pulling in the full orchestrator dependency chain (e.g. rules.ts → async-agents.ts
+ * → @earendil-works/pi-tui, which is a runtime-only dependency not present in
+ * the test install).
+ */
+
+export function substituteRulePlaceholders(text: string, values: { reviewLoopMaxCycles: number }): string {
+  return text.replaceAll("{{REVIEW_LOOP_MAX_CYCLES}}", String(values.reviewLoopMaxCycles));
+}