kibi-mcp 0.16.1 → 0.17.3

package/dist/semantic-advisor/prose-coverage-evaluator.js

@@ -0,0 +1,66 @@
+import { analyzeSemanticAdvisorInput } from "./analyze-prose.js";
+export function evaluateProseCoverageCorpus(cases) {
+    const failures = cases.flatMap((testCase) => evaluateCase(testCase));
+    const passed = cases.length - failures.length;
+    return {
+        coverage: cases.length === 0 ? 1 : passed / cases.length,
+        summary: {
+            total: cases.length,
+            passed,
+            failed: failures.length,
+        },
+        failures,
+    };
+}
+function evaluateCase(testCase) {
+    const result = analyzeSemanticAdvisorInput({
+        payload: {
+            type: "req",
+            id: `REQ-CORPUS-${testCase.id}`,
+            properties: {
+                title: testCase.id,
+                status: "open",
+                source: "mcp://kibi/prose-coverage-corpus",
+                text_ref: testCase.text,
+            },
+        },
+    });
+    const suggestion = result.receipt.suggestions[0];
+    if (!suggestion) {
+        return [failure(testCase, "No semantic advisor suggestion was produced")];
+    }
+    if (suggestion.kind !== testCase.expected.kind) {
+        return [
+            failure(testCase, `Expected ${testCase.expected.kind} but received ${suggestion.kind}`),
+        ];
+    }
+    if (testCase.expected.kind === "predicate" &&
+        testCase.expected.predicate_name &&
+        suggestion.kind === "predicate" &&
+        suggestion.predicate.predicate_name !== testCase.expected.predicate_name) {
+        return [
+            failure(testCase, `Expected predicate ${testCase.expected.predicate_name} but received ${suggestion.predicate.predicate_name}`),
+        ];
+    }
+    if (testCase.expected.kind === "strict_property") {
+        if (suggestion.kind !== "strict_property") {
+            return [failure(testCase, "Expected strict property suggestion")];
+        }
+        if (testCase.expected.property_key &&
+            suggestion.claim.property_key !== testCase.expected.property_key) {
+            return [
+                failure(testCase, `Expected property ${testCase.expected.property_key} but received ${suggestion.claim.property_key}`),
+            ];
+        }
+        if (testCase.expected.operator &&
+            suggestion.claim.operator !== testCase.expected.operator) {
+            return [
+                failure(testCase, `Expected operator ${testCase.expected.operator} but received ${suggestion.claim.operator}`),
+            ];
+        }
+    }
+    return [];
+}
+function failure(testCase, reason) {
+    return { id: testCase.id, text: testCase.text, reason };
+}

package/dist/semantic-advisor/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/kb-freshness.js

@@ -0,0 +1,88 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+export class KbRefreshError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "KbRefreshError";
+    }
+}
+export async function readBranchKbStamp(branchPath) {
+    const stamp = emptyStamp(branchPath);
+    const errors = [];
+    try {
+        const dirStat = await stat(branchPath);
+        stamp.dirDev = dirStat.dev;
+        stamp.dirIno = dirStat.ino;
+        stamp.dirMtimeMs = dirStat.mtimeMs;
+        stamp.dirCtimeMs = dirStat.ctimeMs;
+        stamp.dirMissing = false;
+    }
+    catch (error) {
+        stamp.dirMissing = true;
+        errors.push(formatStatError(branchPath, error));
+    }
+    const rdfPath = path.join(branchPath, "kb.rdf");
+    try {
+        const rdfStat = await stat(rdfPath);
+        stamp.rdfDev = rdfStat.dev;
+        stamp.rdfIno = rdfStat.ino;
+        stamp.rdfSize = rdfStat.size;
+        stamp.rdfMtimeMs = rdfStat.mtimeMs;
+        stamp.rdfCtimeMs = rdfStat.ctimeMs;
+        stamp.rdfMissing = false;
+    }
+    catch (error) {
+        stamp.rdfMissing = true;
+        errors.push(formatStatError(rdfPath, error));
+    }
+    stamp.errorMessage = errors.length > 0 ? errors.join("; ") : null;
+    return stamp;
+}
+export function sameBranchKbStamp(a, b) {
+    return (a.branchPath === b.branchPath &&
+        a.rdfDev === b.rdfDev &&
+        a.rdfIno === b.rdfIno &&
+        a.rdfSize === b.rdfSize &&
+        a.rdfMtimeMs === b.rdfMtimeMs &&
+        a.rdfCtimeMs === b.rdfCtimeMs &&
+        a.dirDev === b.dirDev &&
+        a.dirIno === b.dirIno &&
+        a.dirMtimeMs === b.dirMtimeMs &&
+        a.dirCtimeMs === b.dirCtimeMs &&
+        a.rdfMissing === b.rdfMissing &&
+        a.dirMissing === b.dirMissing &&
+        a.errorMessage === b.errorMessage);
+}
+export function describeBranchKbStamp(stamp) {
+    return [
+        `branchPath=${stamp.branchPath}`,
+        `rdf(dev=${stamp.rdfDev}, ino=${stamp.rdfIno}, size=${stamp.rdfSize}, mtimeMs=${stamp.rdfMtimeMs}, ctimeMs=${stamp.rdfCtimeMs})`,
+        `dir(dev=${stamp.dirDev}, ino=${stamp.dirIno}, mtimeMs=${stamp.dirMtimeMs}, ctimeMs=${stamp.dirCtimeMs})`,
+        `rdfMissing=${stamp.rdfMissing}`,
+        `dirMissing=${stamp.dirMissing}`,
+        `errorMessage=${stamp.errorMessage ?? "null"}`,
+    ].join(" ");
+}
+function emptyStamp(branchPath) {
+    return {
+        branchPath,
+        rdfDev: null,
+        rdfIno: null,
+        rdfSize: null,
+        rdfMtimeMs: null,
+        rdfCtimeMs: null,
+        dirDev: null,
+        dirIno: null,
+        dirMtimeMs: null,
+        dirCtimeMs: null,
+        rdfMissing: true,
+        dirMissing: true,
+        errorMessage: null,
+    };
+}
+function formatStatError(statPath, error) {
+    if (error instanceof Error) {
+        return `${statPath}: ${error.message}`;
+    }
+    return `${statPath}: ${String(error)}`;
+}

package/dist/server/session.js

@@ -22,6 +22,7 @@ import { PrologProcess } from "kibi-cli/prolog";
 import { copyCleanSnapshot, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, } from "kibi-cli/public/branch-resolver";
 import { getBranchOverride, isMcpDebugEnabled } from "../env.js";
 import { resolveKbPath, resolveWorkspaceRoot } from "../workspace.js";
+import { KbRefreshError, describeBranchKbStamp, readBranchKbStamp, sameBranchKbStamp, } from "./kb-freshness.js";
 const defaultSessionDeps = {
     PrologProcess,
     copyCleanSnapshot,
@@ -39,6 +40,11 @@ let isInitialized = false;
 export let activeBranchName = "develop";
 let ensurePrologTail = Promise.resolve();
 let prologResetGeneration = 0;
+export let attachedBranchKbPath = null;
+let attachedBranchStamp = null;
+export function updateAttachedBranchStamp(stamp) {
+    attachedBranchStamp = stamp;
+}
 export let isShuttingDown = false;
 let shutdownTimeout = null;
 export const inFlightRequests = new Map();
@@ -49,6 +55,8 @@ export function resetSessionStateForTests() {
     activeBranchName = "develop";
     ensurePrologTail = Promise.resolve();
     prologResetGeneration = 0;
+    attachedBranchKbPath = null;
+    attachedBranchStamp = null;
     isShuttingDown = false;
     inFlightRequests.clear();
     if (shutdownTimeout) {
@@ -146,6 +154,8 @@ export async function resetProlog(reason) {
     const current = prologProcess;
     prologProcess = null;
     isInitialized = false;
+    attachedBranchKbPath = null;
+    attachedBranchStamp = null;
     if (current) {
         try {
             await current.terminate();
@@ -155,6 +165,35 @@ export async function resetProlog(reason) {
         }
     }
 }
+async function refreshAttachedBranchKb(prolog, kbPath, assertGeneration) {
+    prolog.invalidateCache();
+    const detachResult = await prolog.query("kb_detach");
+    await assertGeneration();
+    if (!detachResult.success) {
+        throw new KbRefreshError(`KB refresh failed: detach failed: ${detachResult.error || "Unknown error"}`);
+    }
+    const attachResult = await prolog.query(`kb_attach('${kbPath}')`);
+    await assertGeneration();
+    if (!attachResult.success) {
+        throw new KbRefreshError(`KB refresh failed: attach failed: ${attachResult.error || "Unknown error"}`);
+    }
+    return await readBranchKbStamp(kbPath);
+}
+async function refreshAttachedBranchKbWithRetry(prolog, kbPath, currentStamp, assertGeneration) {
+    let postAttachStamp = await refreshAttachedBranchKb(prolog, kbPath, assertGeneration);
+    if (sameBranchKbStamp(postAttachStamp, currentStamp)) {
+        return postAttachStamp;
+    }
+    const preRetryStamp = await readBranchKbStamp(kbPath);
+    postAttachStamp = await refreshAttachedBranchKb(prolog, kbPath, assertGeneration);
+    if (!sameBranchKbStamp(postAttachStamp, preRetryStamp)) {
+        throw new KbRefreshError("KB refresh failed: stamp changed during attach");
+    }
+    return postAttachStamp;
+}
+function usesBranchKbPath(kbPath) {
+    return kbPath.includes("/.kb/branches/") || kbPath.includes("\\.kb\\branches\\");
+}
 // implements REQ-008
 async function ensurePrologUnsafe() {
     const generationAtStart = prologResetGeneration;
@@ -194,8 +233,27 @@ async function ensurePrologUnsafe() {
     }
     // Check if we need to switch branches
     if (isInitialized && prologProcess?.isRunning()) {
+        const kbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
         if (targetBranch === activeBranchName) {
-            // Still on the same branch - return existing connection
+            const currentStamp = await readBranchKbStamp(kbPath);
+            if (usesBranchKbPath(kbPath) &&
+                (currentStamp.rdfMissing ||
+                    currentStamp.dirMissing ||
+                    currentStamp.errorMessage !== null)) {
+                throw new KbRefreshError(`KB refresh failed: branch KB snapshot is unstable: ${describeBranchKbStamp(currentStamp)}`);
+            }
+            const shouldRefresh = attachedBranchKbPath === kbPath &&
+                attachedBranchStamp !== null &&
+                usesBranchKbPath(kbPath) &&
+                !sameBranchKbStamp(currentStamp, attachedBranchStamp);
+            if (shouldRefresh) {
+                attachedBranchStamp = await refreshAttachedBranchKbWithRetry(prologProcess, kbPath, currentStamp, assertGeneration);
+            }
+            else {
+                attachedBranchKbPath = kbPath;
+                attachedBranchStamp = currentStamp;
+            }
+            attachedBranchKbPath = kbPath;
             return prologProcess;
         }
         // Branch changed - need to detach and re-attach
@@ -214,16 +272,17 @@ async function ensurePrologUnsafe() {
         }
         // Ensure new branch KB exists
         ensureBranchKbExists(workspaceRoot, targetBranch);
-        const newKbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
         // Attach to new branch KB
-        const attachResult = await prologProcess.query(`kb_attach('${newKbPath}')`);
+        const attachResult = await prologProcess.query(`kb_attach('${kbPath}')`);
         await assertGeneration();
         if (!attachResult.success) {
             throw new Error(`Failed to attach to new branch KB: ${attachResult.error || "Unknown error"}`);
         }
         activeBranchName = targetBranch;
+        attachedBranchKbPath = kbPath;
+        attachedBranchStamp = await readBranchKbStamp(kbPath);
         debugLog(`[KIBI-MCP] Re-attached to branch: ${targetBranch}`);
-        debugLog(`[KIBI-MCP] KB path: ${newKbPath}`);
+        debugLog(`[KIBI-MCP] KB path: ${kbPath}`);
         return prologProcess;
     }
     // First initialization
@@ -275,6 +334,8 @@ async function ensurePrologUnsafe() {
     if (!attachResult.success) {
         throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
     }
+    attachedBranchKbPath = kbPath;
+    attachedBranchStamp = await readBranchKbStamp(kbPath);
     isInitialized = true;
     debugLog(`[KIBI-MCP] Prolog process started (PID: ${prologProcess.getPid()})`);
     debugLog(`[KIBI-MCP] KB attached: ${kbPath}`);

package/dist/server/tools.js

@@ -29,6 +29,7 @@ import { handleKbGraph } from "../tools/graph.js";
 import { handleKbModelRequirement, } from "../tools/model-requirement.js";
 import { handleKbQuery } from "../tools/query.js";
 import { handleKbSearch } from "../tools/search.js";
+import { handleKbSemanticAdvisor, } from "../tools/semantic-advisor.js";
 import { handleKbSkillsList, handleKbSkillsLoad, handleKbSkillsRead, } from "../tools/skills.js";
 import { handleSparql } from "../tools/sparql.js";
 import { handleKbStatus } from "../tools/status.js";
@@ -85,6 +86,7 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbQuery,
     handleKbSearch,
     handleKbStatus,
+    handleKbSemanticAdvisor,
     handleKbSkillsList,
     handleKbSkillsLoad,
     handleKbSkillsRead,
@@ -401,6 +403,9 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
         const prolog = await runtime.ensureProlog();
         return runtime.handleSparql(prolog, args);
     }, runtime);
+    addTool(server, "kb_semantic_advisor", toolDef("kb_semantic_advisor").description, toolDef("kb_semantic_advisor").inputSchema, async (args) => {
+        return runtime.handleKbSemanticAdvisor(args);
+    }, runtime);
     addTool(server, "kb_upsert", toolDef("kb_upsert").description, toolDef("kb_upsert").inputSchema, async (args) => {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbUpsert(prolog, args);

package/dist/tools/check.js

@@ -116,6 +116,8 @@ export async function handleKbCheck(prolog, args) {
                 },
             };
         }
+        // Ensure we read the latest KB state, not a cached snapshot.
+        prolog.invalidateCache();
         // Run aggregated checks using same approach as CLI
         // This now runs ALL rules including symbol-traceability
         const aggregatedViolations = await runAggregatedChecks(prolog, rulesAllowlist, checksConfig.symbolTraceability.requireAdr);

package/dist/tools/semantic-advisor.js

@@ -0,0 +1,42 @@
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+function normalizeText(value) {
+    const text = typeof value === "string" ? value.trim() : "";
+    if (!text) {
+        throw new Error("Semantic advisor failed: text must be a non-empty string");
+    }
+    return text;
+}
+function optionalString(value) {
+    const text = typeof value === "string" ? value.trim() : "";
+    return text.length > 0 ? text : undefined;
+}
+export async function handleKbSemanticAdvisor(args) {
+    const text = normalizeText(args.text);
+    const id = optionalString(args.id) ?? "REQ-SEMANTIC-ADVISOR-PREVIEW";
+    const title = optionalString(args.title) ?? text.split(/[.!?]/, 1)[0] ?? text;
+    const source = optionalString(args.source) ?? "mcp://kibi/semantic-advisor";
+    const result = analyzeSemanticAdvisorInput({
+        payload: {
+            type: optionalString(args.type) ?? "req",
+            id,
+            properties: {
+                title,
+                status: optionalString(args.status) ?? "open",
+                source,
+                text_ref: text,
+            },
+        },
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `kb_semantic_advisor: ${result.receipt.summary} Suggestions: ${result.receipt.suggestions.map((suggestion) => suggestion.kind).join(", ") || "none"}.`,
+            },
+        ],
+        structuredContent: {
+            receipt: result.receipt,
+            warnings: result.warnings,
+        },
+    };
+}