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

package/dist/cli.js

@@ -708,6 +708,22 @@ async function main() {
         }
         return;
     }
+    if (command === "gen-plugin-hooks") {
+        // Maintainer tool: regenerate plugin/hooks/* from the setupAgent("claude-code") templates
+        // so the plugin and the npm install path ship identical hooks (one source of truth).
+        const pluginDir = takeArg(args, "--plugin-dir") ?? (0, node_path_1.join)(process.cwd(), "plugin");
+        const result = (0, kernel_js_1.generatePluginHooks)(pluginDir);
+        if (args.includes("--json")) {
+            console.log(JSON.stringify({ plugin_dir: pluginDir, ...result }, null, 2));
+            return;
+        }
+        console.log(`Generated plugin hooks in ${(0, node_path_1.join)(pluginDir, "hooks")}`);
+        console.log(`  scripts: ${result.scripts.join(", ")}`);
+        console.log(`  events:  ${result.events.join(", ")}`);
+        if (result.removed.length)
+            console.log(`  removed: ${result.removed.join(", ")}`);
+        return;
+    }
     if (command === "daemon") {
         const action = args[1];
         const projectDir = projectArg(args);
@@ -1396,58 +1412,35 @@ async function main() {
         const path = takeArg(args, "--path");
         if (!path)
             usage();
-        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.
+        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.
         return;
     }
     if (command === "prompt-context") {
         // Top-of-task recall for an ambient UserPromptSubmit hook: recall on the user's prompt
-        // and emit the memory PLUS a one-line savings receipt (what was recalled + tokens saved).
-        // Silent when nothing relevant is found, so hooks can gate on empty output.
+        // and emit the memory. Silent when nothing relevant is found, so hooks can gate on empty.
         const query = takeArg(args, "--query") ?? firstPositional(args);
         if (!query)
             usage();
         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, nudges: nudges.items }, null, 2));
+            console.log(JSON.stringify(result, null, 2));
             return;
         }
-        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)
+        if (!result.results.length)
             return;
-        console.log(parts.join("\n\n"));
+        // 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;
+        console.log(result.context_block);
+        console.log(`_${result.results.length} verified team memor${plural} above — follow them.${withheld ? ` ${withheld} stale memor${withheld === 1 ? "y" : "ies"} withheld (code changed under them).` : ""}_`);
         return;
     }
     if (command === "memory-access") {

package/dist/kernel.js

@@ -102,7 +102,7 @@ exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.createDenseEmbeddingProvider = createDenseEmbeddingProvider;
 exports.buildEmbeddingIndex = buildEmbeddingIndex;
-exports.surfacePendingNudges = surfacePendingNudges;
+exports.isUngroundedConversationalCapture = isUngroundedConversationalCapture;
 exports.recall = recall;
 exports.recallWithEmbeddings = recallWithEmbeddings;
 exports.queryCodeGraph = queryCodeGraph;
@@ -151,6 +151,7 @@ exports.capture = capture;
 exports.createPublicCandidate = createPublicCandidate;
 exports.registryRecommendations = registryRecommendations;
 exports.setupAgent = setupAgent;
+exports.generatePluginHooks = generatePluginHooks;
 exports.setupDoctor = setupDoctor;
 exports.verifyAgentActivation = verifyAgentActivation;
 exports.observe = observe;
@@ -1204,9 +1205,8 @@ function replayTokensSaved(packets, 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.
+// absolute paths are made relative to the project root, backslashes/leading "./" and
+// trailing slashes are stripped. Returns "" for an empty/blank input.
 function normalizeRepoPath(projectDir, filePath) {
     let rel = (filePath ?? "").trim().replace(/\\/g, "/");
     if (!rel)
@@ -2135,9 +2135,18 @@ function evaluateMemoryAdmission(projectDir, packet) {
         score -= 10;
         risks.push("too little context");
     }
+    // Ungrounded conversational chatter (a path-less, repo-reference-free user outburst) is not
+    // durable memory regardless of its other signals — keywords like "issue"/"before" can
+    // otherwise score it as a candidate. Hard-block admission so it can never auto-promote.
+    if (isUngroundedConversationalCapture(packet)) {
+        score -= 45;
+        risks.push("ungrounded conversational utterance, not durable knowledge");
+    }
     const bounded = Math.max(0, Math.min(100, score));
     return {
-        admit: bounded >= 45 && risks.indexOf("session bookkeeping, not durable knowledge") === -1,
+        admit: bounded >= 45
+            && risks.indexOf("session bookkeeping, not durable knowledge") === -1
+            && risks.indexOf("ungrounded conversational utterance, not durable knowledge") === -1,
         class: bounded >= 72 ? "high_signal" : bounded >= 45 ? "candidate" : "episodic_only",
         score: bounded,
         reasons,
@@ -7972,63 +7981,61 @@ 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 };
+// Repo grounding signals — does the text point at something concrete in the codebase? These
+// three predicates are the shared vocabulary for "grounded": observationSignalScore weights
+// them into its durable-knowledge score, and the ungrounded-utterance guard uses their union
+// to decide whether a path-less capture references the repo at all. Kept as one source of
+// truth so the scorer and the guard can never drift on what "grounded" means.
+function textCitesPath(text) {
+    return /\b[\w.-]+\/[\w./-]+\b/.test(text)
+        || /\b[\w-]+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|json|ya?ml|toml|md|sh|css|html|sql)\b/i.test(text);
+}
+function textHasCodeIdentifier(text) {
+    return /\b[a-z][a-z0-9]*[A-Z]\w*\b/.test(text) // camelCase
+        || /\b[a-z0-9]+_[a-z0-9_]+\b/.test(text) // snake_case
+        || /`[^`]+`/.test(text)
+        || /\b\w+\(\)/.test(text);
+}
+function textHasCommand(text) {
+    return /(^|\s)(npm|pnpm|yarn|npx|node|git|cargo|make|pytest|go|tsc|kage)\s+[\w.-]/.test(text);
+}
+function hasRepoGroundingSignal(text) {
+    const t = text ?? "";
+    if (!t.trim())
+        return false;
+    return textCitesPath(t) || textHasCodeIdentifier(t) || textHasCommand(t);
+}
+// A raw conversational user utterance: a frustrated/rhetorical/imperative chat message aimed
+// at the agent — e.g. "why are you asking me???!!! it's your job, don't stop before you...".
+// It is plain prose, so the serialized-dump guard waves it through, yet it is chatter, not
+// durable repo knowledge. Detection is deliberately narrow — a run of emphatic terminal
+// punctuation, or one of a curated set of rhetorical / second-person-at-the-assistant
+// phrases — so it stays clear of normal declarative learnings (which read as statements, not
+// outbursts addressed to "you").
+function looksLikeRawUserUtterance(text) {
+    const t = (text ?? "").trim();
+    if (!t)
+        return false;
+    // Emphatic or mixed terminal punctuation ("???", "!!", "?!") — common in venting chat,
+    // essentially absent from curated memory prose.
+    if (/[!?]{2,}/.test(t))
+        return true;
+    // Rhetorical questions / second-person-imperative frustration directed at the assistant.
+    return /\b(why are you|why did you|why would you|why aren'?t you|are you (kidding|serious|even|really)|it'?s your job|that'?s your job|do your job|don'?t stop|stop asking|stop before you|keep going|hurry up|just do it|figure it out yourself|i (already )?told you)\b/i.test(t);
+}
+// Capture-noise guard for ungrounded chat. A packet trips it only when ALL hold: it cites zero
+// repo paths, its text carries no repo grounding signal (no path/file/identifier/command), and
+// it reads as a raw conversational user utterance. The conjunction is what keeps it safe — a
+// real ungrounded decision or convention names a symbol, file, command, or rule and so is never
+// caught. Such packets are routed to pending (not auto-approved) at capture time and withheld
+// from recall, mirroring how serialized dumps are gated.
+function isUngroundedConversationalCapture(packet) {
+    if (packet.paths && packet.paths.length > 0)
+        return false;
+    const text = `${packet.title ?? ""}\n${packet.body ?? ""}`;
+    if (hasRepoGroundingSignal(text))
+        return false;
+    return looksLikeRawUserUtterance(text);
 }
 // 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
@@ -8115,7 +8122,7 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         ];
         return { packet, score: score_breakdown.final, relevance, why_matched: unique(why).slice(0, 12), score_breakdown };
     })
-        .filter((entry) => entry.relevance > 0 && !isSerializedDumpTitle(entry.packet.title))
+        .filter((entry) => entry.relevance > 0 && !isSerializedDumpTitle(entry.packet.title) && !isUngroundedConversationalCapture(entry.packet))
         .sort((a, b) => b.score - a.score || a.packet.title.localeCompare(b.packet.title));
     const scored = diversifyRecallEntries(rankedScored, limit)
         .map(({ relevance, ...entry }) => entry);
@@ -8127,7 +8134,7 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         const { score, why } = pendingLexicalScores.get(packet.id) ?? { score: 0, why: [] };
         return { packet, score, why_matched: why };
     })
-        .filter((entry) => entry.score > 0)
+        .filter((entry) => entry.score > 0 && !isUngroundedConversationalCapture(entry.packet))
         .sort((a, b) => b.score - a.score || a.packet.title.localeCompare(b.packet.title))
         .filter((entry) => {
         const key = `${entry.packet.type}:${entry.packet.title.toLowerCase()}:${entry.packet.paths.join(",")}`;
@@ -13771,6 +13778,20 @@ function capture(input) {
     if (missingPaths.length) {
         warnings.push(`Some referenced paths do not exist in this repo: ${missingPaths.join(", ")}`);
     }
+    // Ungrounded conversational chatter — a frustrated/rhetorical user message with no cited repo
+    // paths — is not durable memory. Don't hard-reject (a reviewer may still salvage it); instead
+    // deny it the auto-approve fast path so it lands in the pending inbox, tagged with why. Recall
+    // withholds it regardless of status. Explicit pendingReview captures already route to review.
+    const ungroundedUtterance = isUngroundedConversationalCapture({
+        title: input.title,
+        body: input.body,
+        paths: groundedPaths,
+    });
+    const routeToPending = Boolean(input.pendingReview) || ungroundedUtterance;
+    if (ungroundedUtterance && !input.pendingReview) {
+        warnings.push("Routed to pending review: this reads as an ungrounded conversational message with no cited repo paths, " +
+            "not a durable learning. Cite a repo path or restate it as a reusable insight to approve it.");
+    }
     const createdAt = nowIso();
     // Agent-asserted links to code-graph nodes (PRD `graph_nodes`): the agent recording the
     // memory knows which symbol/route/file the rule is about, so let it declare them instead
@@ -13789,9 +13810,9 @@ function capture(input) {
         scope: "repo",
         visibility: "team",
         sensitivity: "internal",
-        status: input.pendingReview ? "pending" : "approved",
+        status: routeToPending ? "pending" : "approved",
         confidence: DEFAULT_CONFIDENCE,
-        tags: input.tags ?? [],
+        tags: ungroundedUtterance ? unique([...(input.tags ?? []), "needs-grounding"]) : (input.tags ?? []),
         paths: groundedPaths,
         stack: input.stack ?? [],
         source_refs: [
@@ -13853,7 +13874,7 @@ function capture(input) {
         ...evaluateMemoryQuality(input.projectDir, packet),
         ...(contradictions.length ? { contradicts: contradictions.map((c) => c.packet_id) } : {}),
     };
-    const path = writePacket(input.projectDir, packet, input.pendingReview ? "pending" : "packets");
+    const path = writePacket(input.projectDir, packet, routeToPending ? "pending" : "packets");
     recordMemoryAudit(input.projectDir, "capture", [packet], {
         type: packet.type,
         status: packet.status,
@@ -14414,6 +14435,58 @@ exit 0
     setSnippet(paths[agent] || null, universal, [`Merge this MCP stdio config into ${agent}'s MCP settings.`, "Restart the agent after updating config."]);
     return result;
 }
+// Single source of truth for Claude Code hooks. The plugin's hook scripts and hooks.json are
+// GENERATED from the exact same setupAgent("claude-code") output the npm install path writes —
+// so a hook fix lands in both channels and they can't silently drift. The hook scripts call the
+// kage CLI and never reference their own location, so the same bodies serve both the ~/.claude
+// install and the plugin; only the wiring's command path is re-targeted to ${CLAUDE_PLUGIN_ROOT}.
+// Run via `kage gen-plugin-hooks`; a unit test asserts the committed plugin/hooks match this.
+function generatePluginHooks(pluginDir) {
+    const tmpHome = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "kage-plugin-home-"));
+    const tmpProject = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "kage-plugin-proj-"));
+    try {
+        setupAgent("claude-code", tmpProject, { write: true, homeDir: tmpHome });
+        const srcHookDir = (0, node_path_1.join)(tmpHome, ".claude", "kage", "hooks");
+        const settings = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(tmpHome, ".claude", "settings.json"), "utf8"));
+        const hooksOut = (0, node_path_1.join)(pluginDir, "hooks");
+        (0, node_fs_1.mkdirSync)(hooksOut, { recursive: true });
+        // Copy the generated hook scripts verbatim (path-agnostic — they shell out to `kage`).
+        const scripts = (0, node_fs_1.readdirSync)(srcHookDir).filter((f) => f.endsWith(".sh")).sort();
+        for (const file of scripts) {
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hooksOut, file), (0, node_fs_1.readFileSync)((0, node_path_1.join)(srcHookDir, file), "utf8"), { mode: 0o755 });
+        }
+        // Re-target the event wiring from the install path's `~/.claude/kage/hooks/` to the plugin's
+        // `${CLAUDE_PLUGIN_ROOT}/hooks/`, preserving events, matchers, and timeouts exactly.
+        const events = Object.keys(settings.hooks ?? {});
+        const pluginHooks = { hooks: {} };
+        for (const event of events) {
+            pluginHooks.hooks[event] = (settings.hooks ?? {})[event].map((entry) => ({
+                ...(entry.matcher !== undefined ? { matcher: entry.matcher } : {}),
+                hooks: entry.hooks.map((h) => {
+                    const m = h.command.match(/^bash ~\/\.claude\/kage\/hooks\/(.+)$/);
+                    return {
+                        type: h.type,
+                        command: m ? `bash "\${CLAUDE_PLUGIN_ROOT}/hooks/${m[1]}"` : h.command,
+                        ...(h.timeout !== undefined ? { timeout: h.timeout } : {}),
+                    };
+                }),
+            }));
+        }
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hooksOut, "hooks.json"), `${JSON.stringify(pluginHooks, null, 2)}\n`, "utf8");
+        // Drop committed scripts the install path no longer emits (e.g. kage-prompt-context.sh,
+        // now subsumed by observe.sh handling UserPromptSubmit).
+        const removed = [];
+        for (const stale of (0, node_fs_1.readdirSync)(hooksOut).filter((f) => f.endsWith(".sh") && !scripts.includes(f))) {
+            (0, node_fs_1.unlinkSync)((0, node_path_1.join)(hooksOut, stale));
+            removed.push(stale);
+        }
+        return { scripts, removed, events };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(tmpHome, { recursive: true, force: true });
+        (0, node_fs_1.rmSync)(tmpProject, { recursive: true, force: true });
+    }
+}
 function upsertJsonMcpServer(path, name, server) {
     ensureDir((0, node_path_1.dirname)(path));
     let config = {};
@@ -14816,19 +14889,13 @@ function observationSignalScore(observation) {
     const causalHits = SIGNAL_CAUSAL_MARKERS.filter((marker) => lower.includes(marker)).length;
     if (causalHits > 0)
         score += Math.min(0.35, 0.25 + (causalHits - 1) * 0.05);
-    const citesPath = Boolean(observation.path)
-        || /\b[\w.-]+\/[\w./-]+\b/.test(prose)
-        || /\b[\w-]+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|json|ya?ml|toml|md|sh|css|html|sql)\b/i.test(prose);
+    const citesPath = Boolean(observation.path) || textCitesPath(prose);
     if (citesPath)
         score += 0.2;
-    const codeIdentifier = /\b[a-z][a-z0-9]*[A-Z]\w*\b/.test(prose) // camelCase
-        || /\b[a-z0-9]+_[a-z0-9_]+\b/.test(prose) // snake_case
-        || /`[^`]+`/.test(prose)
-        || /\b\w+\(\)/.test(prose);
+    const codeIdentifier = textHasCodeIdentifier(prose);
     if (codeIdentifier)
         score += 0.15;
-    const commandLine = Boolean(observation.command)
-        || /(^|\s)(npm|pnpm|yarn|npx|node|git|cargo|make|pytest|go|tsc|kage)\s+[\w.-]/.test(prose);
+    const commandLine = Boolean(observation.command) || textHasCommand(prose);
     if (commandLine)
         score += 0.15;
     const words = combined.split(/\s+/).filter(Boolean).length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "2.5.3",
+  "version": "2.5.5",
   "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": [