kibi-mcp 0.3.3 → 0.5.0

package/dist/diagnostics.js

@@ -83,6 +83,34 @@ export const DIAGNOSTIC_TELEMETRY_SCHEMA = {
         },
     },
 };
+// implements REQ-002
+export function deriveDiagnosticFields(toolName, args, telemetry, result) {
+    const fields = {
+        telemetry_status: telemetry ? "provided" : "missing",
+    };
+    const structuredContent = result && typeof result === "object" && "structuredContent" in result
+        ? result
+            .structuredContent
+        : undefined;
+    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`;
+    }
+    if (toolName === "kb_check") {
+        const violationCount = Number(structuredContent?.count ?? 0);
+        fields.violation_count = violationCount;
+        fields.requested_rules = Array.isArray(args.rules) ? args.rules : [];
+        fields.result_summary =
+            violationCount === 0 ? "0 violations" : `${violationCount} violations`;
+    }
+    if (!fields.result_summary) {
+        fields.result_summary = `${toolName} completed`;
+    }
+    return fields;
+}
 /**
  * Extract business args and telemetry from tool call arguments.
  */

package/dist/server/docs.js

@@ -35,6 +35,7 @@ function renderToolsDoc() {
     return lines.join("\n");
 }
 export const PROMPTS = [
+    // implements REQ-002, REQ-013, REQ-mcp-search-discovery
     {
         name: "init-kibi",
         description: "Bootstrap Kibi on an existing repository with zero entities.",
@@ -104,8 +105,13 @@ export const PROMPTS = [
             "",
             "Treat this server as a branch-aware knowledge graph interface for software traceability.",
             "",
-            "The server exposes 4 public tools for KB operations:",
-            "- `kb_query`: Read-only lookup of entities by type, ID, tags, or source file",
+            "The server exposes a curated public tool surface for KB operations:",
+            "- `kb_search`: Discovery across metadata and markdown body text",
+            "- `kb_query`: Exact lookup of entities by type, ID, tags, or source file",
+            "- `kb_status`: Branch, snapshot, and freshness inspection",
+            "- `kb_find_gaps`: Bulk missing/present relationship analysis",
+            "- `kb_coverage`: Curated coverage reporting",
+            "- `kb_graph`: Bounded graph traversal from seed IDs",
             "- `kb_upsert`: Create or update entities and their relationships",
             "- `kb_delete`: Remove entities by ID (with dependency safety checks)",
             "- `kb_check`: Validate KB integrity against configurable rules",
@@ -113,7 +119,7 @@ export const PROMPTS = [
             "Core modeling principles:",
             "- Encode requirements as linked facts: `req --constrains--> fact` plus `req --requires_property--> fact`.",
             "- Reuse canonical fact IDs across requirements; shared constrained facts make contradictions detectable.",
-            "- Use `kb_query` first to confirm current state before any mutation.",
+            "- Use `kb_search` first for discovery, then `kb_query` for exact follow-up before any mutation.",
             "- Use `kb_upsert` and `kb_delete` only for intentional, traceable KB changes.",
             "- Run `kb_check` after meaningful mutations to catch integrity issues early.",
             "- Prefer explicit IDs and enum values to avoid invalid parameters.",
@@ -128,7 +134,7 @@ export const PROMPTS = [
             "",
             "Follow this sequence for reliable operation:",
             "",
-            "1. **Query-first**: Always call `kb_query` to confirm current state before any mutation.",
+            "1. **Discover first**: Call `kb_search` for exploratory discovery, then `kb_query` to confirm exact current state before mutation.",
             "2. **Create-before-link**: Create endpoint entities with `kb_upsert` before linking them.",
             "3. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
             "4. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property`.",
@@ -167,8 +173,8 @@ function registerDocResources() {
         "kibi-mcp is a stdio MCP server for querying and mutating the Kibi knowledge base.",
         "",
         "Scope:",
-        "- Entity CRUD-like operations for KB records",
-        "- Validation of KB integrity after changes",
+        "- Read-only discovery and reporting (`kb_search`, `kb_query`, `kb_status`, `kb_find_gaps`, `kb_coverage`, `kb_graph`)",
+        "- KB mutation and validation (`kb_upsert`, `kb_delete`, `kb_check`)",
         "- Automatic branch-local attachment for the active workspace",
         "",
         "Use this server when you need branch-local, machine-readable project memory.",
@@ -188,6 +194,11 @@ function registerDocResources() {
     const examples = [
         "# kibi-mcp Examples",
         "",
+        "## Discover before mutating",
+        '1. `kb_search` with `{ "query": "login flow" }` to discover related requirements, tests, and ADRs',
+        '2. `kb_query` with `{ "type": "req", "sourceFile": "src/auth/login.ts" }` for exact follow-up',
+        "3. `kb_status` with `{}` when branch attachment or freshness confidence matters",
+        "",
         "## Model requirements as reusable facts",
         '1. `kb_query` with `{ "type": "fact" }` to find existing fact IDs before creating new ones',
         "2. `kb_upsert` for the fact entity first (create-before-link)",
@@ -195,6 +206,11 @@ function registerDocResources() {
         "4. Reuse the same constrained fact ID across related requirements; vary property facts only when semantics differ",
         '5. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }` for targeted validation',
         "",
+        "## Find missing coverage",
+        '1. `kb_find_gaps` with `{ "type": "req", "missingRelationships": ["specified_by", "verified_by"] }` to find under-linked requirements',
+        '2. `kb_coverage` with `{ "by": "req", "includePassing": false }` to review evaluated coverage rows',
+        '3. `kb_graph` with `{ "seedIds": ["REQ-001"], "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',
         '2. `kb_query` with `{ "id": "REQ-XXX" }` to verify the requirement exists',

package/dist/server/tools.js

@@ -17,11 +17,16 @@
  */
 import process from "node:process";
 import { z } from "zod";
-import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, extractToolCallPayload, } from "../diagnostics.js";
+import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, deriveDiagnosticFields, extractToolCallPayload, } from "../diagnostics.js";
 import { TOOLS } from "../tools-config.js";
 import { handleKbCheck } from "../tools/check.js";
+import { handleKbCoverage } from "../tools/coverage.js";
 import { handleKbDelete } from "../tools/delete.js";
+import { handleKbFindGaps } from "../tools/find-gaps.js";
+import { handleKbGraph } from "../tools/graph.js";
 import { handleKbQuery } from "../tools/query.js";
+import { handleKbSearch } from "../tools/search.js";
+import { handleKbStatus } from "../tools/status.js";
 import { handleKbUpsert } from "../tools/upsert.js";
 import { activeBranchName, ensureProlog, inFlightRequests, isShuttingDown, prologProcess, } from "./session.js";
 const ACTIVE_TOOLS = TOOLS;
@@ -164,6 +169,7 @@ function addTool(server, name, description, inputSchema, handler) {
                 // Log usage in diagnostic mode
                 if (DIAGNOSTIC_MODE_ENABLED) {
                     const finishedAt = new Date();
+                    const diagnosticFields = deriveDiagnosticFields(name, businessArgs, telemetry, result);
                     appendUsageLogLine({
                         timestamp: finishedAt.toISOString(),
                         request_id: requestId,
@@ -176,6 +182,7 @@ function addTool(server, name, description, inputSchema, handler) {
                         duration_ms: finishedAt.getTime() - startedAt.getTime(),
                         prolog_pid: prologProcess?.getPid() ?? null,
                         active_branch: activeBranchName,
+                        ...diagnosticFields,
                     });
                 }
                 return result;
@@ -218,6 +225,7 @@ function addTool(server, name, description, inputSchema, handler) {
     };
     server.registerTool(name, { description, inputSchema: jsonSchemaToZod(inputSchema) }, wrappedHandler);
 }
+// implements REQ-002, REQ-013
 export function registerAllTools(server) {
     const toolDef = (name) => {
         const t = ACTIVE_TOOLS.find((t) => t.name === name);
@@ -229,6 +237,26 @@ export function registerAllTools(server) {
         const prolog = await ensureProlog();
         return handleKbQuery(prolog, args);
     });
+    addTool(server, "kb_search", toolDef("kb_search").description, toolDef("kb_search").inputSchema, async (args) => {
+        const prolog = await ensureProlog();
+        return handleKbSearch(prolog, args);
+    });
+    addTool(server, "kb_status", toolDef("kb_status").description, toolDef("kb_status").inputSchema, async (args) => {
+        const prolog = await ensureProlog();
+        return handleKbStatus(prolog, args);
+    });
+    addTool(server, "kb_find_gaps", toolDef("kb_find_gaps").description, toolDef("kb_find_gaps").inputSchema, async (args) => {
+        const prolog = await ensureProlog();
+        return handleKbFindGaps(prolog, args);
+    });
+    addTool(server, "kb_coverage", toolDef("kb_coverage").description, toolDef("kb_coverage").inputSchema, async (args) => {
+        const prolog = await ensureProlog();
+        return handleKbCoverage(prolog, args);
+    });
+    addTool(server, "kb_graph", toolDef("kb_graph").description, toolDef("kb_graph").inputSchema, async (args) => {
+        const prolog = await ensureProlog();
+        return handleKbGraph(prolog, args);
+    });
     addTool(server, "kb_upsert", toolDef("kb_upsert").description, toolDef("kb_upsert").inputSchema, async (args) => {
         const prolog = await ensureProlog();
         return handleKbUpsert(prolog, args);

package/dist/tools/check.js

@@ -18,6 +18,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
+import { DEFAULT_CHECKS_CONFIG, RULE_NAMES, } from "kibi-cli/public/check-types";
 import { resolveWorkspaceRoot } from "../workspace.js";
 const require = createRequire(import.meta.url);
 function resolveChecksPlPath() {
@@ -31,30 +32,15 @@ function resolveChecksPlPath() {
             return installedChecksPl;
         }
     }
-    catch { }
+    catch {
+        // require.resolve not available or package not installed
+    }
     const localChecksPl = path.join(process.cwd(), "packages/core/src/checks.pl");
     if (existsSync(localChecksPl)) {
         return localChecksPl;
     }
     throw new Error("Unable to resolve checks.pl path");
 }
-const ALL_RULES = [
-    "must-priority-coverage",
-    "no-dangling-refs",
-    "no-cycles",
-    "required-fields",
-    "symbol-coverage",
-    "symbol-traceability",
-    "deprecated-adr-no-successor",
-    "domain-contradictions",
-];
-const RULE_NAMES = new Set(ALL_RULES);
-const DEFAULT_CHECKS_CONFIG = {
-    rules: Object.fromEntries(ALL_RULES.map((rule) => [rule, true])),
-    symbolTraceability: {
-        requireAdr: false,
-    },
-};
 function formatDiagnosticsForMcp(diagnostics) {
     return diagnostics.map((d) => ({
         category: d.category,
@@ -64,6 +50,24 @@ function formatDiagnosticsForMcp(diagnostics) {
         suggestion: d.suggestion,
     }));
 }
+function formatViolationText(violations) {
+    if (violations.length === 0) {
+        return "No violations found";
+    }
+    const details = violations.map((violation) => {
+        const parts = [
+            violation.rule,
+            violation.entityId,
+            violation.source ?? "unknown-source",
+            violation.description,
+        ];
+        if (violation.suggestion) {
+            parts.push(`Suggestion: ${violation.suggestion}`);
+        }
+        return `- ${parts.join(" | ")}`;
+    });
+    return `${violations.length} violations found\n${details.join("\n")}`;
+}
 // implements REQ-002
 function loadChecksConfig(workspaceRoot) {
     const configPath = path.join(workspaceRoot, ".kb", "config.json");
@@ -103,21 +107,16 @@ function loadChecksConfig(workspaceRoot) {
 }
 // implements REQ-002
 function getEffectiveRules(configRules, requestedRules) {
+    if (requestedRules && requestedRules.length > 0) {
+        return new Set(requestedRules.filter((rule) => RULE_NAMES.has(rule)));
+    }
     const effective = new Set();
-    for (const rule of ALL_RULES) {
+    for (const rule of RULE_NAMES) {
         const enabled = configRules[rule] ?? true;
         if (enabled) {
             effective.add(rule);
         }
     }
-    if (requestedRules && requestedRules.length > 0) {
-        const allowed = new Set(requestedRules.filter((rule) => RULE_NAMES.has(rule)));
-        for (const rule of Array.from(effective)) {
-            if (!allowed.has(rule)) {
-                effective.delete(rule);
-            }
-        }
-    }
     return effective;
 }
 /**
@@ -151,9 +150,7 @@ export async function handleKbCheck(prolog, args) {
             file: v.source,
             suggestion: v.suggestion,
         }));
-        const summary = aggregatedViolations.length === 0
-            ? "No violations found"
-            : `${aggregatedViolations.length} violations found`;
+        const summary = formatViolationText(aggregatedViolations);
         return {
             content: [
                 {

package/dist/tools/core-module.js

@@ -0,0 +1,85 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { PrologProcess } from "kibi-cli/prolog";
+import { escapeAtomContent } from "kibi-cli/prolog/codec";
+const require = createRequire(import.meta.url);
+// implements REQ-002, REQ-013
+export function resolveCorePlPath(fileName) {
+    const envKey = `KIBI_${fileName.replace(/\W/g, "_").toUpperCase()}_PATH`;
+    const override = process.env[envKey];
+    if (override && existsSync(override)) {
+        return override;
+    }
+    try {
+        const installedPath = require.resolve(`kibi-core/src/${fileName}`);
+        if (existsSync(installedPath)) {
+            return installedPath;
+        }
+    }
+    catch {
+        // require.resolve not available or package not installed
+    }
+    const localPath = path.join(process.cwd(), "packages/core/src", fileName);
+    if (existsSync(localPath)) {
+        return localPath;
+    }
+    throw new Error(`Unable to resolve core module path for ${fileName}`);
+}
+// implements REQ-002, REQ-013
+export async function runJsonModuleQuery(prolog, fileName, goal, errorLabel) {
+    const modulePath = escapeAtomContent(resolveCorePlPath(fileName).replace(/\\/g, "/"));
+    if (!(prolog instanceof PrologProcess)) {
+        const mockedResult = await prolog.query(`(use_module('${modulePath}'), ${goal})`);
+        if (!mockedResult.success) {
+            throw new Error(`${errorLabel} query failed: ${mockedResult.error || "Unknown error"}`);
+        }
+        const mockedJson = mockedResult.bindings.JsonString;
+        if (!mockedJson) {
+            throw new Error(`${errorLabel} query returned no JsonString binding`);
+        }
+        let mockedParsed = JSON.parse(mockedJson);
+        if (typeof mockedParsed === "string") {
+            mockedParsed = JSON.parse(mockedParsed);
+        }
+        return mockedParsed;
+    }
+    const oneShotCapable = prolog;
+    prolog.invalidateCache();
+    const result = oneShotCapable.useOneShotMode
+        ? await prolog.query(`(use_module('${modulePath}'), ${goal})`)
+        : await runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel);
+    if (!result.success) {
+        throw new Error(`${errorLabel} query failed: ${result.error || "Unknown error"}`);
+    }
+    const rawJson = result.bindings.JsonString;
+    if (!rawJson) {
+        throw new Error(`${errorLabel} query returned no JsonString binding`);
+    }
+    let parsed = JSON.parse(rawJson);
+    if (typeof parsed === "string") {
+        parsed = JSON.parse(parsed);
+    }
+    return parsed;
+}
+async function runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel) {
+    const loadResult = await prolog.query(`use_module('${modulePath}')`);
+    if (!loadResult.success) {
+        throw new Error(`${errorLabel} module load failed: ${loadResult.error || "Unknown error"}`);
+    }
+    return prolog.query(goal);
+}
+// implements REQ-002, REQ-013
+export function toPrologAtom(value) {
+    if (!value) {
+        return "none";
+    }
+    return `'${escapeAtomContent(value)}'`;
+}
+// implements REQ-002, REQ-013
+export function toPrologList(values) {
+    if (!values || values.length === 0) {
+        return "[]";
+    }
+    return `[${values.map((value) => `'${escapeAtomContent(value)}'`).join(",")}]`;
+}

package/dist/tools/coverage.js

@@ -0,0 +1,28 @@
+import { runJsonModuleQuery, toPrologList } from "./core-module.js";
+// implements REQ-002, REQ-013
+export async function handleKbCoverage(prolog, args) {
+    const by = args.by ?? "req";
+    const limit = args.limit ?? 100;
+    const offset = args.offset ?? 0;
+    const includePassing = args.includePassing ?? false;
+    const includeTransitive = args.includeTransitive ?? true;
+    try {
+        const payload = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:coverage_report_json('${by}', ${toPrologList(args.tags)}, ${includePassing}, ${includeTransitive}, ${limit}, ${offset}, JsonString)`, "Coverage execution");
+        const summary = payload?.summary ?? {};
+        const fullyCovered = Number(summary.fullyCovered ?? 0);
+        const total = Number(summary.total ?? 0);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Coverage summary: ${fullyCovered} fully covered out of ${total}.`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Coverage execution failed: ${message}`);
+    }
+}

package/dist/tools/entity-query.js

@@ -0,0 +1,111 @@
+import { escapeAtomContent, parseEntityFromBinding, parseEntityFromList, parseListOfLists, } from "kibi-cli/prolog/codec";
+export const VALID_ENTITY_TYPES = [
+    // implements REQ-002
+    "req",
+    "scenario",
+    "test",
+    "adr",
+    "flag",
+    "event",
+    "symbol",
+    "fact",
+];
+// implements REQ-002, REQ-013
+export function validateEntityType(type) {
+    if (type && !VALID_ENTITY_TYPES.includes(type)) {
+        throw new Error(`Invalid type '${type}'. Valid types: ${VALID_ENTITY_TYPES.join(", ")}. Use a single type value, or omit this parameter to query all entities.`);
+    }
+}
+// implements REQ-002, REQ-013
+export function buildEntityGoal(args) {
+    const { type, id, tags, sourceFile } = args;
+    if (sourceFile) {
+        const safeSource = escapeAtomContent(sourceFile);
+        if (type) {
+            const safeType = escapeAtomContent(type);
+            return `findall([Id,'${safeType}',Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, '${safeType}', Props)), Results)`;
+        }
+        return `findall([Id,Type,Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, Type, Props)), Results)`;
+    }
+    if (id && type) {
+        const safeId = escapeAtomContent(id);
+        const safeType = escapeAtomContent(type);
+        return `findall(['${safeId}','${safeType}',Props], kb_entity('${safeId}', '${safeType}', Props), Results)`;
+    }
+    if (id) {
+        const safeId = escapeAtomContent(id);
+        return `findall(['${safeId}',Type,Props], kb_entity('${safeId}', Type, Props), Results)`;
+    }
+    if (tags && tags.length > 0) {
+        if (type) {
+            const safeType = escapeAtomContent(type);
+            return `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
+        }
+        return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
+    }
+    if (type) {
+        const safeType = escapeAtomContent(type);
+        return `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
+    }
+    return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
+}
+// implements REQ-002, REQ-013
+export async function loadEntities(prolog, args) {
+    validateEntityType(args.type);
+    const goal = buildEntityGoal(args);
+    const queryResult = await prolog.query(goal);
+    let results = [];
+    if (!queryResult.success) {
+        throw new Error(queryResult.error || "Query failed with unknown error");
+    }
+    if (queryResult.bindings.Results) {
+        const entitiesData = parseListOfLists(queryResult.bindings.Results);
+        for (const data of entitiesData) {
+            results.push(parseEntityFromList(data));
+        }
+    }
+    else if (queryResult.bindings.Result) {
+        results = [parseEntityFromBinding(queryResult.bindings.Result)];
+    }
+    if (args.tags && args.tags.length > 0) {
+        const requestedTags = args.tags;
+        results = dedupeEntities(results.filter((entity) => hasAnyTag(entity, requestedTags)));
+    }
+    return dedupeEntities(results);
+}
+// implements REQ-002
+export function paginateResults(results, limit = 100, offset = 0) {
+    return results.slice(offset, offset + limit);
+}
+function hasAnyTag(entity, requestedTags) {
+    const expected = new Set(requestedTags.map(normalizeTagValue));
+    const rawTags = entity.tags;
+    if (!Array.isArray(rawTags) || rawTags.length === 0) {
+        return false;
+    }
+    for (const tag of rawTags) {
+        if (expected.has(normalizeTagValue(tag))) {
+            return true;
+        }
+    }
+    return false;
+}
+function normalizeTagValue(tag) {
+    return String(tag).trim();
+}
+// implements REQ-002
+export function dedupeEntities(entities) {
+    const seen = new Set();
+    const deduped = [];
+    for (const entity of entities) {
+        const id = String(entity.id ?? "");
+        const type = String(entity.type ?? "");
+        const key = `${type}::${id}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(entity);
+    }
+    return deduped;
+}

package/dist/tools/find-gaps.js

@@ -0,0 +1,29 @@
+import { runJsonModuleQuery, toPrologAtom, toPrologList, } from "./core-module.js";
+import { validateEntityType } from "./entity-query.js";
+// implements REQ-002, REQ-013
+export async function handleKbFindGaps(prolog, args) {
+    validateEntityType(args.type);
+    const limit = args.limit ?? 100;
+    const offset = args.offset ?? 0;
+    try {
+        const payload = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:find_gaps_json(${toPrologAtom(args.type)}, ${toPrologList(args.missingRelationships)}, ${toPrologList(args.presentRelationships)}, ${toPrologList(args.tags)}, ${toPrologAtom(args.sourceFile)}, ${limit}, ${offset}, JsonString)`, "Find-gaps execution");
+        const rows = payload?.rows ?? [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: rows.length === 0
+                        ? "No matching gaps found."
+                        : `Found ${payload?.count ?? rows.length} gap rows. Showing ${rows.length}: ${rows
+                            .map((row) => row.id)
+                            .join(", ")}`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Find-gaps execution failed: ${message}`);
+    }
+}

package/dist/tools/graph.js

@@ -0,0 +1,27 @@
+import { runJsonModuleQuery, toPrologList } from "./core-module.js";
+// implements REQ-002, REQ-013
+export async function handleKbGraph(prolog, args) {
+    const direction = args.direction ?? "outgoing";
+    const depth = args.depth ?? 1;
+    const maxNodes = args.maxNodes ?? 200;
+    const maxEdges = args.maxEdges ?? 500;
+    try {
+        const payload = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:graph_expand_json(${toPrologList(args.seedIds)}, ${toPrologList(args.relationships)}, '${direction}', ${depth}, ${toPrologList(args.entityTypes)}, ${maxNodes}, ${maxEdges}, JsonString)`, "Graph execution");
+        const nodes = payload?.nodes ?? [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: nodes.length === 0
+                        ? "Graph traversal returned no nodes."
+                        : `Graph traversal returned ${nodes.length} nodes and ${(payload?.edges ?? []).length} edges from ${args.seedIds.join(", ")}.`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Graph execution failed: ${message}`);
+    }
+}

package/dist/tools/prolog-list.js

@@ -15,6 +15,7 @@
  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/>.
 */
+import { splitTopLevel } from "kibi-cli/prolog/codec";
 // implements REQ-002
 export function parseAtomList(raw) {
     const trimmed = raw.trim();
@@ -86,49 +87,6 @@ function unwrapList(value) {
     }
     return value;
 }
-function splitTopLevel(input, delimiter) {
-    const parts = [];
-    let current = "";
-    let depth = 0;
-    let inDoubleQuotes = false;
-    let inSingleQuotes = false;
-    for (let i = 0; i < input.length; i++) {
-        const ch = input[i];
-        const prev = i > 0 ? input[i - 1] : "";
-        if (ch === '"' && !inSingleQuotes && prev !== "\\") {
-            inDoubleQuotes = !inDoubleQuotes;
-            current += ch;
-            continue;
-        }
-        if (ch === "'" && !inDoubleQuotes && prev !== "\\") {
-            inSingleQuotes = !inSingleQuotes;
-            current += ch;
-            continue;
-        }
-        if (!inSingleQuotes && !inDoubleQuotes && (ch === "[" || ch === "(")) {
-            depth++;
-            current += ch;
-            continue;
-        }
-        if (!inSingleQuotes && !inDoubleQuotes && (ch === "]" || ch === ")")) {
-            depth--;
-            current += ch;
-            continue;
-        }
-        if (!inSingleQuotes && !inDoubleQuotes && depth === 0 && ch === delimiter) {
-            if (current.length > 0) {
-                parts.push(current);
-            }
-            current = "";
-            continue;
-        }
-        current += ch;
-    }
-    if (current.length > 0) {
-        parts.push(current);
-    }
-    return parts;
-}
 function stripQuotes(value) {
     if (value.startsWith("'") && value.endsWith("'")) {
         return value.slice(1, -1);