knodin 0.7.5 → 0.7.6

package/dist/src/response-budget.js

@@ -1,194 +0,0 @@
-const encoder = new TextEncoder();
-export const MIN_RESPONSE_BUDGET_BYTES = 256;
-const MAX_REPORTED_TOTAL_PATHS = 128;
-function bytes(value) {
-    return encoder.encode(JSON.stringify(value)).byteLength;
-}
-function positiveInt(value, fallback) {
-    return value == null || !Number.isFinite(value) ? fallback : Math.max(1, Math.trunc(value));
-}
-function collectArrays(value, path = "$") {
-    if (Array.isArray(value)) {
-        return [{ path, value }, ...value.flatMap((item, i) => collectArrays(item, `${path}/${i}`))];
-    }
-    if (!value || typeof value !== "object")
-        return [];
-    return Object.entries(value).flatMap(([key, child]) => collectArrays(child, `${path}/${key}`));
-}
-function collectStrings(value, path = "$") {
-    if (!value || typeof value !== "object")
-        return [];
-    const entries = Array.isArray(value) ? value.entries() : Object.entries(value);
-    const found = [];
-    for (const [key, child] of entries) {
-        const childPath = `${path}/${String(key)}`;
-        if (typeof child === "string") {
-            found.push({ parent: value, key, path: childPath, value: child });
-        }
-        else {
-            found.push(...collectStrings(child, childPath));
-        }
-    }
-    return found;
-}
-const PROTECTED_CONTRACT_KEYS = new Set([
-    "identity",
-    "symbol",
-    "file",
-    "filePath",
-    "error",
-    "status",
-    "operation",
-    "kind",
-    "name",
-    "target",
-    "to",
-]);
-function isTruncatableDetail(entry) {
-    return typeof entry.key !== "string" || !PROTECTED_CONTRACT_KEYS.has(entry.key);
-}
-/**
- * Applies limits to the value that is actually JSON-serialized. Token accounting
- * intentionally uses the deterministic local estimate of four UTF-8 bytes/token;
- * callers can therefore reproduce the ceiling without installing a tokenizer.
- */
-export function applyResponseBudget(value, operation, request, defaults) {
-    const byteRequest = positiveInt(request.bytes, defaults.bytes);
-    const tokenLimit = positiveInt(request.tokens, defaults.tokens);
-    const byteLimit = Math.min(byteRequest, tokenLimit * 4);
-    if (byteLimit < MIN_RESPONSE_BUDGET_BYTES) {
-        throw new RangeError(`response budget must allow at least ${MIN_RESPONSE_BUDGET_BYTES} serialized bytes (64 estimated tokens)`);
-    }
-    const itemLimit = positiveInt(request.items, defaults.items);
-    const payload = structuredClone(value);
-    const root = Array.isArray(payload)
-        ? { results: payload }
-        : payload && typeof payload === "object"
-            ? payload
-            : { result: payload };
-    const totals = {};
-    let truncated = false;
-    const initialArrays = collectArrays(root);
-    const reportedTotals = [...initialArrays]
-        .sort((left, right) => left.path.split("/").length - right.path.split("/").length ||
-        left.path.localeCompare(right.path))
-        .slice(0, MAX_REPORTED_TOTAL_PATHS);
-    for (const entry of reportedTotals)
-        totals[entry.path] = entry.value.length;
-    for (const entry of initialArrays) {
-        if (entry.value.length > itemLimit) {
-            entry.value.splice(itemLimit);
-            truncated = true;
-        }
-    }
-    const metadata = {
-        byteLimit,
-        tokenLimit,
-        itemLimit,
-        serializedBytes: 0,
-        estimatedTokens: 0,
-        truncated: false,
-        totals,
-        ...(initialArrays.length > reportedTotals.length
-            ? { omittedTotalPaths: initialArrays.length - reportedTotals.length }
-            : {}),
-    };
-    root.responseBudget = metadata;
-    // Preserve collection contracts and identifiers where possible: large source,
-    // artifact and diagnostic strings are the first expendable detail.
-    while (bytes(root) > byteLimit) {
-        const candidate = collectStrings(root)
-            .filter((entry) => !entry.path.startsWith("$/responseBudget") &&
-            entry.value.length > 0 &&
-            isTruncatableDetail(entry))
-            .sort((a, b) => b.value.length - a.value.length)[0];
-        if (!candidate)
-            break;
-        const marker = "\n… [truncated]";
-        if (candidate.value.length <= marker.length + 1) {
-            if (Array.isArray(candidate.parent))
-                candidate.parent.splice(candidate.key, 1);
-            else
-                delete candidate.parent[candidate.key];
-            truncated = true;
-            continue;
-        }
-        const keep = Math.max(0, Math.floor((candidate.value.length - marker.length) / 2));
-        candidate.parent[candidate.key] =
-            `${candidate.value.slice(0, keep)}${marker}`;
-        truncated = true;
-    }
-    // Only drop tail items after scalar detail has been exhausted.
-    while (bytes(root) > byteLimit) {
-        const candidate = collectArrays(root)
-            .filter((entry) => !entry.path.startsWith("$/responseBudget") && entry.value.length > 0)
-            .sort((a, b) => bytes(b.value) - bytes(a.value))[0];
-        if (!candidate)
-            break;
-        candidate.value.pop();
-        truncated = true;
-    }
-    metadata.truncated = truncated;
-    if (truncated) {
-        metadata.continuation = {
-            operation,
-            after: "returned-items",
-            instruction: `Repeat ${operation} with a narrower selector, larger budget, or query drill-down.`,
-        };
-    }
-    // Metadata changes the byte count, so converge after setting it. The reserve
-    // above is normally enough; this final pass handles unusually long paths.
-    metadata.serializedBytes = bytes(root);
-    metadata.estimatedTokens = Math.ceil(metadata.serializedBytes / 4);
-    if (bytes(root) > byteLimit && metadata.continuation) {
-        metadata.continuation.instruction = "Narrow or increase budget.";
-        metadata.serializedBytes = bytes(root);
-        metadata.estimatedTokens = Math.ceil(metadata.serializedBytes / 4);
-    }
-    while (bytes(root) > byteLimit) {
-        const candidate = collectStrings(root)
-            .filter((entry) => !entry.path.startsWith("$/responseBudget") &&
-            entry.value.length > 0 &&
-            isTruncatableDetail(entry))
-            .sort((a, b) => b.value.length - a.value.length)[0];
-        if (!candidate)
-            break;
-        const marker = "\n… [truncated]";
-        if (candidate.value.length <= marker.length + 1) {
-            if (Array.isArray(candidate.parent))
-                candidate.parent.splice(candidate.key, 1);
-            else
-                delete candidate.parent[candidate.key];
-        }
-        else {
-            const keep = Math.max(0, Math.floor((candidate.value.length - marker.length) / 2));
-            candidate.parent[candidate.key] =
-                `${candidate.value.slice(0, keep)}${marker}`;
-        }
-        metadata.truncated = true;
-    }
-    metadata.serializedBytes = bytes(root);
-    metadata.estimatedTokens = Math.ceil(metadata.serializedBytes / 4);
-    while (bytes(root) > byteLimit) {
-        const candidate = collectArrays(root)
-            .filter((entry) => !entry.path.startsWith("$/responseBudget") && entry.value.length > 0)
-            .sort((a, b) => bytes(b.value) - bytes(a.value))[0];
-        if (!candidate)
-            break;
-        candidate.value.pop();
-        metadata.truncated = true;
-        metadata.serializedBytes = bytes(root);
-        metadata.estimatedTokens = Math.ceil(metadata.serializedBytes / 4);
-    }
-    for (let iteration = 0; iteration < 8; iteration++) {
-        const actual = bytes(root);
-        const tokens = Math.ceil(actual / 4);
-        if (metadata.serializedBytes === actual && metadata.estimatedTokens === tokens)
-            break;
-        metadata.serializedBytes = actual;
-        metadata.estimatedTokens = tokens;
-    }
-    if (bytes(root) > byteLimit)
-        throw new RangeError(`response budget ${byteLimit} cannot preserve the ${operation} response contract; narrow the request or increase the budget`);
-    return root;
-}

package/dist/src/server.js

@@ -1,172 +0,0 @@
-/**
- * knodin MCP server (stdio).
- *
- * Registration uses the low-level request-handler API — NOT the high-level
- * `server.tool()` overload — so `tsc` never pays the Zod→handler-arg inference
- * cost that OOMs large tool sets. Gateway `inputSchema`s are hand-written JSON
- * Schema literals; handler args are narrowed manually inside each dispatcher.
- */
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { recordDiagnosticFailure } from "./diagnostics.js";
-import { getKnodinTools, handleKnodinTool } from "./tools/knodin-tools.js";
-import { KNODIN_VERSION } from "./version.js";
-const RETRY_SAFE_OPERATIONS = new Set([
-    "architecture_overview",
-    "context",
-    "docs",
-    "explain",
-    "map",
-    "query",
-    "review",
-    "search",
-    "status",
-]);
-class GatewayRequestQueue {
-    tail = Promise.resolve();
-    pending = 0;
-    async run(signal, task) {
-        const position = this.pending++;
-        const predecessor = this.tail;
-        let release;
-        this.tail = new Promise((resolve) => {
-            release = resolve;
-        });
-        try {
-            await predecessor;
-            if (signal.aborted)
-                throw Object.assign(new Error("MCP request cancelled before dispatch"), {
-                    code: "KNODIN_REQUEST_CANCELLED",
-                });
-            return await task(position);
-        }
-        finally {
-            this.pending--;
-            release();
-        }
-    }
-}
-function ignoreNotificationFailure() {
-    // Progress is advisory; a client that stops accepting it must not fail the tool call.
-}
-function startHeartbeat(notify, operation, startedAt) {
-    return setInterval(() => {
-        void notify(`${operation} still running (${Math.round((Date.now() - startedAt) / 1000)}s)`).catch(ignoreNotificationFailure);
-    }, 10_000);
-}
-export function recordMcpDiagnosticFailure(args, error, defaultRepo = process.cwd()) {
-    const effectiveRepo = typeof args?.repoPath === "string" ? args.repoPath : defaultRepo;
-    const diagnostic = recordDiagnosticFailure(effectiveRepo, {
-        surface: "mcp",
-        operation: typeof args?.operation === "string" ? args.operation : "unknown",
-        phase: "dispatch",
-        error,
-    });
-    return diagnostic.recorded
-        ? new Error(`${error instanceof Error ? error.message : String(error)} [diagnostic ${diagnostic.correlationId}]`, { cause: error })
-        : error;
-}
-export function createServer(dispatch = handleKnodinTool) {
-    const queue = new GatewayRequestQueue();
-    const server = new Server({ name: "knodin", version: KNODIN_VERSION }, {
-        capabilities: { tools: {} },
-        instructions: "Use knodin first for cold or unfamiliar codebase work: context to orient, explain for source-evidenced symbol context, query impact before meaningful edits, and review before handoff. Prefer direct reads for exact literals, non-code files, or files just edited this turn. If status reports repair-needed, follow its typed repair steps: repair graph damage or init displaced lifecycle routing before relying on graph evidence.",
-    });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: getKnodinTools(),
-    }));
-    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-        const { name, arguments: args } = request.params;
-        if (name !== "knodin") {
-            throw new Error(`unknown tool: ${name}`);
-        }
-        const values = args;
-        const operation = typeof values?.operation === "string" ? values.operation : "unknown";
-        const progressToken = extra._meta?.progressToken;
-        const requestId = String(extra.requestId);
-        const startedAt = Date.now();
-        let heartbeat;
-        try {
-            const result = await queue.run(extra.signal, async (position) => {
-                const notify = async (message) => {
-                    if (progressToken === undefined)
-                        return;
-                    await extra.sendNotification({
-                        method: "notifications/progress",
-                        params: {
-                            progressToken,
-                            progress: Date.now() - startedAt,
-                            message,
-                        },
-                    });
-                };
-                await notify(position > 0
-                    ? `Starting ${operation} after waiting behind ${position} earlier request(s)`
-                    : `Starting ${operation}`);
-                heartbeat = startHeartbeat(notify, operation, startedAt);
-                // Keep the production handler explicit: knodin's own source-evidence
-                // extractor maps this low-level MCP registration to its dispatcher.
-                return dispatch === handleKnodinTool ? await handleKnodinTool(args) : await dispatch(args);
-            });
-            return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-            };
-        }
-        catch (error) {
-            const recorded = recordMcpDiagnosticFailure(values, error);
-            const message = recorded instanceof Error ? recorded.message : String(recorded);
-            const traceId = /\[diagnostic ([a-f0-9]{16})\]/.exec(message)?.[1] ?? `mcp-${requestId}`;
-            const retrySafe = RETRY_SAFE_OPERATIONS.has(operation);
-            return {
-                isError: true,
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            code: error?.code === "KNODIN_REQUEST_CANCELLED"
-                                ? "KNODIN_REQUEST_CANCELLED"
-                                : "KNODIN_OPERATION_FAILED",
-                            message,
-                            traceId,
-                            requestId,
-                            operation,
-                            repository: typeof values?.repoPath === "string" ? values.repoPath : process.cwd(),
-                            phase: "dispatch",
-                            retrySafe,
-                            diagnosticLog: ".knodin/diagnostics/events.jsonl (only when opt-in diagnostics are enabled)",
-                            recovery: retrySafe
-                                ? "Retry once. If the transport closes, restart the MCP client and run `knodin doctor`; include `knodin diagnostics export` when diagnostics are enabled."
-                                : "Do not retry automatically. Run `knodin doctor`, inspect repository state, and include `knodin diagnostics export` when diagnostics are enabled.",
-                        }, null, 2),
-                    },
-                ],
-            };
-        }
-        finally {
-            if (heartbeat)
-                clearInterval(heartbeat);
-        }
-    });
-    return server;
-}
-async function main() {
-    const server = createServer();
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    // stdio server: log to stderr so stdout stays a clean JSON-RPC channel.
-    console.error("knodin MCP server running on stdio");
-}
-/** Start the stdio gateway from either the direct server entry or the packaged CLI. */
-export async function startServer() {
-    await main();
-}
-// Run only when invoked directly (not when imported by tests).
-if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
-    startServer().catch((err) => {
-        console.error(err);
-        process.exit(1);
-    });
-}