@misaka-net/misakanet-setup 0.5.3 → 0.5.5

package/hook/checkpoint_reminder.mjs

@@ -21,6 +21,7 @@
  *   echo '{"session_id":"demo"}' | node checkpoint_reminder.mjs prompt
  */
 import { writeFileSync, mkdirSync, renameSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 
@@ -69,11 +70,20 @@ function parsePayload(raw) {
 }
 
 function sessionKey(payload) {
+  // An explicit key wins: the same value the strategy below would derive, but chosen by the user or
+  // by an agent that knows its own conversation boundaries.
+  const pinned = (process.env.MISAKANET_SESSION_KEY || '').trim();
+  if (pinned) return pinned.slice(0, 64);
   for (const key of ['session_id', 'sessionId', 'session', 'thread_id', 'conversation_id']) {
     const value = payload[key];
     if (typeof value === 'string' && value.trim()) return value.trim().slice(0, 64);
   }
-  return 'default';
+  // No session id at all used to fall back to the single name `default`, so every agent on the
+  // machine that does not report one shared *one* turn counter: agent A's twentieth turn fired the
+  // checkpoint in agent B's session and B never saw its own reminder (2026-09-18 review, 意见 9).
+  // Deriving the key from the working directory keeps one counter per project, which is the closest
+  // thing to "this conversation" that a hook can see without an id — and it is stable across turns.
+  return `default-${createHash('sha1').update(process.cwd()).digest('hex').slice(0, 8)}`;
 }
 
 function statePath(session) {
@@ -277,7 +287,11 @@ function promptMode(payload) {
     '1) 挑出本会话真正值得复用的「失败→根因→修复→验证」；门槛：可泛化、有可跑判据、且先 ' +
     'misakanet_search 确认语料里没有重复（有就引用其 id，不要另写一篇）。\n' +
     '2) 脱敏：密钥/token/凭据 → <REDACTED>；人名/邮箱/真实域名/绝对家目录 → 泛化成 ~/project、example.com；' +
-    '不要粘会话转录或整段工具输出。\n' +
+    // The "内部业务细节抽象成结构性描述" clause is the Python hook's wording, which is the one that
+    // carries it (added 2026-09-14, `2af7a41df`). The two hooks had drifted here and nothing
+    // compared them; `tests/test_agent_autostart_parity.py` now does, and this line was its first
+    // find. The stronger clause wins: it is a redaction rule, and the weaker copy was the Node one.
+    '不要粘会话转录或整段工具输出；内部业务细节抽象成结构性描述。\n' +
     '3) 提交（无需 token）：misakanet_submit_intake(kind="missing_lesson", problem="## Problem\\n…\\n\\n' +
     '## Root Cause\\n…\\n\\n## Solution\\n…\\n\\n## Verification\\n…")；若这条其实是「问题」而非经验，' +
     '用 kind="question"；若确实不够泛化/价值不高 → 不提交。\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misaka-net/misakanet-setup",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "One-command setup: teach your Claude Code / Codex / Hermes / OpenClaw / codewhale to search MisakaNet failure lessons before repeating a mistake, and to distil the session at a checkpoint.",
   "bin": {
     "misakanet-setup": "bin/misakanet-setup.mjs"

package/voice/voice-hook.mjs

@@ -1,36 +1,103 @@
 #!/usr/bin/env node
 /**
- * MisakaNet voice hook — play the cue a tool result asked for.
+ * MisakaNet attention hook — route the cue a tool result asked for to a sound and/or a
+ * desktop notification.
  *
  * The MCP server already answers with a `voice` field (`lesson-found` when a search hit,
  * `failure-warning` when it did not, `connect-success` for a lesson, `pair-success` for a
- * usage receipt). This hook turns that field into a sound. It is registered as a Claude Code
- * `PostToolUse` hook by `npx @misaka-net/misakanet-setup --voice`, and it is *opt-in*: nobody
- * wants an assistant that starts talking on its own.
+ * usage receipt). This hook turns that field into attention: a sound, and — because the
+ * *model* cannot see that a tool ran and neither can the human watching — a short desktop
+ * notification. It is registered as a Claude Code `PostToolUse` hook by
+ * `npx @misaka-net/misakanet-setup --voice`, and it is *opt-in*: nobody wants an assistant
+ * that starts talking on its own.
  *
  * Why Node and not the older shell script: that one parses stdin with `python`, and `python`
  * is not on PATH on many Linux/WSL boxes (`python3` is) — this repo has that exact bug on
  * record. Node is guaranteed here: the installer itself runs on it.
  *
  * Rules it must never break:
- * - **never block the agent**: the player is spawned detached and the process exits
- *   immediately, with a hard timeout as a backstop;
- * - **never fail loudly**: a missing player, a missing MP3 or unparsable stdin all end in
- *   exit 0 with no output, because a hook that prints to stderr can show up as a tool error;
- * - **be silent when asked**: `MISAKANET_VOICE=0` mutes it even after it is installed.
+ * - **never block the agent**: players and notifiers are spawned detached and the process
+ *   exits immediately, with a hard timeout as a backstop;
+ * - **never fail loudly**: a missing player, a missing notification binary, a missing MP3,
+ *   an unwritable state file or unparsable stdin all end in exit 0 with no output, because a
+ *   hook that prints to stderr can show up as a tool error;
+ * - **be silent when asked**: `MISAKANET_VOICE=0` mutes sound *and* notifications even after
+ *   it is installed, and `MISAKANET_NOTIFY=0` turns off only the notifications;
+ * - **never execute anything derived from server input**: see the table below.
  *
  * Test/debug affordances:
- * - `MISAKANET_VOICE_DRY_RUN=1` prints the cue name instead of playing it (that is what the
- *   test suite uses, so CI never needs an audio device);
- * - `MISAKANET_VOICE_DIR` overrides where the MP3s live.
+ * - `MISAKANET_VOICE_DRY_RUN=1` prints the cue name and what the hook *would* do — sound and
+ *   notification — while executing nothing (that is what the test suite uses, so CI never
+ *   needs an audio device or a desktop session);
+ * - `MISAKANET_VOICE_DEBUG=1` prints one line per real run: cue, player, file, notification;
+ * - `MISAKANET_VOICE_DIR` overrides where the MP3s live;
+ * - `MISAKANET_HOOK_STATE` (shared with `checkpoint_reminder.mjs`) overrides the state
+ *   directory that holds the "already notified once" ledger.
  */
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
-const CUES = ['connect-success', 'pair-success', 'lesson-found', 'failure-warning'];
+
+/**
+ * THE TABLE — the single place a cue name turns into something this process does.
+ *
+ * ─── HARD SECURITY RULE (issue #1785) ──────────────────────────────────────────────────
+ * The cue is **server-supplied** and is used for exactly one thing: as a *key* into this
+ * table. It is never concatenated into a command line, never concatenated into a path,
+ * never handed to a shell, and never passed as an argument to any process. Every executable
+ * name, every argument, every MP3 file name and every notification text executed by this
+ * hook is a literal written in this file.
+ *
+ * An unknown cue — including `rm -rf /`, a cue full of `;`/`$()`/backticks, or a 5000
+ * character cue — matches no key, so there is no action: the hook exits 0 having done
+ * nothing at all, and reaches no binary. `workers/agent-autostart-hook.test.mjs` asserts
+ * this by running the hook with a stubbed PATH (every player and notifier replaced by a
+ * recording stub) and requiring the recording to stay empty.
+ * ──────────────────────────────────────────────────────────────────────────────────────
+ *
+ * Three more decisions worth stating:
+ * - `sound` is the MP3 **file name, spelled out**, rather than `${cue}.mp3`: the file name is
+ *   then not built out of server input either, so there is no interpolation left to argue
+ *   about.
+ * - `once: true` means "notify only the first time this cue is seen on this machine". Both
+ *   success cues repeat on every single call (a lesson fetch, a receipt), and a toast per
+ *   call is exactly the noise that makes people mute the whole feature; the ledger that
+ *   remembers this lives in the state directory (see `ledgerMark`).
+ * - `notify: ''` for `failure-warning` is deliberate: "no lesson found" is a *negative*
+ *   result the agent is already telling the user about, and it happens on every empty
+ *   search — a notification there buys nothing and costs attention. Sound only, as the
+ *   issue's acceptance criteria require. The issue drafted 「MisakaNet：未找到相关经验，已记录」
+ *   for it; that string is deliberately not wired to anything, and is recorded here only so
+ *   a future translation pass knows it was considered and dropped.
+ */
+const CUE_ACTIONS = Object.freeze({
+  'lesson-found': Object.freeze({
+    sound: 'lesson-found.mp3',
+    notify: 'MisakaNet：找到一条相关经验',
+    once: false,
+  }),
+  'failure-warning': Object.freeze({
+    sound: 'failure-warning.mp3',
+    notify: '',                                   // sound only — see above
+    once: false,
+  }),
+  'connect-success': Object.freeze({
+    sound: 'connect-success.mp3',
+    notify: 'MisakaNet：已连接',
+    once: true,
+  }),
+  'pair-success': Object.freeze({
+    sound: 'pair-success.mp3',
+    notify: 'MisakaNet：已连接',
+    once: true,
+  }),
+});
+
+const CUES = Object.keys(CUE_ACTIONS);
 
 /**
  * Find the first cue name anywhere in the payload.
@@ -81,9 +148,18 @@ function parseCue(raw) {
       /* try the next shape */
     }
   }
-  // Last resort: a bare cue name on the line, so a hand-rolled hook still works.
-  const bare = trimmed.match(new RegExp(`\\b(${CUES.join('|')})\\b`));
-  return bare ? bare[1] : '';
+  // Last resort: a bare cue name on its own line, so a hand-rolled hook still works.
+  //
+  // The whole line must *be* the cue name. A fuzzy "contains a cue name" match would mean a
+  // hostile string like `lesson-found; notify-send pwned` routes to the legitimately-tabled
+  // `lesson-found` action: no injection happens either way (the action comes from the table),
+  // but "a cue we did not send triggers an action" is not a contract worth keeping. An exact
+  // match is also what lets the security test below demand *no* action for hostile input.
+  for (const line of trimmed.split('\n')) {
+    const bare = line.trim();
+    if (CUES.includes(bare)) return bare;
+  }
+  return '';
 }
 
 /** The path Windows needs, for the WSL case. */
@@ -152,32 +228,215 @@ function play(file) {
   return '';
 }
 
-function main() {
-  if (process.env.MISAKANET_VOICE === '0') return;
-  const cue = parseCue(readStdin());
-  if (!cue) return;
+/**
+ * Where the "already notified once" ledger lives.
+ *
+ * The installer already owns `~/.misakanet-agent/` (it writes the version stamp and
+ * checkpoints state there), so the voice hook writes its one small file in the same place
+ * instead of inventing a second home-directory convention. `MISAKANET_HOOK_STATE` is the
+ * same override `checkpoint_reminder.mjs` honours, which is also how the test suite keeps
+ * these files out of a developer's real home.
+ */
+const AGENT_DIR = process.env.MISAKANET_AGENT_DIR || join(homedir(), '.misakanet-agent');
+const STATE_DIR = process.env.MISAKANET_HOOK_STATE || join(AGENT_DIR, 'state');
+const NOTIFY_LEDGER = join(STATE_DIR, 'voice-notified.json');
 
-  if (process.env.MISAKANET_VOICE_DRY_RUN === '1') {
-    process.stdout.write(`${cue}\n`);
-    return;
+function ledgerRead() {
+  try {
+    const raw = JSON.parse(readFileSync(NOTIFY_LEDGER, 'utf8'));
+    return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  } catch {
+    return {};                            // missing or unreadable: nothing has been announced
+  }
+}
+
+/**
+ * Remember that `cue` has been announced, atomically (temp file + rename, so a hook killed
+ * mid-write cannot leave half a JSON file behind).
+ *
+ * Every failure here is swallowed on purpose: this is bookkeeping for a courtesy, and a
+ * read-only home directory must not be able to turn a desktop notification into a tool
+ * error. The worst case of a lost write is one extra toast after a reboot.
+ *
+ * The key is always a key of `CUE_ACTIONS` (see the security rule there) — never raw input.
+ */
+function ledgerMark(cue) {
+  try {
+    mkdirSync(dirname(NOTIFY_LEDGER), { recursive: true });
+    const next = { ...ledgerRead(), [cue]: new Date().toISOString() };
+    const tmp = `${NOTIFY_LEDGER}.tmp`;
+    writeFileSync(tmp, JSON.stringify(next));
+    renameSync(tmp, NOTIFY_LEDGER);
+  } catch {
+    /* never break the agent over bookkeeping */
+  }
+}
+
+/**
+ * Is `name` an executable we can actually run? (A plain PATH walk — never `which`, because
+ * spawning a shell to answer "does X exist" is the execution surface this hook must not
+ * have.)
+ *
+ * Deliberate, rather than spawn-and-swallow-the-ENOENT: a machine with no notifier at all
+ * then forks nothing on every tool call, and the debug/dry-run line can name the notifier it
+ * really would use instead of guessing. `name` always comes from the code table below.
+ */
+function findExecutable(name) {
+  const path = process.env.PATH || '/usr/local/bin:/usr/bin:/bin';
+  for (const entry of path.split(delimiter)) {
+    const dir = entry.trim().replace(/^"(.*)"$/, '$1');
+    if (!dir) continue;
+    try {
+      accessSync(join(dir, name), constants.X_OK);
+      return join(dir, name);
+    } catch {
+      /* keep looking */
+    }
   }
+  return '';
+}
 
-  // The cues sit next to the player when it is installed (…/voice/), next to the canonical
-  // copy in a repo checkout, or under docs/assets/voice/ there. Getting this wrong is silent
-  // by design — which is exactly how the first version of this file shipped mute.
+/**
+ * The notifier candidates for *this* platform, in preference order.
+ *
+ * Every binary name and every argument below is a literal; the only thing that varies is the
+ * message text, which is a literal in `CUE_ACTIONS`. Nothing in this function looks at the
+ * cue — that is the whole point of the table.
+ *
+ * - **macOS**: `osascript -e 'display notification "…" with title "MisakaNet"'`.
+ * - **Linux**: `notify-send -a MisakaNet <text>` (the freedesktop notifier every desktop
+ *   environment ships).
+ * - **Windows / WSL**: PowerShell. The real WinRT toast API
+ *   (`Windows.UI.Notifications.ToastNotificationManager`) needs a registered AppID — a
+ *   Start-menu shortcut with the right AUMID — and on a clean machine it fails with
+ *   "Element not found", which a hook can only swallow. The dependency-free call that does
+ *   work from a bare `powershell.exe` is a `NotifyIcon` balloon, which Windows 10/11 renders
+ *   through the same Action Center; that is the documented fallback. On WSL the Windows side
+ *   goes **first**, exactly like the player, because the Linux side of WSL usually has no
+ *   notification daemon to talk to (and, as `players` records, no usable audio card either).
+ *
+ * `powershell.exe` over argv carries the message text; PowerShell single quotes are escaped
+ * by doubling, and the string itself is a constant from the table.
+ */
+function notifiers(text) {
+  const winText = `'${text.replace(/'/g, "''")}'`;
+  const powershell = [
+    'powershell.exe',
+    [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      'Add-Type -AssemblyName System.Windows.Forms;'
+        + 'Add-Type -AssemblyName System.Drawing;'
+        + '$n = New-Object System.Windows.Forms.NotifyIcon;'
+        + '$n.Icon = [System.Drawing.SystemIcons]::Information;'
+        + "$n.BalloonTipTitle = 'MisakaNet';"
+        + `$n.BalloonTipText = ${winText};`
+        + '$n.Visible = $true; $n.ShowBalloonTip(5000);'
+        + 'Start-Sleep -Seconds 6; $n.Dispose()',
+    ],
+  ];
+  const candidates = [];
+  if (isWsl() || process.platform === 'win32') candidates.push(powershell);
+  if (process.platform === 'darwin') {
+    const escaped = text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    candidates.push(['osascript', ['-e', `display notification "${escaped}" with title "MisakaNet"`]]);
+  }
+  if (process.platform === 'linux') candidates.push(['notify-send', ['-a', 'MisakaNet', text]]);
+  return candidates;
+}
+
+/**
+ * Best-effort desktop notification. Returns the binary that was used, or ''.
+ *
+ * Missing binary, missing platform, denied dbus, a `spawn` throw — all of them mean "no
+ * notification happened", which is a silent outcome by design: this hook must never print an
+ * error that surfaces as a tool failure in the middle of someone's session.
+ */
+function notify(text) {
+  for (const [cmd, args] of notifiers(text)) {
+    if (!findExecutable(cmd)) continue;
+    try {
+      const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+      child.on('error', () => {});
+      child.unref();
+      return cmd;
+    } catch {
+      /* try the next notifier */
+    }
+  }
+  return '';
+}
+
+/**
+ * The MP3 for a table entry, or ''.
+ *
+ * The cues sit next to the player when it is installed (…/voice/), next to the canonical
+ * copy in a repo checkout, or under docs/assets/voice/ there. Getting this wrong is silent
+ * by design — which is exactly how the first version of this file shipped mute. `name` is a
+ * literal from `CUE_ACTIONS`, never the cue.
+ */
+function cueFile(name) {
   const dirs = [
     process.env.MISAKANET_VOICE_DIR,
     HERE,
     join(HERE, 'voice'),
     join(HERE, '..', '..', 'docs', 'assets', 'voice'),
   ].filter(Boolean);
-  const file = dirs.map((dir) => join(dir, `${cue}.mp3`)).find((candidate) => existsSync(candidate));
-  if (!file) return;
-  const used = play(file);
-  if (process.env.MISAKANET_VOICE_DEBUG === '1') {
+  return dirs.map((dir) => join(dir, name)).find((candidate) => existsSync(candidate)) || '';
+}
+
+function main() {
+  // One switch silences both halves: sound *and* notifications.
+  if (process.env.MISAKANET_VOICE === '0') return;
+  const cue = parseCue(readStdin());
+  if (!cue) return;
+
+  // ── the cue's only use, right here: a table lookup ────────────────────────────────
+  const action = CUE_ACTIONS[cue];
+  if (!action) return;               // unreachable (parseCue only returns table keys), and
+                                     // keeping it explicit is what makes the rule total:
+                                     // no table entry ⇒ no action, no process, no path.
+  const dryRun = process.env.MISAKANET_VOICE_DRY_RUN === '1';
+  const notifyAllowed = process.env.MISAKANET_NOTIFY !== '0';
+  const debug = process.env.MISAKANET_VOICE_DEBUG === '1';
+
+  // ── sound ────────────────────────────────────────────────────────────────────────
+  const file = cueFile(action.sound);
+  const would = file ? `sound=${action.sound} (would play)` : `sound=${action.sound} (missing — would be silent)`;
+  const player = dryRun || !file ? '' : play(file);
+
+  // ── notification ─────────────────────────────────────────────────────────────────
+  let note;
+  if (!action.notify) {
+    note = 'none (this cue does not notify)';
+  } else if (!notifyAllowed) {
+    note = 'disabled (MISAKANET_NOTIFY=0)';
+  } else {
+    const seen = action.once ? ledgerRead()[cue] : '';
+    if (seen) {
+      note = `already sent at ${seen} (first time only)`;
+    } else if (dryRun) {
+      note = `would send "${action.notify}"${action.once ? ' (first time only)' : ''}`;
+    } else {
+      const used = notify(action.notify);
+      // Marked even when no notifier was available: otherwise a machine without one would
+      // retry the lookup on every single tool call forever, for a toast nobody can see.
+      if (action.once) ledgerMark(cue);
+      note = used ? `${used} "${action.notify}"` : 'none (no notifier available on this platform)';
+    }
+  }
+
+  if (dryRun) {
+    // Reports both halves and executes neither. Read-only on purpose: a preview must not
+    // consume the one-time notification or write a ledger a real run would then trust.
+    process.stdout.write(`${cue}\n${would}\nnotify=${note}\n`);
+    return;
+  }
+  if (debug) {
     // Synchronous write: process.exit(0) below would truncate an async stdout write, and a
     // hook that prints on the normal path can look like a tool failure.
-    writeFileSync(1, `cue=${cue} player=${used || 'none'} file=${file}\n`);
+    writeFileSync(1, `cue=${cue} player=${player || 'none'} file=${file || 'none'} notify=${note}\n`);
   }
 }
 
@@ -185,10 +444,28 @@ try {
   main();
 } catch {
   /* a hook must never surface as a tool failure */
-} finally {
-  process.exit(0);
 }
 
-// Backstop: if a detached player leaves this process alive (some players keep a handle),
-// leave anyway. The sound is best-effort by design.
-setTimeout(() => process.exit(0), 3000).unref();
+// Exit on the next tick rather than through `process.exit(0)` *in* the finally above.
+//
+// The old shape was:
+//
+//     } finally { process.exit(0); }
+//     setTimeout(() => process.exit(0), 3000).unref();   // ← unreachable, every run
+//
+// `process.exit` ends the process before the backstop line is ever evaluated, so the safety net
+// for "a detached player kept a handle open" had never run — dead code that read like protection.
+// (Found by the 2026-09-18 setup review; verified by reading the tail of this file, which is also
+// why the package's `voice/voice-hook.mjs` copy is regenerated by `prepack`.)
+//
+// Why not just `process.exitCode = 0` with no exit call at all: the debug line above is written with
+// `writeFileSync(1, …)` precisely so it cannot be truncated, and this process must not stay alive
+// waiting on a spawned player — the agent is waiting for the hook to return. `setImmediate` keeps
+// stdout draining for one tick while still ending the process deterministically, and the timer is
+// the real backstop for a handle the spawn left behind.
+setImmediate(() => {
+  setTimeout(() => process.exit(0), 3000).unref();
+  // If the loop is otherwise empty, `unref`ed timers do not hold it open, so Node exits by itself
+  // within this tick — the timer only matters when something else is still keeping us alive.
+  process.exitCode = 0;
+});