@kage-core/kage-graph-mcp 2.5.4 → 2.5.6

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);

package/dist/kernel.js

@@ -102,6 +102,7 @@ exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.createDenseEmbeddingProvider = createDenseEmbeddingProvider;
 exports.buildEmbeddingIndex = buildEmbeddingIndex;
+exports.isUngroundedConversationalCapture = isUngroundedConversationalCapture;
 exports.recall = recall;
 exports.recallWithEmbeddings = recallWithEmbeddings;
 exports.queryCodeGraph = queryCodeGraph;
@@ -150,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;
@@ -2133,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,
@@ -7004,10 +7015,11 @@ function gcProject(projectDir, options = {}) {
             skipped.push({ id: packet.id, title: packet.title, reason: "already deprecated" });
             continue;
         }
-        // Serialized transcript / tool-output / file-content dumps carry no durable knowledge
-        // and bloat recall + the graph. Always delete them (deprecating would leave the blob on
-        // disk) — this also reclaims legacy dumps written before the capture-time guard existed.
-        if (isSerializedDumpTitle(packet.title) || isSerializedDumpBody(packet.body)) {
+        // Serialized transcript / tool-output / file-content dumps and ungrounded conversational
+        // chatter (a path-less rant at the assistant) carry no durable knowledge and bloat recall +
+        // the digest. Always delete them (deprecating would leave the blob on disk) — this also
+        // reclaims legacy junk written before the capture-time guards existed.
+        if (isSerializedDumpTitle(packet.title) || isSerializedDumpBody(packet.body) || isUngroundedConversationalCapture(packet)) {
             if (!options.dryRun)
                 (0, node_fs_1.unlinkSync)(path);
             deleted.push({ id: packet.id, title: packet.title });
@@ -7970,6 +7982,73 @@ 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));
 }
+// 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").
+// Phrases that rant AT the assistant ("why are you...", "it's your job", "don't stop"). These
+// never appear in a curated learning, so they mark chatter even when the outburst name-drops a
+// platform word (github, pr, x, linkedin) that the loose grounding matcher would otherwise
+// treat as a repo reference. This is the override that closes the leak where a frustrated
+// message peppered with nouns slipped through and was captured as approved memory.
+function looksFrustratedAtAssistant(text) {
+    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(text ?? "");
+}
+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 looksFrustratedAtAssistant(t);
+}
+// Capture-noise guard for ungrounded chat. A packet trips it when it cites zero repo paths and
+// either (a) it rants at the assistant — which overrides incidental repo-ish words, since the
+// grounding matcher false-positives on bare platform names — or (b) it reads as a raw outburst
+// and carries no repo grounding signal at all. The override + conjunction keep it safe: a real
+// ungrounded decision or convention is declarative (no "why are you.../don't stop") and usually
+// names a symbol, file, command, or rule, so it is never caught. Such packets route to pending
+// (not auto-approved) at capture time and are withheld from recall, like serialized dumps.
+function isUngroundedConversationalCapture(packet) {
+    if (packet.paths && packet.paths.length > 0)
+        return false;
+    const text = `${packet.title ?? ""}\n${packet.body ?? ""}`;
+    if (looksFrustratedAtAssistant(text))
+        return true;
+    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
 // the assembled output — the 270k-char overflow that motivated this guard.
@@ -8055,7 +8134,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);
@@ -8067,7 +8146,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(",")}`;
@@ -13711,6 +13790,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
@@ -13729,9 +13822,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: [
@@ -13793,7 +13886,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,
@@ -14354,6 +14447,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 = {};
@@ -14756,19 +14901,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;
@@ -15488,20 +15627,17 @@ function kageResume(projectDir) {
         updated_at: packetRecency(packet),
         age: humanPacketAge(packetRecency(packet)),
     }));
-    const hasSessionContent = Boolean(lastSession || lastChangeMemory || pendingAutoDistilled || reconciliation.unresolved_count);
-    const hasContent = hasSessionContent || recentMemory.length > 0;
+    // A new session starts on a fresh task, so SessionStart does NOT replay last session's files,
+    // commands, or a recency-ranked memory list — that was pre-task noise (it fires before the
+    // first prompt, so it can't be task-targeted) and the surface that leaked raw command dumps and
+    // junk packets. Task-relevant memory is pulled on the first prompt via prompt-context; recall
+    // at the moment a file is read via file-context. SessionStart carries only always-on curated
+    // repo facts (the pinned block, below) plus a few actionable open-thread pointers.
+    const hasSessionContent = Boolean(lastChangeMemory || pendingAutoDistilled || reconciliation.unresolved_count);
+    const hasContent = hasSessionContent;
     const lines = [];
-    if (hasContent) {
-        lines.push("# Previously (Kage)");
-        if (lastSession) {
-            lines.push(`Last session ${lastSession.session_id} (${lastSession.observations} observation${lastSession.observations === 1 ? "" : "s"}, ended ${lastSession.last_at}).`);
-            if (lastSession.paths.length)
-                lines.push(`Worked on: ${lastSession.paths.join(", ")}`);
-            if (lastSession.commands.length)
-                lines.push(`Commands: ${lastSession.commands.join("; ")}`);
-            if (lastSession.distilled_titles.length)
-                lines.push(`Learned: ${lastSession.distilled_titles.join("; ")}`);
-        }
+    if (hasSessionContent) {
+        lines.push("# Open threads (Kage)");
         if (lastChangeMemory) {
             lines.push(`Change memory: ${lastChangeMemory.title} — ${lastChangeMemory.summary}`);
         }
@@ -15514,22 +15650,7 @@ function kageResume(projectDir) {
                 lines.push(`  - ${item.packet_id}: ${item.title}`);
         }
     }
-    // Compact timeline index: one line per recent packet, full detail (summary)
-    // only for the newest few, hard-capped to the resume token budget.
-    const block = lines.slice(0, 15);
-    if (recentPackets.length) {
-        block.push("", "## Recent memory");
-        recentPackets.forEach((packet, position) => {
-            const entry = `[${packet.id.slice(0, 12)}] ${packet.type} ${packet.title} (${humanPacketAge(packetRecency(packet))})`;
-            const candidate = [entry];
-            if (position < RESUME_TIMELINE_DETAILED && packet.summary) {
-                const summary = packet.summary.replace(/\s+/g, " ").trim();
-                candidate.push(`    ${summary.length > 160 ? `${summary.slice(0, 157)}...` : summary}`);
-            }
-            if (estimateTokens([...block, ...candidate].join("\n")) <= RESUME_CONTEXT_TOKEN_BUDGET)
-                block.push(...candidate);
-        });
-    }
+    const block = lines.slice(0, 12);
     // Lead the SessionStart injection with the team's pinned, always-on repo memory (the
     // curated high-signal facts), not just the recent-timeline digest — parity with recall's
     // context block, so a new session starts already holding the key knowledge, not only a

package/package.json

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