kibi-mcp 3.2.0 → 3.5.0

package/dist/runtime/mcp-runtime.js

@@ -64,6 +64,7 @@ export function createMcpRuntime(session) {
                 ...(fs ? { sourceFirst: true } : {}),
                 ...(git ? { git } : {}),
                 ...(net ? { net } : {}),
+                ...(options.onProgress ? { onProgress: options.onProgress } : {}),
             };
             const resolved = resolveMcpAttachment(context.workspaceRoot, spec);
             const attachment = resolved instanceof Promise ? await resolved : resolved;

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

@@ -13,23 +13,92 @@ export function singleLiteralOrAny(literalSchemas, description) {
     }
     return description ? single.describe(description) : single;
 }
-function hasRequiredProperties(value, schema) {
-    if (schema === null || typeof schema !== "object")
+function matchesJsonType(value, type) {
+    switch (type) {
+        case "object":
+            return (value !== null && typeof value === "object" && !Array.isArray(value));
+        case "array":
+            return Array.isArray(value);
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        default:
+            return true;
+    }
+}
+function sameJsonValue(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+// Evaluates a JSON Schema `if` condition the way a JSON Schema validator
+// would for the keywords Kibi's operation schemas use in conditionals:
+// boolean schemas, type, const, enum, required, properties (applied only to
+// present keys), not, anyOf, allOf and oneOf. Keywords outside this set do not
+// constrain the condition. The CLI validates the same schemas with ajv, so
+// this must stay faithful: a mismatch makes MCP reject payloads the CLI
+// accepts (or the reverse).
+// implements REQ-002, REQ-mcp-conditional-input-validation
+export function matchesJsonSchemaCondition(value, schema) {
+    if (schema === true || schema === undefined)
+        return true;
+    if (schema === false)
         return false;
+    if (schema === null || typeof schema !== "object")
+        return true;
     const condition = schema;
-    const required = Array.isArray(condition.required)
-        ? condition.required.filter((key) => typeof key === "string" && key.length > 0)
-        : [];
-    if (required.length > 0 &&
-        !required.every((key) => Object.hasOwn(value, key))) {
+    const types = Array.isArray(condition.type)
+        ? condition.type.filter((entry) => typeof entry === "string")
+        : typeof condition.type === "string"
+            ? [condition.type]
+            : [];
+    if (types.length > 0 && !types.some((type) => matchesJsonType(value, type))) {
+        return false;
+    }
+    if (Object.hasOwn(condition, "const") &&
+        !sameJsonValue(value, condition.const)) {
+        return false;
+    }
+    if (Array.isArray(condition.enum) &&
+        !condition.enum.some((entry) => sameJsonValue(value, entry))) {
+        return false;
+    }
+    const isObject = value !== null && typeof value === "object" && !Array.isArray(value);
+    if (isObject) {
+        const record = value;
+        const required = Array.isArray(condition.required)
+            ? condition.required.filter((key) => typeof key === "string" && key.length > 0)
+            : [];
+        if (!required.every((key) => Object.hasOwn(record, key)))
+            return false;
+        if (condition.properties && typeof condition.properties === "object") {
+            for (const [key, propertySchema] of Object.entries(condition.properties)) {
+                if (Object.hasOwn(record, key) &&
+                    !matchesJsonSchemaCondition(record[key], propertySchema)) {
+                    return false;
+                }
+            }
+        }
+    }
+    if ("not" in condition && matchesJsonSchemaCondition(value, condition.not)) {
         return false;
     }
     if (Array.isArray(condition.anyOf) &&
-        !condition.anyOf.some((entry) => hasRequiredProperties(value, entry))) {
+        !condition.anyOf.some((entry) => matchesJsonSchemaCondition(value, entry))) {
         return false;
     }
     if (Array.isArray(condition.allOf) &&
-        !condition.allOf.every((entry) => hasRequiredProperties(value, entry))) {
+        !condition.allOf.every((entry) => matchesJsonSchemaCondition(value, entry))) {
+        return false;
+    }
+    if (Array.isArray(condition.oneOf) &&
+        condition.oneOf.filter((entry) => matchesJsonSchemaCondition(value, entry))
+            .length !== 1) {
         return false;
     }
     return true;
@@ -40,7 +109,7 @@ function conditionalRequiredKeys(value, condition) {
     const rule = condition;
     if (!("if" in rule) || !("then" in rule))
         return [];
-    if (!hasRequiredProperties(value, rule.if))
+    if (!matchesJsonSchemaCondition(value, rule.if))
         return [];
     if (rule.then === null || typeof rule.then !== "object")
         return [];
@@ -49,7 +118,68 @@ function conditionalRequiredKeys(value, condition) {
         ? required.filter((key) => typeof key === "string" && key.length > 0)
         : [];
 }
-// implements REQ-002
+const GUARD_KEYWORDS = new Set([
+    "required",
+    "not",
+    "anyOf",
+    "allOf",
+    "description",
+]);
+// A guard branch only states which keys must or must not be present
+// (required/not/anyOf/allOf of such conditions). It carries no property
+// schemas, so enforcing a oneOf of guard branches can only tighten
+// validation, never loosen it.
+function isGuardBranch(branch) {
+    if (branch === null || typeof branch !== "object" || Array.isArray(branch))
+        return false;
+    const record = branch;
+    const keys = Object.keys(record);
+    if (keys.length === 0)
+        return false;
+    return keys.every((key) => {
+        if (!GUARD_KEYWORDS.has(key))
+            return false;
+        const entry = record[key];
+        if (key === "required")
+            return (Array.isArray(entry) && entry.every((item) => typeof item === "string"));
+        if (key === "not")
+            return isGuardBranch(entry);
+        if (key === "anyOf" || key === "allOf")
+            return Array.isArray(entry) && entry.every(isGuardBranch);
+        return true;
+    });
+}
+function guardOneOfBranches(obj) {
+    if (!Array.isArray(obj.oneOf) || obj.oneOf.length < 2)
+        return [];
+    return obj.oneOf.every(isGuardBranch) ? obj.oneOf : [];
+}
+function describeGuardBranch(branch) {
+    const required = Array.isArray(branch.required)
+        ? branch.required
+        : [];
+    const forbidden = new Set();
+    const collect = (entry) => {
+        if (entry === null || typeof entry !== "object")
+            return;
+        const record = entry;
+        if (Array.isArray(record.required))
+            for (const key of record.required)
+                forbidden.add(key);
+        if (Array.isArray(record.anyOf))
+            for (const item of record.anyOf)
+                collect(item);
+        if (Array.isArray(record.allOf))
+            for (const item of record.allOf)
+                collect(item);
+    };
+    collect(branch.not);
+    const parts = [`{${required.join(", ")}}`];
+    if (forbidden.size > 0)
+        parts.push(`without ${[...forbidden].join(", ")}`);
+    return parts.join(" ");
+}
+// implements REQ-002, REQ-mcp-oneof-guard-input-validation
 export function jsonSchemaToZod(schema) {
     if (!schema || typeof schema !== "object") {
         return z.any();
@@ -91,9 +221,10 @@ export function jsonSchemaToZod(schema) {
     // 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.
+    // kibi.job.v1 async receipt. oneOf is not turned into a union: its
+    // required-guard branches carry no properties and a union would loosen
+    // input validation. Guard oneOf branches on an object are enforced as a
+    // refinement in the object case below instead.
     const anyOfVariants = Array.isArray(obj.anyOf) ? obj.anyOf : [];
     if (anyOfVariants.length > 0) {
         const variants = anyOfVariants.map((variant) => jsonSchemaToZod(variant));
@@ -149,6 +280,27 @@ export function jsonSchemaToZod(schema) {
                 })
                     .meta({ allOf: obj.allOf });
             }
+            // A top-level oneOf of guard branches (for example "plan with
+            // approvedPlanHash, or recoveryJournalId alone") is enforced with the
+            // same condition matcher as if/then: exactly one branch must match.
+            // It is not republished as JSON Schema metadata, because hosts reject
+            // a top-level oneOf in a tool input schema; the CLI enforces the same
+            // rule with ajv.
+            const guardBranches = guardOneOfBranches(obj);
+            if (guardBranches.length > 0) {
+                result = result.superRefine((value, context) => {
+                    if (value === null || typeof value !== "object")
+                        return;
+                    const matches = guardBranches.filter((branch) => matchesJsonSchemaCondition(value, branch)).length;
+                    if (matches === 1)
+                        return;
+                    context.addIssue({
+                        code: "custom",
+                        path: [],
+                        message: `Input must match exactly one of: ${guardBranches.map(describeGuardBranch).join("; ")} (matched ${matches}).`,
+                    });
+                });
+            }
             return result;
         }
         case "array": {

package/dist/server/tool-registration.js

@@ -1,5 +1,5 @@
 import { getSpec, statusSpec } from "kibi-runtime";
-import { MODEL_ROUTES, SKILL_ROUTES, dispatchComposite, executeApplyPlan, executeCompileIntent, executeDelete, executeIngestProof, executeUpsert, } from "kibi-runtime";
+import { MODEL_ROUTES, SKILL_ROUTES, dispatchComposite, executeApplyPlan, executeCompileIntent, executeDelete, executeIngestProof, executeUpsert, preflightApplyPlan, } from "kibi-runtime";
 import { OPTIONAL_TOOL_NAMES, enabledOptionalTools } from "../tools-config.js";
 import { startJob } from "./jobs.js";
 // implements REQ-002, REQ-013
@@ -150,9 +150,37 @@ export function registerConfiguredTools(server, runtime, registerTool) {
     });
     register({
         name: "kb_apply_plan",
-        execute: async (context, args) => runtime.handleKbApplyPlan
-            ? runtime.handleKbApplyPlan(args, context)
-            : executeApplyPlan(args, context),
+        execute: async (context, args) => {
+            const { async: asyncMode, ...applyArgs } = args;
+            const apply = (applyContext) => runtime.handleKbApplyPlan
+                ? runtime.handleKbApplyPlan(applyArgs, applyContext)
+                : executeApplyPlan(applyArgs, applyContext);
+            // Without a registered kb_job_status nothing could poll the receipt,
+            // so async falls back to a synchronous apply (which still reports
+            // progress when the request carries a progressToken).
+            if (asyncMode !== true || !enabledOptionalTools().has("kb_job_status")) {
+                return apply(context);
+            }
+            // A large bootstrap plan can outlast any client request timeout.
+            // Detach it into a job and return the kibi.job.v1 receipt; the agent
+            // polls kb_job_status. The request is over once the receipt returns,
+            // so the job reports no progress and refreshes the branch stamp itself.
+            // Input and stale-plan errors (missing or wrong approvedPlanHash, a
+            // changed snapshot) fail this call rather than the job; the apply
+            // repeats every check under the workspace lock.
+            await (runtime.preflightApplyPlan ?? preflightApplyPlan)(applyArgs, context);
+            const { onProgress: _requestProgress, ...jobContext } = context;
+            return startJob("kb_apply_plan", async () => {
+                const result = await apply(jobContext);
+                await runtime.operationRuntime.afterSuccess({
+                    name: "kb_apply_plan",
+                    effects: getSpec("kb_apply_plan").effects,
+                    requiresProlog: true,
+                    execute: async () => undefined,
+                }, jobContext);
+                return result;
+            });
+        },
     });
     register({
         name: "kb_ingest_proof",

package/dist/server/tools.js

@@ -85,12 +85,14 @@ function isToolTimeoutError(value) {
         value.code === "KIBI_TOOL_TIMEOUT");
 }
 // implements REQ-002
-async function withToolTimeout(toolName, operation, onTimeout) {
+async function withToolTimeout(toolName, operation, onTimeout, activity) {
     const timeoutMs = getToolTimeoutMs();
     let timeout;
+    let fired = false;
     try {
         const timeoutPromise = new Promise((_, reject) => {
-            timeout = setTimeout(() => {
+            const fire = () => {
+                fired = true;
                 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
@@ -105,7 +107,17 @@ async function withToolTimeout(toolName, operation, onTimeout) {
                     ]);
                 })
                     .finally(() => reject(error));
-            }, timeoutMs);
+            };
+            timeout = setTimeout(fire, timeoutMs);
+            if (activity) {
+                activity.touch = () => {
+                    if (fired)
+                        return;
+                    if (timeout)
+                        clearTimeout(timeout);
+                    timeout = setTimeout(fire, timeoutMs);
+                };
+            }
         });
         // When abort settles `operation` before this timeout promise rejects,
         // the late reject must not become an unhandled rejection.
@@ -118,6 +130,35 @@ async function withToolTimeout(toolName, operation, onTimeout) {
         }
     }
 }
+/**
+ * Forward operation progress as MCP notifications/progress when the request
+ * carries a progressToken, and push the server-side tool timeout back on each
+ * report. Progress values must increase, so repeats are nudged forward.
+ */
+// implements REQ-bootstrap-apply-long-running
+export function progressReporter(extra, activity) {
+    const token = extra?._meta?.progressToken;
+    const send = extra?.sendNotification;
+    if (token === undefined || typeof send !== "function")
+        return undefined;
+    let last = -1;
+    return ({ progress, total, message }) => {
+        activity.touch();
+        const value = progress > last ? progress : last + 0.001;
+        last = value;
+        void send({
+            method: "notifications/progress",
+            params: {
+                progressToken: token,
+                progress: value,
+                ...(total === undefined ? {} : { total }),
+                ...(message === undefined ? {} : { message }),
+            },
+        }).catch((error) => {
+            debugLog("[KIBI-MCP] progress notification failed:", error instanceof Error ? error.message : String(error));
+        });
+    };
+}
 /**
  * A module that vanished after startup means the package was upgraded or
  * reinstalled under a running server; only a restart loads the new install.
@@ -177,7 +218,7 @@ export function addTool(server, name, description, inputSchema, handler,
 // generic TProlog parameter exists so tests can inject a mock type. The cast is safe
 // because the runtime object satisfies the full ToolsRuntime contract at runtime.
 runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
-    const wrappedHandler = async (rawArgs) => {
+    const wrappedHandler = async (rawArgs, extra) => {
         const startedAt = new Date();
         const diagnosticModeEnabled = runtime.diagnosticModeEnabled();
         let args = rawArgs;
@@ -228,7 +269,12 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                 execute: async (input, _context) => handler(input),
             };
             const observed = observeDetachedReads(runtime.operationRuntime);
-            const handlerPromise = executeOperation(observed.runtime, operationSpec, businessArgs, { signal: controller.signal });
+            const activity = { touch: () => undefined };
+            const onProgress = progressReporter(extra, activity);
+            const handlerPromise = executeOperation(observed.runtime, operationSpec, businessArgs, {
+                signal: controller.signal,
+                ...(onProgress ? { onProgress } : {}),
+            });
             trackedRequests.set(requestId, handlerPromise);
             let resetAttempted = false;
             let resetSucceeded = false;
@@ -261,7 +307,7 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                                 ? resetFailure.message
                                 : String(resetFailure);
                     }
-                });
+                }, activity);
                 const data = operationData(result);
                 const envelope = withWorkspaceNotice(withWorkspaceNotice(toKibiResult(operationSpec, data), workspaceNotice), observed.notice());
                 // Log usage in diagnostic mode
@@ -414,12 +460,12 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
 }
 /**
  * kb_job_status polls background jobs started by long-running operations
- * (currently `kb_check` with `async: true`). This is an MCP-server-native
+ * (`kb_check` and `kb_apply_plan` with `async: true`). This is an MCP-server-native
  * companion to the job receipts, not part of the canonical CLI operation
  * catalog: jobs live in the server process and have no CLI counterpart.
  */
 function registerJobStatusTool(server) {
-    addTool(server, "kb_job_status", "Poll a background job started with async:true (e.g. kb_check async jobs). Returns the kibi.job.v1 state: running, succeeded (with the full result), or failed (with the error).", {
+    addTool(server, "kb_job_status", "Poll a background job started with async:true (kb_check or kb_apply_plan async jobs). Returns the kibi.job.v1 state: running, succeeded (with the full result), or failed (with the error).", {
         type: "object",
         properties: {
             jobId: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "3.2.0",
+  "version": "3.5.0",
   "mcpName": "io.github.Looted/kibi-mcp",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
@@ -10,8 +10,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-runtime": "^2.5.0",
-    "kibi-core": "^0.16.0",
+    "kibi-runtime": "^2.8.0",
+    "kibi-core": "^0.17.0",
     "zod": "^4.3.6"
   },
   "type": "module",