knodin 0.8.6 → 0.9.0

package/dist/src/repository-management.js

@@ -901,7 +901,12 @@ function decodeCursor(cursor, hash) {
             (value.repository ?? -1) < 0 ||
             (value.offset ?? -1) < 0)
             throw new Error("invalid cursor");
-        return { repository: value.repository ?? 0, offset: value.offset ?? 0 };
+        return {
+            repository: value.repository ?? 0,
+            offset: value.offset ?? 0,
+            ...(value.mode === "fallback" ? { mode: "fallback" } : {}),
+            ...(value.mode === "symbol-only" ? { mode: "symbol-only" } : {}),
+        };
     }
     catch {
         throw new Error("knodin repos search: cursor does not match this query and selection");
@@ -930,8 +935,146 @@ function searchCandidate(inventory, match, exposePaths) {
         confidence: match.rrfScore || match.similarity,
         freshness: inventory.freshness,
         health: "healthy",
+        matchType: "symbol",
+        systemMemberships: inventory.systemMemberships,
     };
 }
+const TRACKED_TEXT_CANDIDATE_LIMIT = 1000;
+const TRACKED_TEXT_REPOSITORY_LIMIT = 200;
+const TRACKED_TEXT_OUTPUT_LIMIT = 2 * 1024 * 1024;
+const TRACKED_TEXT_TIMEOUT_MS = 5000;
+function queryTokens(query) {
+    return [
+        ...new Set(query
+            .toLowerCase()
+            .match(/[a-z0-9][a-z0-9._-]{2,}/g)
+            ?.map((token) => token.replace(/^[._-]+|[._-]+$/g, ""))
+            .filter(Boolean) ?? []),
+    ];
+}
+function tokenCoverage(value, tokens) {
+    const lower = value.toLowerCase();
+    return tokens.filter((token) => lower.includes(token)).length;
+}
+function textFallbackReason(results, query) {
+    if (results.length === 0)
+        return "no-symbol-results";
+    const tokens = queryTokens(query);
+    if (tokens.length < 3)
+        return undefined;
+    return results.every((result) => {
+        const identityCoverage = tokenCoverage(`${result.symbol} ${result.file}`, tokens);
+        const sourceCoverage = tokenCoverage(result.sourceEvidence, tokens);
+        return identityCoverage < 2 && (identityCoverage === 0 || sourceCoverage < 2);
+    })
+        ? "weak-symbol-coverage"
+        : undefined;
+}
+function committedFile(repository, file, timeout) {
+    const result = child_process.spawnSync(gitExecutable(), ["show", `HEAD:${file}`], {
+        cwd: repository,
+        encoding: "buffer",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout,
+        maxBuffer: 1024 * 1024,
+    });
+    return result.status === 0 && !result.error ? result.stdout : undefined;
+}
+function trackedTextWindow(repository, file, line, timeout, cache) {
+    try {
+        let content = cache?.get(file);
+        if (!cache?.has(file)) {
+            content = committedFile(repository, file, timeout);
+            cache?.set(file, content);
+        }
+        if (!content || content.includes(0))
+            return "";
+        const lines = content.toString("utf8").split(/\r?\n/);
+        const start = Math.max(0, line - 3);
+        return lines
+            .slice(start, Math.min(lines.length, line + 2))
+            .map((value, index) => `${start + index + 1}: ${value}`)
+            .join("\n");
+    }
+    catch {
+        return "";
+    }
+}
+function trackedTextMatches(inventory, query, exposePaths) {
+    if (!inventory.path)
+        return { matches: [], truncated: false };
+    const tokens = queryTokens(query);
+    if (tokens.length === 0)
+        return { matches: [], truncated: false };
+    const started = Date.now();
+    const remaining = () => Math.max(1, TRACKED_TEXT_TIMEOUT_MS - (Date.now() - started));
+    const args = ["grep", "-n", "-I", "-F", "-i"];
+    for (const token of tokens)
+        args.push("-e", token);
+    args.push("HEAD");
+    const result = child_process.spawnSync(gitExecutable(), args, {
+        cwd: inventory.path,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: remaining(),
+        maxBuffer: TRACKED_TEXT_OUTPUT_LIMIT,
+    });
+    if (result.error && result.error.code !== "ENOBUFS")
+        return { matches: [], truncated: true };
+    const lines = String(result.stdout ?? "")
+        .split(/\r?\n/)
+        .filter(Boolean);
+    const truncated = lines.length > TRACKED_TEXT_REPOSITORY_LIMIT || result.error !== undefined;
+    const records = lines.flatMap((record) => {
+        const match = /^HEAD:(.+?):(\d+):(.*)$/.exec(record);
+        if (!match?.[1] || !match[2])
+            return [];
+        const file = match[1];
+        const extension = path.extname(file).toLowerCase();
+        if (![".yaml", ".yml", ".sh", ".bash", ".zsh", ""].includes(extension))
+            return [];
+        if (extension === "") {
+            const content = committedFile(inventory.path ?? "", file, remaining());
+            if (!content || !content.toString("utf8", 0, 128).startsWith("#!"))
+                return [];
+        }
+        return [{ file, line: Number(match[2]), matchedSource: match[3] ?? "" }];
+    });
+    const phrase = query.trim().toLowerCase();
+    const contentCache = new Map();
+    const matches = records.slice(0, TRACKED_TEXT_REPOSITORY_LIMIT).flatMap((record) => {
+        const { file, line, matchedSource } = record;
+        const source = trackedTextWindow(inventory.path ?? "", file, line, remaining(), contentCache) ||
+            matchedSource;
+        const coverage = tokenCoverage(`${file} ${source}`, tokens);
+        const exactPhrase = phrase.length > 0 && source.toLowerCase().includes(phrase) ? 1 : 0;
+        const pathCoverage = tokenCoverage(file, tokens);
+        return [
+            {
+                repositoryId: inventory.id,
+                ...(exposePaths === false ? {} : { repositoryPath: inventory.path }),
+                identity: `text_${crypto.createHash("sha256").update(`${inventory.id}\0${file}\0${line}`).digest("hex").slice(0, 20)}`,
+                symbol: path.basename(file),
+                kind: "tracked-text",
+                file,
+                line,
+                sourceEvidence: source.slice(0, 4000),
+                sourceTruncated: source.length > 4000,
+                confidence: coverage / tokens.length + exactPhrase * 0.01 + pathCoverage * 0.001,
+                freshness: inventory.freshness,
+                health: "healthy",
+                matchType: "tracked-text",
+                systemMemberships: inventory.systemMemberships,
+                _score: [coverage, exactPhrase, pathCoverage],
+            },
+        ];
+    });
+    matches.sort((left, right) => right._score[0] - left._score[0] ||
+        right._score[1] - left._score[1] ||
+        right._score[2] - left._score[2] ||
+        compareBytes(`${left.repositoryId}:${left.file}:${left.line}`, `${right.repositoryId}:${right.file}:${right.line}`));
+    return { matches: matches.map(({ _score: _ignored, ...match }) => match), truncated };
+}
 async function searchHealthyRepository(inventory, repositoryIndex, offset, context) {
     const { query, itemLimit, effectiveBytes, results, omissions, selected, options } = context;
     const page = await options.search(query, inventory.path ?? "", itemLimit - results.length + 1, offset);
@@ -1013,6 +1156,7 @@ export async function searchRepositories(roots, query, options) {
         .digest("hex")
         .slice(0, 20);
     const start = decodeCursor(options.cursor, hash);
+    const symbolStart = start.mode === "fallback" ? { repository: 0, offset: 0 } : start;
     const itemLimit = Math.min(Math.max(options.itemBudget ?? 25, 1), 1000);
     if (options.byteBudget !== undefined && options.byteBudget < 1024)
         throw new Error("knodin repos search: byte budget must be at least 1024");
@@ -1021,7 +1165,58 @@ export async function searchRepositories(roots, query, options) {
     const byteLimit = options.byteBudget ?? 65_536;
     const tokenLimit = options.tokenBudget ?? 16_384;
     const effectiveBytes = Math.min(byteLimit, tokenLimit * 4);
-    const { results, omissions, next } = await collectRepositorySearchResults(selected, start, query, itemLimit, effectiveBytes, options);
+    const { results, omissions, next } = await collectRepositorySearchResults(selected, symbolStart, query, itemLimit, effectiveBytes, options);
+    const fallbackReason = start.mode === "symbol-only" ? undefined : textFallbackReason(results, query);
+    let textFallbackTruncated = false;
+    let fallbackCursor;
+    if (fallbackReason) {
+        const textMatches = [];
+        const eligible = selected.filter(({ health }) => health === "healthy");
+        const inspected = eligible.slice(0, 25);
+        if (inspected.length < eligible.length)
+            textFallbackTruncated = true;
+        for (const inventory of inspected) {
+            const text = trackedTextMatches(inventory, query, options.exposePaths);
+            textFallbackTruncated ||= text.truncated;
+            textMatches.push(...text.matches);
+            if (textMatches.length >= TRACKED_TEXT_CANDIDATE_LIMIT) {
+                textFallbackTruncated = true;
+                break;
+            }
+        }
+        textMatches.sort((left, right) => right.confidence - left.confidence ||
+            compareBytes(`${left.repositoryId}:${left.file}:${left.line ?? 0}`, `${right.repositoryId}:${right.file}:${right.line ?? 0}`));
+        const combined = textMatches.slice(0, TRACKED_TEXT_CANDIDATE_LIMIT);
+        const fallbackOffset = start.mode === "fallback" ? start.offset : 0;
+        const page = [];
+        let nextOffset = fallbackOffset;
+        while (nextOffset < combined.length && page.length < itemLimit) {
+            const candidate = combined[nextOffset];
+            if (!candidate)
+                break;
+            const probe = JSON.stringify({
+                results: [...page, candidate],
+                omissions,
+                repositories: selected,
+            });
+            if (Buffer.byteLength(probe) > effectiveBytes && page.length > 0)
+                break;
+            page.push(candidate);
+            nextOffset += 1;
+            if (Buffer.byteLength(probe) > effectiveBytes)
+                break;
+        }
+        results.splice(0, results.length, ...page);
+        if (nextOffset < combined.length)
+            fallbackCursor = encodeCursor({
+                hash,
+                repository: 0,
+                offset: nextOffset,
+                mode: "fallback",
+            });
+        else if (results.length > 0 || next)
+            fallbackCursor = encodeCursor({ hash, repository: 0, offset: 0, mode: "symbol-only" });
+    }
     if (omissions.length > 0 && options.allowPartial !== true) {
         return finalizeRepositorySearch({
             schemaVersion: 1,
@@ -1040,7 +1235,28 @@ export async function searchRepositories(roots, query, options) {
         results,
         repositories: selected,
         omissions,
-        ...(next ? { cursor: encodeCursor({ hash, ...next }) } : {}),
+        ...(fallbackReason
+            ? {
+                retrieval: {
+                    textFallback: true,
+                    reason: fallbackReason,
+                    inspectedRepositories: Math.min(25, selected.filter(({ health }) => health === "healthy").length),
+                    candidateLimit: TRACKED_TEXT_CANDIDATE_LIMIT,
+                    truncated: textFallbackTruncated,
+                },
+            }
+            : {}),
+        ...(fallbackCursor
+            ? { cursor: fallbackCursor }
+            : !fallbackReason && next
+                ? {
+                    cursor: encodeCursor({
+                        hash,
+                        ...next,
+                        mode: start.mode === "symbol-only" ? "symbol-only" : "symbol",
+                    }),
+                }
+                : {}),
     };
     return finalizeRepositorySearch(base, byteLimit, tokenLimit, itemLimit);
 }

package/dist/src/response-budget.js

@@ -42,9 +42,11 @@ const PROTECTED_CONTRACT_KEYS = new Set([
     "operation",
     "kind",
     "name",
+    "client",
     "target",
     "to",
 ]);
+const PROTECTED_CONTRACT_ARRAY_PATHS = new Set(["$/agents/clients"]);
 function isTruncatableDetail(entry) {
     return (!entry.path.startsWith("$/sharedIndex/") &&
         (typeof entry.key !== "string" || !PROTECTED_CONTRACT_KEYS.has(entry.key)));
@@ -105,7 +107,9 @@ function truncatePayloadToBytes(root, byteLimit) {
     }
     while (bytes(root) > byteLimit) {
         const candidate = collectArrays(root)
-            .filter((entry) => !entry.path.startsWith("$/responseBudget") && entry.value.length > 0)
+            .filter((entry) => !entry.path.startsWith("$/responseBudget") &&
+            !PROTECTED_CONTRACT_ARRAY_PATHS.has(entry.path) &&
+            entry.value.length > 0)
             .sort((a, b) => bytes(b.value) - bytes(a.value))[0];
         if (!candidate)
             break;

package/dist/src/server.js

@@ -23,6 +23,7 @@ const RETRY_SAFE_OPERATIONS = new Set([
     "explain",
     "map",
     "query",
+    "query_batch",
     "review",
     "search",
     "status",
@@ -69,7 +70,9 @@ export function recordMcpDiagnosticFailure(args, error, defaultRepo = process.cw
     });
     const message = error instanceof Error ? error.message : String(error);
     return diagnostic.recorded
-        ? new Error(`${message} [diagnostic ${diagnostic.correlationId}]`, { cause: error })
+        ? new Error(`${message} [diagnostic ${diagnostic.correlationId}]`, {
+            cause: error,
+        })
         : error;
 }
 export function createServer(dispatch = handleKnodinTool) {
@@ -111,7 +114,11 @@ export function createServer(dispatch = handleKnodinTool) {
                         void extra
                             .sendNotification({
                             method: "notifications/progress",
-                            params: { progressToken, progress: sequence, message: phase },
+                            params: {
+                                progressToken,
+                                progress: sequence,
+                                message: phase,
+                            },
                         })
                             .catch(ignoreNotificationFailure);
                 })
@@ -121,7 +128,9 @@ export function createServer(dispatch = handleKnodinTool) {
                             if (progressToken === undefined)
                                 return;
                             progressSequence++;
-                            recordMcpLifecycle(context, "progress", { sequence: progressSequence });
+                            recordMcpLifecycle(context, "progress", {
+                                sequence: progressSequence,
+                            });
                             await extra.sendNotification({
                                 method: "notifications/progress",
                                 params: {
@@ -143,7 +152,9 @@ export function createServer(dispatch = handleKnodinTool) {
                     }, { cooperativeCancellation: operation === "repair" })),
                 };
             const result = execution.result;
-            recordMcpLifecycle(context, "success", { elapsedMs: Date.now() - startedAt });
+            recordMcpLifecycle(context, "success", {
+                elapsedMs: Date.now() - startedAt,
+            });
             return {
                 _meta: {
                     requestId: context.requestId,
@@ -192,7 +203,9 @@ export function createServer(dispatch = handleKnodinTool) {
         finally {
             if (heartbeat)
                 clearInterval(heartbeat);
-            recordMcpLifecycle(context, "cleanup", { elapsedMs: Date.now() - startedAt });
+            recordMcpLifecycle(context, "cleanup", {
+                elapsedMs: Date.now() - startedAt,
+            });
         }
     });
     return server;

package/dist/src/shared-index/compatibility.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL_ID, EMBEDDING_MODEL_REVISION, } from "../engine/embeddings.js";
+import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL_DTYPE, EMBEDDING_MODEL_ID, EMBEDDING_MODEL_REVISION, } from "../engine/embeddings.js";
 import { KNODIN_SCHEMA_VERSION } from "../engine/index.js";
 import { prunePolicyDescriptor } from "../engine/prune.js";
 import { KNODIN_VERSION } from "../version.js";
@@ -44,6 +44,7 @@ export function currentSharedIndexCompatibility() {
         id: EMBEDDING_MODEL_ID,
         revision: EMBEDDING_MODEL_REVISION,
         dimensions: EMBEDDING_DIMENSIONS,
+        dtype: EMBEDDING_MODEL_DTYPE,
         runtime: `@huggingface/transformers@${packageVersion("@huggingface/transformers")}`,
     };
     const parsers = {
@@ -61,9 +62,10 @@ export function currentSharedIndexCompatibility() {
         modelDigest: digest(model),
         parserBundleDigest: digest(parsers),
         indexConfigDigest: digest({
-            policyVersion: 1,
+            policyVersion: 2,
             databaseSchemaVersion: KNODIN_SCHEMA_VERSION,
             embeddingDimensions: EMBEDDING_DIMENSIONS,
+            embeddingDtype: EMBEDDING_MODEL_DTYPE,
         }),
         prunePolicyDigest: digest(prunePolicyDescriptor()),
     };

package/dist/src/skill-management.js

@@ -0,0 +1,149 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const KNODIN_SKILLS = [
+    "knodin-explore",
+    "knodin-debug",
+    "knodin-impact",
+    "knodin-refactor",
+    "knodin-review",
+    "knodin-systems",
+    "knodin-lifecycle",
+];
+const MANIFEST = ".knodin-managed.json";
+function canonicalRoot() {
+    const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(moduleDirectory, "..", "skills"),
+        path.resolve(moduleDirectory, "..", "..", "skills"),
+    ];
+    const root = candidates.find((candidate) => fs.existsSync(candidate));
+    if (!root)
+        throw new Error("knodin packaged skills are missing");
+    return root;
+}
+function destinationRoot(client, scope, repo, home) {
+    if (scope === "team") {
+        if (client === "codex")
+            return path.join(repo, ".agents", "skills");
+        if (client === "claude")
+            return path.join(repo, ".claude", "skills");
+        return path.join(repo, ".gemini", "skills");
+    }
+    if (client === "codex")
+        return path.join(home, ".agents", "skills");
+    if (client === "claude")
+        return path.join(home, ".claude", "skills");
+    return path.join(home, ".gemini", "skills");
+}
+function sourceDigest(source) {
+    const hash = crypto.createHash("sha256");
+    for (const relative of ["SKILL.md", path.join("agents", "openai.yaml")])
+        hash.update(fs.readFileSync(path.join(source, relative)));
+    return hash.digest("hex");
+}
+function managedState(target) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(target, MANIFEST), "utf8"));
+        if (manifest.owner !== "knodin")
+            return "unmanaged";
+        return manifest.digest === sourceDigest(target) ? "managed" : "modified";
+    }
+    catch {
+        return "unmanaged";
+    }
+}
+export function installKnodinSkills(options) {
+    const result = {
+        scope: options.scope,
+        installed: [],
+        removed: [],
+        unchanged: [],
+        issues: [],
+    };
+    if (options.scope === "cli-only")
+        return result;
+    const home = options.home ?? os.homedir();
+    for (const client of options.clients) {
+        const root = destinationRoot(client, options.scope, path.resolve(options.repo), home);
+        for (const name of KNODIN_SKILLS) {
+            const source = path.join(canonicalRoot(), name);
+            const target = path.join(root, name);
+            const digest = sourceDigest(source);
+            if (fs.existsSync(target)) {
+                const state = managedState(target);
+                if (state !== "managed") {
+                    result.issues.push({
+                        path: target,
+                        message: `${state} skill collision; left unchanged`,
+                    });
+                    continue;
+                }
+            }
+            try {
+                const current = JSON.parse(fs.readFileSync(path.join(target, MANIFEST), "utf8"));
+                if (current.digest === digest) {
+                    result.unchanged.push(target);
+                    continue;
+                }
+            }
+            catch {
+                // Missing managed version is installed below.
+            }
+            result.installed.push(target);
+            if (options.dryRun)
+                continue;
+            fs.mkdirSync(root, { recursive: true });
+            const temporary = path.join(root, `.${name}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`);
+            fs.cpSync(source, temporary, { recursive: true, errorOnExist: true });
+            fs.writeFileSync(path.join(temporary, MANIFEST), `${JSON.stringify({ owner: "knodin", digest, client }, null, 2)}\n`);
+            if (fs.existsSync(target))
+                fs.renameSync(target, `${temporary}.old`);
+            fs.renameSync(temporary, target);
+            fs.rmSync(`${temporary}.old`, { recursive: true, force: true });
+        }
+    }
+    return result;
+}
+export function removeKnodinSkills(options) {
+    const result = {
+        scope: options.scope,
+        installed: [],
+        removed: [],
+        unchanged: [],
+        issues: [],
+    };
+    const home = options.home ?? os.homedir();
+    for (const client of options.clients) {
+        const root = destinationRoot(client, options.scope, path.resolve(options.repo), home);
+        for (const name of KNODIN_SKILLS) {
+            const target = path.join(root, name);
+            if (!fs.existsSync(target))
+                continue;
+            const state = managedState(target);
+            if (state !== "managed") {
+                result.issues.push({ path: target, message: `${state} skill collision; left unchanged` });
+                continue;
+            }
+            result.removed.push(target);
+            if (!options.dryRun)
+                fs.rmSync(target, { recursive: true });
+        }
+        if (!options.dryRun) {
+            try {
+                fs.rmdirSync(root);
+                fs.rmdirSync(path.dirname(root));
+            }
+            catch (error) {
+                if (!["ENOENT", "ENOTEMPTY"].includes(error.code ?? ""))
+                    throw error;
+            }
+        }
+    }
+    return result;
+}
+export function inspectKnodinSkills(options) {
+    return installKnodinSkills({ ...options, dryRun: true });
+}