@kage-core/kage-graph-mcp 1.1.30 → 1.1.32

package/README.md

@@ -36,15 +36,17 @@ Restart your agent once after setup so MCP tools reload.
 
 - repo-local memory for decisions, runbooks, bug fixes, gotchas, conventions,
   and code explanations
-- a code graph for files, symbols, imports, calls, routes, tests, and packages,
-  including generic call/test signals and mixed-language framework routes
+- a code graph for files, symbols, imports, confidence-scored calls, routes,
+  tests, and packages, including generic call/test signals and mixed-language
+  framework routes
 - conservative cleanup candidates for unreferenced files, unused exports, and
   internal-looking unused symbols
 - memory-code links so project knowledge points at the code it affects
 - decision intelligence for why-memory coverage, stale/weak packets, and
   important files that still lack linked repo knowledge
-- lightweight workspace recall across sibling repos, including package and
-  route-contract links when existing code graphs expose them
+- lightweight workspace recall across sibling repos, including package,
+  route-contract, and topic/event contract links when existing code graphs
+  expose them
 - local git intelligence for risk, reviewers, contributor profiles, co-change
   warnings, ownership silos, and module health
 - `AGENTS.md` bootstrap instructions so agents recall context automatically

package/dist/cli.js

@@ -849,6 +849,12 @@ async function main() {
                 console.log(`- ${contract.provider_repo} ${contract.method} ${contract.path} -> ${contract.consumer_repo}/${contract.consumer_file}`);
             }
         }
+        if (result.topic_contracts.length) {
+            console.log("Topic/event contracts:");
+            for (const contract of result.topic_contracts.slice(0, 10)) {
+                console.log(`- ${contract.producer_repo} ${contract.topic} -> ${contract.consumer_repo}/${contract.consumer_file}`);
+            }
+        }
         if (result.warnings.length)
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         return;

package/dist/index.js

@@ -322,7 +322,7 @@ function listTools() {
         },
         {
             name: "kage_workspace",
-            description: "Summarize a local multi-repo workspace: discovered git repos, Kage memory coverage, code graph counts, and package dependencies between repos. Use when a task spans multiple sibling repos.",
+            description: "Summarize a local multi-repo workspace: discovered git repos, Kage memory coverage, code graph counts, package dependencies, route contracts, and topic/event contracts between repos. Use when a task spans multiple sibling repos.",
             inputSchema: {
                 type: "object",
                 properties: {

package/dist/kernel.js

@@ -1656,7 +1656,9 @@ function hydrateCodeGraphArtifact(projectDir, artifact, structural) {
             ...index.imports,
             ...(artifact.extra_imports ?? []),
         ].sort((a, b) => a.from_path.localeCompare(b.from_path) || a.line - b.line || a.specifier.localeCompare(b.specifier)),
-        calls: artifact.calls ?? [],
+        calls: (artifact.calls ?? [])
+            .map((call) => normalizeCallEdge(call, { confidence: 0.7, resolution: "generic_static_name" }))
+            .filter((call) => Boolean(call)),
         routes: artifact.routes ?? [],
         tests: artifact.tests ?? [],
         packages: artifact.packages ?? [],
@@ -2755,6 +2757,27 @@ function symbolAtLine(symbols, path, line) {
         .filter((symbol) => symbol.path === path && symbol.line <= line && (symbol.end_line ?? symbol.line) >= line)
         .sort((a, b) => (b.line - a.line) || ((a.end_line ?? a.line) - (b.end_line ?? b.line)))[0] ?? null;
 }
+function normalizeCallConfidence(value, fallback) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric))
+        return fallback;
+    return Number(Math.max(0, Math.min(1, numeric)).toFixed(2));
+}
+function normalizeCallResolution(value, fallback) {
+    return value === "typescript_ast_name" || value === "generic_static_name" || value === "external_index" ? value : fallback;
+}
+function normalizeCallEdge(call, fallback) {
+    if (!isRecord(call) || typeof call.to_symbol !== "string")
+        return null;
+    return {
+        from_symbol: typeof call.from_symbol === "string" ? call.from_symbol : null,
+        to_symbol: call.to_symbol,
+        path: String(call.path ?? ""),
+        line: Math.max(1, Number(call.line ?? 1)),
+        confidence: normalizeCallConfidence(call.confidence, fallback.confidence),
+        resolution: normalizeCallResolution(call.resolution, fallback.resolution),
+    };
+}
 function extractCalls(path, text, symbols, symbolByName) {
     const sourceFile = sourceFileFor(path, text);
     const calls = [];
@@ -2782,7 +2805,14 @@ function extractCalls(path, text, symbols, symbolByName) {
                 break;
             if (target.path === path && target.line === line)
                 continue;
-            calls.push({ from_symbol: caller?.id ?? null, to_symbol: target.id, path, line });
+            calls.push({
+                from_symbol: caller?.id ?? null,
+                to_symbol: target.id,
+                path,
+                line,
+                confidence: target.path === path ? 0.9 : 0.75,
+                resolution: "typescript_ast_name",
+            });
         }
         ts.forEachChild(node, visit);
     };
@@ -2824,7 +2854,14 @@ function extractGenericCalls(path, text, symbols, symbolByName) {
             for (const target of targets.slice(0, 3)) {
                 if (calls.length >= MAX_CODE_GRAPH_CALLS_PER_FILE)
                     break;
-                calls.push({ from_symbol: caller?.id ?? null, to_symbol: target.id, path, line });
+                calls.push({
+                    from_symbol: caller?.id ?? null,
+                    to_symbol: target.id,
+                    path,
+                    line,
+                    confidence: target.path === path ? 0.7 : 0.55,
+                    resolution: "generic_static_name",
+                });
             }
         }
     }
@@ -3173,9 +3210,8 @@ function parseKageExternalIndex(projectDir, parser, path) {
         : [];
     const calls = Array.isArray(raw.calls)
         ? raw.calls.flatMap((item) => {
-            if (!isRecord(item) || typeof item.to_symbol !== "string")
-                return [];
-            return [{ from_symbol: typeof item.from_symbol === "string" ? item.from_symbol : null, to_symbol: item.to_symbol, path: String(item.path ?? ""), line: Math.max(1, Number(item.line ?? 1)) }];
+            const call = normalizeCallEdge(item, { confidence: 0.85, resolution: "external_index" });
+            return call ? [call] : [];
         })
         : [];
     return { symbols, imports, calls };
@@ -3230,7 +3266,7 @@ function parseScipJsonObject(projectDir, raw) {
                     symbols.push(symbol);
             }
             else {
-                calls.push({ from_symbol: null, to_symbol: name, path: rel, line });
+                calls.push({ from_symbol: null, to_symbol: name, path: rel, line, confidence: 0.85, resolution: "external_index" });
             }
         }
     }
@@ -4995,7 +5031,7 @@ function queryCodeGraph(projectDir, query, limit = 10, graph) {
         ...imports.map(({ item }, index) => `${index + 1}. ${item.from_path}:${item.line} ${item.kind} ${item.specifier}${item.to_path ? ` -> ${item.to_path}` : ""}`),
         calls.length ? "" : "",
         calls.length ? "## Calls" : "",
-        ...calls.map((call, index) => `${index + 1}. ${call.from_symbol ? symbolNameById.get(call.from_symbol) ?? call.from_symbol : call.path} calls ${symbolNameById.get(call.to_symbol) ?? call.to_symbol} at ${call.path}:${call.line}`),
+        ...calls.map((call, index) => `${index + 1}. ${call.from_symbol ? symbolNameById.get(call.from_symbol) ?? call.from_symbol : call.path} calls ${symbolNameById.get(call.to_symbol) ?? call.to_symbol} at ${call.path}:${call.line} (${call.resolution}, confidence ${call.confidence.toFixed(2)})`),
     ];
     return {
         query,
@@ -6451,6 +6487,96 @@ function workspaceRouteContracts(workspaceDir, repos) {
         .sort((a, b) => a.provider_repo.localeCompare(b.provider_repo) || a.path.localeCompare(b.path) || a.consumer_repo.localeCompare(b.consumer_repo))
         .slice(0, 50);
 }
+const TOPIC_PRODUCER_METHODS = "publish|produce|send|emit|enqueue|dispatch";
+const TOPIC_CONSUMER_METHODS = "subscribe|consume|listen|handle";
+function likelyWorkspaceTopic(value) {
+    const topic = value.trim();
+    if (topic.length < 3 || topic.length > 120)
+        return false;
+    if (topic.startsWith("/") || /^https?:\/\//i.test(topic))
+        return false;
+    if (/\s/.test(topic))
+        return false;
+    if (/[.:-]/.test(topic))
+        return true;
+    if (/_/.test(topic) && /^[a-z0-9_]+$/i.test(topic))
+        return true;
+    return /\b(created|updated|deleted|requested|completed|failed|received|changed)$/i.test(topic);
+}
+function extractWorkspaceTopicMentions(repo, file, text) {
+    const mentions = [];
+    const patterns = [
+        { role: "producer", regex: new RegExp(`\\b(?:${TOPIC_PRODUCER_METHODS})\\s*\\(\\s*["'\`]([^"'\`]+)["'\`]`, "gi") },
+        { role: "producer", regex: new RegExp(`\\.(?:${TOPIC_PRODUCER_METHODS})\\s*\\(\\s*["'\`]([^"'\`]+)["'\`]`, "gi") },
+        { role: "consumer", regex: new RegExp(`\\b(?:${TOPIC_CONSUMER_METHODS})\\s*\\(\\s*["'\`]([^"'\`]+)["'\`]`, "gi") },
+        { role: "consumer", regex: new RegExp(`\\.(?:${TOPIC_CONSUMER_METHODS})\\s*\\(\\s*["'\`]([^"'\`]+)["'\`]`, "gi") },
+    ];
+    for (const pattern of patterns) {
+        for (const match of text.matchAll(pattern.regex)) {
+            const topic = match[1]?.trim();
+            if (!topic || !likelyWorkspaceTopic(topic))
+                continue;
+            mentions.push({
+                repo,
+                file,
+                topic,
+                role: pattern.role,
+                evidence: `${file} ${pattern.role === "producer" ? "publishes" : "subscribes to"} ${topic}`,
+            });
+        }
+    }
+    return mentions;
+}
+function workspaceTopicContracts(workspaceDir, repos) {
+    const mentions = [];
+    for (const repo of repos) {
+        const repoRoot = repo.path === "." ? workspaceDir : (0, node_path_1.join)(workspaceDir, repo.path);
+        const graph = readCurrentCodeGraph(repoRoot);
+        if (!graph)
+            continue;
+        for (const file of graph.files) {
+            if (!["source", "config", "manifest"].includes(file.kind))
+                continue;
+            if (file.size_bytes > MAX_CODE_FILE_BYTES)
+                continue;
+            const absolutePath = (0, node_path_1.join)(repoRoot, file.path);
+            if (!(0, node_fs_1.existsSync)(absolutePath))
+                continue;
+            try {
+                mentions.push(...extractWorkspaceTopicMentions(repo.alias, file.path, (0, node_fs_1.readFileSync)(absolutePath, "utf8")));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    const producers = mentions.filter((mention) => mention.role === "producer");
+    const consumers = mentions.filter((mention) => mention.role === "consumer");
+    const contracts = [];
+    const seen = new Set();
+    for (const producer of producers) {
+        for (const consumer of consumers) {
+            if (producer.topic !== consumer.topic || producer.repo === consumer.repo)
+                continue;
+            const key = `${producer.repo}\0${producer.file}\0${consumer.repo}\0${consumer.file}\0${producer.topic}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            contracts.push({
+                topic: producer.topic,
+                producer_repo: producer.repo,
+                producer_file: producer.file,
+                consumer_repo: consumer.repo,
+                consumer_file: consumer.file,
+                confidence: /[.:/-]/.test(producer.topic) ? "high" : "medium",
+                evidence: `${producer.evidence}; ${consumer.evidence}`,
+            });
+        }
+    }
+    return contracts
+        .sort((a, b) => a.topic.localeCompare(b.topic) || a.producer_repo.localeCompare(b.producer_repo) || a.consumer_repo.localeCompare(b.consumer_repo))
+        .slice(0, 50);
+}
 function kageWorkspace(projectDir) {
     const root = (0, node_path_1.resolve)(projectDir);
     const warnings = [];
@@ -6476,6 +6602,7 @@ function kageWorkspace(projectDir) {
         return { ...rest, dependencies_on_workspace_repos: deps };
     });
     const routeContracts = workspaceRouteContracts(root, repos);
+    const topicContracts = workspaceTopicContracts(root, repos);
     if (repos.length && repos.every((repo) => !repo.indexed))
         warnings.push("Workspace repos were found, but none has .agent_memory yet. Run kage init or kage refresh in each repo you want searchable.");
     return {
@@ -6485,8 +6612,9 @@ function kageWorkspace(projectDir) {
         repos,
         package_dependencies: packageDependencies.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to)),
         route_contracts: routeContracts,
+        topic_contracts: topicContracts,
         warnings,
-        summary: `${repos.length} repo(s), ${repos.filter((repo) => repo.indexed).length} with Kage memory, ${packageDependencies.length} workspace package dependenc${packageDependencies.length === 1 ? "y" : "ies"}, ${routeContracts.length} route contract link(s).`,
+        summary: `${repos.length} repo(s), ${repos.filter((repo) => repo.indexed).length} with Kage memory, ${packageDependencies.length} workspace package dependenc${packageDependencies.length === 1 ? "y" : "ies"}, ${routeContracts.length} route contract link(s), ${topicContracts.length} topic contract link(s).`,
     };
 }
 function kageWorkspaceRecall(projectDir, query, limit = 8) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "1.1.30",
+  "version": "1.1.32",
   "description": "Local-first repo memory, code graph, and recall MCP server for coding agents",
   "main": "dist/index.js",
   "files": [

package/viewer/app.js

@@ -698,19 +698,21 @@
       seen.add(entity.id);
       entities.push(entity);
     };
-    var addEdge = function (from, to, relation, fact, source) {
+    var addEdge = function (from, to, relation, fact, source, options) {
       if (!from || !to) return;
+      options = options || {};
       edges.push({
         id: relation + ":" + from + ":" + to + ":" + edges.length,
         from: from,
         to: to,
         relation: relation,
         fact: fact,
-        confidence: 1,
+        confidence: options.confidence == null ? 1 : Number(options.confidence),
         evidence: [],
         commit: graph.repo_state && graph.repo_state.head,
         source: source || "code_graph",
-        graph_kind: "code"
+        graph_kind: "code",
+        resolution: options.resolution
       });
     };
 
@@ -764,7 +766,11 @@
     });
 
     (graph.calls || []).forEach(function (call) {
-      addEdge(call.from_symbol || "file:" + call.path, call.to_symbol, "calls", call.path + ":" + call.line + " calls target symbol.", "calls");
+      var confidence = call.confidence == null ? 0.7 : Number(call.confidence);
+      addEdge(call.from_symbol || "file:" + call.path, call.to_symbol, "calls", call.path + ":" + call.line + " calls target symbol.", "calls", {
+        confidence: confidence,
+        resolution: call.resolution
+      });
     });
 
     (graph.routes || []).forEach(function (route) {
@@ -2613,6 +2619,7 @@
       var repos = Array.isArray(workspace.repos) ? workspace.repos : [];
       var deps = Array.isArray(workspace.package_dependencies) ? workspace.package_dependencies : [];
       var contracts = Array.isArray(workspace.route_contracts) ? workspace.route_contracts : [];
+      var topics = Array.isArray(workspace.topic_contracts) ? workspace.topic_contracts : [];
       cards.push({
         title: "Workspace",
         kicker: "multi-repo memory",
@@ -2621,7 +2628,8 @@
           ["Repos", String(repos.length)],
           ["Indexed", String(repos.filter(function (repo) { return repo.indexed; }).length)],
           ["Package deps", String(deps.length)],
-          ["Route links", String(contracts.length)]
+          ["Route links", String(contracts.length)],
+          ["Topic links", String(topics.length)]
         ].concat(repos.slice(0, 2).map(function (repo) { return [repo.alias, repo.approved_packets + " packets, " + repo.code_files + " files"]; }))
       });
     }