mirror-mind 0.0.1 → 0.32.1

package/ts/src/hooks/claude.ts

@@ -0,0 +1,176 @@
+// Claude Code hook entries (CV22.DS10.TS5 plateau 1, decision D4).
+//
+// Replaces the bodies of `.claude/hooks/*.sh` and the identical set under
+// `plugins/mirror-mind/hooks/`, which spawned the Python interpreter for the
+// core's CLI, for two hook modules, and for an inline import of the
+// conversation logger's `hook_user_prompt` -- the last two reaching into
+// modules that were never commands, and so never in DS7's denominator.
+//
+// Behavior is preserved case for case, including the cases that look like
+// bugs and are not: a skill invocation is still logged (Claude's hook fires
+// for every prompt and the logger decides), a missing session id still fails
+// loud, and every failure is still non-fatal to the user's turn.
+
+import { resolveDbPath } from "#frontDoor/dbPath.ts";
+import { openLiveWriteDatabase } from "#frontDoor/liveBackup.ts";
+import { markInjected, needsInject, readMirrorState } from "./mirrorState.ts";
+import { parseHookPayload, readStdin } from "./payload.ts";
+import {
+  noteHookFailure,
+  operatingInstructionsFor,
+  runFrontDoor,
+  runFrontDoorQuietly,
+  sessionStartOutput,
+} from "./runtime.ts";
+
+/**
+ * `session-start.sh`: make sure logging is on for this session, and hand
+ * Claude Code the Operating Instructions unless the project it opened in is
+ * this same tree (US3, D13 -- `operatingInstructionsFor`). The plugin in
+ * Claude Code's cache delivers them this way; the checkout's own wrappers
+ * find the project already carrying the file and stay quiet, as before.
+ */
+export async function claudeSessionStart(env: NodeJS.ProcessEnv = process.env): Promise<number> {
+  await runFrontDoorQuietly("claude:session-start", ["conversation-logger", "session-start"]);
+  process.stdout.write(
+    sessionStartOutput(operatingInstructionsFor("claude:session-start", env.CLAUDE_PROJECT_DIR)),
+  );
+  return 0;
+}
+
+/**
+ * `log-user-prompt.sh`: record the user's turn.
+ *
+ * The shell piped stdin into `hook_user_prompt()`. The front door already owns
+ * that surface -- `conversation-logger user-prompt` is one of its two
+ * stdin-reading subcommands -- so the payload is handed straight to it rather
+ * than re-parsed here.
+ */
+export async function claudeUserPrompt(): Promise<number> {
+  // stdin is deliberately NOT consumed here: the route reads it itself, so
+  // handing it the payload means not reading it first.
+  await runFrontDoorQuietly("claude:user-prompt", ["conversation-logger", "user-prompt"]);
+  return 0;
+}
+
+/** `log-session-end.sh`: close the session, then take the silent backup. */
+export async function claudeSessionEnd(): Promise<number> {
+  await runFrontDoorQuietly("claude:session-end", ["conversation-logger", "session-end"]);
+  await runFrontDoorQuietly("claude:session-end", ["backup", "--silent"]);
+  return 0;
+}
+
+/**
+ * `mirror-inject.sh`: inject identity context before the model answers.
+ *
+ * Two cases, exactly as the shell had them:
+ *
+ *   1. an explicit `/mm:mirror [query]` -- load context for that query;
+ *   2. Mirror Mode already active for this session with context not yet
+ *      injected -- load it with the session's persona and journey, then mark
+ *      it injected so it happens once.
+ *
+ * `--context-only` matters in both: it loads context WITHOUT starting a
+ * conversation session, because the model does that. A hook that silently
+ * opened conversations would fork every session in two.
+ */
+export async function claudeInject(stdin: string): Promise<number> {
+  const payload = parseHookPayload(stdin);
+  const sessionId = payload.sessionId;
+
+  // Case 1: the explicit invocation.
+  if (/^\/mm:mirror/.test(payload.prompt)) {
+    const query = payload.prompt.replace(/^\/mm:mirror\s*/, "");
+    const argv = ["mirror", "load", "--context-only", "--query", query];
+    if (sessionId) argv.push("--session-id", sessionId);
+    const result = await runFrontDoor(argv);
+    if (result.stdout.trim()) process.stdout.write(result.stdout);
+    return 0;
+  }
+
+  // Case 2: active Mirror Mode owed an injection.
+  if (!sessionId) {
+    // Python's `mirror_state` warned on stderr rather than no-op'ing silently,
+    // so a hook wired without a session id is visible. Kept: it is the
+    // difference between "Mirror Mode is off" and "this hook is misconfigured".
+    process.stderr.write("warning: mirror inject hook received no session_id; no state read.\n");
+    return 0;
+  }
+
+  let dbPath: string;
+  try {
+    dbPath = resolveDbPath([], process.env);
+  } catch (error) {
+    noteHookFailure("claude:inject", error instanceof Error ? error.message : String(error));
+    return 0;
+  }
+
+  const state = readMirrorState(dbPath, sessionId);
+  if (!needsInject(state)) return 0;
+
+  const argv = [
+    "mirror",
+    "load",
+    "--context-only",
+    "--query",
+    payload.prompt,
+    "--session-id",
+    sessionId,
+  ];
+  if (state.persona) argv.push("--persona", state.persona);
+  if (state.journey) argv.push("--journey", state.journey);
+
+  const result = await runFrontDoor(argv);
+  if (!result.stdout.trim()) return 0;
+
+  process.stdout.write(result.stdout);
+  // Only after the context actually reached the model: the shell marked it
+  // inside `if [ -n "$CONTEXT" ]` for the same reason. Marking first would
+  // lose the injection whenever the load produced nothing.
+  try {
+    // The sanctioned live-write path: a verified pre-write snapshot, same as
+    // every other routed write.
+    //
+    // Python's `mark_injected` wrote UNGATED, so this adds a `VACUUM INTO`
+    // that the old hook did not pay. Measured on a real 53 MB database:
+    // **95 ms**, once per Mirror Mode session -- only the single prompt that
+    // owes an injection reaches this line, and that turn is already loading
+    // identity and memories. The ordinary turn returns above without opening
+    // a writable handle at all (114 ms end to end, nothing written).
+    //
+    // Paying the front door's own safety contract for a real write to a real
+    // user database beat inventing a second narrowed write handle inside a
+    // deletion story. Recorded with the number so the trade is visible.
+    //
+    // This hook runs AT THE SAME TIME as `log-user-prompt`, which writes too.
+    // Until finding F21 the two snapshots collided on one fixed file and one
+    // write was lost -- in the Navigator walk, two injections in three
+    // prompts. `openLiveWriteDatabase` gives each writer its own staging
+    // snapshot, so concurrent hooks no longer race.
+    const db = openLiveWriteDatabase(dbPath);
+    try {
+      markInjected(db, sessionId, new Date().toISOString());
+    } finally {
+      db.close();
+    }
+  } catch (error) {
+    noteHookFailure("claude:inject", error instanceof Error ? error.message : String(error));
+  }
+  return 0;
+}
+
+export async function claudeHook(name: string): Promise<number> {
+  switch (name) {
+    case "session-start":
+      return claudeSessionStart();
+    case "user-prompt":
+      return claudeUserPrompt();
+    case "session-end":
+      return claudeSessionEnd();
+    case "inject":
+      return claudeInject(readStdin());
+    default:
+      noteHookFailure("claude", `unknown hook: ${name}`);
+      return 0;
+  }
+}

package/ts/src/hooks/codex.ts

@@ -0,0 +1,45 @@
+// Codex hook entries (CV22.DS10.TS5 handoff review, finding N3).
+//
+// Codex has no hook system, so `scripts/codex-mirror.sh` wraps the `codex`
+// command itself and calls these through two generated wrappers under
+// `scripts/codex-hooks/`. Until the handoff review the script called the front
+// door directly: it found `node` on PATH alone, silenced every failure, and
+// built its command as a string that a checkout path with a space split in
+// two. Going through the wrappers gives it the same Node resolution and the
+// same hooks.log record as every other runtime.
+//
+// The payload comes as arguments, not stdin: the wrapper, not a runtime,
+// decides what to pass, and a path is safer as one quoted argument than
+// embedded in hand-written JSON.
+
+import { runFrontDoorQuietly } from "./runtime.ts";
+
+/** Wrapper start: make sure logging is on for this session. */
+export async function codexSessionStart(): Promise<number> {
+  await runFrontDoorQuietly("codex:session-start", ["conversation-logger", "session-start"]);
+  return 0;
+}
+
+/**
+ * Wrapper exit: import the session Codex wrote, close it, then take the silent
+ * backup. The transcript and its session id are both absent when Codex wrote
+ * no session for this directory; the backup runs either way, as it always has.
+ */
+export async function codexSessionEnd(transcriptPath: string, sessionId: string): Promise<number> {
+  if (transcriptPath && sessionId) {
+    await runFrontDoorQuietly("codex:session-end", [
+      "conversation-logger",
+      "backfill-codex-session",
+      transcriptPath,
+      "--interface",
+      "codex",
+    ]);
+    await runFrontDoorQuietly("codex:session-end", [
+      "conversation-logger",
+      "session-end-pi",
+      sessionId,
+    ]);
+  }
+  await runFrontDoorQuietly("codex:session-end", ["backup", "--silent"]);
+  return 0;
+}

package/ts/src/hooks/gemini.ts

@@ -0,0 +1,126 @@
+// Gemini CLI hook entries (CV22.DS10.TS5 plateau 1, decision D4).
+//
+// These hooks already entered the TypeScript front door for every Mirror
+// command -- the Python they carried was only inline interpreter one-liners
+// importing `sys` and `json`, to read a field out of the payload and to print
+// one back. Four spawns of an interpreter to parse JSON, in a Node process's
+// hook.
+//
+// The Gemini contract, preserved exactly:
+//   stdin  -- JSON: { session_id, prompt, ... }
+//   stdout -- JSON: { hookSpecificOutput: { additionalContext } } or {}
+//   stderr -- logs only; never parsed
+//
+// `GEMINI_SESSION_ID` still wins over the payload's `session_id`, because the
+// runtime sets it and the payload is the fallback.
+
+import { parseHookPayload } from "./payload.ts";
+import {
+  operatingInstructionsFor,
+  runFrontDoor,
+  runFrontDoorQuietly,
+  sessionStartOutput,
+} from "./runtime.ts";
+
+function sessionIdFrom(payloadSessionId: string, env = process.env): string {
+  return env.GEMINI_SESSION_ID || payloadSessionId;
+}
+
+/**
+ * BeforeAgent: log the user's turn, and inject context when Mirror Mode is on.
+ *
+ * A prompt starting with `/` is a skill invocation -- a command, not a
+ * conversational message -- and is not logged. That rule is Gemini-specific
+ * and stays; Claude's hook has no equivalent because its logger decides.
+ */
+export async function geminiLogUser(stdin: string): Promise<number> {
+  const payload = parseHookPayload(stdin);
+  const sessionId = sessionIdFrom(payload.sessionId);
+
+  if (payload.prompt.startsWith("/")) {
+    process.stdout.write("{}\n");
+    return 0;
+  }
+
+  if (payload.prompt && sessionId) {
+    await runFrontDoorQuietly("gemini:log-user", [
+      "conversation-logger",
+      "log-user",
+      sessionId,
+      payload.prompt,
+      "--interface",
+      "gemini_cli",
+    ]);
+  }
+
+  const context = await runFrontDoor([
+    "mirror",
+    "load",
+    "--context-only",
+    "--query",
+    payload.prompt,
+    "--session-id",
+    sessionId,
+  ]);
+
+  process.stdout.write(
+    context.stdout.trim()
+      ? `${JSON.stringify({ hookSpecificOutput: { additionalContext: context.stdout } })}\n`
+      : "{}\n",
+  );
+  return 0;
+}
+
+/** AfterAgent: record the assistant's turn. */
+export async function geminiLogAssistant(stdin: string): Promise<number> {
+  const payload = parseHookPayload(stdin);
+  const sessionId = sessionIdFrom(payload.sessionId);
+  if (payload.response && sessionId) {
+    await runFrontDoorQuietly("gemini:log-assistant", [
+      "conversation-logger",
+      "log-assistant",
+      sessionId,
+      payload.response,
+      "--interface",
+      "gemini_cli",
+    ]);
+  }
+  process.stdout.write("{}\n");
+  return 0;
+}
+
+/** SessionEnd: close the conversation for this session. */
+export async function geminiSessionEnd(stdin: string): Promise<number> {
+  const payload = parseHookPayload(stdin);
+  const sessionId = sessionIdFrom(payload.sessionId);
+  if (sessionId) {
+    await runFrontDoorQuietly("gemini:session-end", [
+      "conversation-logger",
+      "session-end-pi",
+      sessionId,
+    ]);
+  }
+  process.stdout.write("{}\n");
+  return 0;
+}
+
+/**
+ * SessionStart: unmute logging for the new session.
+ *
+ * Fires on startup, resume, and `/clear`. This wrapper was already free of
+ * Python -- it entered the front door directly -- but it is generated from the
+ * same template as the other eleven so it cannot drift away from them, which
+ * is the failure CR071 recorded for the skill copies.
+ */
+export async function geminiSessionStart(env: NodeJS.ProcessEnv = process.env): Promise<number> {
+  await runFrontDoorQuietly("gemini:session-start", ["conversation-logger", "session-start"]);
+  // US3, D13: the Operating Instructions as SessionStart context, unless the
+  // project is this tree -- the checkout's GEMINI/CLAUDE.md import the file.
+  process.stdout.write(
+    sessionStartOutput(
+      operatingInstructionsFor("gemini:session-start", env.GEMINI_PROJECT_DIR),
+      "{}\n",
+    ),
+  );
+  return 0;
+}

package/ts/src/hooks/main.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+// The single entry point every Mirror hook wrapper calls.
+//
+// CV22.DS10.TS5 plateau 1, decision D4. Twelve shell scripts across four
+// runtimes each spawned the interpreter one to five times per event. They now
+// run one Node process and name which hook they are:
+//
+//     node ts/src/hooks/main.ts claude:inject
+//
+// Arguments after the name are the hook's own; only the Codex wrapper passes
+// any, since Codex has no hook payload to read (`codex.ts`).
+//
+// One entry rather than one file per hook because the generated wrappers then
+// differ only in the hook name and their depth, and `hooks.test.ts` asserts
+// that -- copies that can differ in only one place cannot drift the way the
+// skill copies did (CR071, eleven skills, two runtimes wrong for months).
+//
+// Since CV22.DS10.US3 (D3, D5) the wrappers run this file through the
+// `mirror-hook` bin (`bin/mirror-hook.js`), and it reads configuration and
+// silences the sqlite warning itself, in `runAsEntry()`: the `--env-file`
+// and `--no-warnings` flags the wrappers used to pass could only ever point
+// at a checkout's `.env`, and an installed package has none.
+//
+// **A hook never fails the user's turn.** Every path returns 0 and every
+// failure is recorded in `<mirror-home>/hooks.log` instead. That was the
+// Python posture too (`2>/dev/null || true`), with one difference that
+// matters: silence there hid nothing, because `python3` is on every macOS.
+// Node is often absent from a GUI-launched runtime's PATH, so silence here
+// would hide a NEW failure -- which is why the wrappers write the log line
+// themselves when they cannot find a Node that runs this file. That is also
+// why this file must exit 0: the wrappers read any other exit as Node failing.
+
+import { pathToFileURL } from "node:url";
+import { loadConfiguration, silenceExperimentalWarnings } from "#runtime/config.ts";
+import { claudeHook } from "./claude.ts";
+import { codexSessionEnd, codexSessionStart } from "./codex.ts";
+import {
+  geminiLogAssistant,
+  geminiLogUser,
+  geminiSessionEnd,
+  geminiSessionStart,
+} from "./gemini.ts";
+import { readStdin } from "./payload.ts";
+import { noteHookFailure } from "./runtime.ts";
+
+async function dispatch(name: string, args: readonly string[]): Promise<number> {
+  const [runtime, hook] = name.split(":");
+
+  switch (runtime) {
+    case "claude":
+      return claudeHook(hook ?? "");
+    case "gemini":
+      switch (hook) {
+        case "log-user":
+          return geminiLogUser(readStdin());
+        case "log-assistant":
+          return geminiLogAssistant(readStdin());
+        case "session-end":
+          return geminiSessionEnd(readStdin());
+        case "session-start":
+          return geminiSessionStart();
+        default:
+          break;
+      }
+      break;
+    case "codex":
+      // Called by `scripts/codex-mirror.sh` through its generated wrappers.
+      switch (hook) {
+        case "session-start":
+          return codexSessionStart();
+        case "session-end":
+          return codexSessionEnd(args[0] ?? "", args[1] ?? "");
+        default:
+          break;
+      }
+      break;
+    default:
+      break;
+  }
+
+  noteHookFailure("hooks", `unknown hook name: ${name}`);
+  return 0;
+}
+
+/**
+ * What the entry does, for the two ways it is started: this file run directly
+ * (a checkout), or the `bin/mirror-hook.js` shim (D15). Configuration and the
+ * warning filter run here and nowhere else, so importing this module does
+ * neither.
+ */
+export async function runAsEntry(rawArgv = process.argv.slice(2)): Promise<number> {
+  silenceExperimentalWarnings();
+  loadConfiguration({ entryPath: import.meta.filename });
+  const name = rawArgv[0] ?? "";
+  try {
+    return await dispatch(name, rawArgv.slice(1));
+  } catch (error) {
+    // The last line of defense. A hook that throws must still not break the
+    // turn, and must still leave a trace that it happened.
+    noteHookFailure(name || "hooks", error instanceof Error ? error.message : String(error));
+    return 0;
+  }
+}
+
+// Run only when invoked as the entry, not when imported.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  process.exitCode = await runAsEntry();
+}

package/ts/src/hooks/mirrorState.ts

@@ -0,0 +1,71 @@
+// Mirror Mode state for one runtime session, as the inject hook needs it.
+//
+// The TypeScript replacement for the Python hook module `mirror_state` (144
+// lines, deleted with the core at CV22.DS10.TS5), which
+// `mirror-inject.sh` invoked up to three times per prompt -- `needs-inject`,
+// `get persona`, `get journey` -- each a separate interpreter start, each
+// re-opening the database and re-running bootstrap.
+//
+// It is NOT ported as a front-door command. Its only caller was ever that one
+// script, and the state it reads already belongs to `#mirror/runtimeSession.ts`;
+// adding two commands whose sole consumer is a hook would widen the command
+// surface this story exists to shrink.
+//
+// One Python behavior is deliberately kept, because it is a real safeguard:
+// a missing session id FAILS LOUD on stderr rather than silently answering
+// "nothing to do". A hook integration that forgets to pass one would otherwise
+// look like a user who simply has Mirror Mode off.
+
+import { openDatabaseReadOnly, type WritableDatabase } from "#db/database.ts";
+import { getRuntimeSession, upsertRuntimeSession } from "#mirror/runtimeSession.ts";
+
+export interface MirrorHookState {
+  readonly active: boolean;
+  readonly hookInjected: boolean;
+  readonly persona: string;
+  readonly journey: string;
+}
+
+const NO_STATE: MirrorHookState = {
+  active: false,
+  hookInjected: false,
+  persona: "",
+  journey: "",
+};
+
+/** Python `_load_state`: the session's Mirror fields, or empty when unknown. */
+export function readMirrorState(dbPath: string, sessionId: string): MirrorHookState {
+  if (!sessionId) return NO_STATE;
+  let db: ReturnType<typeof openDatabaseReadOnly>;
+  try {
+    db = openDatabaseReadOnly(dbPath);
+  } catch {
+    return NO_STATE;
+  }
+  try {
+    const session = getRuntimeSession(db, sessionId);
+    if (!session) return NO_STATE;
+    return {
+      active: session.mirrorActive,
+      hookInjected: session.hookInjected,
+      persona: session.persona ?? "",
+      journey: session.journey ?? "",
+    };
+  } catch {
+    return NO_STATE;
+  } finally {
+    db.close();
+  }
+}
+
+/** Python `needs_inject`: Mirror Mode is on and context has not been injected. */
+export function needsInject(state: MirrorHookState): boolean {
+  return state.active && !state.hookInjected;
+}
+
+/** Python `mark_injected`, over an already-open writable connection. */
+export function markInjected(db: WritableDatabase, sessionId: string, nowIso: string): void {
+  if (!sessionId) return;
+  if (!getRuntimeSession(db, sessionId)) return;
+  upsertRuntimeSession(db, sessionId, { hookInjected: true }, nowIso);
+}

package/ts/src/hooks/payload.ts

@@ -0,0 +1,68 @@
+// Reading a runtime's hook payload from stdin.
+//
+// Replaces the Python hook module `extract_prompt` (25 lines) and the four
+// inline interpreter one-liners the Claude and Gemini hooks used to parse the
+// same JSON. None of them was a command, so none was in
+// DS7's denominator of 29 -- which is why TS5's inventory had to find them by
+// reading the hooks rather than by counting commands.
+//
+// Python's `extract_prompt` returns "" for malformed JSON rather than raising,
+// because a hook that throws on a payload it did not recognize would break the
+// user's turn. That posture is preserved exactly.
+
+import { readFileSync } from "node:fs";
+
+export interface HookPayload {
+  /** The user's prompt text, or "" when the payload has none. */
+  readonly prompt: string;
+  /** The runtime's session id, or "" when the payload has none. */
+  readonly sessionId: string;
+  /** The assistant's response text (Gemini's `prompt_response`), or "". */
+  readonly response: string;
+  /** Everything else, for hooks that need a field these three do not cover. */
+  readonly raw: Record<string, unknown>;
+}
+
+const EMPTY: HookPayload = { prompt: "", sessionId: "", response: "", raw: {} };
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+/** Parse a hook payload. Never throws: an unparseable payload is empty. */
+export function parseHookPayload(input: string): HookPayload {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(input);
+  } catch {
+    return EMPTY;
+  }
+  if (typeof parsed !== "object" || parsed === null) return EMPTY;
+  const raw = parsed as Record<string, unknown>;
+  return {
+    prompt: text(raw.prompt),
+    sessionId: text(raw.session_id),
+    // Gemini's AfterAgent payload names it `prompt_response`, and that is the
+    // field the Python hook read. The first port read three guessed names
+    // instead and dropped every Gemini assistant turn in silence until
+    // `smoke_gemini_cli.sh` caught it (CV22.DS10.TS5 plateau 3).
+    response: text(raw.prompt_response),
+    raw,
+  };
+}
+
+/**
+ * Read stdin to the end, synchronously.
+ *
+ * Hooks are short-lived processes whose whole job is one payload, and the
+ * runtimes close the pipe. Reading fd 0 directly avoids an async entry point
+ * for every hook, and returns "" when there is no stdin at all -- which is the
+ * case for `session-start`, invoked with no payload.
+ */
+export function readStdin(): string {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}