@rarusoft/dendrite-wiki 0.1.0-alpha.0

package/dist/wiki-synthesis.js

@@ -0,0 +1,901 @@
+/**
+ * Synthesis providers — deterministic prompt builders for LLM-assisted wiki work.
+ *
+ * Builds structured prompts for three distinct tasks: claim synthesis (turn a page's prose
+ * into source-backed `[planned]`/`[current]` claims), guidance synthesis (suggest where a
+ * piece of agent guidance should live based on existing patterns), and proposal synthesis
+ * (draft a `WikiMergeGuidanceProposal` or `WikiRouteGuidanceProposal` for the maintenance
+ * inbox). Drift-resolution prompts assist when a page-drift finding needs an LLM to
+ * suggest whether to update the page, the project log, or both.
+ *
+ * No LLM is called from this module — every function returns a structured prompt the
+ * operator pastes into Claude/GPT/local-Ollama, then feeds the result back through the
+ * normal `wiki_apply_proposal` or `memory_remember` paths. This is the "agent provider"
+ * pattern: provider-agnostic, no API keys required by default, no opaque dependencies.
+ * `listOllamaModels` exists for the optional local-model path.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { extractWikiClaims, listProjectGuidanceFiles, listWikiPages, listWikiProposals, readWikiPage } from './store.js';
+import { buildChartPrompt, parseChartResponse } from './chart-prompts.js';
+const defaultOllamaUrl = 'http://localhost:11434';
+// Per-provider default timeouts. Local Ollama generations on slow hardware can take
+// 30-90s for the first call (cold-start of a freshly-loaded model is the worst case).
+// Cloud APIs reliably respond well under 30s. The agent provider doesn't actually call
+// out — it just returns a handoff prompt — so its timeout is only here for symmetry.
+// All values are an upper bound; the request will return as soon as the provider does.
+//
+// Ollama default at 5 minutes: chart synthesis (M4 of the AI-mermaid-charts roadmap)
+// regularly exceeds the previous 2-minute default for small models on CPU producing
+// flowcharts with many nodes. The env var DENDRITE_WIKI_SYNTHESIS_TIMEOUT_MS overrides
+// for operators with bigger workloads or beefier hardware.
+const defaultSynthesisTimeoutMsByKind = {
+    none: 8_000,
+    agent: 5_000,
+    ollama: 300_000,
+    cloud: 30_000
+};
+const fallbackSynthesisTimeoutMs = 8_000;
+const maxSynthesizedSummaryLength = 280;
+const maxSynthesizedExplanationLength = 360;
+const maxSynthesizedDistillationLength = 600;
+const maxPromptContentLength = 4_000;
+const repoRoot = path.resolve(process.cwd());
+export function resolveWikiSynthesisProvider(options = {}) {
+    const env = options.env ?? process.env;
+    const kind = options.requestedKind ?? parseProviderKind(env.DENDRITE_WIKI_SYNTHESIS_PROVIDER);
+    // Default timeout depends on provider kind. The env var still wins for explicit overrides.
+    const timeoutMs = parseTimeoutMs(env.DENDRITE_WIKI_SYNTHESIS_TIMEOUT_MS, defaultSynthesisTimeoutMsByKind[kind]);
+    switch (kind) {
+        case 'none':
+            return {
+                kind,
+                status: 'disabled',
+                reason: 'Optional synthesis is disabled. Set DENDRITE_WIKI_SYNTHESIS_PROVIDER=ollama or pass provider "ollama" to this tool.',
+                timeoutMs
+            };
+        case 'agent':
+            return {
+                kind,
+                status: 'ready',
+                reason: 'The agent provider returns a bounded handoff prompt for the active coding agent instead of running server-side inference.',
+                timeoutMs
+            };
+        case 'cloud':
+            return resolveCloudProvider(env, timeoutMs);
+        case 'ollama': {
+            // Per-call override (e.g., from the review board model picker) wins over env.
+            const overrideModel = options.requestedOllamaModel?.trim() ?? '';
+            const model = overrideModel || env.OLLAMA_MODEL?.trim() || '';
+            const endpoint = env.OLLAMA_URL?.trim() || defaultOllamaUrl;
+            if (model.length === 0) {
+                return {
+                    kind,
+                    status: 'misconfigured',
+                    reason: 'OLLAMA_MODEL must be set (or a model passed in the request) before the ollama provider can run.',
+                    endpoint,
+                    timeoutMs
+                };
+            }
+            return {
+                kind,
+                status: 'ready',
+                model,
+                endpoint,
+                timeoutMs
+            };
+        }
+    }
+}
+function resolveCloudProvider(env, timeoutMs) {
+    const endpoint = env.DENDRITE_WIKI_CLOUD_URL?.trim() ?? '';
+    const model = env.DENDRITE_WIKI_CLOUD_MODEL?.trim() ?? '';
+    const apiKey = env.DENDRITE_WIKI_CLOUD_API_KEY?.trim() ?? '';
+    if (!endpoint || !model || !apiKey) {
+        const missing = [
+            endpoint ? '' : 'DENDRITE_WIKI_CLOUD_URL',
+            model ? '' : 'DENDRITE_WIKI_CLOUD_MODEL',
+            apiKey ? '' : 'DENDRITE_WIKI_CLOUD_API_KEY'
+        ].filter(Boolean).join(', ');
+        return {
+            kind: 'cloud',
+            status: 'misconfigured',
+            reason: `Cloud synthesis requires ${missing}.`,
+            endpoint: endpoint || undefined,
+            model: model || undefined,
+            timeoutMs
+        };
+    }
+    return {
+        kind: 'cloud',
+        status: 'ready',
+        endpoint,
+        model,
+        timeoutMs
+    };
+}
+export async function synthesizeWikiProposals(options = {}) {
+    const provider = resolveWikiSynthesisProvider(options);
+    const proposals = options.proposals ?? (await listWikiProposals());
+    const selected = selectProposals(proposals, options.reviewSlug, options.maxItems);
+    return {
+        provider,
+        proposals: await Promise.all(selected.map((proposal) => synthesizeProposalSummary(proposal, provider, { fetcher: options.fetcher })))
+    };
+}
+export async function synthesizeWikiClaims(options = {}) {
+    const provider = resolveWikiSynthesisProvider(options);
+    const claims = options.claims ?? (await listStaleClaims());
+    const selected = selectClaims(claims, options.pageSlug, options.maxItems);
+    return {
+        provider,
+        claims: await Promise.all(selected.map((claim) => synthesizeStaleClaimExplanation(claim, provider, { fetcher: options.fetcher })))
+    };
+}
+export async function synthesizeWikiGuidance(options = {}) {
+    const provider = resolveWikiSynthesisProvider(options);
+    const guidanceFiles = options.guidanceFiles ?? (await listProjectGuidanceFiles());
+    const selected = selectGuidanceFiles(guidanceFiles, options.guidancePath, options.maxItems);
+    return {
+        provider,
+        guidanceFiles: await Promise.all(selected.map((guidance) => synthesizeGuidanceDistillation(guidance, provider, { fetcher: options.fetcher })))
+    };
+}
+export async function synthesizeProposalSummary(proposal, provider, options = {}) {
+    const synthesis = await synthesizeText(buildProposalSummaryPrompt(proposal), provider, {
+        fetcher: options.fetcher,
+        maxLength: maxSynthesizedSummaryLength,
+        emptyMessage: 'Synthesis provider returned an empty proposal summary.'
+    });
+    return {
+        reviewSlug: proposal.reviewSlug,
+        kind: proposal.kind,
+        summary: proposal.summary,
+        currentStateSummary: proposal.currentStateSummary,
+        afterApplySummary: proposal.afterApplySummary,
+        rationale: proposal.rationale,
+        synthesisStatus: synthesis.status,
+        synthesizedSummary: synthesis.text,
+        handoffPrompt: synthesis.handoffPrompt,
+        failureReason: synthesis.failureReason
+    };
+}
+export async function synthesizeStaleClaimExplanation(claim, provider, options = {}) {
+    const synthesis = await synthesizeText(buildClaimExplanationPrompt(claim), provider, {
+        fetcher: options.fetcher,
+        maxLength: maxSynthesizedExplanationLength,
+        emptyMessage: 'Synthesis provider returned an empty stale-claim explanation.'
+    });
+    return {
+        pageSlug: claim.pageSlug,
+        text: claim.text,
+        status: claim.status,
+        sources: claim.sources,
+        synthesisStatus: synthesis.status,
+        synthesizedExplanation: synthesis.text,
+        handoffPrompt: synthesis.handoffPrompt,
+        failureReason: synthesis.failureReason
+    };
+}
+export async function synthesizeGuidanceDistillation(guidance, provider, options = {}) {
+    const content = await fs.readFile(path.join(repoRoot, guidance.path), 'utf8').catch(() => '');
+    const synthesis = await synthesizeText(buildGuidanceDistillationPrompt(guidance, content), provider, {
+        fetcher: options.fetcher,
+        maxLength: maxSynthesizedDistillationLength,
+        emptyMessage: 'Synthesis provider returned an empty guidance distillation.'
+    });
+    return {
+        path: guidance.path,
+        kind: guidance.kind,
+        summary: guidance.summary,
+        synthesisStatus: synthesis.status,
+        synthesizedDistillation: synthesis.text,
+        handoffPrompt: synthesis.handoffPrompt,
+        failureReason: synthesis.failureReason
+    };
+}
+function selectProposals(proposals, reviewSlug, maxItems = 3) {
+    if (reviewSlug) {
+        const proposal = proposals.find((candidate) => candidate.reviewSlug === reviewSlug);
+        if (!proposal) {
+            throw new Error(`Unknown active proposal: ${reviewSlug}`);
+        }
+        return [proposal];
+    }
+    return proposals.slice(0, maxItems);
+}
+function selectClaims(claims, pageSlug, maxItems = 5) {
+    return (pageSlug ? claims.filter((claim) => claim.pageSlug === pageSlug) : claims).slice(0, maxItems);
+}
+function selectGuidanceFiles(guidanceFiles, guidancePath, maxItems = 3) {
+    return (guidancePath ? guidanceFiles.filter((guidance) => guidance.path === guidancePath) : guidanceFiles).slice(0, maxItems);
+}
+async function listStaleClaims() {
+    const pages = await listWikiPages();
+    const pageByPath = new Map(pages.map((page) => [page.path, page.slug]));
+    const claims = [];
+    for (const page of pages) {
+        const content = await readWikiPage(page.slug);
+        claims.push(...extractWikiClaims(page.slug, content, pageByPath).filter((claim) => claim.status !== 'current'));
+    }
+    return claims.sort((left, right) => `${left.pageSlug}:${left.text}`.localeCompare(`${right.pageSlug}:${right.text}`));
+}
+function parseProviderKind(value) {
+    switch (value?.trim()) {
+        case 'agent':
+            return 'agent';
+        case 'ollama':
+            return 'ollama';
+        case 'cloud':
+            return 'cloud';
+        default:
+            return 'none';
+    }
+}
+function parseTimeoutMs(value, fallback = fallbackSynthesisTimeoutMs) {
+    if (!value) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+async function synthesizeText(prompt, provider, options) {
+    if (provider.status === 'disabled') {
+        return {
+            status: 'disabled',
+            failureReason: provider.reason
+        };
+    }
+    if (provider.status !== 'ready') {
+        return {
+            status: 'unavailable',
+            failureReason: provider.reason
+        };
+    }
+    if (provider.kind === 'agent') {
+        return {
+            status: 'handoff',
+            handoffPrompt: prompt
+        };
+    }
+    try {
+        if (provider.kind === 'cloud') {
+            return {
+                status: 'generated',
+                text: await requestCloudSynthesis(prompt, provider, options.fetcher ?? fetch, options.maxLength, options.emptyMessage)
+            };
+        }
+        return {
+            status: 'generated',
+            text: await requestOllamaSynthesis(prompt, provider, options.fetcher ?? fetch, options.maxLength, options.emptyMessage)
+        };
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            failureReason: error instanceof Error ? error.message : 'Unknown synthesis error.'
+        };
+    }
+}
+async function requestCloudSynthesis(prompt, provider, fetcher, maxLength, emptyMessage) {
+    const apiKey = process.env.DENDRITE_WIKI_CLOUD_API_KEY?.trim() ?? '';
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), provider.timeoutMs);
+    try {
+        const response = await fetcher(provider.endpoint ?? '', {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${apiKey}`,
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                model: provider.model,
+                messages: [
+                    { role: 'system', content: 'You produce bounded, read-only synthesis for a local project wiki.' },
+                    { role: 'user', content: prompt }
+                ],
+                temperature: 0
+            }),
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            throw new Error(`Cloud synthesis request failed with status ${response.status}.`);
+        }
+        const payload = (await response.json());
+        const content = typeof payload.output_text === 'string'
+            ? payload.output_text
+            : typeof payload.choices?.[0]?.message?.content === 'string'
+                ? payload.choices[0].message.content
+                : '';
+        return normalizeSynthesizedText(content, maxLength, emptyMessage);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error(`Cloud synthesis timed out after ${provider.timeoutMs}ms.`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+async function requestOllamaSynthesis(prompt, provider, fetcher, maxLength, emptyMessage) {
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), provider.timeoutMs);
+    try {
+        const response = await fetcher(new URL('/api/generate', provider.endpoint ?? defaultOllamaUrl), {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                model: provider.model,
+                stream: false,
+                prompt
+            }),
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            throw new Error(`Ollama request failed with status ${response.status}.`);
+        }
+        const payload = (await response.json());
+        return normalizeSynthesizedText(typeof payload.response === 'string' ? payload.response : '', maxLength, emptyMessage);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error(`Ollama synthesis timed out after ${provider.timeoutMs}ms.`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+function buildProposalSummaryPrompt(proposal) {
+    return [
+        'You are summarizing a deterministic wiki maintenance proposal for a cautious reviewer.',
+        `Return exactly one sentence under ${maxSynthesizedSummaryLength} characters.`,
+        'Mention the cleanup being suggested and the main safety boundary.',
+        'Do not use markdown bullets, code fences, or extra commentary.',
+        '',
+        `Proposal kind: ${proposal.kind}`,
+        `Summary: ${proposal.summary}`,
+        `Current state: ${proposal.currentStateSummary}`,
+        `After apply: ${proposal.afterApplySummary}`,
+        `Rationale: ${proposal.rationale}`
+    ].join('\n');
+}
+function buildClaimExplanationPrompt(claim) {
+    const sources = claim.sources.length > 0 ? claim.sources.map((source) => `${source.label} (${source.slug})`).join(', ') : 'No linked sources.';
+    return [
+        'You are explaining a stale or non-current wiki claim for a cautious project maintainer.',
+        `Return exactly one sentence under ${maxSynthesizedExplanationLength} characters.`,
+        'Explain why this claim should be reviewed before it is trusted, using only the evidence below.',
+        'Do not mark the claim current and do not propose a write.',
+        '',
+        `Page: ${claim.pageSlug}`,
+        `Status: ${claim.status}`,
+        `Claim: ${claim.text}`,
+        `Sources: ${sources}`
+    ].join('\n');
+}
+function buildGuidanceDistillationPrompt(guidance, content) {
+    return [
+        'You are distilling an agent guidance file into concise candidate notes for review.',
+        `Return at most three short bullets under ${maxSynthesizedDistillationLength} characters total.`,
+        'Preserve only durable operating guidance and mention if details should stay in linked wiki pages.',
+        'Do not output replacement file content and do not propose an automatic edit.',
+        '',
+        `Guidance path: ${guidance.path}`,
+        `Guidance kind: ${guidance.kind}`,
+        `Existing summary: ${guidance.summary}`,
+        '',
+        'Guidance content excerpt:',
+        truncateForPrompt(content)
+    ].join('\n');
+}
+function normalizeSynthesizedText(value, maxLength, emptyMessage) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    if (normalized.length === 0) {
+        throw new Error(emptyMessage);
+    }
+    if (normalized.length > maxLength) {
+        throw new Error(`Synthesis provider returned ${normalized.length} characters, which exceeds the ${maxLength} character limit.`);
+    }
+    return normalized;
+}
+function truncateForPrompt(value) {
+    const normalized = value.trim();
+    if (normalized.length <= maxPromptContentLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, maxPromptContentLength)}\n[truncated]`;
+}
+// =============================================================================
+// PAGE-DRIFT RESOLUTION SYNTHESIS
+// =============================================================================
+//
+// The maintenance review board's drift findings ask the operator to either
+// rewrite a page's first paragraph or snooze the finding. Asking the operator
+// to draft prose from scratch is hostile UX — they don't know what the page
+// currently says, what recent activity has been about, or what new wording
+// would close the vocabulary gap. This synthesizer flips the workflow:
+// the system gathers the evidence, asks the configured AI provider for a
+// proposed replacement, and the operator just approves / regenerates / snoozes.
+//
+// The synthesizer also recognizes a "this is session noise, recommend snooze"
+// outcome — if the AI examines the evidence and concludes the drift signal
+// shouldn't be acted on, it returns a snooze recommendation with reasoning
+// instead of a replacement paragraph.
+import { extractPageIntent, extractRecentEntriesMentioningPage } from './page-drift.js';
+import { pagePathFromSlug } from './store.js';
+const maxSynthesizedFirstParagraphLength = 800;
+const maxRecentActivityEntriesShown = 6;
+export async function synthesizeWikiDriftResolution(slug, options = {}) {
+    // The review board's model picker passes ollamaModel as a UX-friendly shortcut.
+    // It implies requestedKind='ollama' (the picker only makes sense for ollama).
+    const resolverOptions = options.ollamaModel?.trim()
+        ? {
+            ...options,
+            requestedKind: 'ollama',
+            requestedOllamaModel: options.ollamaModel
+        }
+        : options;
+    const provider = resolveWikiSynthesisProvider(resolverOptions);
+    const evidence = await gatherDriftEvidence(slug);
+    // If we couldn't even gather the evidence (page missing, no activity), return early
+    // with a snooze recommendation — there's nothing for the AI to chew on.
+    if (!evidence.currentIntent) {
+        return {
+            provider,
+            evidence,
+            suggestion: {
+                outcome: 'unavailable',
+                status: 'failed',
+                failureReason: `Could not read page intent for ${slug}.`
+            }
+        };
+    }
+    if (evidence.recentActivityEntries.length === 0) {
+        return {
+            provider,
+            evidence,
+            suggestion: {
+                outcome: 'snooze-recommended',
+                status: 'generated',
+                reasoning: 'No recent project-log activity mentions this page right now. The drift signal has nothing to compare against — snoozing is safer than guessing at a rewrite.'
+            }
+        };
+    }
+    const prompt = buildDriftResolutionPrompt(evidence);
+    const result = await synthesizeText(prompt, provider, {
+        fetcher: options.fetcher,
+        maxLength: maxSynthesizedFirstParagraphLength,
+        emptyMessage: 'Synthesis provider returned no text for the drift resolution.'
+    });
+    if (result.status === 'handoff') {
+        return {
+            provider,
+            evidence,
+            suggestion: {
+                outcome: 'replacement',
+                status: 'handoff',
+                handoffPrompt: result.handoffPrompt
+            }
+        };
+    }
+    if (result.status === 'generated' && result.text) {
+        const parsed = parseDriftResolutionResponse(result.text);
+        return {
+            provider,
+            evidence,
+            suggestion: { ...parsed, status: 'generated' }
+        };
+    }
+    return {
+        provider,
+        evidence,
+        suggestion: {
+            outcome: 'unavailable',
+            status: result.status,
+            failureReason: result.failureReason
+        }
+    };
+}
+async function gatherDriftEvidence(slug) {
+    const pageContent = await fs.readFile(pagePathFromSlug(slug), 'utf8').catch(() => '');
+    const projectLog = await fs.readFile(pagePathFromSlug('project-log'), 'utf8').catch(() => '');
+    const intent = pageContent ? extractPageIntent(pageContent) : '';
+    const match = projectLog
+        ? extractRecentEntriesMentioningPage(projectLog, slug, maxRecentActivityEntriesShown, 7)
+        : { entries: [], distinctDays: 0 };
+    return {
+        slug,
+        currentIntent: intent,
+        recentActivityEntries: match.entries,
+        matchedDistinctDays: match.distinctDays
+    };
+}
+function buildDriftResolutionPrompt(evidence) {
+    const activityBlock = evidence.recentActivityEntries
+        .map((entry, idx) => `${idx + 1}. ${entry}`)
+        .join('\n');
+    return [
+        `You are helping resolve a "page drift" finding on a project wiki page (slug: ${evidence.slug}).`,
+        '',
+        'Page drift fires when the page\'s first paragraph (its stated intent) does not share much vocabulary with recent project-log entries that mention the page. The hypothesis is that the page may have outgrown its summary.',
+        '',
+        'CURRENT FIRST PARAGRAPH (the page\'s stated intent — title + first paragraph):',
+        `"""${truncateForPrompt(evidence.currentIntent)}"""`,
+        '',
+        `RECENT PROJECT-LOG ENTRIES MENTIONING THIS PAGE (last 7 days, ${evidence.matchedDistinctDays} distinct day${evidence.matchedDistinctDays === 1 ? '' : 's'}):`,
+        activityBlock,
+        '',
+        'Decide ONE of two outcomes:',
+        '',
+        '1. The activity reflects a real shift in what the page is about. Generate a replacement first paragraph (1-3 sentences, plain prose, no markdown headings) that better describes what the page is now actually about. The replacement should keep the same level of abstraction as the current intent — it summarizes the page, it does not list every recent change.',
+        '',
+        '2. The activity is just session noise (a temporary burst of unrelated work, or implementation detail that doesn\'t belong in the page summary). Recommend snooze instead.',
+        '',
+        'Respond in EXACTLY one of these two formats and nothing else:',
+        '',
+        'REPLACEMENT: <one to three sentence replacement first paragraph>',
+        'REASONING: <one sentence explaining why this rewrite captures the page better>',
+        '',
+        'OR',
+        '',
+        'SNOOZE: <one sentence reason — what makes this look like noise rather than real drift>'
+    ].join('\n');
+}
+export async function listOllamaModels(options = {}) {
+    const env = options.env ?? process.env;
+    const endpoint = env.OLLAMA_URL?.trim() || defaultOllamaUrl;
+    const fetcher = options.fetcher ?? fetch;
+    const timeoutMs = options.timeoutMs ?? parseTimeoutMs(env.DENDRITE_WIKI_SYNTHESIS_TIMEOUT_MS);
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), Math.min(timeoutMs, 5_000));
+    try {
+        const response = await fetcher(new URL('/api/tags', endpoint), {
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            return {
+                endpoint,
+                status: 'error',
+                models: [],
+                failureReason: `Ollama returned HTTP ${response.status}`
+            };
+        }
+        const payload = (await response.json());
+        const rawModels = Array.isArray(payload.models) ? payload.models : [];
+        const models = rawModels.flatMap((entry) => {
+            if (!entry || typeof entry !== 'object')
+                return [];
+            const e = entry;
+            if (typeof e.name !== 'string' || !e.name.trim())
+                return [];
+            const details = (e.details && typeof e.details === 'object') ? e.details : {};
+            return [{
+                    name: e.name,
+                    size: typeof e.size === 'number' ? e.size : undefined,
+                    modifiedAt: typeof e.modified_at === 'string'
+                        ? e.modified_at
+                        : typeof e.modifiedAt === 'string' ? e.modifiedAt : undefined,
+                    details: {
+                        family: typeof details.family === 'string' ? details.family : undefined,
+                        parameterSize: typeof details.parameter_size === 'string'
+                            ? details.parameter_size
+                            : typeof details.parameterSize === 'string' ? details.parameterSize : undefined
+                    }
+                }];
+        });
+        // Sort alphabetical for stable UX in the picker.
+        models.sort((left, right) => left.name.localeCompare(right.name));
+        return { endpoint, status: 'ok', models };
+    }
+    catch (error) {
+        const failureReason = error instanceof Error
+            ? (error.name === 'AbortError' ? `Ollama did not respond within ${Math.min(timeoutMs, 5_000)}ms — is the server running on ${endpoint}?` : error.message)
+            : String(error);
+        return {
+            endpoint,
+            status: 'unreachable',
+            models: [],
+            failureReason
+        };
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+function parseDriftResolutionResponse(text) {
+    const normalized = text.replace(/\r\n/g, '\n').trim();
+    // Snooze recommendation
+    const snoozeMatch = normalized.match(/^SNOOZE:\s*(.+?)$/im);
+    if (snoozeMatch) {
+        return {
+            outcome: 'snooze-recommended',
+            reasoning: snoozeMatch[1].trim()
+        };
+    }
+    // Replacement (with optional REASONING line)
+    const replacementMatch = normalized.match(/^REPLACEMENT:\s*([\s\S]+?)(?=\n\s*REASONING:|$)/im);
+    if (replacementMatch) {
+        const replacementText = replacementMatch[1].trim();
+        const reasoningMatch = normalized.match(/^REASONING:\s*(.+?)$/im);
+        return {
+            outcome: 'replacement',
+            text: replacementText,
+            reasoning: reasoningMatch?.[1].trim()
+        };
+    }
+    // Provider didn't follow the format — treat the whole response as a candidate
+    // replacement so the operator can still see it. They can edit before applying.
+    return {
+        outcome: 'replacement',
+        text: normalized,
+        reasoning: 'Provider did not follow the structured format; using full response as the candidate replacement.'
+    };
+}
+const CHART_SYNTHESIS_MAX_LENGTH = 4_096;
+export async function synthesizeWikiChart(input, options = {}) {
+    const resolverOptions = options.ollamaModel?.trim()
+        ? { ...options, requestedKind: 'ollama', requestedOllamaModel: options.ollamaModel }
+        : options;
+    const provider = resolveWikiSynthesisProvider(resolverOptions);
+    const prompt = buildChartPrompt({ kind: input.chartKind, context: input.context, intent: input.intent });
+    const startedAt = Date.now();
+    const result = await synthesizeText(prompt, provider, {
+        fetcher: options.fetcher,
+        maxLength: CHART_SYNTHESIS_MAX_LENGTH,
+        emptyMessage: 'Synthesis provider returned no text for the chart request.'
+    });
+    const durationMs = Date.now() - startedAt;
+    if (result.status === 'handoff') {
+        return { provider, status: 'handoff', handoffPrompt: result.handoffPrompt, durationMs };
+    }
+    if (result.status === 'generated' && result.text) {
+        const mermaidSource = parseChartResponse(result.text);
+        return { provider, status: 'generated', mermaidSource, rawResponse: result.text, durationMs };
+    }
+    return { provider, status: result.status, failureReason: result.failureReason, durationMs };
+}
+const memoryAutoCleanResponseMaxLength = 32_000;
+export async function synthesizeMemoryAutoCleanDecisions(candidates, options = {}) {
+    const resolverOptions = options.ollamaModel?.trim()
+        ? { ...options, requestedKind: 'ollama', requestedOllamaModel: options.ollamaModel }
+        : options;
+    const provider = resolveWikiSynthesisProvider(resolverOptions);
+    if (candidates.length === 0) {
+        return { provider, status: 'generated', decisions: [] };
+    }
+    const prompt = buildMemoryAutoCleanPrompt(candidates);
+    if (provider.status === 'disabled') {
+        return { provider, status: 'disabled', failureReason: provider.reason };
+    }
+    if (provider.status !== 'ready') {
+        return { provider, status: 'unavailable', failureReason: provider.reason };
+    }
+    if (provider.kind === 'agent') {
+        return { provider, status: 'handoff', handoffPrompt: prompt };
+    }
+    let rawResponse;
+    try {
+        rawResponse =
+            provider.kind === 'cloud'
+                ? await requestCloudMemoryAutoCleanResponse(prompt, provider, options.fetcher ?? fetch)
+                : await requestOllamaMemoryAutoCleanResponse(prompt, provider, options.fetcher ?? fetch);
+    }
+    catch (error) {
+        return {
+            provider,
+            status: 'failed',
+            failureReason: error instanceof Error ? error.message : String(error)
+        };
+    }
+    const parsed = parseMemoryAutoCleanResponse(rawResponse, candidates);
+    if (!parsed.ok) {
+        return { provider, status: 'parse-failed', rawResponse, failureReason: parsed.failureReason };
+    }
+    return { provider, status: 'generated', decisions: parsed.decisions, rawResponse };
+}
+function buildMemoryAutoCleanPrompt(candidates) {
+    const lines = [
+        'You are an expert memory archivist for an AI coding agent\'s project-local memory store.',
+        'For each candidate memory below, decide one of two verbs:',
+        '  - "archive": junk, vague, restates the obvious, no actionable content, or a weaker duplicate of another memory.',
+        '  - "keep-and-watch": concrete lessons, specific facts, decisions with context — still has signal. When uncertain, prefer this.',
+        '',
+        'Output format:',
+        '  Return a JSON object with exactly this shape:',
+        '    { "decisions": [ { "memoryId": "...", "verb": "...", "reason": "...", "confidence": 0.0 }, ... ] }',
+        '  Field rules per decision:',
+        '    - memoryId: string, exactly the id given in the input (e.g. "mem_abc-123").',
+        '    - verb: either "archive" or "keep-and-watch" (literal string, no other values).',
+        '    - reason: one short sentence (under 200 chars) explaining the choice.',
+        '    - confidence: a number from 0.0 to 1.0.',
+        '  Cover EVERY candidate memoryId below exactly once. No code fences. No prose outside the JSON.',
+        '',
+        'Guidelines:',
+        '  - Memories with recallCount > 0 almost always keep-and-watch (recall proves usefulness).',
+        '  - Memories under 14 days old default to keep-and-watch unless the text is clearly junk.',
+        '  - High-confidence (>=0.8) for clearly junk or clearly valuable. Lower for genuinely uncertain.',
+        '',
+        'Candidates:'
+    ];
+    candidates.forEach((candidate, index) => {
+        const text = candidate.text.length > 600 ? `${candidate.text.slice(0, 597)}...` : candidate.text;
+        const lastRecalled = candidate.lastRecalledAt ? `, last recalled ${candidate.lastRecalledAt.slice(0, 10)}` : ', never recalled';
+        lines.push('', `[${index + 1}] memoryId: ${candidate.memoryId}`, `    kind: ${candidate.kind}, finding: ${candidate.reviewFindingKind}, age: ${candidate.ageInDays}d, recallCount: ${candidate.recallCount}${lastRecalled}, sources: ${candidate.sources}`, `    text: ${text.replace(/\n+/g, ' ').trim()}`);
+    });
+    lines.push('', 'Return the JSON array now.');
+    return lines.join('\n');
+}
+async function requestOllamaMemoryAutoCleanResponse(prompt, provider, fetcher) {
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), provider.timeoutMs);
+    try {
+        const response = await fetcher(new URL('/api/generate', provider.endpoint ?? defaultOllamaUrl), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                model: provider.model,
+                stream: false,
+                prompt,
+                format: 'json',
+                // Keep the model resident across batches. Without this, Ollama unloads after each
+                // request and the next batch pays a cold-load penalty (often 30-60s on slow boxes),
+                // which compounds painfully across N batches. 15 minutes covers the full auto-clean
+                // sweep with margin for slow generation.
+                keep_alive: '15m'
+            }),
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            throw new Error(`Ollama request failed with status ${response.status}.`);
+        }
+        const payload = (await response.json());
+        const raw = typeof payload.response === 'string' ? payload.response : '';
+        if (raw.length === 0) {
+            throw new Error('Ollama returned an empty response.');
+        }
+        if (raw.length > memoryAutoCleanResponseMaxLength) {
+            throw new Error(`Ollama returned ${raw.length} characters, which exceeds the ${memoryAutoCleanResponseMaxLength} character limit for auto-clean decisions.`);
+        }
+        return raw;
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error(`Ollama auto-clean synthesis timed out after ${provider.timeoutMs}ms.`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+async function requestCloudMemoryAutoCleanResponse(prompt, provider, fetcher) {
+    const apiKey = process.env.DENDRITE_WIKI_CLOUD_API_KEY?.trim() ?? '';
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), provider.timeoutMs);
+    try {
+        const response = await fetcher(provider.endpoint ?? '', {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${apiKey}`,
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                model: provider.model,
+                messages: [
+                    { role: 'system', content: 'You produce strict JSON output for an AI memory archivist task. No prose. No fences.' },
+                    { role: 'user', content: prompt }
+                ],
+                temperature: 0
+            }),
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            throw new Error(`Cloud auto-clean request failed with status ${response.status}.`);
+        }
+        const payload = (await response.json());
+        const content = typeof payload.output_text === 'string'
+            ? payload.output_text
+            : typeof payload.choices?.[0]?.message?.content === 'string'
+                ? payload.choices[0].message.content
+                : '';
+        if (!content) {
+            throw new Error('Cloud provider returned an empty response.');
+        }
+        if (content.length > memoryAutoCleanResponseMaxLength) {
+            throw new Error(`Cloud provider returned ${content.length} characters, which exceeds the ${memoryAutoCleanResponseMaxLength} character limit.`);
+        }
+        return content;
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error(`Cloud auto-clean synthesis timed out after ${provider.timeoutMs}ms.`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+function parseMemoryAutoCleanResponse(text, candidates) {
+    const candidateIds = new Set(candidates.map((candidate) => candidate.memoryId));
+    let parsed;
+    try {
+        parsed = JSON.parse(stripJsonWrapping(text));
+    }
+    catch (error) {
+        return { ok: false, failureReason: `Response was not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    // Walk the tree and collect anything that looks like a decision. Handles all the shapes
+    // local models tend to emit under `format: 'json'`:
+    //   - bare array: [ {...}, {...} ]
+    //   - wrapped:    { decisions: [...] }, { results: [...] }, { memories: [...] }
+    //   - keyed map:  { mem_abc: { verb, reason }, mem_def: { verb, reason } }
+    //   - nested:     { data: { decisions: [...] } }
+    const collected = collectDecisionLikeObjects(parsed);
+    const decisions = [];
+    const seenIds = new Set();
+    for (const entry of collected) {
+        const memoryId = typeof entry.memoryId === 'string' ? entry.memoryId : '';
+        const verbRaw = typeof entry.verb === 'string' ? entry.verb : '';
+        const reason = typeof entry.reason === 'string' ? entry.reason : '';
+        const confidenceRaw = typeof entry.confidence === 'number' ? entry.confidence : Number.NaN;
+        if (!memoryId || !candidateIds.has(memoryId))
+            continue;
+        if (seenIds.has(memoryId))
+            continue;
+        if (verbRaw !== 'archive' && verbRaw !== 'keep-and-watch')
+            continue;
+        if (!reason)
+            continue;
+        const confidence = Number.isFinite(confidenceRaw) ? Math.max(0, Math.min(1, confidenceRaw)) : 0.5;
+        decisions.push({ memoryId, verb: verbRaw, reason, confidence });
+        seenIds.add(memoryId);
+    }
+    if (decisions.length === 0) {
+        return { ok: false, failureReason: 'No decisions in the response matched the candidate IDs.' };
+    }
+    return { ok: true, decisions };
+}
+// Walk a parsed JSON value and collect every object that looks like an auto-clean
+// decision (has both `memoryId` and `verb`). Handles arbitrary nesting / wrapping so
+// it tolerates whatever shape the local model decides to emit under `format: 'json'`.
+// Also handles the "keyed map" shape where decisions are object keys: `{mem_abc: {verb, reason}}`.
+function collectDecisionLikeObjects(value) {
+    if (!value)
+        return [];
+    if (Array.isArray(value)) {
+        return value.flatMap((item) => collectDecisionLikeObjects(item));
+    }
+    if (typeof value === 'object') {
+        const obj = value;
+        if (typeof obj.memoryId === 'string' && typeof obj.verb === 'string') {
+            return [obj];
+        }
+        // Keyed-map fallback: if every key looks like a memory id (`mem_*`) and every value
+        // is a verb-bearing object, treat the keys as memoryIds and the values as decisions.
+        const entries = Object.entries(obj);
+        if (entries.length > 0 && entries.every(([key, val]) => key.startsWith('mem_') &&
+            val !== null && typeof val === 'object' &&
+            typeof val.verb === 'string')) {
+            return entries.map(([key, val]) => ({ memoryId: key, ...val }));
+        }
+        return entries.flatMap(([, val]) => collectDecisionLikeObjects(val));
+    }
+    return [];
+}
+function stripJsonWrapping(text) {
+    // Be lenient: some local models wrap JSON in code fences or add a prose preamble.
+    // Strip the most common offenders and trim. The parser is tolerant about object vs
+    // array roots, so we don't need to surgically extract a [...] block anymore.
+    return text
+        .replace(/^[^{[]*([{[])/, '$1') // drop any prose preamble before the first { or [
+        .replace(/^```(?:json)?\s*/i, '')
+        .replace(/\s*```\s*$/i, '')
+        .trim();
+}