hydramcp 1.0.0

package/dist/tools/consensus.js

@@ -0,0 +1,267 @@
+/**
+ * consensus — Ask multiple models, aggregate into a single answer.
+ *
+ * This is the "I need confidence" tool. Instead of getting 5 opinions
+ * and reading them all, you get one answer with a confidence score.
+ *
+ * Strategy options:
+ * - majority:     >50% of models agree
+ * - supermajority: >=66% agree (for higher confidence)
+ * - unanimous:     100% agree (for critical decisions)
+ *
+ * How "agreement" works:
+ * We use a judge model to evaluate whether responses agree semantically.
+ * One of the available models gets picked as a judge (or the user can
+ * specify one). The judge reads all responses and groups them by
+ * agreement. This is way better than keyword matching because it
+ * understands that "start with a monolith" and "monolith, it's simpler"
+ * are the same answer.
+ *
+ * Falls back to naive keyword matching if the judge call fails.
+ */
+import { z } from "zod";
+import { logger } from "../utils/logger.js";
+export const consensusSchema = z.object({
+    models: z
+        .array(z.string())
+        .min(3)
+        .max(7)
+        .describe("List of model IDs to poll (3-7 models)"),
+    prompt: z.string().describe("The prompt to send to all models"),
+    strategy: z
+        .enum(["majority", "supermajority", "unanimous"])
+        .optional()
+        .default("majority")
+        .describe("Voting strategy — how many models must agree"),
+    judge_model: z.string().optional().describe("Optional model ID to use as judge. Auto-picks if not specified."),
+    system_prompt: z.string().optional(),
+    temperature: z.number().min(0).max(2).optional().default(0),
+    max_tokens: z.number().int().positive().optional().default(1024),
+});
+export async function consensus(provider, input) {
+    // Query all models in parallel
+    const results = await Promise.allSettled(input.models.map((model) => provider.query(model, input.prompt, {
+        system_prompt: input.system_prompt,
+        temperature: input.temperature,
+        max_tokens: input.max_tokens,
+    })));
+    const votes = results.map((result, i) => {
+        if (result.status === "fulfilled") {
+            return { model: input.models[i], content: result.value.content };
+        }
+        return {
+            model: input.models[i],
+            content: "",
+            error: result.reason instanceof Error
+                ? result.reason.message
+                : String(result.reason),
+        };
+    });
+    const successful = votes.filter((v) => !v.error);
+    const failed = votes.filter((v) => v.error);
+    if (successful.length < 2) {
+        return `## Consensus Failed\n\nOnly ${successful.length} model(s) responded. Need at least 2 for consensus.\n\nErrors:\n${failed.map((f) => `- ${f.model}: ${f.error}`).join("\n")}`;
+    }
+    const threshold = getThreshold(input.strategy ?? "majority");
+    const requiredVotes = Math.ceil(successful.length * threshold);
+    // Use a judge model to determine agreement
+    const judgeModel = input.judge_model ?? await pickJudge(provider, input.models);
+    let agreeing;
+    let dissenting;
+    let judgeLatency;
+    if (judgeModel) {
+        logger.info(`consensus: using ${judgeModel} as judge`);
+        const judgeStart = Date.now();
+        const judgeResult = await judgeAgreement(provider, judgeModel, successful);
+        judgeLatency = Date.now() - judgeStart;
+        if (judgeResult) {
+            agreeing = judgeResult.agreeing;
+            dissenting = judgeResult.dissenting;
+        }
+        else {
+            // Judge failed, fall back to keyword matching
+            logger.warn("consensus: judge failed, falling back to keyword matching");
+            ({ agreeing, dissenting } = keywordFallback(successful));
+        }
+    }
+    else {
+        logger.warn("consensus: no judge available, using keyword matching");
+        ({ agreeing, dissenting } = keywordFallback(successful));
+    }
+    const reached = agreeing.length >= requiredVotes;
+    return formatConsensus({
+        reached,
+        strategy: input.strategy ?? "majority",
+        agreeing,
+        dissenting,
+        failed,
+        requiredVotes,
+        totalVoters: successful.length,
+        judgeModel,
+        judgeLatency,
+    });
+}
+function getThreshold(strategy) {
+    switch (strategy) {
+        case "majority":
+            return 0.5;
+        case "supermajority":
+            return 0.66;
+        case "unanimous":
+            return 1.0;
+    }
+}
+/**
+ * Pick a judge model. Prefers a model not in the poll list so
+ * there's no conflict of interest. Falls back to first available
+ * if all models are in the poll.
+ */
+async function pickJudge(provider, polledModels) {
+    try {
+        const available = await provider.listModels();
+        if (available.length === 0)
+            return null;
+        // Prefer a model that's NOT being polled
+        const polledSet = new Set(polledModels.map((m) => m.toLowerCase()));
+        const outside = available.find((m) => !polledSet.has(m.id.toLowerCase()) && !polledSet.has(m.id.split("/").pop()?.toLowerCase() ?? ""));
+        if (outside)
+            return outside.id;
+        // Everyone's in the poll. Just use the first available model.
+        return available[0].id;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ask a judge model to group responses by agreement.
+ * Returns the largest agreement group as "agreeing" and the rest as "dissenting".
+ */
+async function judgeAgreement(provider, judgeModel, votes) {
+    const responseSummary = votes
+        .map((v, i) => `Response ${i + 1} (${v.model}):\n${v.content}`)
+        .join("\n\n---\n\n");
+    const judgePrompt = `You are judging whether multiple AI model responses agree with each other.
+
+Here are ${votes.length} responses to the same question:
+
+${responseSummary}
+
+Do these responses fundamentally agree on the same answer/position, even if they use different words or go into different levels of detail?
+
+Reply with ONLY valid JSON in this exact format, no other text:
+{"groups": [[0, 1, 2]], "reasoning": "all three say the same thing"}
+
+Rules:
+- Each group is an array of response numbers (0-indexed)
+- Responses that agree go in the same group
+- If all responses agree, put them all in one group like [[0, 1, 2]]
+- If there are two camps, make two groups like [[0, 1], [2]]
+- Focus on the substance of the answer, not the wording
+- "reasoning" should be one short sentence`;
+    try {
+        const result = await provider.query(judgeModel, judgePrompt, {
+            temperature: 0,
+            max_tokens: 256,
+        });
+        // Parse the judge's JSON response
+        const jsonMatch = result.content.match(/\{[\s\S]*\}/);
+        if (!jsonMatch) {
+            logger.warn("consensus judge: no JSON found in response");
+            return null;
+        }
+        const parsed = JSON.parse(jsonMatch[0]);
+        if (!parsed.groups || !Array.isArray(parsed.groups)) {
+            logger.warn("consensus judge: invalid groups format");
+            return null;
+        }
+        // Find the largest agreement group
+        const groups = parsed.groups;
+        const largest = groups.reduce((a, b) => (a.length >= b.length ? a : b), []);
+        const agreeing = largest.map((i) => votes[i]).filter(Boolean);
+        const agreeingSet = new Set(largest);
+        const dissenting = votes.filter((_, i) => !agreeingSet.has(i));
+        logger.info(`consensus judge: ${agreeing.length}/${votes.length} agree. ${parsed.reasoning ?? ""}`);
+        return { agreeing, dissenting };
+    }
+    catch (err) {
+        logger.warn(`consensus judge failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * Keyword-based fallback when no judge model is available.
+ * Naive but better than nothing.
+ */
+function keywordFallback(votes) {
+    const baseline = votes[0];
+    const agreeing = [baseline];
+    const dissenting = [];
+    for (let i = 1; i < votes.length; i++) {
+        if (responsesAgreeByKeywords(baseline.content, votes[i].content)) {
+            agreeing.push(votes[i]);
+        }
+        else {
+            dissenting.push(votes[i]);
+        }
+    }
+    return { agreeing, dissenting };
+}
+function responsesAgreeByKeywords(a, b) {
+    const wordsA = new Set(a.toLowerCase().split(/\s+/).filter((w) => w.length > 4));
+    const wordsB = new Set(b.toLowerCase().split(/\s+/).filter((w) => w.length > 4));
+    if (wordsA.size === 0 || wordsB.size === 0)
+        return false;
+    let overlap = 0;
+    for (const word of wordsA) {
+        if (wordsB.has(word))
+            overlap++;
+    }
+    const similarity = overlap / Math.max(wordsA.size, wordsB.size);
+    return similarity > 0.3;
+}
+function formatConsensus(result) {
+    const confidence = Math.round((result.agreeing.length / result.totalVoters) * 100);
+    const lines = [
+        `## Consensus: ${result.reached ? "REACHED" : "NOT REACHED"}`,
+        "",
+        `**Strategy:** ${result.strategy} (needed ${result.requiredVotes}/${result.totalVoters})`,
+        `**Agreement:** ${result.agreeing.length}/${result.totalVoters} models (${confidence}%)`,
+        result.judgeModel
+            ? `**Judge:** ${result.judgeModel}${result.judgeLatency ? ` (${result.judgeLatency}ms)` : ""}`
+            : "",
+        "",
+    ];
+    // Show the consensus answer (first agreeing model's response)
+    if (result.agreeing.length > 0) {
+        lines.push("### Consensus Response");
+        lines.push("");
+        lines.push(result.agreeing[0].content);
+        lines.push("");
+        lines.push(`*Agreed by: ${result.agreeing.map((v) => v.model).join(", ")}*`);
+        lines.push("");
+    }
+    // Show what each model actually said so the judge can be sanity-checked
+    const allVotes = [...result.agreeing, ...result.dissenting];
+    if (allVotes.length > 1) {
+        lines.push("### Individual Responses");
+        for (const v of allVotes) {
+            const summary = v.content.slice(0, 150).replace(/\n/g, " ");
+            lines.push(`- **${v.model}:** ${summary}${v.content.length > 150 ? "..." : ""}`);
+        }
+        lines.push("");
+    }
+    // Show dissent
+    if (result.dissenting.length > 0) {
+        lines.push("### Dissenting Views");
+        for (const d of result.dissenting) {
+            lines.push(`- **${d.model}:** ${d.content.slice(0, 200)}${d.content.length > 200 ? "..." : ""}`);
+        }
+        lines.push("");
+    }
+    // Show failures
+    if (result.failed.length > 0) {
+        lines.push(`*${result.failed.length} model(s) failed to respond*`);
+    }
+    return lines.join("\n");
+}

package/dist/tools/session-recap.d.ts

@@ -0,0 +1,38 @@
+/**
+ * session-recap — Two-pass session recap using a large-context model.
+ *
+ * Reads previous Claude Code sessions from disk (server-side), sends them
+ * to a large-context model like Gemini, and returns a smart-sized summary.
+ * Claude never sees the raw session data — only the distilled recap.
+ *
+ * How it works:
+ * 1. Read N recent session JSONL files from ~/.claude/projects/
+ * 2. Parse & filter (keep meaningful content, strip noise + secrets)
+ * 3. PASS 1: Send to model — "triage this, return event counts as JSON"
+ * 4. Calculate summary budget from triage results
+ * 5. PASS 2: Send to model — "write a recap in {budget} tokens"
+ * 6. Return only the recap to Claude
+ */
+import { z } from "zod";
+import { Provider } from "../providers/provider.js";
+export declare const sessionRecapSchema: z.ZodObject<{
+    sessions: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    project: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    max_summary_tokens: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    sessions: number;
+    model?: string | undefined;
+    project?: string | undefined;
+    focus?: string | undefined;
+    max_summary_tokens?: number | undefined;
+}, {
+    model?: string | undefined;
+    sessions?: number | undefined;
+    project?: string | undefined;
+    focus?: string | undefined;
+    max_summary_tokens?: number | undefined;
+}>;
+export type SessionRecapInput = z.infer<typeof sessionRecapSchema>;
+export declare function sessionRecap(provider: Provider, input: SessionRecapInput): Promise<string>;

package/dist/tools/session-recap.js

@@ -0,0 +1,341 @@
+/**
+ * session-recap — Two-pass session recap using a large-context model.
+ *
+ * Reads previous Claude Code sessions from disk (server-side), sends them
+ * to a large-context model like Gemini, and returns a smart-sized summary.
+ * Claude never sees the raw session data — only the distilled recap.
+ *
+ * How it works:
+ * 1. Read N recent session JSONL files from ~/.claude/projects/
+ * 2. Parse & filter (keep meaningful content, strip noise + secrets)
+ * 3. PASS 1: Send to model — "triage this, return event counts as JSON"
+ * 4. Calculate summary budget from triage results
+ * 5. PASS 2: Send to model — "write a recap in {budget} tokens"
+ * 6. Return only the recap to Claude
+ */
+import { z } from "zod";
+import { logger } from "../utils/logger.js";
+import { readSessions, formatSessionsForPrompt, } from "../utils/session-reader.js";
+import { pickLargeContextModel } from "../utils/model-selection.js";
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+export const sessionRecapSchema = z.object({
+    sessions: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .optional()
+        .default(3)
+        .describe("Number of recent sessions to recap (default: 3)"),
+    project: z
+        .string()
+        .optional()
+        .describe("Project path to recap, e.g. 'C:\\\\Users\\\\Beast\\\\Documents\\\\GitHub\\\\MyProject'. Auto-detects most recent project if omitted."),
+    focus: z
+        .string()
+        .optional()
+        .describe("Optional focus area to filter both triage and recap, e.g. 'auth implementation' or 'database migration'. When set, only events related to this topic are counted and summarized."),
+    model: z
+        .string()
+        .optional()
+        .describe("Model to use for recap. Should be a large-context model like Gemini. Auto-picks if omitted."),
+    max_summary_tokens: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Override the auto-calculated summary budget (in tokens). Auto-calculation ranges from 1K to 30K based on session density."),
+});
+// ---------------------------------------------------------------------------
+// Pass 1: Triage
+// ---------------------------------------------------------------------------
+const TRIAGE_SYSTEM_PROMPT = `You are a precise code session analyzer. You read Claude Code conversation transcripts and extract structured metadata. Return ONLY valid JSON, no markdown, no explanation.`;
+function buildTriagePrompt(sessionText, focus) {
+    const focusInstruction = focus
+        ? `\n**FOCUS FILTER:** Only count events, files, decisions, and work related to: "${focus}". Ignore everything unrelated to this topic.\n`
+        : "";
+    return `Analyze these Claude Code session transcripts and return ONLY valid JSON with this exact structure:
+
+{
+  "files_modified": ["src/auth.ts", "src/db.ts"],
+  "decisions_made": [{"summary": "Chose JWT over sessions for auth", "importance": "high"}],
+  "errors_resolved": [{"summary": "Fixed auth redirect loop in middleware", "importance": "medium"}],
+  "features_built": [{"summary": "User login flow with email verification", "status": "complete"}],
+  "unfinished_work": [{"summary": "Database migration script for v2 schema", "priority": "high"}],
+  "total_meaningful_events": 15
+}
+
+Rules:
+- Count only substantive events. Greetings, small talk, and meta-questions are NOT events.
+- A file being created/modified, a bug fixed, an architecture decision, a feature implemented — those ARE events.
+- For files_modified, list unique file paths mentioned in tool calls or discussions.
+- Importance/priority: "high", "medium", or "low".
+- Status: "complete", "partial", or "planned".
+${focusInstruction}
+Session transcripts:
+
+${sessionText}`;
+}
+function parseTriage(response) {
+    try {
+        // Extract JSON from response (handle any preamble/postamble)
+        const jsonMatch = response.match(/\{[\s\S]*\}/);
+        if (!jsonMatch)
+            return null;
+        const parsed = JSON.parse(jsonMatch[0]);
+        return {
+            files_modified: Array.isArray(parsed.files_modified)
+                ? parsed.files_modified
+                : [],
+            decisions_made: Array.isArray(parsed.decisions_made)
+                ? parsed.decisions_made
+                : [],
+            errors_resolved: Array.isArray(parsed.errors_resolved)
+                ? parsed.errors_resolved
+                : [],
+            features_built: Array.isArray(parsed.features_built)
+                ? parsed.features_built
+                : [],
+            unfinished_work: Array.isArray(parsed.unfinished_work)
+                ? parsed.unfinished_work
+                : [],
+            total_meaningful_events: typeof parsed.total_meaningful_events === "number"
+                ? parsed.total_meaningful_events
+                : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Budget calculation
+// ---------------------------------------------------------------------------
+function calculateBudget(triage, totalInputChars, sessionCount) {
+    const inputTokens = Math.ceil(totalInputChars / 4);
+    const eventCount = triage.total_meaningful_events;
+    // Base: 4% of input tokens
+    const baseSummary = inputTokens * 0.04;
+    // Density factor: more events → bigger summary (0.5x to 2.0x)
+    const densityFactor = Math.max(0.5, Math.min(2.0, eventCount / 20));
+    let adjusted = baseSummary * densityFactor;
+    // Multi-session bonus: 30% more per additional session
+    adjusted *= 1 + (sessionCount - 1) * 0.3;
+    // Clamp to reasonable bounds
+    const MIN = 1000;
+    const MAX = 30000;
+    return Math.max(MIN, Math.min(MAX, Math.round(adjusted)));
+}
+function calculateWeights(triage) {
+    const counts = {
+        files: triage.files_modified.length,
+        decisions: triage.decisions_made.length,
+        features: triage.features_built.length,
+        errors: triage.errors_resolved.length,
+        unfinished: triage.unfinished_work.length,
+    };
+    const total = Object.values(counts).reduce((a, b) => a + b, 0) || 1;
+    // Each section gets proportional weight, minimum 10% each
+    const weights = {};
+    for (const [key, count] of Object.entries(counts)) {
+        weights[key] = Math.max(10, Math.round((count / total) * 100));
+    }
+    return weights;
+}
+// ---------------------------------------------------------------------------
+// Pass 2: Recap
+// ---------------------------------------------------------------------------
+const RECAP_SYSTEM_PROMPT = `You are a developer context reconstructor. You read Claude Code session transcripts and produce structured, actionable recaps that let a developer resume work immediately. Be specific — include file paths, function names, error messages. No filler.`;
+function buildRecapPrompt(sessionText, triage, budget, sessionCount, focus) {
+    const weights = calculateWeights(triage);
+    const focusInstruction = focus
+        ? `\n**FOCUS AREA:** The developer specifically wants to know about: "${focus}". Prioritize information related to this topic.\n`
+        : "";
+    return `You are creating a session recap for a developer starting a new Claude Code session.
+They need to understand what happened in their previous ${sessionCount} session(s) without reading the raw transcripts.
+
+Your budget: approximately ${budget} tokens. Use it wisely — be dense, not verbose.
+${focusInstruction}
+Write a structured recap with these sections. Allocate space proportionally:
+- ~${weights.files}% for **File Map** (${triage.files_modified.length} files detected)
+- ~${weights.decisions}% for **Key Decisions** (${triage.decisions_made.length} decisions detected)
+- ~${weights.features}% for **What Was Built** (${triage.features_built.length} features detected)
+- ~${weights.errors}% for **Errors Resolved** (${triage.errors_resolved.length} errors detected)
+- ~${weights.unfinished}% for **Unfinished / In Progress** (${triage.unfinished_work.length} items detected)
+
+Required format:
+
+## Project State
+Current branch, key files, what's working. One paragraph max.
+
+## What Was Built
+- Feature: status, key files involved
+
+## Key Decisions
+- Decision: reasoning in one sentence
+
+## Errors Resolved
+- Error: how it was fixed, in which file
+
+## Unfinished / In Progress
+- Item: last known state, what's needed next
+
+## File Map
+- path — one-line description of what changed
+
+Omit any section that has zero items. Be specific. Include file paths, function names, error messages. The developer needs actionable context, not vague summaries.
+
+Session transcripts:
+
+${sessionText}`;
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+export async function sessionRecap(provider, input) {
+    const startTime = Date.now();
+    // Step 1: Read sessions from disk
+    logger.info(`session_recap: reading ${input.sessions} sessions${input.project ? ` for ${input.project}` : " (auto-detect)"}`);
+    let bundle;
+    try {
+        bundle = readSessions(input.project, input.sessions);
+    }
+    catch (err) {
+        return `## Session Recap Failed\n\n${err instanceof Error ? err.message : String(err)}\n\n**Recovery:** If the project was not found, retry with an explicit project path. Run session_recap with the project parameter set to one of the available projects listed above.`;
+    }
+    if (bundle.sessions.length === 0) {
+        return "## Session Recap Failed\n\nNo sessions found to recap. The project directory exists but contains no .jsonl session files.\n\n**Recovery:** Try a different project path, or increase the sessions count. If the user recently started using Claude Code on this project, there may not be any history yet.";
+    }
+    const sessionText = formatSessionsForPrompt(bundle);
+    logger.info(`session_recap: ${bundle.sessionCount} sessions, ${bundle.totalChars} chars`);
+    // Step 2: Pick a model
+    const model = await pickLargeContextModel(provider, input.model);
+    if (!model) {
+        return "## Session Recap Failed\n\nNo models available for summarization.\n\n**Recovery:** The user needs to start a model provider. Tell them to start CLIProxyAPI or Ollama, then retry. You can also verify provider status by calling list_models first.";
+    }
+    logger.info(`session_recap: using model ${model}`);
+    // Step 3: Pass 1 — Triage
+    const triageStart = Date.now();
+    let triage = null;
+    try {
+        const triageResult = await provider.query(model, buildTriagePrompt(sessionText, input.focus), {
+            system_prompt: TRIAGE_SYSTEM_PROMPT,
+            temperature: 0,
+            max_tokens: 1024,
+        });
+        triage = parseTriage(triageResult.content);
+    }
+    catch (err) {
+        logger.warn(`session_recap: triage failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const triageMs = Date.now() - triageStart;
+    // Step 4: Calculate budget
+    let budget;
+    if (input.max_summary_tokens) {
+        budget = input.max_summary_tokens;
+    }
+    else if (triage) {
+        budget = calculateBudget(triage, bundle.totalChars, bundle.sessionCount);
+    }
+    else {
+        // Fallback: fixed budget if triage failed
+        budget = 5000;
+        logger.warn("session_recap: using fallback budget of 5000 tokens");
+    }
+    // Use a default triage if pass 1 failed
+    const effectiveTriage = triage ?? {
+        files_modified: [],
+        decisions_made: [],
+        errors_resolved: [],
+        features_built: [],
+        unfinished_work: [],
+        total_meaningful_events: 0,
+    };
+    logger.info(`session_recap: budget=${budget} tokens, events=${effectiveTriage.total_meaningful_events}`);
+    // Step 5: Pass 2 — Full recap
+    const recapStart = Date.now();
+    try {
+        const recapResult = await provider.query(model, buildRecapPrompt(sessionText, effectiveTriage, budget, bundle.sessionCount, input.focus), {
+            system_prompt: RECAP_SYSTEM_PROMPT,
+            temperature: 0.2,
+            max_tokens: budget,
+        });
+        const recapMs = Date.now() - recapStart;
+        const totalMs = Date.now() - startTime;
+        // Format date range
+        const firstSession = bundle.sessions[bundle.sessions.length - 1];
+        const lastSession = bundle.sessions[0];
+        const dateRange = `${firstSession?.startTime?.slice(0, 10) ?? "?"} to ${lastSession?.endTime?.slice(0, 10) ?? "?"}`;
+        const lines = [
+            `## Session Recap (${bundle.sessionCount} session${bundle.sessionCount > 1 ? "s" : ""}, ${bundle.projectPath})`,
+            "",
+            `**Model:** ${model} | **Sessions:** ${dateRange} | **Budget:** ${budget} tokens`,
+            "",
+            recapResult.content,
+            "",
+            "---",
+            `*Recap generated by HydraMCP session_recap | Triage: ${triageMs}ms | Recap: ${recapMs}ms | Total: ${totalMs}ms*`,
+        ];
+        return lines.join("\n");
+    }
+    catch (err) {
+        // Graceful degradation: return triage results as basic summary
+        logger.error(`session_recap: recap pass failed: ${err instanceof Error ? err.message : String(err)}`);
+        if (triage) {
+            return formatTriageFallback(triage, bundle, model);
+        }
+        return `## Session Recap Failed\n\nBoth triage and recap passes failed. Error: ${err instanceof Error ? err.message : String(err)}\n\n**Recovery:** Retry with fewer sessions (sessions=1) to reduce input size, or specify a different model. If the error mentions a timeout or rate limit, wait a moment and retry.`;
+    }
+}
+// ---------------------------------------------------------------------------
+// Fallback formatter (when Pass 2 fails but triage succeeded)
+// ---------------------------------------------------------------------------
+function formatTriageFallback(triage, bundle, model) {
+    const lines = [
+        `## Session Recap — Triage Only (${bundle.sessionCount} sessions, ${bundle.projectPath})`,
+        "",
+        `*Full recap failed. Showing triage data from Pass 1.*`,
+        "",
+        `**Model:** ${model}`,
+        "",
+    ];
+    if (triage.features_built.length > 0) {
+        lines.push("### What Was Built");
+        for (const f of triage.features_built) {
+            lines.push(`- ${f.summary} (${f.status ?? "unknown"})`);
+        }
+        lines.push("");
+    }
+    if (triage.decisions_made.length > 0) {
+        lines.push("### Key Decisions");
+        for (const d of triage.decisions_made) {
+            lines.push(`- ${d.summary} [${d.importance ?? "?"}]`);
+        }
+        lines.push("");
+    }
+    if (triage.errors_resolved.length > 0) {
+        lines.push("### Errors Resolved");
+        for (const e of triage.errors_resolved) {
+            lines.push(`- ${e.summary}`);
+        }
+        lines.push("");
+    }
+    if (triage.unfinished_work.length > 0) {
+        lines.push("### Unfinished Work");
+        for (const u of triage.unfinished_work) {
+            lines.push(`- ${u.summary} [${u.priority ?? "?"}]`);
+        }
+        lines.push("");
+    }
+    if (triage.files_modified.length > 0) {
+        lines.push("### Files Modified");
+        for (const f of triage.files_modified) {
+            lines.push(`- ${f}`);
+        }
+        lines.push("");
+    }
+    lines.push(`*Events detected: ${triage.total_meaningful_events}*`);
+    return lines.join("\n");
+}