kibi-mcp 0.16.0 → 0.17.2

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,10 +29,13 @@ 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";
 import { handleKbSuggestPredicates, } from "../tools/suggest-predicates.js";
 import { handleKbUpsert } from "../tools/upsert.js";
+import { handleKbValidateUpsert } from "../tools/validate-upsert.js";
 const DEFAULT_TOOL_TIMEOUT_MS = 90_000;
 const TOOL_TIMEOUT_ENV = "KIBI_MCP_TOOL_TIMEOUT_MS";
 const defaultToolsServerDeps = {
@@ -79,13 +82,16 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbDelete,
     handleKbFindGaps,
     handleKbGraph,
+    handleSparql,
     handleKbQuery,
     handleKbSearch,
     handleKbStatus,
+    handleKbSemanticAdvisor,
     handleKbSkillsList,
     handleKbSkillsLoad,
     handleKbSkillsRead,
     handleKbUpsert,
+    handleKbValidateUpsert,
     handleKbModelRequirement,
     handleKbSuggestPredicates,
     handleKbAutopilotGenerate,
@@ -393,10 +399,20 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbGraph(prolog, args);
     }, runtime);
+    addTool(server, "kb_sparql_remote", toolDef("kb_sparql_remote").description, toolDef("kb_sparql_remote").inputSchema, async (args) => {
+        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);
     }, runtime);
+    addTool(server, "kb_validate_upsert", toolDef("kb_validate_upsert").description, toolDef("kb_validate_upsert").inputSchema, async (args) => {
+        return runtime.handleKbValidateUpsert(args);
+    }, runtime);
     addTool(server, "kb_delete", toolDef("kb_delete").description, toolDef("kb_delete").inputSchema, async (args) => {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbDelete(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/model-requirement.js

@@ -308,6 +308,15 @@ export async function handleKbModelRequirement(_prolog, args) {
     });
     const applyPlan = strictWriteSetToApplyPlan(writeSet);
     const migrationWarning = await getWorkspaceMigrationWarning();
+    const warnings = writeSet.isStrict
+        ? []
+        : [
+            {
+                kind: "low_confidence_observation_downgrade",
+                message: `Claim confidence ${writeSet.confidence.toFixed(2)} is below the strict threshold 0.70, so Kibi emitted an observation fact instead of strict subject/property facts.`,
+                nextAction: "If this is normative, provide subjectKey, propertyKey, operator, and value explicitly, then apply the returned strict write-set sequentially.",
+            },
+        ];
     const strictSummary = writeSet.isStrict
         ? `Modeled strict requirement into ${applyPlan.length} sequential applyPlan step(s).`
         : "Modeled a non-blocking observation review artifact; deterministic claim extraction stayed below the strict threshold.";
@@ -322,6 +331,7 @@ export async function handleKbModelRequirement(_prolog, args) {
         confidence: writeSet.confidence,
         extractionMode: extracted.extractionMode,
         extractionWarnings: extracted.extractionWarnings,
+        warnings,
         migrationWarning,
     };
     return {

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,
+        },
+    };
+}

package/dist/tools/sparql.js

@@ -0,0 +1,96 @@
+import { runJsonModuleQuery, toPrologAtom } from "./core-module.js";
+// implements REQ-002, REQ-013
+export async function handleSparql(prolog, args) {
+    validateSparqlArgs(args);
+    try {
+        const payload = await runJsonModuleQuery(prolog, "sparql_client.pl", `kibi_sparql_client:remote_sparql_select_json(${toPrologAtom(args.endpoint)}, ${toPrologAtom(args.query)}, ${toSparqlOptions(args)}, JsonString)`, "SPARQL remote query");
+        const rows = payload?.rows ?? [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Remote SPARQL query returned ${rows.length} row${rows.length === 1 ? "" : "s"}.`,
+                },
+            ],
+            ...(payload !== undefined ? { structuredContent: payload } : {}),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`SPARQL remote query failed: ${message}`);
+    }
+}
+function validateSparqlArgs(args) {
+    if (!args.endpoint || args.endpoint.trim().length === 0) {
+        throw new Error("SPARQL endpoint is required");
+    }
+    if (!args.query || args.query.trim().length === 0) {
+        throw new Error("SPARQL query is required");
+    }
+    if (!isRemoteHttpEndpoint(args.endpoint)) {
+        throw new Error("SPARQL endpoint must be an http:// or https:// URL");
+    }
+    if (!isSelectQuery(args.query)) {
+        throw new Error("SPARQL query must be a SELECT query");
+    }
+    if (!isPublicRemoteEndpoint(args.endpoint)) {
+        throw new Error("SPARQL endpoint must target a public remote host");
+    }
+    if (args.timeoutMs !== undefined &&
+        (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+        throw new Error("SPARQL timeoutMs must be a positive number when provided");
+    }
+}
+function isRemoteHttpEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function isSelectQuery(query) {
+    return /^\s*select\b/i.test(query);
+}
+function isPublicRemoteEndpoint(endpoint) {
+    const url = new URL(endpoint);
+    const host = normalizeHostname(url.hostname);
+    return !isLocalOrPrivateHost(host);
+}
+function normalizeHostname(hostname) {
+    return hostname
+        .toLowerCase()
+        .replace(/^\[/, "")
+        .replace(/\]$/, "")
+        .replace(/\.$/, "");
+}
+function isLocalOrPrivateHost(host) {
+    if (host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host === "0.0.0.0" ||
+        host === "::1" ||
+        (host.includes(":") &&
+            (host.startsWith("fe80:") ||
+                host.startsWith("fc") ||
+                host.startsWith("fd")))) {
+        return true;
+    }
+    const octets = host.split(".").map((part) => Number(part));
+    if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet))) {
+        return false;
+    }
+    const [first = -1, second = -1] = octets;
+    return (first === 10 ||
+        first === 127 ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168));
+}
+function toSparqlOptions(args) {
+    if (args.timeoutMs === undefined) {
+        return "[]";
+    }
+    const timeoutSeconds = Math.max(1, Math.ceil(args.timeoutMs / 1000));
+    return `[timeout(${timeoutSeconds})]`;
+}