nlm-memory 0.4.0

package/tests/integration/stop-hook.test.ts

@@ -0,0 +1,560 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { runStopHook } from "../../src/hook/stop-hook.js";
+import { recordSurfaced } from "../../src/core/hook/memo.js";
+import { loadCited } from "../../src/core/hook/cite-memo.js";
+import {
+  readAllAssistantTurns,
+  readLastAssistantText,
+  readLastAssistantTurn,
+} from "../../src/core/hook/transcript.js";
+
+function writeTranscript(path: string, lines: object[]): void {
+  writeFileSync(path, lines.map((l) => JSON.stringify(l)).join("\n") + "\n");
+}
+
+describe("readLastAssistantText", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "nlm-transcript-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns the text of the last assistant turn with array content", () => {
+    const path = join(tmp, "t.jsonl");
+    writeTranscript(path, [
+      { type: "user", message: { content: "hi" } },
+      {
+        type: "assistant",
+        message: {
+          content: [
+            { type: "text", text: "first reply" },
+            { type: "tool_use", name: "x" },
+          ],
+        },
+      },
+      { type: "user", message: { content: "more" } },
+      {
+        type: "assistant",
+        message: { content: [{ type: "text", text: "second reply" }] },
+      },
+    ]);
+    expect(readLastAssistantText(path)).toBe("second reply");
+  });
+
+  it("returns null when no assistant turn is present", () => {
+    const path = join(tmp, "t.jsonl");
+    writeTranscript(path, [{ type: "user", message: { content: "hi" } }]);
+    expect(readLastAssistantText(path)).toBeNull();
+  });
+
+  it("returns null when path is missing", () => {
+    expect(readLastAssistantText(join(tmp, "nonexistent.jsonl"))).toBeNull();
+  });
+
+  it("readLastAssistantTurn extracts text + tool_use blocks together", () => {
+    const path = join(tmp, "t.jsonl");
+    writeTranscript(path, [
+      {
+        type: "assistant",
+        message: {
+          content: [
+            { type: "text", text: "Searching..." },
+            {
+              type: "tool_use",
+              name: "mcp__nlm-memory__get_session",
+              input: { id: "cc_sub_abc123" },
+            },
+            { type: "text", text: "second prose chunk" },
+          ],
+        },
+      },
+    ]);
+    const turn = readLastAssistantTurn(path);
+    expect(turn.text).toBe("Searching...\nsecond prose chunk");
+    expect(turn.toolUses).toEqual([
+      {
+        name: "mcp__nlm-memory__get_session",
+        input: { id: "cc_sub_abc123" },
+      },
+    ]);
+  });
+
+  it("skips malformed JSON lines", () => {
+    const path = join(tmp, "t.jsonl");
+    writeFileSync(
+      path,
+      "not json\n" +
+        JSON.stringify({
+          type: "assistant",
+          message: { content: [{ type: "text", text: "real reply" }] },
+        }) +
+        "\n",
+    );
+    expect(readLastAssistantText(path)).toBe("real reply");
+  });
+});
+
+describe("runStopHook", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "nlm-stop-"));
+    process.env["NLM_HOOK_STATE_DIR"] = join(tmp, "state");
+  });
+  afterEach(() => {
+    delete process.env["NLM_HOOK_STATE_DIR"];
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("posts a citation for each surfaced ID found in the last assistant message", async () => {
+    recordSurfaced("conv-1", [
+      "cc_sub_a139f4ab7ca5aa909",
+      "cc_ff88cd96-d1f9-428c-8a97-2e4ca431acbe",
+      "hm_20260427_6ff562",
+    ]);
+    const transcript = join(tmp, "t.jsonl");
+    writeTranscript(transcript, [
+      {
+        type: "assistant",
+        message: {
+          content: [
+            {
+              type: "text",
+              text: "Per cc_sub_a139f4ab7ca5aa909 and hm_20260427_6ff562 we chose FTS5.",
+            },
+          ],
+        },
+      },
+    ]);
+    const postCitation = vi.fn().mockResolvedValue(undefined);
+    const result = await runStopHook(
+      {
+        conversationId: "conv-1",
+        transcriptPath: transcript,
+        stopHookActive: false,
+      },
+      { postCitation },
+    );
+    expect(result.skipped).toBe(false);
+    expect(result.surfacedCount).toBe(3);
+    expect(result.citations.map((c) => c.id).sort()).toEqual(
+      ["cc_sub_a139f4ab7ca5aa909", "hm_20260427_6ff562"].sort(),
+    );
+    expect(result.citations.every((c) => c.kind === "prose")).toBe(true);
+    expect(postCitation).toHaveBeenCalledTimes(2);
+    expect(postCitation).toHaveBeenCalledWith(
+      "conv-1",
+      "cc_sub_a139f4ab7ca5aa909",
+      "prose",
+      expect.stringContaining("cc_sub_a139f4ab7ca5aa909"),
+    );
+  });
+
+  it("posts a tool_use citation when the model invokes an NLM MCP tool referencing a surfaced ID", async () => {
+    recordSurfaced("conv-mcp", [
+      "cc_sub_a139f4ab7ca5aa909",
+      "cc_ff88cd96-d1f9-428c-8a97-2e4ca431acbe",
+    ]);
+    const transcript = join(tmp, "t.jsonl");
+    writeTranscript(transcript, [
+      {
+        type: "assistant",
+        message: {
+          content: [
+            { type: "text", text: "Let me look at that prior session." },
+            {
+              type: "tool_use",
+              name: "mcp__nlm-memory__get_session",
+              input: { id: "cc_sub_a139f4ab7ca5aa909" },
+            },
+          ],
+        },
+      },
+    ]);
+    const postCitation = vi.fn().mockResolvedValue(undefined);
+    const result = await runStopHook(
+      {
+        conversationId: "conv-mcp",
+        transcriptPath: transcript,
+        stopHookActive: false,
+      },
+      { postCitation },
+    );
+    expect(result.citations).toEqual([
+      { id: "cc_sub_a139f4ab7ca5aa909", kind: "tool_use" },
+    ]);
+    expect(postCitation).toHaveBeenCalledWith(
+      "conv-mcp",
+      "cc_sub_a139f4ab7ca5aa909",
+      "tool_use",
+      expect.any(String),
+    );
+  });
+
+  it("ignores tool_use blocks for non-NLM tools", async () => {
+    recordSurfaced("conv-other", ["cc_sub_a139f4ab7ca5aa909"]);
+    const transcript = join(tmp, "t.jsonl");
+    writeTranscript(transcript, [
+      {
+        type: "assistant",
+        message: {
+          content: [
+            {
+              type: "tool_use",
+              name: "Bash",
+              input: { command: "grep cc_sub_a139f4ab7ca5aa909 /tmp/log" },
+            },
+          ],
+        },
+      },
+    ]);
+    const postCitation = vi.fn();
+    const result = await runStopHook(
+      {
+        conversationId: "conv-other",
+        transcriptPath: transcript,
+        stopHookActive: false,
+      },
+      { postCitation },
+    );
+    expect(result.citations).toEqual([]);
+    expect(postCitation).not.toHaveBeenCalled();
+  });
+
+  it("skips when stop_hook_active is true", async () => {
+    recordSurfaced("conv-2", ["cc_sub_a139f4ab7ca5aa909"]);
+    const postCitation = vi.fn();
+    const result = await runStopHook(
+      {
+        conversationId: "conv-2",
+        transcriptPath: "ignored",
+        stopHookActive: true,
+      },
+      { postCitation },
+    );
+    expect(result.skipped).toBe(true);
+    expect(postCitation).not.toHaveBeenCalled();
+  });
+
+  it("returns empty cited when no IDs were surfaced for this conversation", async () => {
+    const transcript = join(tmp, "t.jsonl");
+    writeTranscript(transcript, [
+      {
+        type: "assistant",
+        message: { content: [{ type: "text", text: "anything" }] },
+      },
+    ]);
+    const postCitation = vi.fn();
+    const result = await runStopHook(
+      {
+        conversationId: "conv-no-recall",
+        transcriptPath: transcript,
+        stopHookActive: false,
+      },
+      { postCitation },
+    );
+    expect(result.surfacedCount).toBe(0);
+    expect(result.citations).toEqual([]);
+    expect(postCitation).not.toHaveBeenCalled();
+  });
+
+  it("does not throw when postCitation rejects (daemon down)", async () => {
+    recordSurfaced("conv-3", ["cc_sub_a139f4ab7ca5aa909"]);
+    const transcript = join(tmp, "t.jsonl");
+    writeTranscript(transcript, [
+      {
+        type: "assistant",
+        message: {
+          content: [{ type: "text", text: "cc_sub_a139f4ab7ca5aa909 cited" }],
+        },
+      },
+    ]);
+    const postCitation = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));
+    await expect(
+      runStopHook(
+        {
+          conversationId: "conv-3",
+          transcriptPath: transcript,
+          stopHookActive: false,
+        },
+        { postCitation },
+      ),
+    ).resolves.toBeDefined();
+  });
+
+  it("handles missing transcript path by returning no citations", async () => {
+    recordSurfaced("conv-4", ["cc_sub_a139f4ab7ca5aa909"]);
+    const postCitation = vi.fn();
+    const result = await runStopHook(
+      {
+        conversationId: "conv-4",
+        transcriptPath: join(tmp, "nonexistent.jsonl"),
+        stopHookActive: false,
+      },
+      { postCitation },
+    );
+    expect(result.surfacedCount).toBe(1);
+    expect(result.citations).toEqual([]);
+    expect(postCitation).not.toHaveBeenCalled();
+  });
+
+  it("detects a tool_use citation when the model invoked the tool in an EARLIER turn and the last turn is prose-only", async () => {
+    // Real-world pattern: model calls get_session → reads tool_result →
+    // writes prose summary in a separate assistant turn. Stop fires after
+    // the summary. The pre-fix detector scanned only the summary turn and
+    // missed the get_session call entirely (348 stop firings in production
+    // logged 0 citations despite 23 NLM tool_uses in transcripts).
+    recordSurfaced("conv-multi", [
+      "cc_7ff73609-9ac8-4851-891c-e958915bb7fa",
+    ]);
+    const transcript = join(tmp, "t.jsonl");
+    writeTranscript(transcript, [
+      { type: "user", message: { content: "what did we decide about FTS5?" } },
+      {
+        type: "assistant",
+        message: {
+          content: [
+            { type: "text", text: "Let me check the prior session." },
+            {
+              type: "tool_use",
+              name: "mcp__nlm-memory__get_session",
+              input: { id: "cc_7ff73609-9ac8-4851-891c-e958915bb7fa" },
+            },
+          ],
+        },
+      },
+      {
+        type: "user",
+        message: {
+          content: [{ type: "tool_result", content: "session body..." }],
+        },
+      },
+      {
+        type: "assistant",
+        message: {
+          content: [
+            {
+              type: "text",
+              text: "FTS5 was chosen because the keyword leg already ranks high.",
+            },
+          ],
+        },
+      },
+    ]);
+    const postCitation = vi.fn().mockResolvedValue(undefined);
+    const result = await runStopHook(
+      {
+        conversationId: "conv-multi",
+        transcriptPath: transcript,
+        stopHookActive: false,
+      },
+      { postCitation },
+    );
+    expect(result.citations).toEqual([
+      {
+        id: "cc_7ff73609-9ac8-4851-891c-e958915bb7fa",
+        kind: "tool_use",
+      },
+    ]);
+    expect(postCitation).toHaveBeenCalledTimes(1);
+    expect(postCitation).toHaveBeenCalledWith(
+      "conv-multi",
+      "cc_7ff73609-9ac8-4851-891c-e958915bb7fa",
+      "tool_use",
+      // preview is the LAST turn's prose, not the earlier prose.
+      expect.stringContaining("FTS5 was chosen"),
+    );
+  });
+
+  it("dedupes across repeated Stop firings — same tool_use citation is posted exactly once", async () => {
+    recordSurfaced("conv-dedup", [
+      "cc_sub_a139f4ab7ca5aa909",
+    ]);
+    const transcript = join(tmp, "t.jsonl");
+    writeTranscript(transcript, [
+      {
+        type: "assistant",
+        message: {
+          content: [
+            {
+              type: "tool_use",
+              name: "mcp__nlm-memory__get_session",
+              input: { id: "cc_sub_a139f4ab7ca5aa909" },
+            },
+          ],
+        },
+      },
+      {
+        type: "assistant",
+        message: { content: [{ type: "text", text: "first response" }] },
+      },
+    ]);
+    const postCitation = vi.fn().mockResolvedValue(undefined);
+
+    // First fire — citation detected and posted.
+    const first = await runStopHook(
+      {
+        conversationId: "conv-dedup",
+        transcriptPath: transcript,
+        stopHookActive: false,
+      },
+      { postCitation },
+    );
+    expect(first.citations).toHaveLength(1);
+    expect(postCitation).toHaveBeenCalledTimes(1);
+
+    // Transcript grows with another assistant turn (typical conversation
+    // continuation). The earlier tool_use is still in the file.
+    writeTranscript(transcript, [
+      {
+        type: "assistant",
+        message: {
+          content: [
+            {
+              type: "tool_use",
+              name: "mcp__nlm-memory__get_session",
+              input: { id: "cc_sub_a139f4ab7ca5aa909" },
+            },
+          ],
+        },
+      },
+      {
+        type: "assistant",
+        message: { content: [{ type: "text", text: "first response" }] },
+      },
+      {
+        type: "user",
+        message: { content: "follow up" },
+      },
+      {
+        type: "assistant",
+        message: { content: [{ type: "text", text: "second response" }] },
+      },
+    ]);
+
+    // Second fire — same id, must not post again.
+    const second = await runStopHook(
+      {
+        conversationId: "conv-dedup",
+        transcriptPath: transcript,
+        stopHookActive: false,
+      },
+      { postCitation },
+    );
+    expect(second.citations).toEqual([]);
+    expect(postCitation).toHaveBeenCalledTimes(1);
+
+    // Cite-memo persisted the dedup state.
+    expect(loadCited("conv-dedup")).toEqual(
+      new Set(["cc_sub_a139f4ab7ca5aa909"]),
+    );
+  });
+
+  it("records a citation locally even if postCitation fails — prevents reposting on next fire", async () => {
+    recordSurfaced("conv-failopen", ["cc_sub_a139f4ab7ca5aa909"]);
+    const transcript = join(tmp, "t.jsonl");
+    writeTranscript(transcript, [
+      {
+        type: "assistant",
+        message: {
+          content: [
+            {
+              type: "tool_use",
+              name: "mcp__nlm-memory__get_session",
+              input: { id: "cc_sub_a139f4ab7ca5aa909" },
+            },
+          ],
+        },
+      },
+    ]);
+    const postCitation = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("ECONNREFUSED"))
+      .mockResolvedValue(undefined);
+    await runStopHook(
+      {
+        conversationId: "conv-failopen",
+        transcriptPath: transcript,
+        stopHookActive: false,
+      },
+      { postCitation },
+    );
+    // Second fire must NOT retry — the citation log carries an at-most-once
+    // contract on the hook side; a missed daemon write is a known telemetry
+    // gap, not a reason to double-count.
+    await runStopHook(
+      {
+        conversationId: "conv-failopen",
+        transcriptPath: transcript,
+        stopHookActive: false,
+      },
+      { postCitation },
+    );
+    expect(postCitation).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("readAllAssistantTurns", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "nlm-transcript-all-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns every assistant turn in order", () => {
+    const path = join(tmp, "t.jsonl");
+    writeTranscript(path, [
+      { type: "user", message: { content: "hi" } },
+      {
+        type: "assistant",
+        message: {
+          content: [
+            { type: "text", text: "first" },
+            {
+              type: "tool_use",
+              name: "mcp__nlm-memory__get_session",
+              input: { id: "cc_x" },
+            },
+          ],
+        },
+      },
+      { type: "user", message: { content: "more" } },
+      {
+        type: "assistant",
+        message: { content: [{ type: "text", text: "second" }] },
+      },
+    ]);
+    const turns = readAllAssistantTurns(path);
+    expect(turns).toHaveLength(2);
+    expect(turns[0]?.text).toBe("first");
+    expect(turns[0]?.toolUses[0]?.name).toBe("mcp__nlm-memory__get_session");
+    expect(turns[1]?.text).toBe("second");
+    expect(turns[1]?.toolUses).toEqual([]);
+  });
+
+  it("returns empty array for missing path", () => {
+    expect(readAllAssistantTurns(join(tmp, "missing.jsonl"))).toEqual([]);
+  });
+
+  it("skips malformed lines without throwing", () => {
+    const path = join(tmp, "t.jsonl");
+    writeFileSync(
+      path,
+      "not json\n" +
+        JSON.stringify({
+          type: "assistant",
+          message: { content: [{ type: "text", text: "real" }] },
+        }) +
+        "\n",
+    );
+    const turns = readAllAssistantTurns(path);
+    expect(turns).toHaveLength(1);
+    expect(turns[0]?.text).toBe("real");
+  });
+});

package/tests/integration/wal-checkpoint.test.ts

@@ -0,0 +1,49 @@
+/**
+ * SqliteSessionStore.checkpoint — drains the WAL into the main DB and
+ * truncates the -wal file, so it cannot grow unbounded.
+ */
+
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { SqliteSessionStore } from "../../src/core/storage/sqlite-session-store.js";
+import { makeSession } from "../fixtures/sessions.js";
+
+const MIGRATIONS_DIR = resolve(__dirname, "../../migrations");
+
+describe("SqliteSessionStore.checkpoint", () => {
+  let tmp: string;
+  let dbPath: string;
+  let store: SqliteSessionStore;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "nlm-wal-"));
+    dbPath = join(tmp, "canonical.sqlite");
+    store = new SqliteSessionStore({ dbPath, migrationsDir: MIGRATIONS_DIR });
+  });
+
+  afterEach(() => {
+    store.close();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("truncates the -wal file after checkpoint", () => {
+    for (let i = 0; i < 30; i++) {
+      store.insertSessionForTest(
+        makeSession({ id: `s${i}`, label: `session ${i}`, body: "x".repeat(5000) }),
+      );
+    }
+    const walBefore = statSync(`${dbPath}-wal`).size;
+    expect(walBefore).toBeGreaterThan(0);
+
+    store.checkpoint();
+
+    const walAfter = statSync(`${dbPath}-wal`).size;
+    expect(walAfter).toBe(0);
+  });
+
+  it("is safe to call when the WAL is already empty", () => {
+    expect(() => store.checkpoint()).not.toThrow();
+  });
+});

package/tests/unit/cli/launchctl-helpers.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { isAgentLoaded, isBenignBootoutError } from "../../../src/cli/launchctl-helpers.js";
+
+describe("isBenignBootoutError", () => {
+  it("recognizes the 'Could not find service' message", () => {
+    expect(isBenignBootoutError("Could not find service \"foo\" in domain for port: 0\n")).toBe(true);
+  });
+
+  it("recognizes 'No such process'", () => {
+    expect(isBenignBootoutError("Boot-out failed: No such process")).toBe(true);
+  });
+
+  it("recognizes 'not currently loaded' phrasing", () => {
+    expect(isBenignBootoutError("Service is not currently loaded.")).toBe(true);
+  });
+
+  it("treats unrecognized stderr as a real failure", () => {
+    expect(isBenignBootoutError("Bootstrap failed: 5: Input/output error")).toBe(false);
+  });
+
+  it("treats empty stderr as a real failure (no excuse to be silent)", () => {
+    expect(isBenignBootoutError("")).toBe(false);
+  });
+
+  it("is case-insensitive on the match", () => {
+    expect(isBenignBootoutError("COULD NOT FIND SERVICE")).toBe(true);
+  });
+});
+
+describe("isAgentLoaded", () => {
+  const label = "com.example.test-agent";
+
+  it("returns true when the label appears in the launchctl list output", () => {
+    const stub = () => `12345\t0\tcom.apple.WebKit.GPU\n87530\t0\t${label}\n22222\t0\tsomething.else\n`;
+    expect(isAgentLoaded(label, stub)).toBe(true);
+  });
+
+  it("returns false when the label is absent", () => {
+    const stub = () => `12345\t0\tcom.apple.WebKit.GPU\n22222\t0\tsomething.else\n`;
+    expect(isAgentLoaded(label, stub)).toBe(false);
+  });
+
+  it("returns false when the runner throws (launchctl unreachable)", () => {
+    const stub = (): string => {
+      throw new Error("launchctl not found");
+    };
+    expect(isAgentLoaded(label, stub)).toBe(false);
+  });
+
+  it("requires substring match — partial label collision is fine, full label wins", () => {
+    // A different agent that happens to share a prefix should not falsely match
+    // a query for the full label. (We match by includes(), so this is a guard:
+    // make sure the label is specific enough.)
+    const stub = () => `12345\t0\tcom.example.test-agent-helper\n`;
+    // includes() will return true here — documents the limitation. If we ever
+    // want exact-match, change the helper. For now, the actual NLM label is
+    // distinctive enough that this isn't a concern.
+    expect(isAgentLoaded(label, stub)).toBe(true);
+  });
+});