@monotykamary/pi-vcc 0.3.16

package/tests/deep-extraction.test.ts

@@ -0,0 +1,313 @@
+import { describe, it, expect } from "bun:test";
+import { buildSections } from "../src/core/build-sections";
+import type { NormalizedBlock } from "../src/types";
+
+describe("outstanding context: deep error extraction", () => {
+  it("captures bash non-zero exit codes", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "bash", command: "npm test", output: "1 failed", exitCode: 1 },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.outstandingContext.length).toBeGreaterThan(0);
+    expect(r.outstandingContext[0]).toContain("bash:exit 1");
+    expect(r.outstandingContext[0]).toContain("npm test");
+  });
+
+  it("captures bash non-zero exit code with output context", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "bash", command: "cargo build", output: "error: could not compile", exitCode: 101 },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.outstandingContext.length).toBeGreaterThan(0);
+    expect(r.outstandingContext[0]).toContain("bash:exit 101");
+    expect(r.outstandingContext[0]).toContain("cargo build");
+    expect(r.outstandingContext[0]).toContain("could not compile");
+  });
+
+  it("skips bash with exit code 0", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "bash", command: "echo ok", output: "ok", exitCode: 0 },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.outstandingContext).toEqual([]);
+  });
+
+  it("skips bash with undefined exit code", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "bash", command: "echo ok", output: "ok", exitCode: undefined },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.outstandingContext).toEqual([]);
+  });
+
+  it("captures TypeScript compiler errors", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "bash", command: "tsc --noEmit", output: "src/auth.ts(12,5): error TS2322: Type 'string' is not assignable to type 'number'.", exitCode: 0 },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.outstandingContext.length).toBeGreaterThan(0);
+    expect(r.outstandingContext.some(c => c.includes("[tsc]"))).toBe(true);
+    expect(r.outstandingContext.some(c => c.includes("TS2322"))).toBe(true);
+  });
+
+  it("captures test failures in bash output", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "bash", command: "bun test", output: "2 failed\nFAIL auth.test.ts", exitCode: 1 },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.outstandingContext.length).toBeGreaterThan(0);
+    // Should capture both the exit code AND the test failure signal
+    const hasExitCode = r.outstandingContext.some(c => c.includes("bash:exit 1"));
+    const hasTests = r.outstandingContext.some(c => c.includes("[tests]"));
+    expect(hasExitCode || hasTests).toBe(true);
+  });
+
+  it("captures empty grep results", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "grep", args: { pattern: "verifyToken", path: "src/" } },
+      { kind: "tool_result", name: "grep", text: "No matches found", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.outstandingContext.length).toBeGreaterThan(0);
+    expect(r.outstandingContext[0]).toContain("[no matches]");
+    expect(r.outstandingContext[0]).toContain("grep");
+    expect(r.outstandingContext[0]).toContain("verifyToken");
+  });
+
+  it("captures empty glob results", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "glob", args: { pattern: "**/*.proto" } },
+      { kind: "tool_result", name: "glob", text: "No files matched.", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.outstandingContext.length).toBeGreaterThan(0);
+    expect(r.outstandingContext[0]).toContain("[no matches]");
+    expect(r.outstandingContext[0]).toContain("glob");
+  });
+
+  it("captures tsc errors from tool_result with bash error", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_result", name: "bash", text: "src/utils.ts(5,1): error TS2305: Module has no exported member 'foo'.", isError: true },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.outstandingContext.length).toBeGreaterThan(0);
+    expect(r.outstandingContext.some(c => c.includes("[tsc]"))).toBe(true);
+  });
+
+  it("still captures BLOCKER_RE text from assistant", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "assistant", text: "The deployment is still failing because of the auth configuration." },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.outstandingContext.length).toBeGreaterThan(0);
+    expect(r.outstandingContext[0]).toContain("still failing");
+  });
+
+  it("deduplicates error items", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_result", name: "bash", text: "Command not found", isError: true },
+      { kind: "tool_result", name: "bash", text: "Command not found", isError: true },
+    ];
+    const r = buildSections({ blocks });
+    const matchCount = r.outstandingContext.filter(c => c.includes("Command not found")).length;
+    expect(matchCount).toBeLessThanOrEqual(1);
+  });
+});
+
+describe("files and changes: symbol annotations", () => {
+  it("annotates modified files with exported symbol names from Edit newText", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Edit", args: { file_path: "auth.ts", newText: "export function login() {}\nexport function verifyToken() {}\nconst _internal = 1;" } },
+      { kind: "tool_result", name: "Edit", text: "ok", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.filesAndChanges.length).toBeGreaterThan(0);
+    expect(r.filesAndChanges[0]).toContain("Modified");
+    expect(r.filesAndChanges[0]).toContain("login");
+    expect(r.filesAndChanges[0]).toContain("verifyToken");
+  });
+
+  it("annotates read files with exported symbol names from Read result", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "types.ts" } },
+      { kind: "tool_result", name: "Read", text: "export interface User { name: string; }\nexport type AuthPayload = { email: string; }", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.filesAndChanges.length).toBeGreaterThan(0);
+    expect(r.filesAndChanges[0]).toContain("Read");
+    expect(r.filesAndChanges[0]).toContain("User");
+    expect(r.filesAndChanges[0]).toContain("AuthPayload");
+  });
+
+  it("does not annotate files when no symbols are found", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "config.json" } },
+      { kind: "tool_result", name: "Read", text: '{ "name": "test" }', isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.filesAndChanges[0]).toContain("config.json");
+    expect(r.filesAndChanges[0]).not.toContain("(");
+  });
+
+  it("handles Mixed Edit+Read with combined symbols", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "utils.ts" } },
+      { kind: "tool_result", name: "Read", text: "export function helper() {}\nexport class Util {}", isError: false },
+      { kind: "tool_call", name: "Edit", args: { file_path: "utils.ts", newText: "export function newHelper() {}" } },
+      { kind: "tool_result", name: "Edit", text: "ok", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.filesAndChanges[0]).toContain("Modified");
+    expect(r.filesAndChanges[0]).toContain("utils.ts");
+    // Should contain symbols from both Read result and Edit newText
+    expect(r.filesAndChanges[0]).toContain("newHelper");
+  });
+
+  it("annotates Python def and class exports", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "auth.py" } },
+      { kind: "tool_result", name: "Read", text: "def login(email, pwd):\n    pass\n\nclass AuthProvider:\n    pass", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.filesAndChanges[0]).toContain("login");
+    expect(r.filesAndChanges[0]).toContain("AuthProvider");
+  });
+
+  it("annotates Go exported functions", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "handler.go" } },
+      { kind: "tool_result", name: "Read", text: "func HandleRequest(w http.ResponseWriter, r *http.Request) {\n\t// ...\n}\n\nfunc internalHelper() {}", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.filesAndChanges[0]).toContain("HandleRequest");
+    // unexported Go functions (lowercase) should not be included
+    expect(r.filesAndChanges[0]).not.toContain("internalHelper");
+  });
+});
+
+describe("type catalog", () => {
+  it("extracts exported signatures from modified files", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Edit", args: { file_path: "auth.ts", newText: "export function login(email: string, pwd: string): Promise<Session> {\n  // impl\n}" } },
+      { kind: "tool_result", name: "Edit", text: "ok", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.typeCatalog.length).toBeGreaterThan(0);
+    expect(r.typeCatalog[0]).toContain("auth.ts");
+    expect(r.typeCatalog.some(l => l.includes("login"))).toBe(true);
+  });
+
+  it("extracts exported signatures from Read results", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "types.ts" } },
+      { kind: "tool_result", name: "Read", text: "export interface User {\n  name: string;\n  email: string;\n}\n\nexport type Session = {\n  token: string;\n  user: User;\n}", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.typeCatalog.length).toBeGreaterThan(0);
+    expect(r.typeCatalog.some(l => l.includes("interface User"))).toBe(true);
+    expect(r.typeCatalog.some(l => l.includes("type Session"))).toBe(true);
+  });
+
+  it("prioritizes modified files over read files", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "read_only.ts" } },
+      { kind: "tool_result", name: "Read", text: "export function readOnly() {}", isError: false },
+      { kind: "tool_call", name: "Edit", args: { file_path: "modified.ts", newText: "export function modified() {}" } },
+      { kind: "tool_result", name: "Edit", text: "ok", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.typeCatalog.length).toBeGreaterThan(0);
+    // Modified file should appear first
+    expect(r.typeCatalog[0]).toContain("modified.ts");
+    expect(r.typeCatalog[0]).toContain("[modified]");
+  });
+
+  it("returns empty for files with no exportable signatures", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "data.json" } },
+      { kind: "tool_result", name: "Read", text: '{ "key": "value" }', isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.typeCatalog).toEqual([]);
+  });
+
+  it("caps signatures per file to 8", () => {
+    const sigs = Array.from({ length: 15 }, (_, i) => `export function fn${i}(): void {}`).join("\n");
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "big.ts" } },
+      { kind: "tool_result", name: "Read", text: sigs, isError: false },
+    ];
+    const r = buildSections({ blocks });
+    // The catalog should have the file but max 8 signatures
+    const sigLines = r.typeCatalog.filter(l => l.startsWith("  "));
+    expect(sigLines.length).toBeLessThanOrEqual(8);
+  });
+});
+
+describe("symbol changes", () => {
+  it("extracts symbol refs from Edit/Write tool calls", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Edit", args: { file_path: "auth.ts", newText: "export function login() {}\nexport function verifyToken() {}" } },
+      { kind: "tool_result", name: "Edit", text: "ok", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    expect(r.symbolChanges.length).toBeGreaterThan(0);
+    expect(r.symbolChanges.some(s => s.name === "login" && s.file === "auth.ts")).toBe(true);
+    expect(r.symbolChanges.some(s => s.name === "verifyToken" && s.kind === "function")).toBe(true);
+  });
+
+  it("marks read vs modified access correctly", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "types.ts" } },
+      { kind: "tool_result", name: "Read", text: "export interface User {}", isError: false },
+      { kind: "tool_call", name: "Edit", args: { file_path: "auth.ts", newText: "export function login() {}" } },
+      { kind: "tool_result", name: "Edit", text: "ok", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    const loginSym = r.symbolChanges.find(s => s.name === "login");
+    const userSym = r.symbolChanges.find(s => s.name === "User");
+    expect(loginSym?.access).toBe("modified");
+    expect(userSym?.access).toBe("read");
+  });
+
+  it("deduplicates symbols by name+file", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "auth.ts" } },
+      { kind: "tool_result", name: "Read", text: "export function login() {}", isError: false },
+      { kind: "tool_call", name: "Edit", args: { file_path: "auth.ts", newText: "export function login() {}" } },
+      { kind: "tool_result", name: "Edit", text: "ok", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    const loginSymCount = r.symbolChanges.filter(s => s.name === "login" && s.file === "auth.ts").length;
+    expect(loginSymCount).toBe(1);
+  });
+});
+
+describe("format output integration", () => {
+  it("includes Type Catalog section in formatted output between Files and Commits", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Read", args: { file_path: "types.ts" } },
+      { kind: "tool_result", name: "Read", text: "export interface User { name: string; }", isError: false },
+    ];
+    const r = buildSections({ blocks });
+    const { formatSummary } = require("../src/core/format");
+    const output = formatSummary(r);
+    expect(output).toContain("[Type Catalog]");
+    // Should appear after Files And Changes and before Commits
+    const filesIdx = output.indexOf("[Files And Changes]");
+    const typeIdx = output.indexOf("[Type Catalog]");
+    const commitsIdx = output.indexOf("[Commits]");
+    if (filesIdx >= 0 && typeIdx >= 0) expect(filesIdx).toBeLessThan(typeIdx);
+    // Commits may or may not be present
+    if (commitsIdx >= 0 && typeIdx >= 0) expect(typeIdx).toBeLessThan(commitsIdx);
+  });
+
+  it("Type Catalog is volatile (fresh only) on merge", () => {
+    const { compile } = require("../src/core/summarize");
+    const prev = "[Session Goal]\n- goal\n\n[Type Catalog]\n- old-file.ts [read]:\n  export function old()";
+    const fresh = compile({ messages: [], previousSummary: prev });
+    // Type Catalog should be fresh-only, not merged from previous
+    expect(fresh).not.toContain("old-file.ts");
+    expect(fresh).not.toContain("old()");
+  });
+});

package/tests/extract-goals.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from "bun:test";
+import { extractGoals } from "../src/extract/goals";
+import type { NormalizedBlock } from "../src/types";
+
+describe("extractGoals", () => {
+  it("returns empty for no blocks", () => {
+    expect(extractGoals([])).toEqual([]);
+  });
+
+  it("returns empty when no user blocks", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "assistant", text: "hello" },
+    ];
+    expect(extractGoals(blocks)).toEqual([]);
+  });
+
+  it("extracts first user message lines as goals", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "Fix login bug\nCheck auth flow" },
+    ];
+    const goals = extractGoals(blocks);
+    expect(goals).toEqual(["Fix login bug", "Check auth flow"]);
+  });
+
+  it("takes up to 6 lines from first user block", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "fix the login bug\ncheck auth flow\nupdate the tests\nrefactor utils\nclean up" },
+    ];
+    expect(extractGoals(blocks)).toHaveLength(5);
+  });
+
+  it("ignores subsequent user blocks", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "first goal" },
+      { kind: "assistant", text: "ok" },
+      { kind: "user", text: "second request" },
+    ];
+    expect(extractGoals(blocks)).toEqual(["first goal"]);
+  });
+
+  it("detects scope change with explicit pivot keywords", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "Fix login bug" },
+      { kind: "assistant", text: "ok" },
+      { kind: "user", text: "Actually, instead let's refactor the auth module" },
+    ];
+    const goals = extractGoals(blocks);
+    expect(goals).toContain("Fix login bug");
+    expect(goals).toContain("[Scope change]");
+    expect(goals.some((g) => g.includes("refactor"))).toBe(true);
+  });
+
+  it("detects scope change from new task statements", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "Fix login bug" },
+      { kind: "assistant", text: "done" },
+      { kind: "user", text: "Now implement the user registration flow" },
+    ];
+    const goals = extractGoals(blocks);
+    expect(goals).toContain("[Scope change]");
+  });
+
+  it("keeps latest scope change only", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "Fix login bug" },
+      { kind: "assistant", text: "done" },
+      { kind: "user", text: "Actually, fix the signup page instead" },
+      { kind: "assistant", text: "ok" },
+      { kind: "user", text: "Change of plan, implement password reset" },
+    ];
+    const goals = extractGoals(blocks);
+    const scopeIdx = goals.indexOf("[Scope change]");
+    expect(goals[scopeIdx + 1]).toContain("password reset");
+  });
+
+  it("skips noise short user messages as goals", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "ok" },
+      { kind: "assistant", text: "hello" },
+      { kind: "user", text: "Fix the authentication module" },
+    ];
+    const goals = extractGoals(blocks);
+    expect(goals[0]).toContain("Fix the authentication");
+    expect(goals.some((g) => g === "ok")).toBe(false);
+  });
+});

package/tests/extract-preferences.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "bun:test";
+import { extractPreferences } from "../src/extract/preferences";
+import type { NormalizedBlock } from "../src/types";
+
+describe("extractPreferences", () => {
+  it("returns empty for no blocks", () => {
+    expect(extractPreferences([])).toEqual([]);
+  });
+
+  it("captures preference patterns from user", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "I prefer TypeScript over JavaScript" },
+    ];
+    expect(extractPreferences(blocks).length).toBe(1);
+  });
+
+  it("ignores assistant blocks", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "assistant", text: "I always use best practices" },
+    ];
+    expect(extractPreferences(blocks)).toEqual([]);
+  });
+
+  it("captures please use pattern", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "please use bun instead of node" },
+    ];
+    expect(extractPreferences(blocks).length).toBe(1);
+  });
+});

package/tests/filter-noise.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "bun:test";
+import { filterNoise } from "../src/core/filter-noise";
+import type { NormalizedBlock } from "../src/types";
+
+describe("filterNoise", () => {
+  it("removes thinking blocks", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "thinking", text: "hmm", redacted: false },
+      { kind: "assistant", text: "hello" },
+    ];
+    expect(filterNoise(blocks)).toEqual([{ kind: "assistant", text: "hello" }]);
+  });
+
+  it("removes noise tool calls and results", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "TodoWrite", args: {} },
+      { kind: "tool_result", name: "TodoWrite", text: "ok", isError: false },
+      { kind: "tool_call", name: "Read", args: { path: "x.ts" } },
+    ];
+    const result = filterNoise(blocks);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({ kind: "tool_call", name: "Read", args: { path: "x.ts" } });
+  });
+
+  it("removes user blocks that are pure XML wrappers", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "<system-reminder>some noise</system-reminder>" },
+      { kind: "user", text: "Fix the bug" },
+    ];
+    const result = filterNoise(blocks);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({ kind: "user", text: "Fix the bug" });
+  });
+
+  it("cleans XML wrappers from user text but keeps real content", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "<system-reminder>noise</system-reminder>\nFix the login" },
+    ];
+    const result = filterNoise(blocks);
+    expect(result).toHaveLength(1);
+    expect((result[0] as any).text).toBe("Fix the login");
+  });
+
+  it("removes known noise strings", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "user", text: "Continue from where you left off." },
+      { kind: "user", text: "real task" },
+    ];
+    const result = filterNoise(blocks);
+    expect(result).toHaveLength(1);
+    expect((result[0] as any).text).toBe("real task");
+  });
+
+  it("preserves non-noise tool calls", () => {
+    const blocks: NormalizedBlock[] = [
+      { kind: "tool_call", name: "Edit", args: { path: "a.ts" } },
+      { kind: "tool_result", name: "Edit", text: "ok", isError: false },
+    ];
+    expect(filterNoise(blocks)).toHaveLength(2);
+  });
+});

package/tests/fixtures.ts

@@ -0,0 +1,61 @@
+import type { Message } from "@earendil-works/pi-ai";
+
+const ts = Date.now();
+const assistBase = {
+  api: "messages" as any,
+  provider: "anthropic" as any,
+  model: "test",
+  usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  timestamp: ts,
+};
+
+export const userMsg = (text: string): Message => ({
+  role: "user",
+  content: text,
+  timestamp: ts,
+});
+
+export const assistantText = (text: string): Message => ({
+  role: "assistant",
+  content: [{ type: "text", text }],
+  ...assistBase,
+  stopReason: "stop",
+});
+
+export const assistantWithThinking = (
+  text: string,
+  thinking: string,
+): Message => ({
+  role: "assistant",
+  content: [
+    { type: "thinking", thinking },
+    { type: "text", text },
+  ],
+  ...assistBase,
+  stopReason: "stop",
+});
+
+export const assistantWithToolCall = (
+  name: string,
+  args: Record<string, unknown>,
+): Message => ({
+  role: "assistant",
+  content: [{ type: "toolCall", id: "tc_1", name, arguments: args }],
+  ...assistBase,
+  stopReason: "toolUse",
+});
+
+export const toolResult = (
+  name: string,
+  text: string,
+  isError = false,
+): Message => ({
+  role: "toolResult",
+  toolCallId: "tc_1",
+  toolName: name,
+  content: [{ type: "text", text }],
+  isError,
+  timestamp: ts,
+});
+
+

package/tests/format-recall.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "bun:test";
+import { formatRecallOutput } from "../src/core/format-recall";
+import type { SearchHit } from "../src/core/search-entries";
+
+describe("formatRecallOutput", () => {
+  it("shows no-match message with query", () => {
+    const r = formatRecallOutput([], "xyz");
+    expect(r).toContain('No matches for "xyz"');
+  });
+
+  it("shows no-entries message without query", () => {
+    expect(formatRecallOutput([])).toContain("No entries");
+  });
+
+  describe("browse mode (no query)", () => {
+    it("formats entries with index and role", () => {
+      const entries: SearchHit[] = [
+        { index: 0, role: "user", summary: "hello" },
+      ];
+      const r = formatRecallOutput(entries);
+      expect(r).toContain("#0 [user] hello");
+    });
+
+    it("shows session history header", () => {
+      const entries: SearchHit[] = [
+        { index: 0, role: "user", summary: "a" },
+        { index: 1, role: "assistant", summary: "b" },
+      ];
+      const r = formatRecallOutput(entries);
+      expect(r).toContain("Session history (2 entries)");
+    });
+  });
+
+  describe("search mode (with query)", () => {
+    it("shows match count with query", () => {
+      const entries: SearchHit[] = [
+        { index: 2, role: "assistant", summary: "done", snippet: "done" },
+      ];
+      const r = formatRecallOutput(entries, "done");
+      expect(r).toContain('Found 1 matches for "done"');
+    });
+
+    it("groups entries into segments by turn", () => {
+      // Segments are split on user/bash boundaries
+      const entries: SearchHit[] = [
+        // Segment 1: user + assistant + tool_result (only user matches)
+        { index: 0, role: "user", summary: "fix auth", snippet: "fix auth" },
+        { index: 1, role: "assistant", summary: "checking...", snippet: undefined },
+        { index: 2, role: "tool_result", summary: "file not found", snippet: undefined },
+        // Segment 2: second user turn (assistant matches)
+        { index: 3, role: "user", summary: "check the logs", snippet: undefined },
+        { index: 4, role: "assistant", summary: "found the auth bug", snippet: "auth bug" },
+      ];
+      const r = formatRecallOutput(entries, "auth");
+      expect(r).toContain("--- #0-#2 (1/3 entries match) ---");
+      expect(r).toContain("> #0 [user] fix auth");
+      expect(r).toContain("  #1 [assistant] checking...");
+      expect(r).toContain("--- #3-#4 (1/2 entries match) ---");
+      expect(r).toContain("> #4 [assistant] auth bug");
+    });
+
+    it("shows segment context for adjacent turns", () => {
+      // Single match — adjacent segments shown as context
+      const entries: SearchHit[] = [
+        { index: 0, role: "user", summary: "hello", snippet: undefined },
+        { index: 1, role: "assistant", summary: "hi", snippet: undefined },
+        { index: 2, role: "user", summary: "fix auth", snippet: "fix auth" },
+        { index: 3, role: "assistant", summary: "done", snippet: undefined },
+        { index: 4, role: "user", summary: "thanks", snippet: undefined },
+      ];
+      const r = formatRecallOutput(entries, "auth");
+      expect(r).toMatch(/---/);
+      expect(r).toContain("fix auth");
+    });
+
+    it("handles entries without snippet (assume all matched)", () => {
+      const entries: SearchHit[] = [
+        { index: 0, role: "user", summary: "hello" },
+        { index: 1, role: "assistant", summary: "world" },
+      ];
+      const r = formatRecallOutput(entries, "search term");
+      expect(r).toContain('Found 2 matches for "search term"');
+      expect(r).toContain("> #0 [user] hello");
+      expect(r).toContain("> #1 [assistant] world");
+    });
+  });
+});