kibi-mcp 2.0.0 → 2.1.1

package/dist/diagnostics.js

@@ -10,13 +10,32 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendPayloadCountField, normalizeResultPayload } from "kibi-runtime";
 import { resolveWorkspaceRoot } from "./workspace.js";
 export { buildDiagnosticToolCall, classifyDiagnosticError, deriveDiagnosticHints, deriveDiagnosticRetryKey, extractToolCallPayload, redactDiagnosticArgs, } from "./diagnostics-helpers.js";
 const DIAGNOSTIC_MODE_FLAG = "--diagnostic-mode";
-export const DIAGNOSTIC_MODE_ENABLED = process.argv.includes(DIAGNOSTIC_MODE_FLAG);
+const DIAGNOSTIC_MODE_ENV_KEY = "KIBI_DIAGNOSTIC_MODE";
+/**
+ * Usage telemetry is opt-in and stays off unless the operator asks for it.
+ *
+ * The launch flag covers hosts whose MCP command line the operator writes by
+ * hand.  `KIBI_DIAGNOSTIC_MODE=1` covers hosts where a plugin owns the command
+ * line, so opting in never requires editing a shipped launcher.  Neither
+ * signal is set by default, and plugin installation alone never enables it.
+ */
+export function diagnosticModeRequested(argv = process.argv, env = process.env) {
+    if (argv.includes(DIAGNOSTIC_MODE_FLAG))
+        return true;
+    const optIn = env[DIAGNOSTIC_MODE_ENV_KEY]?.trim().toLowerCase();
+    return optIn === "1" || optIn === "true";
+}
+export const DIAGNOSTIC_MODE_ENABLED = diagnosticModeRequested();
 let diagnosticUsageLogPath = null;
+let diagnosticOriginFields = {};
 export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
     diagnosticUsageLogPath = null;
+    diagnosticOriginFields = {};
     if (!enabled) {
         process.env.KIBI_MCP_DIAGNOSTIC_MODE = "0";
         return;
@@ -30,13 +49,50 @@ export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
     diagnosticUsageLogPath =
         process.env.KIBI_MCP_DIAGNOSTIC_USAGE_LOG_PATH ??
             path.join(workspaceRoot, ".kb", "usage.log");
+    diagnosticOriginFields = resolveOriginFields(workspaceRoot);
     process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
 }
+/**
+ * Identify which host, package build, and checkout produced a usage row.
+ *
+ * Without these a multi-worktree or multi-host setup cannot tell whether a
+ * behavioral difference came from the agent, the editor integration, or the
+ * installed Kibi version, because nothing else in a row names its origin.
+ */
+function resolveOriginFields(workspaceRoot) {
+    return {
+        interface: "mcp",
+        host: process.env.KIBI_MCP_HOST?.trim() || "unknown",
+        package_version: readMcpPackageVersion(),
+        workspace_root: workspaceRoot,
+    };
+}
+function readMcpPackageVersion() {
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = path.join(current, "package.json");
+        if (fs.existsSync(candidate)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(candidate, "utf8"));
+                const version = isRecord(parsed) ? parsed.version : undefined;
+                return typeof version === "string" ? version : null;
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
 export function appendUsageLogLine(entry) {
     if (!diagnosticUsageLogPath)
         return;
     fs.mkdirSync(path.dirname(diagnosticUsageLogPath), { recursive: true });
-    fs.appendFileSync(diagnosticUsageLogPath, `${JSON.stringify(entry)}\n`, {
+    const row = { ...diagnosticOriginFields, ...entry };
+    fs.appendFileSync(diagnosticUsageLogPath, `${JSON.stringify(row)}\n`, {
         encoding: "utf8",
     });
 }
@@ -77,12 +133,6 @@ export const DIAGNOSTIC_TELEMETRY_SCHEMA = {
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function structuredContentFrom(result) {
-    if (!isRecord(result))
-        return undefined;
-    const structuredContent = result.structuredContent;
-    return isRecord(structuredContent) ? structuredContent : undefined;
-}
 function stringArray(value) {
     if (!Array.isArray(value))
         return [];
@@ -276,11 +326,8 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
             fields.actor_id = telemetry.actor_id;
         }
     }
-    const envelope = structuredContentFrom(result);
-    const structuredContent = envelope?.kibiProtocol === 1 && isRecord(envelope.data)
-        ? envelope.data
-        : envelope;
-    if (envelope?.kibiProtocol === 1) {
+    const { envelope, data: structuredContent } = normalizeResultPayload(result);
+    if (envelope) {
         fields.protocol_version = envelope.kibiProtocol;
         fields.result_version = envelope.resultVersion ?? null;
         fields.result_status = envelope.status ?? null;
@@ -296,18 +343,14 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
         fields.unsafe_original_retry = telemetry?.unsafe_original_retry === true;
     }
     if (toolName === "kb_query" || toolName === "kb_search") {
-        const resultCount = Number(structuredContent?.count ?? 0);
-        fields.result_count = resultCount;
-        fields.zero_results = resultCount === 0;
-        fields.result_summary =
-            resultCount === 0 ? "0 results" : `${resultCount} results`;
+        appendPayloadCountField(fields, "result_count", "results", structuredContent);
+        if (typeof fields.result_count === "number") {
+            fields.zero_results = fields.result_count === 0;
+        }
     }
     if (toolName === "kb_check") {
-        const violationCount = Number(structuredContent?.count ?? 0);
-        fields.violation_count = violationCount;
+        appendPayloadCountField(fields, "violation_count", "violations", structuredContent);
         fields.requested_rules = Array.isArray(args.rules) ? args.rules : [];
-        fields.result_summary =
-            violationCount === 0 ? "0 violations" : `${violationCount} violations`;
     }
     if (toolName === "kb_coverage" && structuredContent) {
         appendCoverageFields(fields, args, structuredContent);

package/dist/env.js

@@ -16,8 +16,7 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import fs from "node:fs";
-import { resolveEnvFilePath, resolveWorkspaceRoot } from "./workspace.js";
-const DEFAULT_ENV_FILE = ".env";
+import { KIBI_PROJECT_ENV_FILE, bootstrapKibiEnvironment, inspectSecretSource, parseEnvContent, resolveEnvFilePath, resolveKibiProjectEnvPath, resolveKibiWorkspaceRoot, } from "kibi-runtime";
 function getEnvValue(key) {
     const value = process.env[key];
     return typeof value === "string" ? value : undefined;
@@ -26,9 +25,10 @@ function getTrimmedEnvValue(key) {
     const value = getEnvValue(key)?.trim();
     return value ? value : undefined;
 }
+/** Preferred project env file name (`.env.kibi` or `KIBI_ENV_FILE` override). */
 export function getEnvFileName() {
     // implements REQ-002
-    return getTrimmedEnvValue("KIBI_ENV_FILE") ?? DEFAULT_ENV_FILE;
+    return getTrimmedEnvValue("KIBI_ENV_FILE") ?? KIBI_PROJECT_ENV_FILE;
 }
 export function isMcpDebugEnabled() {
     // implements REQ-002
@@ -51,12 +51,26 @@ export function getCoreModulePathOverride(fileName) {
     const envKey = `KIBI_${fileName.replace(/\W/g, "_").toUpperCase()}_PATH`;
     return getEnvValue(envKey);
 }
+/**
+ * Harness-independent bootstrap: process → project `.env.kibi`/`KIBI_ENV_FILE`
+ * → user `~/.config/kibi/env`, plus legacy `.env` gap-fill.
+ * Prefer calling from `startServer()` only.
+ */
 export function loadDefaultEnvFile() {
     // implements REQ-002
-    const envFileName = getEnvFileName();
-    const workspaceRoot = resolveWorkspaceRoot();
-    return loadEnvFile({ envFileName, workspaceRoot });
+    const result = bootstrapKibiEnvironment();
+    const keysLoaded = [
+        ...result.keysLoadedFromUser,
+        ...result.keysLoadedFromProject,
+        ...result.keysLoadedFromLegacy,
+    ];
+    return {
+        loaded: keysLoaded.length > 0,
+        envFilePath: result.projectEnvPath,
+        keysLoaded,
+    };
 }
+/** @deprecated Prefer bootstrapKibiEnvironment; kept for targeted file tests. */
 export function loadEnvFile(options) {
     const { envFileName, workspaceRoot } = options;
     const envFilePath = resolveEnvFilePath(envFileName, workspaceRoot);
@@ -80,27 +94,4 @@ export function loadEnvFile(options) {
         return { loaded: false, envFilePath, keysLoaded };
     }
 }
-function parseEnvContent(content) {
-    const lines = content.split(/\r?\n/);
-    const entries = [];
-    for (const rawLine of lines) {
-        const line = rawLine.trim();
-        if (!line || line.startsWith("#")) {
-            continue;
-        }
-        const eqIndex = line.indexOf("=");
-        if (eqIndex <= 0) {
-            continue;
-        }
-        const key = line.substring(0, eqIndex).trim();
-        let value = line.substring(eqIndex + 1).trim();
-        if (value.startsWith('"') && value.endsWith('"')) {
-            value = value.slice(1, -1);
-        }
-        else if (value.startsWith("'") && value.endsWith("'")) {
-            value = value.slice(1, -1);
-        }
-        entries.push({ key, value });
-    }
-    return entries;
-}
+export { resolveEnvFilePath, resolveKibiProjectEnvPath, resolveKibiWorkspaceRoot, inspectSecretSource, };

package/dist/runtime/mcp-runtime.js

@@ -1,19 +1,38 @@
-import { resolveBranchAttachment } from "kibi-runtime";
+import { CapabilityRegistryCache, ensureCapabilityRegistry, resolveBranchAttachment, } from "kibi-runtime";
 export function attachedContextWithProlog(withAttachment, prolog) {
     return { ...withAttachment, prolog };
 }
+function resolvePluginsOption(plugins) {
+    if (plugins === undefined)
+        return undefined;
+    if (typeof plugins === "function")
+        return plugins;
+    return async () => plugins;
+}
 // implements REQ-kibi-operation-interface-parity
 export function createMcpRuntime(session) {
     const sessionPrologs = new WeakMap();
+    // Per-runtime cache — not a process-global singleton.
+    const pluginCache = new CapabilityRegistryCache();
     return {
         open: async (spec, options = {}) => {
             const fs = options.fs ?? session.fs;
             const git = options.git ?? session.git;
             const net = options.net ?? session.net;
+            const pluginsOption = options.plugins ?? session.plugins;
+            const injectedPlugins = resolvePluginsOption(pluginsOption);
+            const workspaceRoot = options.workspaceRoot ?? session.workspaceRoot;
+            const ensurePlugins = async () => {
+                if (injectedPlugins)
+                    return injectedPlugins();
+                return ensureCapabilityRegistry(workspaceRoot, { cache: pluginCache });
+            };
             const context = {
-                workspaceRoot: options.workspaceRoot ?? session.workspaceRoot,
+                workspaceRoot,
                 signal: options.signal ?? session.signal ?? new AbortController().signal,
                 clock: options.clock ?? session.clock ?? (() => new Date()),
+                ensurePlugins,
+                ...(pluginsOption !== undefined ? { plugins: pluginsOption } : {}),
                 ...(fs ? { fs } : {}),
                 ...(fs ? { sourceFirst: true } : {}),
                 ...(git ? { git } : {}),

package/dist/server/docs.js

@@ -199,7 +199,7 @@ function registerDocResources() {
         '2. `kb_coverage` with `{ "by": "req", "includePassing": false }` to review proof rows and `repairPlan`; require `repairPlan.scope.complete` before treating it as a project-wide inventory',
         "3. Apply only a `repairPlan` batch whose state is `ready`; batches are non-auto-applicable guidance, so query current endpoints, validate every write, and keep `kb_upsert` sequential",
         "4. Re-run `kb_coverage` after each batch instead of continuing from a stale plan",
-        '5. `kb_graph` with `{ "seedIds": ["REQ-001"], "direction": "both", "depth": 2 }` to inspect neighboring entities',
+        '5. `kb_graph` with `{ "seedIds": ["REQ-cli-gc"], "direction": "both", "depth": 2 }` to inspect neighboring entities',
         "",
         "## Add a requirement and link it to a test",
         '1. `kb_query` with `{ "type": "test" }` to check for existing test IDs',

package/dist/server/json-schema-to-zod.js

@@ -88,6 +88,20 @@ export function jsonSchemaToZod(schema) {
         : typeof obj.type === "string"
             ? [obj.type]
             : [];
+    // JSON Schema anyOf unions become real Zod unions so MCP output
+    // validation enforces the declared alternatives instead of silently
+    // degrading to z.any() — e.g. kb_check's synchronous payload versus its
+    // kibi.job.v1 async receipt. oneOf is intentionally left degrading: its
+    // required-guard branches carry no properties and would loosen input
+    // validation instead of tightening it.
+    const anyOfVariants = Array.isArray(obj.anyOf) ? obj.anyOf : [];
+    if (anyOfVariants.length > 0) {
+        const variants = anyOfVariants.map((variant) => jsonSchemaToZod(variant));
+        const union = z.union(variants);
+        return typeof obj.description === "string"
+            ? union.describe(obj.description)
+            : union;
+    }
     // JSON Schema nullable fields are represented as a type union in the
     // catalog. Build a real Zod union so MCP publishes and validates the same
     // nullability instead of silently degrading the field to z.any().

package/dist/server/tool-registration.js

@@ -27,6 +27,9 @@ export function registerConfiguredTools(server, runtime, registerTool) {
             name,
             effects: publicSpec.effects,
             requiresProlog: publicSpec.requiresProlog,
+            ...(publicSpec.agentVisibleStructuredData === true
+                ? { agentVisibleStructuredData: true }
+                : {}),
             execute: (args, context) => execute(context, args),
         };
         registerTool(server, name, definition.description, definition.inputSchema, async () => undefined, runtime, spec, definition.annotations, definition.outputSchema);
@@ -81,7 +84,7 @@ export function registerConfiguredTools(server, runtime, registerTool) {
     });
     register({
         name: "kb_semantic_advisor",
-        execute: async (_context, args) => runtime.handleKbSemanticAdvisor(args),
+        execute: async (context, args) => runtime.handleKbSemanticAdvisor(args, context),
     });
     register({
         name: "kb_upsert",
@@ -110,11 +113,11 @@ export function registerConfiguredTools(server, runtime, registerTool) {
     });
     register({
         name: "kb_model_requirement",
-        execute: async (context, args) => runtime.handleKbModelRequirement(prologFor(context), args),
+        execute: async (context, args) => runtime.handleKbModelRequirement(prologFor(context), args, withSessionProlog(context)),
     });
     register({
         name: "kb_suggest_predicates",
-        execute: async (context, args) => runtime.handleKbSuggestPredicates(prologFor(context), args),
+        execute: async (context, args) => runtime.handleKbSuggestPredicates(prologFor(context), args, withSessionProlog(context)),
     });
     register({
         name: "kb_plan_bootstrap",

package/dist/server/tools-runtime.js

@@ -49,10 +49,15 @@ function adaptProlog(prolog) {
     if (existing) {
         return existing;
     }
+    const engine = prolog;
+    const queryEntities = engine.queryEntities;
+    const searchEntities = engine.searchEntities;
+    const storageStatus = engine.storageStatus;
+    const queryStatusJson = engine.queryStatusJson;
     let lastResult = null;
     const port = {
-        query: async (goal) => {
-            lastResult = await prolog.query(goal);
+        query: async (goal, signal) => {
+            lastResult = await engine.query(goal, signal);
             return lastResult;
         },
         nextSolution: async () => {
@@ -60,35 +65,37 @@ function adaptProlog(prolog) {
             lastResult = null;
             return result;
         },
-        save: () => prolog.query("kb_save"),
-        ...(typeof prolog.queryEntities ===
-            "function"
+        save: (signal) => engine.query("kb_save", signal),
+        ...(typeof queryEntities === "function"
             ? {
-                queryEntities: (input) => prolog.queryEntities(input),
+                // The captured method uses .call(engine, ...) below to preserve the
+                // EngineClient receiver (unbound queryStatusJson breaks this.command).
+                queryEntities: (input, signal) => queryEntities.call(engine, input, signal),
             }
             : {}),
-        ...(typeof prolog.searchEntities ===
-            "function"
+        ...(typeof searchEntities === "function"
             ? {
-                searchEntities: (input) => prolog.searchEntities(input),
+                searchEntities: (input, signal) => searchEntities.call(engine, input, signal),
             }
             : {}),
-        ...(typeof prolog.storageStatus ===
-            "function"
+        ...(typeof storageStatus === "function"
             ? {
-                storageStatus: () => prolog.storageStatus(),
+                storageStatus: () => storageStatus.call(engine),
             }
             : {}),
-        ...(typeof prolog.queryStatusJson ===
-            "function"
+        ...(typeof queryStatusJson === "function"
             ? {
-                queryStatusJson: () => prolog.queryStatusJson(),
+                queryStatusJson: (signal) => queryStatusJson.call(engine, signal),
             }
             : {}),
     };
     prologPorts.set(prolog, port);
     return port;
 }
+/** Test seam: adapt a session engine so AbortSignal reaches EngineClient/PrologPort methods. */
+export function _adaptPrologForTests(prolog) {
+    return adaptProlog(prolog);
+}
 const operationRuntime = createMcpRuntime({
     workspaceRoot: resolveWorkspaceRoot(),
     activeBranchName: async () => (await getSessionModule()).getActiveBranchName(),

package/dist/server/tools.js

@@ -28,10 +28,32 @@ export { jsonSchemaToZod } from "./json-schema-to-zod.js";
 export { _resetSessionModulePromise, _setToolsServerDepsForTests };
 const DEFAULT_TOOL_TIMEOUT_MS = 90_000;
 const TOOL_TIMEOUT_ENV = "KIBI_MCP_TOOL_TIMEOUT_MS";
-// Give cancellation and the Prolog reset a short bounded grace period, but do
-// not hold the MCP request open for the full five-second shutdown budget when
-// a handler never observes AbortSignal.
+// Give cancellation a short bounded grace period, but do not hold the MCP
+// request open for the full five-second shutdown budget when a handler never
+// observes AbortSignal.
 const TOOL_TIMEOUT_GRACE_MS = 100;
+// Mutations that ignore AbortSignal may leave the journal indeterminate. Only
+// then tear down the shared session engine — never on ordinary read timeouts,
+// which would reject sibling tools with "Kibi engine connection closed".
+const TOOL_TIMEOUT_WEDGE_MS = 1_000;
+function isMutationEffect(effects) {
+    return (effects?.some((effect) => effect === "kb-write" || effect === "workspace-write") ?? false);
+}
+/** Embed envelope data in content text for opted-in tools (hosts that hide structuredContent).
+ * Preserves non-text content parts; only augments/replaces text parts. */
+function withAgentVisibleText(content, data) {
+    const textParts = content.filter((part) => part.type === "text" && typeof part.text === "string");
+    const nonTextParts = content.filter((part) => part.type !== "text");
+    const summary = textParts
+        .map((part) => part.text)
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim();
+    const payload = JSON.stringify(data);
+    // Prefer JSON-first so first-line-only host summaries still include machine data.
+    const text = summary.length > 0 ? `${payload}\n${summary}` : payload;
+    return [{ type: "text", text }, ...nonTextParts];
+}
 // implements REQ-008
 function debugLog(...args) {
     if (isMcpDebugEnabled()) {
@@ -64,27 +86,28 @@ async function withToolTimeout(toolName, operation, onTimeout) {
     const timeoutMs = getToolTimeoutMs();
     let timeout;
     try {
-        return await Promise.race([
-            operation,
-            new Promise((_, reject) => {
-                timeout = setTimeout(() => {
-                    const error = createToolTimeoutError(toolName, timeoutMs);
-                    // Do not report the timeout until cancellation/reset has completed
-                    // and the original request has reached a terminal state. This is
-                    // especially important for source-first mutations: a caller must
-                    // never retry while the authoritative journal is still deciding its
-                    // outcome.
-                    void onTimeout(error, timeoutMs)
-                        .then(async () => {
-                        await Promise.race([
-                            operation.then(() => undefined, () => undefined),
-                            new Promise((resolve) => setTimeout(resolve, TOOL_TIMEOUT_GRACE_MS)),
-                        ]);
-                    })
-                        .finally(() => reject(error));
-                }, timeoutMs);
-            }),
-        ]);
+        const timeoutPromise = new Promise((_, reject) => {
+            timeout = setTimeout(() => {
+                const error = createToolTimeoutError(toolName, timeoutMs);
+                // Do not report the timeout until cancellation/reset has completed
+                // and the original request has reached a terminal state. This is
+                // especially important for source-first mutations: a caller must
+                // never retry while the authoritative journal is still deciding its
+                // outcome.
+                void onTimeout(error, timeoutMs)
+                    .then(async () => {
+                    await Promise.race([
+                        operation.then(() => undefined, () => undefined),
+                        new Promise((resolve) => setTimeout(resolve, TOOL_TIMEOUT_GRACE_MS)),
+                    ]);
+                })
+                    .finally(() => reject(error));
+            }, timeoutMs);
+        });
+        // When abort settles `operation` before this timeout promise rejects,
+        // the late reject must not become an unhandled rejection.
+        timeoutPromise.catch(() => undefined);
+        return await Promise.race([operation, timeoutPromise]);
     }
     finally {
         if (timeout) {
@@ -139,15 +162,30 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
             try {
                 // Execute handler
                 const result = await withToolTimeout(name, handlerPromise, async (error) => {
-                    resetAttempted = true;
                     controller.abort(error);
+                    // Read/discovery timeouts must cancel in-flight RPCs without
+                    // terminating the shared session engine. A global resetProlog here
+                    // rejects sibling tools with "Kibi engine connection closed".
+                    if (!isMutationEffect(operationSpec.effects)) {
+                        return;
+                    }
+                    const settled = await Promise.race([
+                        handlerPromise.then(() => true, () => true),
+                        new Promise((resolve) => setTimeout(() => resolve(false), TOOL_TIMEOUT_WEDGE_MS)),
+                    ]);
+                    if (settled) {
+                        return;
+                    }
+                    resetAttempted = true;
                     try {
                         await runtime.resetProlog(`tool timeout: ${name}`);
                         resetSucceeded = true;
                     }
-                    catch (error) {
+                    catch (resetFailure) {
                         resetError =
-                            error instanceof Error ? error.message : String(error);
+                            resetFailure instanceof Error
+                                ? resetFailure.message
+                                : String(resetFailure);
                     }
                 });
                 const data = operationData(result);
@@ -169,8 +207,13 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                     typeof result === "object" &&
                     !Array.isArray(result) &&
                     "content" in result) {
+                    const withContent = result;
+                    const content = operationSpec.agentVisibleStructuredData === true
+                        ? withAgentVisibleText(withContent.content, data)
+                        : withContent.content;
                     return {
                         ...result,
+                        content,
                         structuredContent: envelope,
                     };
                 }
@@ -195,7 +238,7 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                     });
                 }
                 if (isToolTimeoutError(error) &&
-                    operationSpec.effects.some((effect) => effect === "kb-write" || effect === "workspace-write")) {
+                    isMutationEffect(operationSpec.effects)) {
                     const recoveryActions = [
                         {
                             operation: "kb_status",
@@ -313,7 +356,7 @@ function registerJobStatusTool(server) {
             content: [{ type: "text", text: JSON.stringify(snapshot) }],
             structuredContent: snapshot,
         };
-    }, undefined, undefined, undefined, {
+    }, undefined, undefined, {
         title: "Poll a Kibi background job",
         readOnlyHint: true,
         destructiveHint: false,

package/dist/tools/check-impact.js

@@ -22,7 +22,7 @@ export function hasImpactOptions(args) {
         args.includeWorkingTreeDiff ||
         (args.sourceFiles && args.sourceFiles.length > 0));
 }
-export function analyzeKbCheckImpact(workspaceRoot, args) {
+export async function analyzeKbCheckImpact(workspaceRoot, args) {
     if (!hasImpactOptions(args)) {
         return undefined;
     }

package/dist/tools/discovery-adapter.js

@@ -1,12 +1,21 @@
 import { resolveWorkspaceRoot } from "../workspace.js";
 export function createDiscoveryContext(prolog, baseContext) {
     // implements REQ-kibi-operation-interface-parity
+    // Keep this adapter aligned with tools-runtime adaptProlog: indexed discovery
+    // and typed status must reach EngineClient command frames (not query-only
+    // fallbacks), and AbortSignal must forward for MCP tool cancellation.
+    const engine = prolog;
+    const queryEntities = engine.queryEntities;
+    const searchEntities = engine.searchEntities;
+    const storageStatus = engine.storageStatus;
+    const queryStatusJson = engine.queryStatusJson;
     let lastResult = null;
     const mode = prolog
         .useOneShotMode;
+    const signal = baseContext?.signal ?? new AbortController().signal;
     const port = {
-        query: async (goal) => {
-            lastResult = await prolog.query(goal);
+        query: async (goal, querySignal) => {
+            lastResult = await engine.query(goal, querySignal ?? signal);
             return lastResult;
         },
         oneShotMode: mode === undefined
@@ -17,18 +26,32 @@ export function createDiscoveryContext(prolog, baseContext) {
             lastResult = null;
             return result;
         },
-        save: () => prolog.query("kb_save"),
-        ...(typeof prolog.queryStatusJson ===
-            "function"
+        save: (saveSignal) => engine.query("kb_save", saveSignal ?? signal),
+        ...(typeof queryEntities === "function"
             ? {
-                queryStatusJson: () => prolog.queryStatusJson(),
+                queryEntities: (input, querySignal) => queryEntities.call(engine, input, querySignal ?? signal),
+            }
+            : {}),
+        ...(typeof searchEntities === "function"
+            ? {
+                searchEntities: (input, querySignal) => searchEntities.call(engine, input, querySignal ?? signal),
+            }
+            : {}),
+        ...(typeof storageStatus === "function"
+            ? {
+                storageStatus: () => storageStatus.call(engine),
+            }
+            : {}),
+        ...(typeof queryStatusJson === "function"
+            ? {
+                queryStatusJson: (statusSignal) => queryStatusJson.call(engine, statusSignal ?? signal),
             }
             : {}),
     };
     return {
         ...(baseContext ?? {}),
         workspaceRoot: baseContext?.workspaceRoot ?? resolveWorkspaceRoot(),
-        signal: baseContext?.signal ?? new AbortController().signal,
+        signal,
         clock: baseContext?.clock ?? (() => new Date()),
         prolog: port,
     };

package/dist/tools/model-requirement.js

@@ -2,11 +2,11 @@ import { modelRequirementSpec } from "kibi-runtime";
 import { estimateNormativeSignalConfidence, extractRequirementClaim, getWorkspaceMigrationWarning, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, } from "kibi-runtime";
 import { resolveWorkspaceRoot } from "../workspace.js";
 export { estimateNormativeSignalConfidence, extractRequirementClaim, getWorkspaceMigrationWarning, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, };
-export async function handleKbModelRequirement(_prolog, args) {
-    const context = {
+export async function handleKbModelRequirement(_prolog, args, context) {
+    const resolved = context ?? {
         workspaceRoot: resolveWorkspaceRoot(),
         signal: new AbortController().signal,
         clock: () => new Date(),
     };
-    return modelRequirementSpec.execute(args, context);
+    return modelRequirementSpec.execute(args, resolved);
 }

package/dist/tools/semantic-advisor.js

@@ -1,4 +1,4 @@
 import { executeSemanticAdvisor } from "kibi-runtime";
-export async function handleKbSemanticAdvisor(args) {
-    return executeSemanticAdvisor(args);
+export async function handleKbSemanticAdvisor(args, context) {
+    return executeSemanticAdvisor(args, context);
 }

package/dist/tools/suggest-predicates.js

@@ -1,13 +1,14 @@
 import { suggestPredicatesSpec } from "kibi-runtime";
 import { resolveWorkspaceRoot } from "../workspace.js";
 import { createDiscoveryContext } from "./discovery-adapter.js";
-export async function handleKbSuggestPredicates(prolog, args) {
-    const context = prolog === null
-        ? {
-            workspaceRoot: resolveWorkspaceRoot(),
-            signal: new AbortController().signal,
-            clock: () => new Date(),
-        }
-        : createDiscoveryContext(prolog);
-    return suggestPredicatesSpec.execute(args, context);
+export async function handleKbSuggestPredicates(prolog, args, context) {
+    const resolved = context ??
+        (prolog === null
+            ? {
+                workspaceRoot: resolveWorkspaceRoot(),
+                signal: new AbortController().signal,
+                clock: () => new Date(),
+            }
+            : createDiscoveryContext(prolog));
+    return suggestPredicatesSpec.execute(args, resolved);
 }

package/dist/workspace.js

@@ -13,32 +13,17 @@
  GNU Affero General Public License for more details.
 
  You should have received a copy of the GNU Affero General Public License
- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
-import fs from "node:fs";
 import path from "node:path";
-import { branchStorePath } from "kibi-runtime";
-const WORKSPACE_ENV_KEYS = [
-    "KIBI_WORKSPACE",
-    "KIBI_PROJECT_ROOT",
-    "KIBI_ROOT",
-];
+import { branchStorePath, resolveKibiWorkspaceRoot } from "kibi-runtime";
 const KB_PATH_ENV_KEYS = ["KIBI_KB_PATH", "KB_PATH"];
-// implements REQ-002, REQ-012
+/**
+ * Canonical workspace root — delegates to shared resolveKibiWorkspaceRoot.
+ */
+// implements REQ-002, REQ-012, REQ-kibi-env-bootstrap
 export function resolveWorkspaceRoot(startDir = process.cwd()) {
-    const envRoot = readFirstEnv(WORKSPACE_ENV_KEYS);
-    if (envRoot) {
-        return path.resolve(envRoot);
-    }
-    const kbRoot = findUpwards(startDir, ".kb");
-    if (kbRoot) {
-        return kbRoot;
-    }
-    const gitRoot = findUpwards(startDir, ".git");
-    if (gitRoot) {
-        return gitRoot;
-    }
-    return path.resolve(startDir);
+    return resolveKibiWorkspaceRoot(startDir);
 }
 // implements REQ-002, REQ-012
 export function resolveKbPath(workspaceRoot, branch) {
@@ -72,17 +57,6 @@ export function nextAncestorDirectory(current) {
     const parent = path.dirname(current);
     return parent === current ? undefined : parent;
 }
-function findUpwards(startDir, marker) {
-    let current = path.resolve(startDir);
-    while (current !== undefined) {
-        const candidate = path.join(current, marker);
-        if (fs.existsSync(candidate)) {
-            return current;
-        }
-        current = nextAncestorDirectory(current);
-    }
-    return null;
-}
 function isBranchPath(p) {
     const parent = path.basename(path.dirname(p));
     return parent === "branches";

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "kibi-mcp",
-  "version": "2.0.0",
+  "version": "2.1.1",
+  "mcpName": "io.github.looted/kibi-mcp",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "ajv": "^8.18.0",
@@ -9,10 +10,9 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-runtime": "^2.0.0",
-    "kibi-core": "^0.12.0",
+    "kibi-runtime": "^2.0.1",
+    "kibi-core": "^0.13.0",
     "mcpcat": "^0.1.12",
-    "ts-morph": "^23.0.0",
     "zod": "^4.3.6"
   },
   "type": "module",
@@ -29,10 +29,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build && node ../../scripts/verify-package-contract.mjs kibi-mcp"
   },
-  "files": [
-    "dist",
-    "bin"
-  ],
+  "files": ["dist", "bin"],
   "engines": {
     "node": ">=22"
   },