mnemos-capture 1.7.0 → 1.8.0

package/dist/cli/git-hook.js

@@ -2,13 +2,19 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "f
 import { join, resolve } from "path";
 import { execFileSync } from "child_process";
 import { callMcp, initializeMcp } from "./hooks.js";
+import { syncCodeMap } from "./code-map.js";
+import { currentRepo } from "./session-start.js";
 import { getCurrentVersion } from "./version-check.js";
 /**
  * Links commits to the captures they apply, with any coding agent or none.
  * The commit message carries one `xkg-capture: <filename>` trailer per
  * capture; a git post-commit hook reports each one to apply_capture with the
- * commit sha. The server counts a capture and commit once, so an agent that
- * also calls apply_capture itself does not double count.
+ * commit sha and the repo. The server counts a capture and commit once, so an
+ * agent that also calls apply_capture itself does not double count. A
+ * `git revert` of such a commit is reported as reverted, with no agent.
+ *
+ * The same hooks, plus post-merge and post-checkout, keep the repo's code map
+ * (code-map.ts) fresh, so every agent gets it through git alone.
  */
 const PACKAGE = "@xmu-labs/xkg";
 const MARKER = "# xkg";
@@ -29,44 +35,117 @@ export function captureTrailers(message) {
     const found = [...trailers.matchAll(/^xkg-capture:[ \t]*(\S+)[ \t]*$/gim)].map((m) => m[1]);
     return [...new Set(found)];
 }
-/**
- * Installs or updates xkg's line in the repo's post-commit hook and returns the hook's path.
- * The line holds no credential (the hooks directory may be tracked); the key comes from
- * `xkg config` at run time. It reads the sha before going to the background, so a quick
- * next commit can't be reported in its place. It runs the CLI version that installed it, so
- * a new release reaches a repo only when the hook is installed again.
- */
-export function installPostCommitHook(cwd = process.cwd(), version = getCurrentVersion()) {
-    const hooksDir = resolve(cwd, git(cwd, "rev-parse", "--git-path", "hooks"));
-    const path = join(hooksDir, "post-commit");
-    const pin = version === "0.0.0" ? "latest" : version;
-    const line = `xkg_sha=$(git rev-parse HEAD); npx -y ${PACKAGE}@${pin} post-commit --sha "$xkg_sha" >/dev/null 2>&1 & ${MARKER}`;
+/** Writes `line` as xkg's only line in a shell hook, keeping the user's own lines. */
+function installHookLine(hooksDir, name, line, isOurs) {
+    const path = join(hooksDir, name);
     const existing = existsSync(path) ? readFileSync(path, "utf-8") : "#!/bin/sh\n";
     if (!/^#!\s*\S*\b(?:env\s+)?(?:sh|bash|zsh|dash|ksh)\b/.test(existing.split("\n")[0] ?? "")) {
         throw new Error(`${path} is not a shell script; add this line to it yourself:\n${line}`);
     }
-    const kept = existing.split("\n").filter((l) => !l.endsWith(MARKER) || !l.includes(" post-commit "));
+    const kept = existing.split("\n").filter((l) => !(l.endsWith(MARKER) && isOurs(l)));
     const body = kept.join("\n").replace(/\n*$/, "\n");
     mkdirSync(hooksDir, { recursive: true });
     writeFileSync(path, `${body}${line}\n`);
     chmodSync(path, 0o755);
     return path;
 }
-/** Runs after each commit: reports every `xkg-capture:` trailer of `sha` to apply_capture. Never throws. */
+function hooksDirOf(cwd) {
+    return resolve(cwd, git(cwd, "rev-parse", "--git-path", "hooks"));
+}
+function runner(version) {
+    return `npx -y ${PACKAGE}@${version === "0.0.0" ? "latest" : version}`;
+}
+/**
+ * Installs or updates xkg's line in the repo's post-commit hook and returns the hook's path.
+ * The line holds no credential (the hooks directory may be tracked); the key comes from
+ * `xkg config` at run time. It reads the sha before going to the background, so a quick
+ * next commit can't be reported in its place. It runs the CLI version that installed it, so
+ * a new release reaches a repo only when the hook is installed again.
+ */
+export function installPostCommitHook(cwd = process.cwd(), version = getCurrentVersion()) {
+    const line = `xkg_sha=$(git rev-parse HEAD); ${runner(version)} post-commit --sha "$xkg_sha" >/dev/null 2>&1 & ${MARKER}`;
+    return installHookLine(hooksDirOf(cwd), "post-commit", line, (l) => l.includes(" post-commit "));
+}
+/** Where an agent writes a handoff spec in the code repo. Kept out of git locally, never committed. */
+const LOCAL_DIR = ".xkg/";
+/** Adds `.xkg/` to the repo's local exclude file (not .gitignore, which is shared), once. */
+export function excludeLocalDir(cwd) {
+    const path = resolve(cwd, git(cwd, "rev-parse", "--git-path", "info/exclude"));
+    const current = existsSync(path) ? readFileSync(path, "utf-8") : "";
+    if (current.split("\n").some((l) => l.trim() === LOCAL_DIR || l.trim() === "/.xkg/"))
+        return;
+    mkdirSync(resolve(path, ".."), { recursive: true });
+    writeFileSync(path, `${current.replace(/\n*$/, current ? "\n" : "")}${LOCAL_DIR}\n`);
+}
+/**
+ * Installs the post-commit hook, plus post-merge and post-checkout lines that sync the
+ * code map after a pull or a branch switch (not after a checkout of single files),
+ * and keeps `.xkg/` out of git. Returns the three hooks' paths.
+ */
+export function installGitHooks(cwd = process.cwd(), version = getCurrentVersion()) {
+    excludeLocalDir(cwd);
+    const commit = installPostCommitHook(cwd, version);
+    const dir = hooksDirOf(cwd);
+    const sync = `${runner(version)} sync-map >/dev/null 2>&1 & ${MARKER}`;
+    const isSync = (l) => l.includes(" sync-map ");
+    return [
+        commit,
+        installHookLine(dir, "post-merge", sync, isSync),
+        installHookLine(dir, "post-checkout", `[ "$3" = "1" ] && ${sync}`, isSync),
+    ];
+}
+/**
+ * Runs after each commit: reports every `xkg-capture:` trailer of `sha` to apply_capture
+ * (and, for a revert, the trailers of the commit it undid), then syncs the code map if it
+ * changed. Never throws.
+ */
 export async function postCommit(apiKey, sha, cwd = process.cwd()) {
+    // The map first: the server keeps only an apply's files that are in it, so a file the commit added must be there
+    await syncCodeMap(apiKey, cwd);
+    await reportTrailers(apiKey, sha, cwd);
+}
+/** Changed files sent per report; the server keeps those in the repo's code map. */
+const MAX_FILES = 20;
+/** The commit a `git revert` undid, from git's own message ("This reverts commit <sha>."). */
+export function revertedCommit(message) {
+    return message.match(/^This reverts commit ([0-9a-f]{7,40})\b/m)?.[1] ?? null;
+}
+async function reportTrailers(apiKey, sha, cwd) {
     try {
         const full = git(cwd, "rev-parse", "--verify", `${sha}^{commit}`);
-        const trailers = captureTrailers(git(cwd, "log", "-1", "--format=%B", full));
-        if (trailers.length === 0)
+        const message = git(cwd, "log", "-1", "--format=%B", full);
+        const repo = currentRepo(cwd);
+        const inRepo = repo ? { repo } : {};
+        const reports = [];
+        const trailers = captureTrailers(message);
+        if (trailers.length) {
+            // NUL-separated, so paths come as they are and not as git quotes them ("caf\303\251.ts")
+            const files = git(cwd, "diff-tree", "--root", "--no-commit-id", "--name-only", "-r", "-z", full).split("\0").filter(Boolean);
+            const target = files.slice(0, 5).join(", ") + (files.length > 5 ? ` and ${files.length - 5} more` : "");
+            for (const filename of trailers)
+                reports.push({ filename, commit_sha: full, target_file: target, files: files.slice(0, MAX_FILES), ...inRepo });
+        }
+        // A revert of a commit that applied captures undoes those applies
+        const undone = revertedCommit(message);
+        if (undone) {
+            try {
+                const original = git(cwd, "rev-parse", "--verify", `${undone}^{commit}`);
+                for (const filename of captureTrailers(git(cwd, "log", "-1", "--format=%B", original))) {
+                    reports.push({ filename, commit_sha: original, outcome: "reverted", ...inRepo });
+                }
+            }
+            catch {
+                // The reverted commit isn't in this clone
+            }
+        }
+        if (reports.length === 0)
             return;
-        const files = git(cwd, "diff-tree", "--root", "--no-commit-id", "--name-only", "-r", full).split("\n").filter(Boolean);
-        const target = files.slice(0, 5).join(", ") + (files.length > 5 ? ` and ${files.length - 5} more` : "");
         // One session for all of this commit's reports. Without one they still count, as "unknown".
         const session = await initializeMcp(apiKey, HOOK_CLIENT, 10000)
             .then((res) => (res.ok ? res.headers.get("mcp-session-id") : null))
             .catch(() => null);
-        for (const filename of trailers) {
-            await callMcp(apiKey, "apply_capture", { filename, commit_sha: full, target_file: target }, 10000, session).catch(() => null);
+        for (const args of reports) {
+            await callMcp(apiKey, "apply_capture", args, 10000, session).catch(() => null);
         }
     }
     catch {

package/dist/cli/index.js

@@ -42,7 +42,8 @@ async function main() {
         return;
     }
     if (command === "setup-git-hook") {
-        const { installPostCommitHook, checkHookConnection } = await import("./git-hook.js");
+        const { installGitHooks, checkHookConnection } = await import("./git-hook.js");
+        const { syncCodeMap } = await import("./code-map.js");
         const { readConfig, setConfigField } = await import("./config.js");
         const keyIdx = args.indexOf("--key");
         const keyArg = keyIdx !== -1 ? args[keyIdx + 1] : undefined;
@@ -54,9 +55,10 @@ async function main() {
             process.exit(1);
         }
         try {
-            const path = installPostCommitHook();
-            console.log(`xkg git hook installed: ${path}`);
+            const paths = installGitHooks();
+            console.log(`xkg git hooks installed: ${paths.join(", ")}`);
             console.log("Commits with an `xkg-capture: <filename>` trailer are now recorded as applied.");
+            console.log("Commits, pulls and branch switches keep this repo's code map (file and function names, never code) up to date.");
         }
         catch (err) {
             console.error(err instanceof Error && err.message.includes("not a shell script")
@@ -73,6 +75,47 @@ async function main() {
             console.error(`The hook is installed but can't report yet: ${check.reason}`);
             process.exit(1);
         }
+        console.log(syncMessage(await syncCodeMap(readConfig().key, process.cwd(), { force: true })));
+        return;
+    }
+    if (command === "map") {
+        const { syncCodeMap } = await import("./code-map.js");
+        const { readConfig } = await import("./config.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : readConfig().key;
+        if (!apiKey) {
+            console.error("No API key. Pass --key YOUR_KEY or store it: xkg config set key YOUR_KEY");
+            process.exit(1);
+        }
+        const result = await syncCodeMap(apiKey, process.cwd(), { force: true });
+        if (result.status === "synced") {
+            console.log(syncMessage(result));
+        }
+        else {
+            console.error(syncMessage(result));
+            process.exit(1);
+        }
+        return;
+    }
+    if (command === "sync-map") {
+        const { syncCodeMap } = await import("./code-map.js");
+        const { readConfig } = await import("./config.js");
+        const apiKey = readConfig().key;
+        if (!apiKey)
+            process.exit(0); // silent fail in hook context
+        await syncCodeMap(apiKey);
+        return;
+    }
+    if (command === "session-start") {
+        const { sessionStart } = await import("./session-start.js");
+        const { readConfig } = await import("./config.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : readConfig().key;
+        const agentIdx = args.indexOf("--agent");
+        const agent = agentIdx !== -1 ? args[agentIdx + 1] : undefined;
+        if (!apiKey)
+            return process.exit(0); // silent fail in hook context
+        await sessionStart(apiKey, { agent });
         return;
     }
     if (command === "post-commit") {
@@ -92,18 +135,23 @@ async function main() {
         runConfigCommand(args.slice(1));
         return;
     }
-    if (command === "kos") {
-        const { kos } = await import("./kos.js");
+    if (command === "agent" || command === "kos") {
+        const { runAgent, RENAMED_NOTE } = await import("./agent.js");
+        if (command === "kos")
+            console.error(RENAMED_NOTE);
         const { readConfig } = await import("./config.js");
         const keyIdx = args.indexOf("--key");
         const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : readConfig().key;
-        if (!apiKey) {
+        const specIdx = args.indexOf("--spec");
+        const spec = specIdx !== -1 ? args[specIdx + 1] : undefined;
+        // A local spec is read from disk, so it needs no key
+        if (!apiKey && !spec) {
             console.error("No API key. Pass --key YOUR_KEY or store it: xkg config set key YOUR_KEY");
             process.exit(1);
         }
         const planIdx = args.indexOf("--plan");
         const plan = planIdx !== -1 ? args[planIdx + 1] : undefined;
-        await kos(apiKey, { plan });
+        await runAgent(apiKey ?? "", { plan, spec });
         return;
     }
     // Default: open the hosted app
@@ -121,6 +169,13 @@ async function main() {
     const openCmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
     exec(`${openCmd} ${HOSTED_URL}`);
 }
+function syncMessage(result) {
+    if (result.status === "synced" || result.status === "unchanged")
+        return `Synced ${result.repo}: ${result.files} files`;
+    if (result.status === "skipped")
+        return `Code map not synced: ${result.reason}`;
+    return `Code map not synced${result.repo ? ` for ${result.repo}` : ""}: ${result.reason} Run \`xkg map\` to try again.`;
+}
 function printHelp() {
     console.log(`
   xkg — A knowledge graph for your AI workers
@@ -132,9 +187,14 @@ function printHelp() {
     xkg setup-hooks --key KEY --briefing                       Install full briefing hook (uses LLM)
     xkg setup-hooks --key KEY --vault                          Install vault hook (PreToolUse)
     xkg setup-hooks --key KEY --briefing --vault               Install both hooks
-    xkg setup-git-hook --key KEY                               Record commits with an xkg-capture trailer (any agent)
-    xkg config set agent "claude -p"                           Set which AI worker kos drives
-    xkg kos --key KEY [--plan FILE]                            Implement a plan in an isolated worktree
+    xkg setup-git-hook --key KEY                               Record commits with an xkg-capture trailer and keep the code map fresh (any agent);
+                                                               keeps .xkg/ (handoff specs) out of git
+    xkg map [--key KEY]                                        Send this repo's code map now (file paths and exported names, never code)
+    xkg session-start [--agent NAME]                           For an agent's session-start hook: offer captures waiting for this repo, else new ones
+                                                               (NAME: claude, codex, gemini, copilot, cursor; else plain text)
+    xkg config set agent "claude -p"                           Set which AI worker xkg agent drives
+    xkg agent --key KEY [--plan FILE]                          Implement a plan in an isolated worktree
+    xkg agent --spec PATH                                      Apply a handoff spec your agent wrote (.xkg/handoffs/) in an isolated worktree
     xkg help                                                   Show this help
 
     npx -y @xmu-labs/xkg@latest …                              Same CLI, via the published package
@@ -147,12 +207,12 @@ function printHelp() {
     apply_stats       — Captures applied per week, and how many came with a commit
     curate            — Validate URLs and flag stale captures
 
-  kos — implement plans with your own AI worker (model-agnostic):
+  xkg agent — implement plans with your own AI worker (model-agnostic):
     1. Tell xkg which assistant to drive (once):
          xkg config set agent "claude -p"      # or "codex exec", "aider --yes --message"
     2. Generate a plan via the generate_plan MCP tool.
-    3. Run: xkg kos --key YOUR_KEY
-       kos creates an isolated git worktree, hands the plan to your assistant,
+    3. Run: xkg agent --key YOUR_KEY
+       It creates an isolated git worktree, hands the plan to your assistant,
        and reports the branch + the plan's Verification Checklist when done.
 
   Get started:

package/dist/cli/session-start.js

@@ -0,0 +1,73 @@
+import { execFileSync } from "child_process";
+import { callMcp, initializeMcp } from "./hooks.js";
+import { repoFromRemote } from "./code-map.js";
+/** The name this command's MCP session carries, so the server can tell where a session began. */
+export const SESSION_START_CLIENT = "xkg-session-start";
+/**
+ * How each agent's SessionStart hook reads added context. Agents not listed
+ * here get plain text, which Claude Code and Codex also accept.
+ */
+const FORMATS = {
+    claude: hookSpecificOutput,
+    codex: hookSpecificOutput,
+    gemini: hookSpecificOutput,
+    copilot: (text) => ({ additionalContext: text }),
+    cursor: (text) => ({ additional_context: text }),
+};
+function hookSpecificOutput(text) {
+    return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: text } };
+}
+function message(count) {
+    const ask = count === 1
+        ? "You have 1 new xkg capture. Want to see it and apply it here?"
+        : `You have ${count} new xkg captures. Want to see them and apply one here?`;
+    return (`xkg: ${count} new capture${count === 1 ? "" : "s"} in the user's inbox.\n` +
+        `Before starting the user's task, ask them: "${ask}"\n` +
+        "If they say yes, call the xkg `briefing` tool with this repo's name, branch and last few commit messages, " +
+        "then check each candidate against the code before suggesting where it applies.");
+}
+/** `owner/name` of the repo at `cwd` from its origin remote, or null outside a repo or without an origin. */
+export function currentRepo(cwd = process.cwd()) {
+    try {
+        const url = execFileSync("git", ["remote", "get-url", "origin"], { cwd, encoding: "utf-8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] });
+        return repoFromRemote(url);
+    }
+    catch {
+        return null;
+    }
+}
+/** What the server's briefing starts with when captures wait for the repo. */
+const OFFER_PREFIX = "xkg: ";
+/**
+ * Runs from any agent's SessionStart hook. In a repo with captures waiting for
+ * it (HANDOFFS.md), prints the server's offer as is, so the hook and a briefing
+ * call give the same words. Otherwise counts new captures and, when there are
+ * some, prints the question the agent should ask. Either way shaped for that
+ * agent. Never fails or delays a session for long: on any error it prints nothing.
+ */
+export async function sessionStart(apiKey, opts = {}) {
+    // One limit for the whole command, so a hung server can't hold the session twice as long.
+    const deadline = Date.now() + (opts.timeoutMs ?? 3000);
+    const remaining = () => Math.max(1, deadline - Date.now());
+    try {
+        const session = await initializeMcp(apiKey, SESSION_START_CLIENT, remaining())
+            .then((res) => (res.ok ? res.headers.get("mcp-session-id") : null))
+            .catch(() => null);
+        const format = opts.agent ? FORMATS[opts.agent] : undefined;
+        const print = (body) => process.stdout.write((format ? JSON.stringify(format(body)) : body) + "\n");
+        const repo = opts.repo === undefined ? currentRepo() : opts.repo;
+        if (repo) {
+            const offer = await callMcp(apiKey, "briefing", { repo }, remaining(), session).catch(() => null);
+            if (offer?.startsWith(OFFER_PREFIX))
+                return void print(offer);
+        }
+        const text = await callMcp(apiKey, "list_inbox", {}, remaining(), session);
+        const count = parseInt(text?.match(/^(\d+)\s+capture/)?.[1] ?? "0", 10);
+        if (count <= 0)
+            return;
+        print(message(count));
+    }
+    catch {
+        // Silent fail: never interrupt a session start
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mnemos-capture",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "xkg — Turn what you discover into context your AI workers can use. Capture once, then brief, plan, and execute with any MCP-compatible tool.",
   "type": "module",
   "bin": {