knodin 0.5.0

package/dist/src/response-budget.js

@@ -0,0 +1,184 @@
+const encoder = new TextEncoder();
+export const MIN_RESPONSE_BUDGET_BYTES = 256;
+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;
+    for (const entry of collectArrays(root)) {
+        totals[entry.path] = entry.value.length;
+        if (entry.value.length > itemLimit) {
+            entry.value.splice(itemLimit);
+            truncated = true;
+        }
+    }
+    const metadata = {
+        byteLimit,
+        tokenLimit,
+        itemLimit,
+        serializedBytes: 0,
+        estimatedTokens: 0,
+        truncated: false,
+        totals,
+    };
+    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

@@ -0,0 +1,53 @@
+/**
+ * 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 { getKnodinTools, handleKnodinTool } from "./tools/knodin-tools.js";
+import { KNODIN_VERSION } from "./version.js";
+export function createServer() {
+    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, repair before relying on graph evidence.",
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: getKnodinTools(),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name !== "knodin" && name !== "reckon") {
+            throw new Error(`unknown tool: ${name}`);
+        }
+        const result = await handleKnodinTool(args);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    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);
+    });
+}