@bramburn/pi-model-council 1.6.2 → 1.6.11

package/package.json

@@ -1 +1,76 @@
-{"name":"@bramburn/pi-model-council","version":"1.6.2","description":"test","main":"index.js","files":["index.js"]}
+{
+  "name": "@bramburn/pi-model-council",
+  "version": "1.6.11",
+  "description": "Pi extension: multi-model coding decisions via OpenRouter",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "*.ts",
+    "!*.test.ts",
+    "!tsconfig.json",
+    "!vitest.config.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "DISCLAIMER.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SUPPORT.md"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "openrouter",
+    "ai-council"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bramburn/pi-model-council"
+  },
+  "bugs": {
+    "url": "https://github.com/bramburn/pi-model-council/issues"
+  },
+  "homepage": "https://github.com/bramburn/pi-model-council#readme",
+  "engines": {
+    "node": ">=22.14.0",
+    "npm": ">=11.5.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "audit": "npm audit --audit-level=high",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.2.6"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./"
+    ]
+  }
+}

package/prompts.ts

@@ -0,0 +1,299 @@
+import type {
+  CouncilInput,
+  CouncilModelResult,
+  ModelOpinion,
+  SecondOpinionInput,
+} from "./types.js";
+
+export function buildSecondOpinionPrompt(input: SecondOpinionInput): {
+  systemPrompt: string;
+  userPrompt: string;
+} {
+  const mode = input.mode ?? "general";
+  
+  const systemPrompt = `You are a technical coding advisor providing a second opinion.
+Give a practical, implementation-oriented response.
+Be direct and concise. When uncertain, say so.
+Focus on actionable recommendations.
+Return valid JSON in the requested shape.`;
+
+  const userPromptParts: string[] = [];
+
+  userPromptParts.push(`# Second Opinion Request`);
+  userPromptParts.push(`**Mode:** ${mode.toUpperCase()}`);
+  userPromptParts.push("");
+  userPromptParts.push("## Problem");
+  userPromptParts.push(input.problem);
+
+  if (input.currentUnderstanding) {
+    userPromptParts.push("");
+    userPromptParts.push("## Current Understanding");
+    userPromptParts.push(input.currentUnderstanding);
+  }
+
+  if (input.relevantFiles && input.relevantFiles.length > 0) {
+    userPromptParts.push("");
+    userPromptParts.push("## Relevant Files");
+    for (const file of input.relevantFiles) {
+      userPromptParts.push(`- **${file.path}**: ${file.summary}`);
+      if (file.importantSnippets) {
+        userPromptParts.push(`  \`\`\`\n${file.importantSnippets}\n  \`\`\``);
+      }
+    }
+  }
+
+  if (input.constraints && input.constraints.length > 0) {
+    userPromptParts.push("");
+    userPromptParts.push("## Constraints");
+    for (const constraint of input.constraints) {
+      userPromptParts.push(`- ${constraint}`);
+    }
+  }
+
+  if (input.questions && input.questions.length > 0) {
+    userPromptParts.push("");
+    userPromptParts.push("## Specific Questions");
+    for (const question of input.questions) {
+      userPromptParts.push(`- ${question}`);
+    }
+  }
+
+  userPromptParts.push("");
+  userPromptParts.push("Return JSON in this exact shape:");
+  userPromptParts.push(`{
+  "stance": "short position on the approach",
+  "recommendedApproach": "short description of recommended approach",
+  "steps": ["step 1", "step 2"],
+  "filesToConsider": [
+    {
+      "path": "file path",
+      "reason": "why this file is relevant",
+      "suggestedAction": "modify|add|read-only|no-change"
+    }
+  ],
+  "risks": ["risk 1", "risk 2"],
+  "verification": ["test or check to verify"],
+  "confidence": "low|medium|high"
+}`);
+
+  return {
+    systemPrompt,
+    userPrompt: userPromptParts.join("\n"),
+  };
+}
+
+export function buildProposalPrompts(input: CouncilInput): {
+  systemPrompt: string;
+  userPrompt: string;
+} {
+  const systemPrompt = `You are one member of a three-model coding council.
+Your job is to give an independent technical opinion.
+You are not editing code.
+You are advising the main Pi coding agent.
+Be practical, conservative, and implementation-oriented.
+Prefer minimal, testable changes for fixes.
+For architecture questions, prefer clear boundaries, maintainability, and reversible decisions.
+Return ONLY valid JSON matching the requested shape.
+Do not wrap JSON in Markdown.`;
+
+  const userPromptParts: string[] = [];
+
+  userPromptParts.push(`# Council Mode: ${input.mode.toUpperCase()}`);
+  userPromptParts.push("");
+  userPromptParts.push("## Problem");
+  userPromptParts.push(input.problem);
+
+  if (input.currentUnderstanding) {
+    userPromptParts.push("");
+    userPromptParts.push("## Current Understanding");
+    userPromptParts.push(input.currentUnderstanding);
+  }
+
+  if (input.relevantFiles && input.relevantFiles.length > 0) {
+    userPromptParts.push("");
+    userPromptParts.push("## Relevant Files");
+    for (const file of input.relevantFiles) {
+      userPromptParts.push(`- **${file.path}**: ${file.summary}`);
+      if (file.importantSnippets) {
+        userPromptParts.push(`  \`\`\`\n${file.importantSnippets}\n  \`\`\``);
+      }
+    }
+  }
+
+  if (input.constraints && input.constraints.length > 0) {
+    userPromptParts.push("");
+    userPromptParts.push("## Constraints");
+    for (const constraint of input.constraints) {
+      userPromptParts.push(`- ${constraint}`);
+    }
+  }
+
+  if (input.questionsToCouncil && input.questionsToCouncil.length > 0) {
+    userPromptParts.push("");
+    userPromptParts.push("## Questions to Council");
+    for (const question of input.questionsToCouncil) {
+      userPromptParts.push(`- ${question}`);
+    }
+  }
+
+  userPromptParts.push("");
+  userPromptParts.push(`Return JSON in this exact shape:`);
+  userPromptParts.push(`{
+  "stance": "short position on the approach",
+  "recommendedApproach": "short description of recommended approach",
+  "steps": ["step 1", "step 2"],
+  "filesToConsider": [
+    {
+      "path": "file path",
+      "reason": "why this file is relevant",
+      "suggestedAction": "modify|add|read-only|no-change"
+    }
+  ],
+  "risks": ["risk 1", "risk 2"],
+  "verification": ["test or check to verify"],
+  "confidence": "low|medium|high"
+}`);
+
+  return {
+    systemPrompt,
+    userPrompt: userPromptParts.join("\n"),
+  };
+}
+
+export function buildSynthesisPrompts(input: CouncilInput, results: CouncilModelResult[]): {
+  systemPrompt: string;
+  userPrompt: string;
+  /**
+   * Map from blind label (e.g. "Opinion A") to the underlying model id.
+   * Surfaced after the synthesis output so the chairman's reasoning can be
+   * cross-referenced without biasing the synthesis itself.
+   */
+  labelMap: Array<{ label: string; model: string }>;
+} {
+  const systemPrompt = `You are the chair of a coding model council.
+You will receive the original problem and the opinions of three models.
+Synthesize one practical decision for the main Pi coding agent.
+
+Decision rules (apply in order):
+1. Compare options on evidence, not on which model said them. Do NOT
+   over-weight an opinion because of the model name behind it.
+2. Surface disagreements explicitly. Do NOT blend incompatible views
+   into a mushy compromise — pick one side with a reason, or escalate
+   the disagreement as a "to be validated" item.
+3. Do NOT copy any single opinion verbatim. The plan must reflect the
+   council as a whole, even if one model clearly led.
+4. Prefer approaches that are minimal, testable, reversible, and
+   consistent with the supplied constraints.
+5. When confidence is mixed, lower the overall confidence and call it
+   out in the unknowns list.
+
+Return ONLY valid JSON matching the requested CouncilDecision shape.
+Do not wrap JSON in Markdown.`;
+
+  const userPromptParts: string[] = [];
+
+  userPromptParts.push("# Original Problem");
+  userPromptParts.push(`**Mode:** ${input.mode}`);
+  userPromptParts.push(`**Problem:** ${input.problem}`);
+
+  if (input.currentUnderstanding) {
+    userPromptParts.push(`**Current Understanding:** ${input.currentUnderstanding}`);
+  }
+
+  if (input.constraints && input.constraints.length > 0) {
+    userPromptParts.push("**Constraints:**");
+    for (const constraint of input.constraints) {
+      userPromptParts.push(`- ${constraint}`);
+    }
+  }
+
+  userPromptParts.push("");
+  userPromptParts.push("# Model Opinions (presented anonymously to avoid bias)");
+  userPromptParts.push("");
+
+  // Build blind labels (Opinion A / B / C) for the chairman. The mapping
+  // from blind label to model id is returned separately so the agent
+  // that displays the report can correlate notes without leaking it into
+  // the chairman's reasoning context.
+  const labels = ["A", "B", "C", "D", "E", "F"];
+  const labelMap: Array<{ label: string; model: string }> = [];
+  let labelIdx = 0;
+
+  for (const result of results) {
+    const blindLabel = `Opinion ${labels[labelIdx++] ?? `S${labelIdx}`}`;
+    labelMap.push({ label: blindLabel, model: result.model });
+
+    userPromptParts.push(`## ${blindLabel}`);
+    if (result.ok && result.parsed) {
+      const parsed = result.parsed as ModelOpinion;
+      userPromptParts.push(`**Stance:** ${parsed.stance}`);
+      userPromptParts.push(`**Recommended Approach:** ${parsed.recommendedApproach}`);
+      userPromptParts.push(`**Steps:**`);
+      for (const step of parsed.steps) {
+        userPromptParts.push(`  ${parsed.steps.indexOf(step) + 1}. ${step}`);
+      }
+      if (parsed.filesToConsider.length > 0) {
+        userPromptParts.push(`**Files to Consider:**`);
+        for (const file of parsed.filesToConsider) {
+          userPromptParts.push(`  - ${file.path}: ${file.suggestedAction} — ${file.reason}`);
+        }
+      }
+      userPromptParts.push(`**Risks:** ${parsed.risks.join(", ") || "none"}`);
+      userPromptParts.push(`**Verification:** ${parsed.verification.join(", ") || "none"}`);
+      userPromptParts.push(`**Confidence:** ${parsed.confidence}`);
+    } else if (result.ok && result.rawText) {
+      userPromptParts.push("**Response (unstructured):**");
+      userPromptParts.push(result.rawText.substring(0, 500) + (result.rawText.length > 500 ? "..." : ""));
+    } else if (!result.ok && result.error) {
+      userPromptParts.push(`**Error:** ${result.error}`);
+    }
+    userPromptParts.push("");
+  }
+
+  userPromptParts.push("");
+  userPromptParts.push("# Synthesize Council Decision");
+  userPromptParts.push("");
+  userPromptParts.push(`Generate a decisionId using a timestamp-like format (e.g., "council-${Date.now()}").`);
+  userPromptParts.push(`In the \`modelNotes\` array, refer to each opinion by its blind label ("${labelMap[0]?.label ?? "Opinion A"}", etc.) — do NOT include model ids.`);
+  userPromptParts.push("");
+  userPromptParts.push(`Return JSON in this exact shape:`);
+  userPromptParts.push(`{
+  "decisionId": "council-<timestamp>",
+  "mode": "${input.mode}",
+  "confidence": "low|medium|high",
+  "consensus": {
+    "agreements": ["agreed point 1", "agreed point 2"],
+    "disagreements": ["disagreement 1", "disagreement 2"],
+    "unknowns": ["unknown 1", "unknown 2"]
+  },
+  "recommendedPlan": {
+    "summary": "one-sentence summary of the recommended plan",
+    "steps": ["step 1", "step 2", "step 3"]
+  },
+  "implementationGuidance": {
+    "filesToEdit": [
+      {
+        "path": "file path",
+        "reason": "why to edit this file",
+        "action": "specific action to take"
+      }
+    ],
+    "testsToRun": ["test command or check"],
+    "guardrails": ["constraint or warning to follow"]
+  },
+  "modelNotes": [
+    {
+      "model": "Opinion A",
+      "stance": "one-line stance summary",
+      "keyRisks": ["risk 1", "risk 2"]
+    }
+  ],
+  "handoffPrompt": "Concise instruction for the main Pi coding agent: what to do next, what to avoid, and what success looks like."
+}`);
+
+  return {
+    systemPrompt,
+    userPrompt: userPromptParts.join("\n"),
+    labelMap,
+  };
+}

package/retry.ts

@@ -0,0 +1,92 @@
+/**
+ * Timeout and retry helpers for council model calls.
+ */
+
+/**
+ * Execute a promise with a timeout.
+ */
+export async function withTimeout<T>(
+  promiseFactory: (signal: AbortSignal) => Promise<T>,
+  timeoutMs: number,
+  parentSignal?: AbortSignal
+): Promise<T> {
+  const controller = new AbortController();
+
+  // If parent signal aborts, abort child
+  const parentAbortHandler = () => {
+    controller.abort();
+  };
+
+  if (parentSignal) {
+    parentSignal.addEventListener("abort", parentAbortHandler);
+  }
+
+  // Set timeout
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+  }, timeoutMs);
+
+  try {
+    const result = await promiseFactory(controller.signal);
+    return result;
+  } finally {
+    clearTimeout(timeoutId);
+    if (parentSignal) {
+      parentSignal.removeEventListener("abort", parentAbortHandler);
+    }
+  }
+}
+
+/**
+ * Retry an operation with a delay between attempts.
+ */
+export async function retry<T>(args: {
+  attempts: number;
+  delayMs: number;
+  operation: (attempt: number) => Promise<T>;
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+}): Promise<{ value: T; attemptCount: number }> {
+  const { attempts, delayMs, operation, shouldRetry } = args;
+
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      const value = await operation(attempt);
+      return { value, attemptCount: attempt };
+    } catch (error) {
+      lastError = error;
+
+      // Check if we should retry
+      const shouldRetryThis = shouldRetry?.(error, attempt) ?? true;
+
+      if (shouldRetryThis && attempt < attempts) {
+        // Delay before next attempt
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+  }
+
+  // All attempts failed
+  throw lastError;
+}
+
+/**
+ * Check if an error is likely due to structured output not being supported.
+ */
+export function isStructuredOutputError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+
+  const message = error.message.toLowerCase();
+  const indicators = [
+    "response_format",
+    "json_schema",
+    "structured",
+    "unsupported",
+    "does not support",
+    "400",
+    "invalid request",
+  ];
+
+  return indicators.some((indicator) => message.includes(indicator));
+}

package/runnerHelpers.ts

@@ -0,0 +1,130 @@
+/**
+ * Shared helpers used by both the council runner (multi-model fan-out) and
+ * the second-opinion runner (single-model call). Extracted in v1.6.0 so
+ * the two runners share the same auth resolution, parse-then-repair
+ * pipeline, and call-with-timeout wrapping.
+ *
+ * Per Sandi Metz: these are "the same idea" (cross-cutting concerns:
+ * auth, parsing, timeout) so they belong in one place. The orchestration
+ * differences (fan-out vs single-call, synthesis step, fallback decision)
+ * remain in the respective runner files where they belong.
+ */
+
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { CouncilSettings, ModelOpinion } from "./types.js";
+import { callOpenRouterChat } from "./openrouterClient.js";
+import { extractJsonObject } from "./openrouterClient.js";
+import { repairModelOpinion, validateModelOpinion } from "./structuredOutput.js";
+import { withTimeout } from "./retry.js";
+
+/**
+ * Resolve the OpenRouter API key from three sources, in priority order:
+ *
+ *   1. Settings file (`council-settings.json`)
+ *   2. Pi's auth storage (`ctx.modelRegistry.getApiKeyForProvider("openrouter")`)
+ *   3. `process.env.OPENROUTER_API_KEY`
+ *
+ * Returns the trimmed key, or `undefined` if no source yields a key.
+ */
+export async function resolveOpenRouterApiKey(
+  settings: Pick<CouncilSettings, "openRouter">,
+  modelRegistry?: ModelRegistry,
+): Promise<string | undefined> {
+  const fromSettings = settings.openRouter.apiKey?.trim();
+  if (fromSettings) return fromSettings;
+
+  if (modelRegistry) {
+    try {
+      const fromRegistry = await modelRegistry.getApiKeyForProvider("openrouter");
+      const trimmed = fromRegistry?.trim();
+      if (trimmed) return trimmed;
+    } catch {
+      // Registry may not be available in all contexts; fall through.
+    }
+  }
+
+  const fromEnv = process.env.OPENROUTER_API_KEY?.trim();
+  if (fromEnv) return fromEnv;
+
+  return undefined;
+}
+
+/**
+ * Parse a model's raw text response into a `ModelOpinion`, running through
+ * validate → repair → fallback. This consolidates the parse pipeline that
+ * both runners used to inline.
+ *
+ * Returns the parsed opinion and any non-fatal warnings about how it was
+ * recovered. The fallback shape (when even repair fails) preserves the
+ * raw text snippet so the user can still see what the model said.
+ */
+export function parseModelOpinionResponse(rawText: string): {
+  opinion: ModelOpinion;
+  warnings: string[];
+} {
+  try {
+    const jsonObj = extractJsonObject(rawText);
+    const validation = validateModelOpinion(jsonObj);
+
+    if (validation.ok && validation.value) {
+      return { opinion: validation.value, warnings: validation.warnings ?? [] };
+    }
+
+    const repaired = repairModelOpinion(jsonObj, rawText);
+    return { opinion: repaired.value, warnings: repaired.warnings ?? [] };
+  } catch {
+    // Last-ditch fallback: surface the raw text so the user can still see
+    // what the model said, but flag it clearly as unstructured.
+    return {
+      opinion: {
+        stance: "Direct response",
+        recommendedApproach: rawText.substring(0, 500),
+        steps: [],
+        filesToConsider: [],
+        risks: [],
+        verification: [],
+        confidence: "medium",
+      },
+      warnings: ["Response was not structured JSON, showing raw response."],
+    };
+  }
+}
+
+/**
+ * Call OpenRouter with a hard timeout that combines the parent abort
+ * signal (from Pi's extension context) with a per-call deadline.
+ *
+ * Throws with a clear message identifying which model failed, so the
+ * user can distinguish "slow model" from "bad API key" from "network
+ * error" in the runner logs.
+ */
+export async function callModelWithTimeout(args: {
+  apiKey: string;
+  model: string;
+  systemPrompt: string;
+  userPrompt: string;
+  signal?: AbortSignal;
+  timeoutMs: number;
+  structuredOutputSchema?: unknown;
+  structuredOutputName?: string;
+}): Promise<string> {
+  try {
+    return await withTimeout(
+      (childSignal) =>
+        callOpenRouterChat({
+          apiKey: args.apiKey,
+          model: args.model,
+          systemPrompt: args.systemPrompt,
+          userPrompt: args.userPrompt,
+          signal: childSignal,
+          structuredOutputSchema: args.structuredOutputSchema,
+          structuredOutputName: args.structuredOutputName,
+        }),
+      args.timeoutMs,
+      args.signal,
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Model ${args.model} failed: ${message}`, { cause: error });
+  }
+}

package/schemas.ts

@@ -0,0 +1,44 @@
+import { Type } from "@sinclair/typebox";
+
+export const secondOpinionInputSchema = Type.Object({
+  problem: Type.String({
+    description: "The problem, question, or technical decision to get a second opinion on.",
+  }),
+  mode: Type.Optional(Type.Union([
+    Type.Literal("fix"),
+    Type.Literal("ask"),
+    Type.Literal("architecture"),
+    Type.Literal("general"),
+  ])),
+  currentUnderstanding: Type.Optional(Type.String({
+    description: "Your current understanding or proposed approach.",
+  })),
+  relevantFiles: Type.Optional(Type.Array(Type.Object({
+    path: Type.String(),
+    summary: Type.String(),
+    importantSnippets: Type.Optional(Type.String()),
+  }))),
+  constraints: Type.Optional(Type.Array(Type.String())),
+  questions: Type.Optional(Type.Array(Type.String())),
+});
+
+export const councilInputSchema = Type.Object({
+  mode: Type.Union([
+    Type.Literal("fix"),
+    Type.Literal("ask"),
+    Type.Literal("architecture"),
+  ]),
+  problem: Type.String({
+    description: "The problem, question, or architecture decision to ask the council about.",
+  }),
+  currentUnderstanding: Type.Optional(Type.String({
+    description: "The main Pi model's current understanding or proposed approach.",
+  })),
+  relevantFiles: Type.Optional(Type.Array(Type.Object({
+    path: Type.String(),
+    summary: Type.String(),
+    importantSnippets: Type.Optional(Type.String()),
+  }))),
+  constraints: Type.Optional(Type.Array(Type.String())),
+  questionsToCouncil: Type.Optional(Type.Array(Type.String())),
+});