@kage-core/kage-graph-mcp 2.5.1 → 2.5.3

package/dist/cli.js

@@ -1396,12 +1396,25 @@ async function main() {
         const path = takeArg(args, "--path");
         if (!path)
             usage();
-        const result = (0, kernel_js_1.kageFileContext)(projectArg(args), path);
-        if (args.includes("--json"))
-            console.log(JSON.stringify(result, null, 2));
-        else if (result.context_block)
-            console.log(result.context_block);
-        // No verified packets cite this file: print nothing so hooks can gate on empty output.
+        const project = projectArg(args);
+        const result = (0, kernel_js_1.kageFileContext)(project, path);
+        // Surface any watcher nudge targeting THIS file at the edit/read moment (marks it
+        // surfaced so it shows once) — the highest-value trigger for a nudge. prompt-context
+        // still drains file-less / not-yet-touched nudges on the next prompt.
+        const nudges = (0, kernel_js_1.surfacePendingNudges)(project, { path });
+        if (args.includes("--json")) {
+            console.log(JSON.stringify({ ...result, nudges: nudges.items }, null, 2));
+            return;
+        }
+        const parts = [];
+        if (result.context_block)
+            parts.push(result.context_block);
+        if (nudges.block)
+            parts.push(nudges.block.trimStart());
+        if (parts.length)
+            console.log(parts.join("\n\n"));
+        // No verified packets cite this file and no nudge targets it: print nothing so hooks
+        // can gate on empty output.
         return;
     }
     if (command === "prompt-context") {
@@ -1411,21 +1424,30 @@ async function main() {
         const query = takeArg(args, "--query") ?? firstPositional(args);
         if (!query)
             usage();
-        const result = (0, kernel_js_1.recall)(projectArg(args), query, 5, false, {});
+        const project = projectArg(args);
+        const result = (0, kernel_js_1.recall)(project, query, 5, false, {});
+        // Surface any nudges the kage-watcher wrote (marks them surfaced so each shows once) —
+        // this is what makes recall/nudges felt instead of silently sitting in a file.
+        const nudges = (0, kernel_js_1.surfacePendingNudges)(project);
         if (args.includes("--json")) {
-            console.log(JSON.stringify(result, null, 2));
+            console.log(JSON.stringify({ ...result, nudges: nudges.items }, null, 2));
             return;
         }
-        if (!result.results.length)
+        const parts = [];
+        if (result.results.length) {
+            // Lead with felt behavior, not a vanity/gameable token number: tell the agent these are
+            // verified team memories to follow. (The tokens/$ ledger lives in `kage gains`.) Keep
+            // only the trust-relevant stale-withheld signal here.
+            const plural = result.results.length === 1 ? "y" : "ies";
+            const withheld = result.value_receipt?.stale_withheld ?? 0;
+            parts.push(result.context_block);
+            parts.push(`_${result.results.length} verified team memor${plural} above — follow them.${withheld ? ` ${withheld} stale memor${withheld === 1 ? "y" : "ies"} withheld (code changed under them).` : ""}_`);
+        }
+        if (nudges.block)
+            parts.push(nudges.block.trimStart());
+        if (!parts.length)
             return;
-        let out = result.context_block;
-        // Lead with felt behavior, not a vanity/gameable token number: tell the agent these are
-        // verified team memories to follow. (The tokens/$ ledger lives in `kage gains` for anyone
-        // who wants it.) Keep only the trust-relevant stale-withheld signal here.
-        const plural = result.results.length === 1 ? "y" : "ies";
-        const withheld = result.value_receipt?.stale_withheld ?? 0;
-        out += `\n\n_${result.results.length} verified team memor${plural} above — follow them.${withheld ? ` ${withheld} stale memor${withheld === 1 ? "y" : "ies"} withheld (code changed under them).` : ""}_`;
-        console.log(out);
+        console.log(parts.join("\n\n"));
         return;
     }
     if (command === "memory-access") {

package/dist/kernel.js

@@ -102,6 +102,7 @@ exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.createDenseEmbeddingProvider = createDenseEmbeddingProvider;
 exports.buildEmbeddingIndex = buildEmbeddingIndex;
+exports.surfacePendingNudges = surfacePendingNudges;
 exports.recall = recall;
 exports.recallWithEmbeddings = recallWithEmbeddings;
 exports.queryCodeGraph = queryCodeGraph;
@@ -1202,6 +1203,18 @@ function replayTokensSaved(packets, contextBlock) {
     return Math.max(0, discovery - estimateTokens(contextBlock));
 }
 const FILE_CONTEXT_PACKET_CAP = 3;
+// Normalize a file path to the repo-relative form used for packet citation matching:
+// absolute paths are made relative to the project root, backslashes/leading "./" are
+// stripped. Returns "" for an empty/blank input. Shared by file-context citation lookup
+// and edit-time nudge matching so both compare paths identically.
+function normalizeRepoPath(projectDir, filePath) {
+    let rel = (filePath ?? "").trim().replace(/\\/g, "/");
+    if (!rel)
+        return "";
+    if ((0, node_path_1.isAbsolute)(rel))
+        rel = (0, node_path_1.relative)((0, node_path_1.resolve)(projectDir), rel).replace(/\\/g, "/");
+    return rel.replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "");
+}
 // PreToolUse(Read) injection: verified memory at the moment of relevance. Returns at
 // most three currently-verified packets that cite the file an agent is about to read,
 // as a compact context block. Reuses the same staleness machinery as recall — a packet
@@ -1215,12 +1228,7 @@ function kageFileContext(projectDir, filePath) {
         packets: [],
         context_block: "",
     };
-    if (!filePath || !filePath.trim())
-        return result;
-    let rel = filePath.trim().replace(/\\/g, "/");
-    if ((0, node_path_1.isAbsolute)(rel))
-        rel = (0, node_path_1.relative)((0, node_path_1.resolve)(projectDir), rel).replace(/\\/g, "/");
-    rel = rel.replace(/^\.\//, "").replace(/^\/+/, "");
+    const rel = normalizeRepoPath(projectDir, filePath);
     result.path = rel;
     // Files outside the project (or an uninitialized project) never produce context.
     if (!rel || rel.startsWith("..") || !(0, node_fs_1.existsSync)(memoryRoot(projectDir)))
@@ -7942,7 +7950,10 @@ function isSerializedDumpTitle(title) {
     return /^(workflow|runbook)\s*:?\s*[{[]/i.test(t)
         || t.startsWith('{"')
         || /^<(task-notification|div|svg|html)\b/i.test(t)
-        || /\btool_use_id\b|toolu_[A-Za-z0-9]{10}/.test(title);
+        || /\btool_use_id\b|toolu_[A-Za-z0-9]{10}/.test(title)
+        // Shell-prompt / terminal paste, e.g. "user@host dir % cmd" or "user@host:path$ cmd" —
+        // a pasted command transcript, not a durable learning.
+        || /^[\w.+-]+@[\w.+-]+[\s:].*[%$#]\s/.test(t);
 }
 // Durable-learning size ceiling. A memory packet body is a distilled insight, not a
 // document; anything past this is almost certainly a raw transcript, file-content, or
@@ -7961,6 +7972,64 @@ function isSerializedDumpBody(body) {
     return isSerializedDumpTitle(t)
         || /<task-notification\b|<tool-use-id\b|"hookSpecificOutput"|"isImage"\s*:|"noOutputExpected"\s*:|"interrupted"\s*:\s*(true|false)/i.test(t.slice(0, 4000));
 }
+// Surface watcher nudges: read the nudge inbox the kage-watcher writes (.agent_memory/
+// nudges/pending.jsonl), return the unsurfaced ones as a prominent block, and mark them
+// surfaced so each shows exactly once. This is what makes recall/nudges FELT instead of
+// sitting silently in a file. Two trigger points share this: prompt-context
+// (UserPromptSubmit) passes no filter and drains every pending nudge; file-context
+// (PreToolUse Edit/Read) passes opts.path so only a nudge targeting the file being touched
+// fires — surfacing the warning at the edit moment, the highest-value trigger. A file-less
+// nudge has no edit moment, so it waits for the next prompt-context drain.
+function surfacePendingNudges(projectDir, opts = {}) {
+    const path = (0, node_path_1.join)(projectDir, ".agent_memory", "nudges", "pending.jsonl");
+    if (!(0, node_fs_1.existsSync)(path))
+        return { block: "", items: [], count: 0 };
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(path, "utf8");
+    }
+    catch {
+        return { block: "", items: [], count: 0 };
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === "object")
+                records.push(parsed);
+        }
+        catch { /* drop malformed lines */ }
+    }
+    const wantPath = opts.path !== undefined ? normalizeRepoPath(projectDir, opts.path) : undefined;
+    const unsurfaced = records.filter((record) => record.surfaced !== true &&
+        typeof record.message === "string" &&
+        (wantPath === undefined ||
+            (typeof record.file === "string" && normalizeRepoPath(projectDir, record.file) === wantPath)));
+    if (!unsurfaced.length)
+        return { block: "", items: [], count: 0 };
+    const items = unsurfaced.map((record) => ({
+        message: String(record.message),
+        file: typeof record.file === "string" ? record.file : undefined,
+        kind: typeof record.kind === "string" ? record.kind : undefined,
+    }));
+    for (const record of unsurfaced)
+        record.surfaced = true;
+    // Atomic write (tmp + rename): file-context now rewrites this inbox on every edit, so the
+    // window where prompt-context could read a half-written file is wider. rename is atomic, so
+    // a concurrent reader sees either the old or the new file, never a torn one.
+    try {
+        const tmp = `${path}.${process.pid}.tmp`;
+        (0, node_fs_1.writeFileSync)(tmp, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`, "utf8");
+        (0, node_fs_1.renameSync)(tmp, path);
+    }
+    catch { /* best-effort; recall still works */ }
+    const block = ["", "## ⚠ Kage nudges — act on these before proceeding",
+        ...items.map((item) => `- ${item.file ? `${item.file}: ` : ""}${item.message}`)].join("\n");
+    return { block, items, count: items.length };
+}
 // Collapse whitespace and hard-cap a value rendered inline in a context block, so one
 // oversized field (e.g. a graph fact whose body is a raw transcript) can never blow up
 // the assembled output — the 270k-char overflow that motivated this guard.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "description": "Team memory for coding agents: captures the decisions, runbooks, and bug fixes that get lost, verified against your code and shared via git. MCP server, zero deps, no account.",
   "main": "dist/index.js",
   "files": [