@bramburn/pi-model-council 1.6.3 → 1.6.11

package/index.ts

@@ -0,0 +1,304 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { councilInputSchema, secondOpinionInputSchema } from "./schemas.js";
+import type { CouncilInput, SecondOpinionInput } from "./types.js";
+import { CouncilSetupError, OpinionSetupError } from "./types.js";
+import { runCouncil } from "./councilRunner.js";
+import { runSecondOpinion } from "./secondOpinionRunner.js";
+import { parseCouncilCommandArgs, parseSecondOpinionCommandArgs } from "./commandParser.js";
+import {
+  showCurrentSettings,
+  resetSettings,
+  openCouncilSettingsUI,
+  openOpinionSettingsUI,
+} from "./settings-ui.js";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Save the most recent council report under `<cwd>/.pi/council/`. */
+async function saveLatestCouncilReport(cwd: string, markdown: string): Promise<string> {
+  const dir = join(cwd, ".pi", "council");
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, "last-decision.md");
+  await writeFile(path, markdown, "utf8");
+  return path;
+}
+
+/** Save the most recent second-opinion report under `<cwd>/.pi/council/`. */
+async function saveLatestSecondOpinion(cwd: string, markdown: string): Promise<string> {
+  const dir = join(cwd, ".pi", "council");
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, "last-opinion.md");
+  await writeFile(path, markdown, "utf8");
+  return path;
+}
+
+export default function modelCouncilExtension(pi: ExtensionAPI) {
+  // Status keys are namespaced so a long-running /council and a quick /opinion
+  // don't clobber each other's footer message when invoked concurrently.
+  const STATUS_COUNCIL = "model-council:run";
+  const STATUS_OPINION = "model-council:opinion";
+
+  // ── Tools ──────────────────────────────────────────────────────────────────
+
+  // Register the council_decide tool
+  pi.registerTool({
+    name: "council_decide",
+    label: "Model Council Decision",
+    description:
+      "Ask three hard-coded OpenRouter models for a second opinion on a fix, technical question, or architecture decision. Returns a structured plan for the main Pi coding model to implement. This tool does not edit files or run commands.",
+    parameters: councilInputSchema,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const input = params as unknown as CouncilInput;
+
+      try {
+        const result = await runCouncil({
+          input,
+          signal: ctx.signal,
+          onStatus: (message) => ctx.ui.setStatus(STATUS_COUNCIL, message),
+          cwd: ctx.cwd,
+          isProjectTrusted: ctx.isProjectTrusted(),
+          modelRegistry: ctx.modelRegistry,
+        });
+
+        // Save the report so the user can read it later — same artifact the
+        // /council slash command writes, so behaviour is consistent regardless
+        // of which entry point invoked the council.
+        let savedPath: string | undefined;
+        try {
+          savedPath = await saveLatestCouncilReport(ctx.cwd, result.markdown);
+        } catch {
+          // Non-fatal — the tool result still contains the full markdown.
+        }
+
+        const header = savedPath
+          ? `\n_Saved to \`${savedPath}\`_\n\n`
+          : "";
+        return {
+          content: [{ type: "text", text: `${header}${result.markdown}` }],
+          details: {
+            decision: result.decision,
+            rawModelResults: result.rawModelResults,
+            savedPath,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.setStatus(STATUS_COUNCIL, undefined);
+
+        // Show helpful setup instructions for setup errors
+        if (error instanceof CouncilSetupError) {
+          ctx.ui.notify(message, "warning");
+        }
+
+        return {
+          content: [{ type: "text", text: `Model council failed: ${message}` }],
+          details: { error: message },
+          isError: true,
+        };
+      }
+    },
+  });
+
+  // Register the second_opinion tool
+  pi.registerTool({
+    name: "second_opinion",
+    label: "Second Opinion",
+    description:
+      "Get a quick second opinion from a configurable model on a fix, technical question, or architecture decision. Faster than the full council but uses one model.",
+    parameters: secondOpinionInputSchema,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const input = params as unknown as SecondOpinionInput;
+
+      try {
+        const result = await runSecondOpinion({
+          input,
+          signal: ctx.signal,
+          onStatus: (message) => ctx.ui.setStatus(STATUS_OPINION, message),
+          cwd: ctx.cwd,
+          isProjectTrusted: ctx.isProjectTrusted(),
+          modelRegistry: ctx.modelRegistry,
+        });
+
+        let savedPath: string | undefined;
+        try {
+          savedPath = await saveLatestSecondOpinion(ctx.cwd, result.markdown);
+        } catch {
+          // Non-fatal — the tool result still contains the full markdown.
+        }
+
+        const header = savedPath
+          ? `\n_Saved to \`${savedPath}\`_\n\n`
+          : "";
+        return {
+          content: [{ type: "text", text: `${header}${result.markdown}` }],
+          details: {
+            opinion: result.opinion,
+            savedPath,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+
+        ctx.ui.setStatus(STATUS_OPINION, undefined);
+
+        if (error instanceof OpinionSetupError) {
+          ctx.ui.notify(message, "warning");
+        }
+
+        return {
+          content: [{ type: "text", text: `Second opinion failed: ${message}` }],
+          details: { error: message },
+          isError: true,
+        };
+      }
+    },
+  });
+
+  // ── Commands ───────────────────────────────────────────────────────────────
+
+  // Register the /council command
+  pi.registerCommand("council", {
+    description: "Ask the model council: /council [ask|fix|architecture] \"problem\"",
+    handler: async (args, ctx) => {
+      try {
+        const input = parseCouncilCommandArgs(args);
+
+        ctx.ui.setStatus(STATUS_COUNCIL, "Council: starting...");
+
+        const result = await runCouncil({
+          input,
+          signal: ctx.signal,
+          onStatus: (message) => ctx.ui.setStatus(STATUS_COUNCIL, message),
+          cwd: ctx.cwd,
+          isProjectTrusted: ctx.isProjectTrusted(),
+          modelRegistry: ctx.modelRegistry,
+        });
+
+        await saveLatestCouncilReport(ctx.cwd, result.markdown);
+
+        // Notify user
+        ctx.ui.notify("Model council complete. Report saved to .pi/council/last-decision.md", "info");
+
+        ctx.ui.setStatus(STATUS_COUNCIL, undefined);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.setStatus(STATUS_COUNCIL, undefined);
+        if (error instanceof CouncilSetupError) {
+          ctx.ui.notify(message, "warning");
+        } else {
+          ctx.ui.notify(`Model council failed: ${message}`, "error");
+        }
+      }
+    },
+  });
+
+  // Register the /opinion command
+  pi.registerCommand("opinion", {
+    description: 'Get a second opinion: /opinion [fix|ask|architecture|general] "problem"',
+    handler: async (args, ctx) => {
+      try {
+        const input = parseSecondOpinionCommandArgs(args);
+
+        ctx.ui.setStatus(STATUS_OPINION, "Second opinion: starting...");
+
+        const result = await runSecondOpinion({
+          input,
+          signal: ctx.signal,
+          onStatus: (message) => ctx.ui.setStatus(STATUS_OPINION, message),
+          cwd: ctx.cwd,
+          isProjectTrusted: ctx.isProjectTrusted(),
+          modelRegistry: ctx.modelRegistry,
+        });
+
+        await saveLatestSecondOpinion(ctx.cwd, result.markdown);
+
+        // Notify user
+        ctx.ui.notify("Second opinion complete. Report saved to .pi/council/last-opinion.md", "info");
+
+        ctx.ui.setStatus(STATUS_OPINION, undefined);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.setStatus(STATUS_OPINION, undefined);
+        if (error instanceof OpinionSetupError) {
+          ctx.ui.notify(message, "warning");
+        } else {
+          ctx.ui.notify(`Second opinion failed: ${message}`, "error");
+        }
+      }
+    },
+  });
+
+  // Register the /council-settings command
+  pi.registerCommand("council-settings", {
+    description:
+      "Configure model council: /council-settings [list|reset] — opens interactive UI by default",
+    handler: async (args, ctx) => {
+      const normalizedArgs = args?.trim().toLowerCase() ?? "";
+
+      if (normalizedArgs === "list") {
+        await showCurrentSettings(ctx);
+        return;
+      }
+
+      if (normalizedArgs === "reset") {
+        const confirmed = await ctx.ui.confirm(
+          "Reset Council Settings",
+          "This will clear the 3 council models, the synthesis model, and the OpenRouter API key. Your opinion model is kept. Continue?",
+        );
+        if (confirmed) {
+          await resetSettings(ctx, "council");
+        }
+        return;
+      }
+
+      // Default: open settings UI
+      await openCouncilSettingsUI(ctx);
+    },
+  });
+
+  // Register the /opinion-settings command
+  pi.registerCommand("opinion-settings", {
+    description:
+      "Configure second opinion model: /opinion-settings [list|reset] — opens interactive UI by default",
+    handler: async (args, ctx) => {
+      const normalizedArgs = args?.trim().toLowerCase() ?? "";
+
+      if (normalizedArgs === "list") {
+        // Show opinion model from settings
+        const { formatSettingsForDisplay } = await import("./settings.js");
+        const { loadSettings } = await import("./settings.js");
+        const settings = await loadSettings(ctx.cwd, ctx.isProjectTrusted());
+        const lines = formatSettingsForDisplay(settings);
+        const output = lines.slice(3, 5).join("\n"); // Opinion line only
+        ctx.ui.notify(output, "info");
+        return;
+      }
+
+      if (normalizedArgs === "reset") {
+        const { loadSettings, saveSettings, createDefaultSettings } = await import("./settings.js");
+        const defaults = createDefaultSettings();
+        const confirmed = await ctx.ui.confirm(
+          "Reset Opinion Settings",
+          `Reset opinion model to default (${defaults.opinion.provider}/${defaults.opinion.modelId})?`,
+        );
+        if (confirmed) {
+          const existing = await loadSettings(ctx.cwd, ctx.isProjectTrusted());
+          const settings = existing ?? createDefaultSettings();
+          // Source the opinion model from createDefaultSettings() so the
+          // command stays in lock-step with the rest of the codebase.
+          settings.opinion = { ...defaults.opinion };
+          settings.lastUpdated = new Date().toISOString();
+          await saveSettings(settings, ctx.cwd, ctx.isProjectTrusted());
+          ctx.ui.notify(
+            `Opinion model reset to ${defaults.opinion.provider}/${defaults.opinion.modelId}`,
+            "info",
+          );
+        }
+        return;
+      }
+
+      // Default: open opinion settings UI
+      await openOpinionSettingsUI(ctx);
+    },
+  });
+}

package/markdown.ts

@@ -0,0 +1,113 @@
+import type { CouncilDecision } from "./types.js";
+
+export function renderCouncilDecisionMarkdown(decision: CouncilDecision): string {
+  const lines: string[] = [];
+
+  lines.push("# Model Council Decision");
+  lines.push("");
+  lines.push("Generated by: model-council");
+  lines.push("");
+
+  // Add degraded mode warning if applicable
+  if (decision.metadata?.degraded) {
+    lines.push("> **Warning:** This council decision used degraded mode. Some model outputs failed, were repaired, or synthesis fell back.");
+    lines.push("");
+  }
+
+  lines.push(`**Mode:** ${decision.mode}`);
+  lines.push(`**Confidence:** ${decision.confidence}`);
+  lines.push(`**Decision ID:** ${decision.decisionId}`);
+  lines.push("");
+
+  // Add system warnings if any
+  if (decision.metadata?.warnings && decision.metadata.warnings.length > 0) {
+    lines.push("## System Warnings");
+    for (const warning of decision.metadata.warnings) {
+      lines.push(`- ${warning}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Recommended Plan");
+  lines.push(decision.recommendedPlan.summary);
+  lines.push("");
+
+  if (decision.recommendedPlan.steps.length > 0) {
+    lines.push("## Steps");
+    for (let i = 0; i < decision.recommendedPlan.steps.length; i++) {
+      lines.push(`${i + 1}. ${decision.recommendedPlan.steps[i]}`);
+    }
+    lines.push("");
+  }
+
+  if (decision.consensus.agreements.length > 0) {
+    lines.push("## Agreements");
+    for (const agreement of decision.consensus.agreements) {
+      lines.push(`- ${agreement}`);
+    }
+    lines.push("");
+  }
+
+  if (decision.consensus.disagreements.length > 0) {
+    lines.push("## Disagreements");
+    for (const disagreement of decision.consensus.disagreements) {
+      lines.push(`- ${disagreement}`);
+    }
+    lines.push("");
+  }
+
+  if (decision.consensus.unknowns.length > 0) {
+    lines.push("## Unknowns");
+    for (const unknown of decision.consensus.unknowns) {
+      lines.push(`- ${unknown}`);
+    }
+    lines.push("");
+  }
+
+  if (decision.implementationGuidance.filesToEdit.length > 0) {
+    lines.push("## Files to Edit");
+    for (const file of decision.implementationGuidance.filesToEdit) {
+      lines.push(`- \`${file.path}\`: ${file.action} — ${file.reason}`);
+    }
+    lines.push("");
+  }
+
+  if (decision.implementationGuidance.testsToRun.length > 0) {
+    lines.push("## Verification / Tests to Run");
+    for (const test of decision.implementationGuidance.testsToRun) {
+      lines.push(`- ${test}`);
+    }
+    lines.push("");
+  }
+
+  if (decision.implementationGuidance.guardrails.length > 0) {
+    lines.push("## Guardrails");
+    for (const guardrail of decision.implementationGuidance.guardrails) {
+      lines.push(`- ${guardrail}`);
+    }
+    lines.push("");
+  }
+
+  if (decision.modelNotes.length > 0) {
+    lines.push("## Model Notes");
+    for (const note of decision.modelNotes) {
+      lines.push(`### ${note.model}`);
+      lines.push(`**Stance:** ${note.stance}`);
+      if (note.keyRisks.length > 0) {
+        lines.push(`**Key Risks:** ${note.keyRisks.join(", ")}`);
+      }
+      lines.push("");
+    }
+  }
+
+  lines.push("## Handoff Prompt");
+  lines.push(decision.handoffPrompt);
+
+  lines.push("");
+  lines.push("***");
+  lines.push("");
+
+  lines.push("This council decision is advisory. The main Pi coding model must still inspect the code, apply changes, and verify with tests.");
+
+  return lines.join("\n");
+}

package/openrouterClient.ts

@@ -0,0 +1,244 @@
+export async function callOpenRouterChat(args: {
+  apiKey: string;
+  model: string;
+  systemPrompt: string;
+  userPrompt: string;
+  signal?: AbortSignal;
+  maxTokens?: number;
+  temperature?: number;
+  structuredOutputSchema?: unknown;
+  structuredOutputName?: string;
+}): Promise<string> {
+  const {
+    apiKey,
+    model,
+    systemPrompt,
+    userPrompt,
+    signal,
+    // 15k tokens for longer responses with file snippets
+    maxTokens = 15000,
+    temperature = 0.2,
+    structuredOutputSchema,
+    structuredOutputName,
+  } = args;
+
+  const requestBody: Record<string, unknown> = {
+    model,
+    messages: [
+      {
+        role: "system",
+        content: systemPrompt,
+      },
+      {
+        role: "user",
+        content: userPrompt,
+      },
+    ],
+    temperature,
+    max_tokens: maxTokens,
+  };
+
+  // Add structured output if schema is provided
+  if (structuredOutputSchema) {
+    requestBody.response_format = {
+      type: "json_schema",
+      json_schema: {
+        name: structuredOutputName ?? "structured_response",
+        strict: true,
+        schema: structuredOutputSchema,
+      },
+    };
+  }
+
+  const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Authorization": `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+      "HTTP-Referer": "https://pi.dev",
+      "X-OpenRouter-Title": "Pi Model Council",
+    },
+    body: JSON.stringify(requestBody),
+    signal,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`OpenRouter API error (${response.status}): ${errorText}`);
+  }
+
+  const data = await response.json() as {
+    choices?: Array<{ message?: { content?: string | null } }>;
+  };
+
+  const content = data.choices?.[0]?.message?.content;
+
+  if (content === null || content === undefined) {
+    throw new Error("No content in response");
+  }
+
+  // Handle array of content parts
+  if (Array.isArray(content)) {
+    return content
+      .filter((part): part is { type: string; text?: string } =>
+        typeof part === "object" && part !== null && part.type === "text"
+      )
+      .map(part => part.text ?? "")
+      .join("");
+  }
+
+  return content;
+}
+
+export function extractJsonObject(text: string): unknown {
+  // First try direct parse
+  try {
+    return JSON.parse(text);
+  } catch {
+    // Continue to fallback methods
+  }
+
+  // Remove markdown code fences
+  const withoutFences = text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "");
+  try {
+    return JSON.parse(withoutFences);
+  } catch {
+    // Continue to substring extraction
+  }
+
+  // Find the first top-level { and its matching closing brace via
+  // brace-balance scan. More robust than the naive "first { to last }"
+  // approach because it handles JSON strings that legitimately contain
+  // closing braces and tolerates truncation when the JSON object is cut
+  // off mid-stream (e.g. max_tokens hit before close).
+  const firstBrace = withoutFences.indexOf("{");
+  if (firstBrace === -1) {
+    throw new Error("No JSON object found in text");
+  }
+
+  const matchedEnd = findMatchingCloseBrace(withoutFences, firstBrace);
+  const substringEnd = matchedEnd ?? withoutFences.lastIndexOf("}");
+  if (substringEnd > firstBrace) {
+    const jsonSubstring = withoutFences.substring(firstBrace, substringEnd + 1);
+    try {
+      return JSON.parse(jsonSubstring);
+    } catch (err) {
+      // Last-ditch: try repairing common LLM JSON mistakes (trailing
+      // commas, single quotes, Python literals) and parsing again.
+      const repaired = repairCommonJsonMistakes(jsonSubstring);
+      try {
+        return JSON.parse(repaired);
+      } catch {
+        throw new Error(
+          `Failed to parse JSON from text. Extracted substring length: ${jsonSubstring.length}; ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
+  throw new Error("No JSON object found in text");
+}
+
+/**
+ * Walk forward from `openIdx` (the index of an opening brace) and return
+ * the index of its matching closing brace, ignoring braces that appear
+ * inside string literals. Returns `null` if no match is found (e.g. the
+ * JSON was truncated before the close brace).
+ */
+function findMatchingCloseBrace(text: string, openIdx: number): number | null {
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+  for (let i = openIdx; i < text.length; i++) {
+    const ch = text[i];
+    if (escape) { escape = false; continue; }
+    if (inString) {
+      if (ch === "\\") { escape = true; continue; }
+      if (ch === '"') { inString = false; }
+      continue;
+    }
+    if (ch === '"') { inString = true; continue; }
+    if (ch === "{") { depth++; continue; }
+    if (ch === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return null;
+}
+
+/**
+ * Minimal repair pass for common LLM JSON mistakes. Conservative by
+ * design — only fixes things that are unambiguously safe so we don't
+ * silently corrupt valid JSON.
+ *
+ * - Replace `True` / `False` / `None` (Python literals) with their JSON
+ *   equivalents.
+ * - Strip trailing commas before `}` or `]`.
+ *
+ * Single-quote strings are intentionally NOT rewritten because doing so
+ * safely requires understanding escape semantics inside the string.
+ */
+function repairCommonJsonMistakes(text: string): string {
+  return text
+    .replace(/\bTrue\b/g, "true")
+    .replace(/\bFalse\b/g, "false")
+    .replace(/\bNone\b/g, "null")
+    .replace(/,(\s*[}\]])/g, "$1");
+}
+
+export function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+// --- OpenRouter discovery & validation ---
+
+export async function fetchOpenRouterModels(apiKey: string): Promise<Array<{ id: string; name: string }>> {
+  const response = await fetch("https://openrouter.ai/api/v1/models", {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch models: ${response.status} ${response.statusText}`);
+  }
+
+  const data = await response.json() as {
+    data: Array<{ id: string; name?: string; created?: number }>;
+  };
+
+  return data.data.map(m => ({
+    id: m.id,
+    name: m.name ?? m.id,
+  }));
+}
+
+export async function pingOpenRouter(apiKey: string): Promise<{
+  ok: boolean;
+  error?: string;
+  quota?: string;
+}> {
+  try {
+    const response = await fetch("https://openrouter.ai/api/v1/models", {
+      headers: { Authorization: `Bearer ${apiKey}` },
+    });
+
+    if (!response.ok) {
+      if (response.status === 401) return { ok: false, error: "Invalid API key" };
+      if (response.status === 403) return { ok: false, error: "Forbidden — check API key permissions" };
+      if (response.status === 429) return { ok: false, error: "Rate limited — try again later" };
+      return { ok: false, error: `HTTP ${response.status}` };
+    }
+
+    // Parse quota from x-current-credits header
+    const quotaHeader = response.headers.get("x-current-credits");
+    const quota = quotaHeader ? `$${parseFloat(quotaHeader).toFixed(2)} remaining` : undefined;
+
+    return { ok: true, quota };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : "Network error" };
+  }
+}