purecontext-mcp 1.0.1

package/dist/server/transport.d.ts

@@ -0,0 +1,59 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Which MCP transport(s) to start.
+ *   'stdio' — stdin/stdout (default; required for Claude Code integration)
+ *   'http'  — HTTP + Streamable HTTP (for web clients and remote dev environments)
+ *   'both'  — stdio AND HTTP simultaneously (useful for development)
+ */
+export type TransportMode = 'stdio' | 'http' | 'both';
+/** Options passed through to the HTTP server when mode is 'http' or 'both'. */
+export interface TransportOptions {
+    port?: number;
+    host?: string;
+    corsOrigins?: string[];
+}
+/**
+ * Manages stateful MCP-over-HTTP+SSE sessions for a shared server.
+ *
+ * Each agent session is an independent `StreamableHTTPServerTransport` +
+ * `McpServer` pair, keyed by the `mcp-session-id` assigned during initialization.
+ * Multiple agents can connect concurrently; their sessions are fully isolated.
+ *
+ * Protocol (Streamable HTTP):
+ *   POST /mcp/sse (no session ID)    → initialize  → creates session, returns mcp-session-id
+ *   POST /mcp/sse (with session ID)  → tool call   → routes to the correct session
+ *   GET  /mcp/sse (with session ID)  → SSE stream  → server-initiated notifications
+ *   DELETE /mcp/sse (with session ID) → close session
+ *
+ * Connect Claude Code:
+ *   claude mcp add purecontext-remote \
+ *     --transport http \
+ *     --url https://your-server/mcp/sse \
+ *     --header "Authorization: Bearer pctx_yourkey"
+ */
+export declare class HttpSseTransport {
+    private readonly serverFactory;
+    private readonly sessions;
+    constructor(serverFactory: () => McpServer);
+    /**
+     * No-op: sessions are created on demand during initialization requests.
+     * Call this once before the first handleRequest for API symmetry.
+     */
+    init(): Promise<void>;
+    /**
+     * Route an HTTP request to the appropriate MCP session.
+     *
+     * - No `mcp-session-id` header (first request): create a new session.
+     * - With `mcp-session-id` header: look up the existing session.
+     *
+     * Handles GET (SSE open), POST (tool calls), DELETE (close session).
+     * Auth must be validated by the caller before this method is invoked.
+     *
+     * @param parsedBody Pre-parsed JSON body for POST requests; omit for GET/DELETE.
+     */
+    handleRequest(req: IncomingMessage, res: ServerResponse, parsedBody?: unknown): Promise<void>;
+    /** Close all active sessions and their underlying transports. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/server/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/server/transport.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtD,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;gBAElD,aAAa,EAAE,MAAM,SAAS;IAI1C;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;;;;;;;OAUG;IACG,aAAa,CACjB,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,UAAU,CAAC,EAAE,OAAO,GACnB,OAAO,CAAC,IAAI,CAAC;IA6ChB,iEAAiE;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7B"}

package/dist/server/transport.js

@@ -0,0 +1,92 @@
+import { randomUUID } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+/**
+ * Manages stateful MCP-over-HTTP+SSE sessions for a shared server.
+ *
+ * Each agent session is an independent `StreamableHTTPServerTransport` +
+ * `McpServer` pair, keyed by the `mcp-session-id` assigned during initialization.
+ * Multiple agents can connect concurrently; their sessions are fully isolated.
+ *
+ * Protocol (Streamable HTTP):
+ *   POST /mcp/sse (no session ID)    → initialize  → creates session, returns mcp-session-id
+ *   POST /mcp/sse (with session ID)  → tool call   → routes to the correct session
+ *   GET  /mcp/sse (with session ID)  → SSE stream  → server-initiated notifications
+ *   DELETE /mcp/sse (with session ID) → close session
+ *
+ * Connect Claude Code:
+ *   claude mcp add purecontext-remote \
+ *     --transport http \
+ *     --url https://your-server/mcp/sse \
+ *     --header "Authorization: Bearer pctx_yourkey"
+ */
+export class HttpSseTransport {
+    serverFactory;
+    sessions = new Map();
+    constructor(serverFactory) {
+        this.serverFactory = serverFactory;
+    }
+    /**
+     * No-op: sessions are created on demand during initialization requests.
+     * Call this once before the first handleRequest for API symmetry.
+     */
+    async init() {
+        // Sessions are created on demand.
+    }
+    /**
+     * Route an HTTP request to the appropriate MCP session.
+     *
+     * - No `mcp-session-id` header (first request): create a new session.
+     * - With `mcp-session-id` header: look up the existing session.
+     *
+     * Handles GET (SSE open), POST (tool calls), DELETE (close session).
+     * Auth must be validated by the caller before this method is invoked.
+     *
+     * @param parsedBody Pre-parsed JSON body for POST requests; omit for GET/DELETE.
+     */
+    async handleRequest(req, res, parsedBody) {
+        const sessionId = req.headers['mcp-session-id'];
+        if (sessionId) {
+            // Route to existing session
+            const session = this.sessions.get(sessionId);
+            if (!session) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: { code: -32001, message: 'Session not found' },
+                    id: null,
+                }));
+                return;
+            }
+            await session.transport.handleRequest(req, res, parsedBody);
+        }
+        else {
+            // New session — create a fresh transport + McpServer pair.
+            // onsessioninitialized fires during handleRequest once the session ID is assigned.
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sid) => {
+                    // Store immediately so subsequent requests can find this session.
+                    // mcpServer is already assigned (it's a const in the enclosing block).
+                    this.sessions.set(sid, { transport, mcpServer }); // eslint-disable-line @typescript-eslint/no-use-before-define
+                },
+                onsessionclosed: (sid) => {
+                    if (sid)
+                        this.sessions.delete(sid);
+                },
+            });
+            const mcpServer = this.serverFactory();
+            await mcpServer.connect(transport);
+            await transport.handleRequest(req, res, parsedBody);
+        }
+    }
+    /** Close all active sessions and their underlying transports. */
+    async close() {
+        const closings = Array.from(this.sessions.values()).map(async (s) => {
+            await s.transport.close().catch(() => { });
+            await s.mcpServer.close().catch(() => { });
+        });
+        await Promise.all(closings);
+        this.sessions.clear();
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/server/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/server/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AA0BnG;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,gBAAgB;IACV,aAAa,CAAkB;IAC/B,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE9D,YAAY,aAA8B;QACxC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI;QACR,kCAAkC;IACpC,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,aAAa,CACjB,GAAoB,EACpB,GAAmB,EACnB,UAAoB;QAEpB,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAuB,CAAC;QAEtE,IAAI,SAAS,EAAE,CAAC;YACd,4BAA4B;YAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC7C,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;gBAC3D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;oBACrB,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE;oBACrD,EAAE,EAAE,IAAI;iBACT,CAAC,CAAC,CAAC;gBACJ,OAAO;YACT,CAAC;YACD,MAAM,OAAO,CAAC,SAAS,CAAC,aAAa,CACnC,GAAG,EACH,GAAG,EACH,UAAiD,CAClD,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,2DAA2D;YAC3D,mFAAmF;YACnF,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC;gBAClD,kBAAkB,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE;gBACtC,oBAAoB,EAAE,CAAC,GAAG,EAAE,EAAE;oBAC5B,kEAAkE;oBAClE,uEAAuE;oBACvE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,8DAA8D;gBAClH,CAAC;gBACD,eAAe,EAAE,CAAC,GAAG,EAAE,EAAE;oBACvB,IAAI,GAAG;wBAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACrC,CAAC;aACF,CAAC,CAAC;YAEH,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YACvC,MAAM,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YACnC,MAAM,SAAS,CAAC,aAAa,CAC3B,GAAG,EACH,GAAG,EACH,UAAiD,CAClD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,KAAK;QACT,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;YAClE,MAAM,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC1C,MAAM,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QACH,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5B,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF"}

package/dist/summarizer/ai-summarizer.d.ts

@@ -0,0 +1,71 @@
+/**
+ * AI-powered batch summarizer (Stage 3 of the summary pipeline).
+ *
+ * Supports two providers:
+ *   'anthropic'         — Anthropic Messages API (https.request)
+ *   'openai-compatible' — Any /v1/chat/completions endpoint (fetch)
+ *
+ * Error handling: any failure (network, API error, parse failure) logs a
+ * warning and returns an empty Map so the caller can continue with Stage 4
+ * (signature fallback) for the affected symbols.
+ */
+import { request as httpsRequest } from 'https';
+import type { SymbolRecord } from '../core/types.js';
+export interface AISummarizerConfig {
+    /** Enable AI summarization. */
+    enabled: boolean;
+    /** Provider. Defaults to 'anthropic'. */
+    provider?: 'anthropic' | 'openai-compatible';
+    /** Model to use. Provider-specific defaults apply when omitted. */
+    model?: string;
+    /** Resolved API key (after env-var expansion). */
+    apiKey?: string;
+    /**
+     * Base URL for the OpenAI-compatible endpoint (e.g. 'http://localhost:11434').
+     * Required when provider is 'openai-compatible'.
+     */
+    endpoint?: string | null;
+    /** Max symbols per batch. Defaults to 50. */
+    batchSize?: number;
+}
+export interface AISummarizer {
+    /**
+     * Generate summaries for a batch of symbols.
+     * Returns a Map of symbol.id → summary string.
+     * Symbols not covered (error, missing) are absent from the Map.
+     */
+    summarizeBatch(symbols: SymbolRecord[]): Promise<Map<string, string>>;
+}
+/** Injectable type for Node's https.request (Anthropic path). */
+export type HttpRequestFn = typeof httpsRequest;
+/** Injectable type for fetch (OpenAI-compatible path). */
+export type FetchFn = typeof fetch;
+/**
+ * Build the full prompt including file path context and signature.
+ * Response format: `id: summary` per line.
+ */
+export declare function buildPrompt(symbols: SymbolRecord[]): string;
+/**
+ * Simplified prompt used on retry — signatures only, no extra context.
+ */
+export declare function buildSimplePrompt(symbols: SymbolRecord[]): string;
+/**
+ * Parse lines of the form `<id>: <summary>` from the model response.
+ * Lines that don't match the pattern are silently skipped.
+ */
+export declare function parseResponse(text: string, expectedIds: Set<string>): Map<string, string>;
+/**
+ * Send one batch of symbols to the model, retrying once with a simpler prompt
+ * if the first response parses to 0 results.
+ */
+export declare function summarizeBatchWithRetry(symbols: SymbolRecord[], sendPrompt: (prompt: string) => Promise<string>): Promise<Map<string, string>>;
+/**
+ * Create an AISummarizer if AI summarization is enabled and an API key is
+ * available. Returns null if either condition is not met.
+ *
+ * @param config       Summarizer configuration.
+ * @param httpClient   Injectable Anthropic HTTP client (defaults to https.request).
+ * @param fetchFn      Injectable fetch function for OpenAI-compatible path.
+ */
+export declare function createAISummarizer(config: AISummarizerConfig, httpClient?: HttpRequestFn, fetchFn?: FetchFn): AISummarizer | null;
+//# sourceMappingURL=ai-summarizer.d.ts.map

package/dist/summarizer/ai-summarizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-summarizer.d.ts","sourceRoot":"","sources":["../../src/summarizer/ai-summarizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKrD,MAAM,WAAW,kBAAkB;IACjC,+BAA+B;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,WAAW,GAAG,mBAAmB,CAAC;IAC7C,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvE;AAmBD,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,OAAO,YAAY,CAAC;AAEhD,0DAA0D;AAC1D,MAAM,MAAM,OAAO,GAAG,OAAO,KAAK,CAAC;AAInC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAyB3D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAUjE;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAYzF;AAqFD;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,YAAY,EAAE,EACvB,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC9C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAY9B;AAID;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,kBAAkB,EAC1B,UAAU,GAAE,aAA4B,EACxC,OAAO,GAAE,OAA0B,GAClC,YAAY,GAAG,IAAI,CAoFrB"}

package/dist/summarizer/ai-summarizer.js

@@ -0,0 +1,228 @@
+/**
+ * AI-powered batch summarizer (Stage 3 of the summary pipeline).
+ *
+ * Supports two providers:
+ *   'anthropic'         — Anthropic Messages API (https.request)
+ *   'openai-compatible' — Any /v1/chat/completions endpoint (fetch)
+ *
+ * Error handling: any failure (network, API error, parse failure) logs a
+ * warning and returns an empty Map so the caller can continue with Stage 4
+ * (signature fallback) for the affected symbols.
+ */
+import { request as httpsRequest } from 'https';
+import { logger } from '../core/logger.js';
+// ─── Prompt builder ───────────────────────────────────────────────────────────
+/**
+ * Build the full prompt including file path context and signature.
+ * Response format: `id: summary` per line.
+ */
+export function buildPrompt(symbols) {
+    const items = symbols
+        .map((s) => {
+        const parentHint = s.kind === 'method' && s.name.includes('.')
+            ? `  parent=${s.name.slice(0, s.name.lastIndexOf('.'))}`
+            : '';
+        return (`id=${s.id}  kind=${s.kind}  name=${s.name}  file=${s.filePath}${parentHint}\n` +
+            s.signature);
+    })
+        .join('\n\n');
+    return ('For each symbol below, write exactly one line in the format:\n' +
+        'id: <one-line summary>\n\n' +
+        'Rules:\n' +
+        '- Summary must be ≤ 80 characters\n' +
+        '- Use plain English, active voice\n' +
+        '- Do not include the id or name in the summary\n' +
+        '- Output ONLY the id: summary lines, nothing else\n\n' +
+        'Symbols:\n' +
+        items);
+}
+/**
+ * Simplified prompt used on retry — signatures only, no extra context.
+ */
+export function buildSimplePrompt(symbols) {
+    const items = symbols
+        .map((s) => `id=${s.id}\n${s.signature}`)
+        .join('\n\n');
+    return ('For each symbol below, write exactly one line: id: <one-line summary ≤ 80 chars>.\n' +
+        'Output ONLY the id: summary lines.\n\n' +
+        items);
+}
+// ─── Response parser ──────────────────────────────────────────────────────────
+/**
+ * Parse lines of the form `<id>: <summary>` from the model response.
+ * Lines that don't match the pattern are silently skipped.
+ */
+export function parseResponse(text, expectedIds) {
+    const result = new Map();
+    for (const line of text.split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        const id = line.slice(0, colon).trim();
+        const summary = line.slice(colon + 1).trim();
+        if (id && summary && expectedIds.has(id)) {
+            result.set(id, summary);
+        }
+    }
+    return result;
+}
+// ─── Anthropic HTTP call ──────────────────────────────────────────────────────
+function callAnthropic(apiKey, model, messages, httpClient) {
+    return new Promise((resolve, reject) => {
+        const body = JSON.stringify({ model, max_tokens: 1024, messages });
+        const req = httpClient({
+            hostname: 'api.anthropic.com',
+            path: '/v1/messages',
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': apiKey,
+                'anthropic-version': '2023-06-01',
+                'Content-Length': Buffer.byteLength(body),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                const raw = Buffer.concat(chunks).toString('utf8');
+                if (res.statusCode && res.statusCode >= 400) {
+                    reject(new Error(`Anthropic API error ${res.statusCode}: ${raw}`));
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(raw));
+                }
+                catch {
+                    reject(new Error(`Failed to parse Anthropic response: ${raw}`));
+                }
+            });
+            res.on('error', reject);
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+}
+// ─── OpenAI-compatible HTTP call ──────────────────────────────────────────────
+async function callOpenAICompatible(endpoint, apiKey, model, prompt, fetchFn) {
+    const url = `${endpoint.replace(/\/$/, '')}/v1/chat/completions`;
+    const body = JSON.stringify({
+        model,
+        max_tokens: 1024,
+        messages: [{ role: 'user', content: prompt }],
+    });
+    const response = await fetchFn(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        },
+        body,
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`OpenAI-compatible API error ${response.status}: ${text}`);
+    }
+    return response.json();
+}
+// ─── Batch with retry ─────────────────────────────────────────────────────────
+/**
+ * Send one batch of symbols to the model, retrying once with a simpler prompt
+ * if the first response parses to 0 results.
+ */
+export async function summarizeBatchWithRetry(symbols, sendPrompt) {
+    const expectedIds = new Set(symbols.map((s) => s.id));
+    // First attempt — full prompt with file path context
+    const text1 = await sendPrompt(buildPrompt(symbols));
+    const results1 = parseResponse(text1, expectedIds);
+    if (results1.size > 0)
+        return results1;
+    // Retry with simpler prompt
+    logger.debug('AI batch returned 0 results — retrying with simpler prompt');
+    const text2 = await sendPrompt(buildSimplePrompt(symbols));
+    return parseResponse(text2, expectedIds);
+}
+// ─── Public factory ───────────────────────────────────────────────────────────
+/**
+ * Create an AISummarizer if AI summarization is enabled and an API key is
+ * available. Returns null if either condition is not met.
+ *
+ * @param config       Summarizer configuration.
+ * @param httpClient   Injectable Anthropic HTTP client (defaults to https.request).
+ * @param fetchFn      Injectable fetch function for OpenAI-compatible path.
+ */
+export function createAISummarizer(config, httpClient = httpsRequest, fetchFn = globalThis.fetch) {
+    if (!config.enabled)
+        return null;
+    const provider = config.provider ?? 'anthropic';
+    const batchSize = config.batchSize ?? 50;
+    // ── Anthropic ───────────────────────────────────────────────────────────────
+    if (provider === 'anthropic') {
+        const apiKey = config.apiKey || process.env['ANTHROPIC_API_KEY'] || '';
+        if (!apiKey) {
+            logger.warn('AI summarization enabled but no API key available — skipping Stage 3');
+            return null;
+        }
+        const model = config.model ?? 'claude-haiku-4-5-20251001';
+        return {
+            async summarizeBatch(symbols) {
+                if (symbols.length === 0)
+                    return new Map();
+                const allResults = new Map();
+                for (let i = 0; i < symbols.length; i += batchSize) {
+                    const batch = symbols.slice(i, i + batchSize);
+                    try {
+                        const results = await summarizeBatchWithRetry(batch, async (prompt) => {
+                            const response = await callAnthropic(apiKey, model, [
+                                { role: 'user', content: prompt },
+                            ], httpClient);
+                            return response.content.filter((c) => c.type === 'text').map((c) => c.text).join('');
+                        });
+                        for (const [id, summary] of results)
+                            allResults.set(id, summary);
+                        logger.debug(`AI summarized ${results.size}/${batch.length} symbols (batch ${Math.floor(i / batchSize) + 1})`);
+                    }
+                    catch (err) {
+                        logger.warn(`AI summarization batch failed: ${err} — falling back to Stage 4`);
+                    }
+                }
+                return allResults;
+            },
+        };
+    }
+    // ── OpenAI-compatible ───────────────────────────────────────────────────────
+    if (provider === 'openai-compatible') {
+        const endpoint = config.endpoint;
+        if (!endpoint) {
+            logger.warn('ai.provider is openai-compatible but ai.endpoint is not set — skipping Stage 3');
+            return null;
+        }
+        const apiKey = config.apiKey || '';
+        const model = config.model ?? 'gpt-4o-mini';
+        return {
+            async summarizeBatch(symbols) {
+                if (symbols.length === 0)
+                    return new Map();
+                const allResults = new Map();
+                for (let i = 0; i < symbols.length; i += batchSize) {
+                    const batch = symbols.slice(i, i + batchSize);
+                    try {
+                        const results = await summarizeBatchWithRetry(batch, async (prompt) => {
+                            const response = await callOpenAICompatible(endpoint, apiKey, model, prompt, fetchFn);
+                            return response.choices[0]?.message?.content ?? '';
+                        });
+                        for (const [id, summary] of results)
+                            allResults.set(id, summary);
+                        logger.debug(`AI summarized ${results.size}/${batch.length} symbols (batch ${Math.floor(i / batchSize) + 1})`);
+                    }
+                    catch (err) {
+                        logger.warn(`AI summarization batch failed: ${err} — falling back to Stage 4`);
+                    }
+                }
+                return allResults;
+            },
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=ai-summarizer.js.map

package/dist/summarizer/ai-summarizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-summarizer.js","sourceRoot":"","sources":["../../src/summarizer/ai-summarizer.ts"],"names":[],"mappings":"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"}

package/dist/summarizer/docstring-extractor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse JSDoc / TSDoc comment text and extract a clean one-line description.
+ *
+ * Accepts both:
+ *   - raw comment text including delimiters (`/** ... *\/`)
+ *   - already-stripped text (no delimiters)
+ */
+export declare function extractSummaryFromDocstring(raw: string): string | null;
+//# sourceMappingURL=docstring-extractor.d.ts.map

package/dist/summarizer/docstring-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docstring-extractor.d.ts","sourceRoot":"","sources":["../../src/summarizer/docstring-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmDtE"}

package/dist/summarizer/docstring-extractor.js

@@ -0,0 +1,89 @@
+/**
+ * Parse JSDoc / TSDoc comment text and extract a clean one-line description.
+ *
+ * Accepts both:
+ *   - raw comment text including delimiters (`/** ... *\/`)
+ *   - already-stripped text (no delimiters)
+ */
+export function extractSummaryFromDocstring(raw) {
+    if (!raw.trim())
+        return null;
+    // ── 1. Strip /** ... */ delimiters if present ─────────────────────────────
+    let body = raw.trim();
+    if (body.startsWith('/**')) {
+        body = body.slice(2);
+        if (body.endsWith('*/'))
+            body = body.slice(0, -2);
+    }
+    else if (body.startsWith('/*')) {
+        body = body.slice(2);
+        if (body.endsWith('*/'))
+            body = body.slice(0, -2);
+    }
+    else if (body.startsWith('//')) {
+        body = body.replace(/^\/\/\s?/, '').trim();
+        return cleanText(body) || null;
+    }
+    // ── 2. Strip leading * from each line ────────────────────────────────────
+    const lines = body
+        .split('\n')
+        .map((l) => l.replace(/^\s*\*\s?/, '').trim());
+    // ── 3. Check for @description tag ────────────────────────────────────────
+    const descIdx = lines.findIndex((l) => /^@description\b/i.test(l));
+    if (descIdx >= 0) {
+        // Collect content after @description (possibly multi-line, until next @tag)
+        const descLine = lines[descIdx].replace(/^@description\s*/i, '');
+        const continuation = descLine ? [descLine] : [];
+        for (let i = descIdx + 1; i < lines.length; i++) {
+            if (lines[i].startsWith('@'))
+                break;
+            if (lines[i])
+                continuation.push(lines[i]);
+        }
+        const descText = continuation.join(' ');
+        if (descText)
+            return firstSentence(cleanText(descText));
+    }
+    // ── 4. First paragraph: lines before the first @tag or blank+@tag ────────
+    const paragraphLines = [];
+    for (const line of lines) {
+        if (line.startsWith('@'))
+            break; // reached a tag
+        paragraphLines.push(line);
+    }
+    // Collapse runs of blank lines to one, then use the first non-empty block
+    const paragraphText = paragraphLines
+        .join(' ')
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+    if (!paragraphText)
+        return null;
+    return firstSentence(cleanText(paragraphText)) || null;
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Strip inline markdown formatting:
+ *   `code`, **bold**, *italic*, _italic_, ~~strikethrough~~, [text](url)
+ */
+function cleanText(text) {
+    return text
+        .replace(/`[^`]*`/g, (m) => m.slice(1, -1)) // `code` → code
+        .replace(/\*\*([^*]+)\*\*/g, '$1') // **bold** → bold
+        .replace(/\*([^*]+)\*/g, '$1') // *italic* → italic
+        .replace(/_([^_]+)_/g, '$1') // _italic_ → italic
+        .replace(/~~([^~]+)~~/g, '$1') // ~~strike~~ → strike
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // [text](url) → text
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+}
+/**
+ * Return text up to (and including) the first sentence-ending punctuation,
+ * or the full text if none found, capped at 120 chars.
+ */
+function firstSentence(text) {
+    const match = text.match(/^(.{1,120}?[.!?])(?:\s|$)/);
+    if (match)
+        return match[1].trim();
+    return text.slice(0, 120).trim();
+}
+//# sourceMappingURL=docstring-extractor.js.map

package/dist/summarizer/docstring-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docstring-extractor.js","sourceRoot":"","sources":["../../src/summarizer/docstring-extractor.ts"],"names":[],"mappings":"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"}

package/dist/summarizer/embeddings.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Embedding provider abstraction for semantic search.
+ *
+ * Supports:
+ *   voyage            — Voyage AI (voyage-code-2; recommended for code)
+ *   openai-compatible — any /v1/embeddings endpoint (Ollama, OpenAI, etc.)
+ *
+ * Returns null when no provider is configured.
+ */
+import type { PureContextConfig } from '../config/config-schema.js';
+export interface EmbeddingProvider {
+    /** Embed one or more texts. Returns one float array per input text. */
+    embed(texts: string[]): Promise<number[][]>;
+}
+/**
+ * Compute cosine similarity between two float vectors.
+ * Both vectors must have the same length. Returns a value in [-1, 1].
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/** Serialize a number[] to a Buffer of 32-bit floats (little-endian). */
+export declare function packEmbedding(vec: number[]): Buffer;
+/** Deserialize a Buffer of 32-bit floats back to number[]. */
+export declare function unpackEmbedding(buf: Buffer): number[];
+/**
+ * Create an embedding provider from the active config, or return null
+ * if no embedding provider is configured.
+ */
+export declare function createEmbeddingProvider(config: PureContextConfig): EmbeddingProvider | null;
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/summarizer/embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/summarizer/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIpE,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;CAC7C;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAYjE;AAID,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAGnD;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAGrD;AAuED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,IAAI,CA4B3F"}