@monotykamary/pi-vcc 0.3.16

package/tests/recall-tool-scope.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "bun:test";
+import { mkdtempSync, writeFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { registerRecallTool } from "../src/tools/recall";
+
+const makeSession = () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-vcc-recall-scope-"));
+  const file = join(dir, "session.jsonl");
+  const lines = [
+    JSON.stringify({ type: "message", id: "m1", message: { role: "user", content: "active lineage token" } }),
+    JSON.stringify({ type: "message", id: "m2", message: { role: "user", content: "off lineage secret" } }),
+  ];
+  writeFileSync(file, lines.join("\n") + "\n", "utf8");
+  return { dir, file };
+};
+
+const register = () => {
+  let tool: any;
+  registerRecallTool({ registerTool: (t: any) => { tool = t; } } as any);
+  return tool;
+};
+
+const invoke = async (tool: any, file: string, params: Record<string, unknown>) => {
+  const result = await tool.execute("tool-call", params, undefined, undefined, {
+    sessionManager: {
+      getSessionFile: () => file,
+      getBranch: () => [{ id: "m1" }],
+      getEntries: () => [{ id: "m1" }, { id: "m2" }],
+    },
+  });
+  return result.content[0].text as string;
+};
+
+describe("vcc_recall scope", () => {
+  it("defaults to active lineage and opts into all-session search explicitly", async () => {
+    const { dir, file } = makeSession();
+    try {
+      const tool = register();
+
+      const lineage = await invoke(tool, file, { query: "secret" });
+      expect(lineage).toContain("No matches");
+
+      const all = await invoke(tool, file, { query: "secret", scope: "all" });
+      expect(all).toContain("scope: all");
+      expect(all).toContain("off lineage secret");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps expand strict by default but allows off-lineage expand with scope all", async () => {
+    const { dir, file } = makeSession();
+    try {
+      const tool = register();
+
+      const lineage = await invoke(tool, file, { expand: [1] });
+      expect(lineage).toContain("Cannot expand indices outside active lineage: 1");
+
+      const all = await invoke(tool, file, { expand: [1], scope: "all" });
+      expect(all).toContain("Scope: all");
+      expect(all).toContain("#1 [user] off lineage secret");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/tests/render-entries.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from "bun:test";
+import { renderMessage } from "../src/core/render-entries";
+import type { Message } from "@earendil-works/pi-ai";
+import { userMsg, assistantText, assistantWithToolCall, assistantWithThinking, toolResult } from "./fixtures";
+
+describe("renderMessage", () => {
+  it("renders user message", () => {
+    const r = renderMessage(userMsg("hello"), 0);
+    expect(r).toEqual({ index: 0, role: "user", summary: "hello" });
+  });
+
+  it("renders assistant text", () => {
+    const r = renderMessage(assistantText("done"), 1);
+    expect(r.role).toBe("assistant");
+    expect(r.summary).toBe("done");
+  });
+
+  it("renders tool result", () => {
+    const r = renderMessage(toolResult("Read", "file contents"), 2);
+    expect(r.role).toBe("tool_result");
+    expect(r.summary).toContain("[Read]");
+  });
+
+  it("renders tool call arguments with values", () => {
+    const r = renderMessage(assistantWithToolCall("Read", { path: "a.ts" }), 2);
+    expect(r.summary).toContain("Read(path=a.ts)");
+  });
+
+  it("renders error tool result with prefix", () => {
+    const r = renderMessage(toolResult("bash", "not found", true), 3);
+    expect(r.summary).toStartWith("ERROR");
+  });
+
+  it("truncates long user text", () => {
+    const long = "x".repeat(500);
+    const r = renderMessage(userMsg(long), 0);
+    expect(r.summary.length).toBeLessThanOrEqual(300);
+  });
+
+  it("renders bashExecution message", () => {
+    const msg = { role: "bashExecution", command: "ls -la", output: "total 0\n" } as any;
+    const r = renderMessage(msg, 5);
+    expect(r.role).toBe("bash");
+    expect(r.summary).toContain("$ ls -la");
+    expect(r.summary).toContain("total 0");
+  });
+
+  it("renders bashExecution with missing output", () => {
+    const msg = { role: "bashExecution", command: "exit 1" } as any;
+    const r = renderMessage(msg, 6);
+    expect(r.role).toBe("bash");
+    expect(r.summary).toContain("$ exit 1");
+  });
+
+  it("renders assistant with thinking in recall output", () => {
+    const r = renderMessage(assistantWithThinking("Checking auth flow", "The bug is probably in the middleware"), 1);
+    expect(r.role).toBe("assistant");
+    expect(r.summary).toContain("[thinking]");
+    expect(r.summary).toContain("The bug is probably in the middleware");
+    expect(r.summary).toContain("Checking auth flow");
+  });
+
+  it("clips thinking in non-full mode", () => {
+    const longThinking = "x".repeat(400);
+    const r = renderMessage(assistantWithThinking("short", longThinking), 1, false);
+    expect(r.summary).toContain("[thinking]");
+    // Thinking should be clipped to ~150 chars
+    expect(r.summary.length).toBeLessThan(longThinking.length);
+  });
+
+  it("renders full thinking in full mode", () => {
+    const longThinking = "x".repeat(400);
+    const r = renderMessage(assistantWithThinking("short", longThinking), 1, true);
+    expect(r.summary).toContain("[thinking]");
+    expect(r.summary).toContain(longThinking);
+  });
+
+  it("renders assistant without thinking normally", () => {
+    const r = renderMessage(assistantText("done"), 1);
+    expect(r.role).toBe("assistant");
+    expect(r.summary).toBe("done");
+    expect(r.summary).not.toContain("[thinking]");
+  });
+
+  it("handles message with undefined content", () => {
+    const msg = { role: "assistant", content: undefined } as any;
+    const r = renderMessage(msg, 3);
+    expect(r.role).toBe("assistant");
+    expect(r.summary).toBe("");
+  });
+});
+

package/tests/report.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "bun:test";
+import { buildCompactReport } from "../src/core/report";
+import {
+  userMsg,
+  assistantText,
+  assistantWithToolCall,
+  toolResult,
+} from "./fixtures";
+
+describe("buildCompactReport", () => {
+  it("includes before and after compact metrics", () => {
+    const report = buildCompactReport({
+      messages: [
+        userMsg("Fix login bug in auth.ts"),
+        assistantWithToolCall("Read", { path: "auth.ts" }),
+        toolResult("Read", "const x = 1;"),
+        assistantText("Found the root cause in auth.ts.\n1. Fix validation\n2. Run tests"),
+      ],
+    });
+    expect(report.before.messageCount).toBe(4);
+    expect(report.before.roleCounts.user).toBe(1);
+    expect(report.before.topFiles).toContain("auth.ts");
+    expect(report.before.preview).toContain("Fix login bug in auth.ts");
+    expect(report.after.sectionCount).toBeGreaterThan(0);
+    expect(report.after.summaryPreview).toContain("[Session Goal]");
+    expect(report.after.summaryPreview).toContain('* Read "auth.ts"');
+    expect(report.after.briefTranscriptLines).toBeGreaterThan(0);
+    expect(report.compression.ratio).toBeGreaterThan(0);
+  });
+
+  it("marks recall probe coverage for goal and file queries", () => {
+    const report = buildCompactReport({
+      messages: [
+        userMsg("Fix login bug in auth.ts"),
+        assistantWithToolCall("Read", { path: "auth.ts" }),
+        toolResult("Read", "code content"),
+        assistantText("Found the root cause"),
+      ],
+    });
+    expect(report.recall.probes.length).toBeGreaterThanOrEqual(1);
+    const goalProbe = report.recall.probes.find((p) => p.label === "goal");
+    expect(goalProbe?.summaryMentioned).toBe(true);
+  });
+
+  it("counts recall hits with the probe query", () => {
+    const report = buildCompactReport({
+      messages: [
+        userMsg("Handle unrelated setup"),
+        assistantWithToolCall("Read", { path: "unique-auth-file.ts" }),
+        toolResult("Read", "code content"),
+        assistantText("Done"),
+      ],
+    });
+    const fileProbe = report.recall.probes.find((p) => p.label === "file");
+    expect(fileProbe?.query).toBe("unique-auth-file.ts");
+    expect(fileProbe?.recallHits).toBe(1);
+  });
+});

package/tests/sanitize.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "bun:test";
+import { sanitize } from "../src/core/sanitize";
+
+describe("sanitize", () => {
+  it("strips ANSI escape codes", () => {
+    expect(sanitize("\x1b[31mred\x1b[0m")).toBe("red");
+  });
+
+  it("normalizes CRLF to LF", () => {
+    expect(sanitize("a\r\nb\r\n")).toBe("a\nb\n");
+  });
+
+  it("strips bare CR", () => {
+    expect(sanitize("a\rb")).toBe("a\nb");
+  });
+
+  it("strips control characters but preserves newlines and tabs", () => {
+    expect(sanitize("a\x00b\tc\nd")).toBe("ab\tc\nd");
+  });
+
+  it("passes clean text unchanged", () => {
+    expect(sanitize("hello world")).toBe("hello world");
+  });
+});

package/tests/search-entries.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect } from "bun:test";
+import { searchEntries } from "../src/core/search-entries";
+import type { RenderedEntry } from "../src/core/render-entries";
+import type { Message } from "@earendil-works/pi-ai";
+
+const entries: RenderedEntry[] = [
+  { index: 0, role: "user", summary: "Fix login bug" },
+  { index: 1, role: "assistant", summary: "Reading auth.ts" },
+  { index: 2, role: "tool_result", summary: "[Read] code here" },
+  { index: 3, role: "assistant", summary: "Found the root cause in auth module" },
+];
+
+const messages: Message[] = [
+  { role: "user", content: "Fix login bug" } as any,
+  { role: "assistant", content: [{ type: "text", text: "Reading auth.ts" }] } as any,
+  { role: "toolResult", content: [{ type: "text", text: "[Read] code here" }] } as any,
+  { role: "assistant", content: [{ type: "text", text: "Found the root cause in auth module" }] } as any,
+];
+
+describe("searchEntries", () => {
+  it("returns all for empty query", () => {
+    expect(searchEntries(entries, messages)).toEqual(entries);
+    expect(searchEntries(entries, messages, "")).toEqual(entries);
+  });
+
+  it("filters by single term", () => {
+    const r = searchEntries(entries, messages, "login");
+    expect(r).toHaveLength(1);
+    expect(r[0].index).toBe(0);
+  });
+
+  it("returns empty for no match", () => {
+    expect(searchEntries(entries, messages, "xyz123")).toEqual([]);
+  });
+
+  it("finds keyword beyond clip boundary in full content", () => {
+    const longText = "A".repeat(400) + " hidden_keyword here";
+    const longEntries: RenderedEntry[] = [
+      { index: 0, role: "user", summary: "A".repeat(300) },
+    ];
+    const longMsgs: Message[] = [
+      { role: "user", content: longText } as any,
+    ];
+    const r = searchEntries(longEntries, longMsgs, "hidden_keyword");
+    expect(r).toHaveLength(1);
+    expect(r[0].snippet).toContain("hidden_keyword");
+  });
+
+  it("returns snippet around matched term", () => {
+    const r = searchEntries(entries, messages, "root");
+    expect(r).toHaveLength(1);
+    expect(r[0].snippet).toBeDefined();
+    expect(r[0].snippet).toContain("root");
+  });
+
+  // ── regex support ──
+
+  it("supports regex pattern: alternation", () => {
+    const r = searchEntries(entries, messages, "login|auth");
+    expect(r).toHaveLength(3); // "login bug", "auth.ts", "auth module"
+    expect(r.map((h) => h.index).sort()).toEqual([0, 1, 3]);
+  });
+
+  it("supports regex pattern: wildcard", () => {
+    const r = searchEntries(entries, messages, "Read.*auth");
+    expect(r).toHaveLength(1);
+    expect(r[0].index).toBe(1);
+  });
+
+  it("falls back to escaped literal for invalid regex", () => {
+    const extraEntries: RenderedEntry[] = [
+      { index: 0, role: "user", summary: "test (foo" },
+      { index: 1, role: "assistant", summary: "no match here" },
+    ];
+    const extraMsgs: Message[] = [
+      { role: "user", content: "error with (foo pattern" } as any,
+      { role: "assistant", content: [{ type: "text", text: "no match here" }] } as any,
+    ];
+    const r = searchEntries(extraEntries, extraMsgs, "(foo");
+    expect(r).toHaveLength(1);
+    expect(r[0].index).toBe(0);
+  });
+
+  it("regex is case-insensitive", () => {
+    const r = searchEntries(entries, messages, "FIX|ROOT");
+    expect(r).toHaveLength(2);
+  });
+
+  // ── natural language queries (OR logic + ranking) ──
+
+  it("natural language query uses OR logic with multi-term minimum", () => {
+    // "root cause auth" -- 3 meaningful terms → requires ≥2 matches
+    // #3 has all 3 (root, cause, auth); #1 has only auth (1 term, below threshold)
+    const r = searchEntries(entries, messages, "root cause auth");
+    expect(r.length).toBe(1);
+    expect(r[0].index).toBe(3); // "Found the root cause in auth module" matches all 3
+  });
+
+  it("2-term OR query matches on single term (no multi-term floor)", () => {
+    // 2 meaningful terms → no floor, matches entries with ANY term
+    const r = searchEntries(entries, messages, "login auth");
+    expect(r.length).toBeGreaterThanOrEqual(2); // #0 has login, #1 + #3 have auth
+  });
+
+  it("natural language ranks by BM25 score", () => {
+    const r = searchEntries(entries, messages, "root cause auth");
+    // Top result has more terms matched = higher BM25 score
+    expect(r[0].matchCount!).toBeGreaterThanOrEqual(r[r.length - 1].matchCount!);
+  });
+
+  it("filters stopwords from queries", () => {
+    // "the root cause of it" → stopwords: the, of, it → meaningful: root, cause
+    const r = searchEntries(entries, messages, "the root cause of it");
+    expect(r).toHaveLength(1);
+    expect(r[0].index).toBe(3);
+  });
+
+  it("keeps all terms if all are stopwords", () => {
+    // When all terms are stopwords, keep them (don't drop everything)
+    // "the" appears in "Found the root cause" so it matches
+    const r = searchEntries(entries, messages, "the");
+    expect(r.length).toBeGreaterThan(0);
+  });
+
+  // ── line-based snippet ──
+
+  it("snippet shows context lines around match", () => {
+    const multiline = "line 0\nline 1\nline 2 TARGET\nline 3\nline 4\nline 5";
+    const e: RenderedEntry[] = [{ index: 0, role: "user", summary: "test" }];
+    const m: Message[] = [{ role: "user", content: multiline } as any];
+    const r = searchEntries(e, m, "TARGET");
+    expect(r).toHaveLength(1);
+    const snip = r[0].snippet!;
+    expect(snip).toContain("line 2 TARGET");
+    expect(snip).toContain("line 0");
+    expect(snip).toContain("line 4");
+    expect(snip).not.toContain("line 5");
+  });
+
+  it("snippet handles match at beginning", () => {
+    const multiline = "TARGET here\nline 1\nline 2\nline 3";
+    const e: RenderedEntry[] = [{ index: 0, role: "user", summary: "test" }];
+    const m: Message[] = [{ role: "user", content: multiline } as any];
+    const r = searchEntries(e, m, "TARGET");
+    const snip = r[0].snippet!;
+    expect(snip).toContain("TARGET here");
+    expect(snip).toContain("line 2");
+    expect(snip).not.toContain("line 3");
+  });
+
+  // ── thinking content searchability ──
+
+  it("finds terms in thinking content", () => {
+    const e: RenderedEntry[] = [
+      { index: 0, role: "user", summary: "Fix the parser" },
+      { index: 1, role: "assistant", summary: "Looking at parser" },
+    ];
+    const m: Message[] = [
+      { role: "user", content: "Fix the parser" } as any,
+      { role: "assistant", content: [
+        { type: "thinking", thinking: "The race condition is in the event emitter" },
+        { type: "text", text: "Looking at parser" },
+      ] } as any,
+    ];
+    const r = searchEntries(e, m, "race condition");
+    expect(r).toHaveLength(1);
+    expect(r[0].index).toBe(1);
+    expect(r[0].snippet).toContain("race condition");
+  });
+
+  // ── search result grounding (prevents "half the session" returns) ──
+
+  it("filters low-relevance BM25 hits by score ratio threshold", () => {
+    // Build a session where one entry is highly relevant and many are barely relevant
+    const govEntries: RenderedEntry[] = [
+      { index: 0, role: "user", summary: "Review the policy document" },
+      { index: 1, role: "assistant", summary: "I found the policy document. It covers the review process." },
+      { index: 2, role: "user", summary: "Check the deployment pipeline" },
+      { index: 3, role: "assistant", summary: "The pipeline has a step for document generation" }, // weak match
+      { index: 4, role: "user", summary: "Fix the login bug" },
+      { index: 5, role: "assistant", summary: "Updated the document in README" }, // very weak
+    ];
+    const govMsgs: Message[] = [
+      { role: "user", content: "Review the policy document" } as any,
+      { role: "assistant", content: [{ type: "text", text: "I found the policy document. It covers the review process." }] } as any,
+      { role: "user", content: "Check the deployment pipeline" } as any,
+      { role: "assistant", content: [{ type: "text", text: "The pipeline has a step for document generation" }] } as any,
+      { role: "user", content: "Fix the login bug" } as any,
+      { role: "assistant", content: [{ type: "text", text: "Updated the document in README" }] } as any,
+    ];
+    // 2-term query: policy + review → no multi-term floor
+    // Should return both strong matches but may filter very weak ones
+    const r = searchEntries(govEntries, govMsgs, "policy review");
+    // #0 and #1 are strong matches; #3 and #5 only have "document" which isn't queried
+    expect(r.length).toBeLessThanOrEqual(2);
+    expect(r[0].index).toBe(0); // highest BM25: matches both terms
+  });
+
+  it("requires 2+ term matches for 3+ term queries", () => {
+    // Simulates a government session with common domain vocabulary
+    const govEntries: RenderedEntry[] = [
+      { index: 0, role: "user", summary: "Review the policy document" },
+      { index: 1, role: "assistant", summary: "Checking policy" }, // only 1/3 terms
+      { index: 2, role: "user", summary: "Fix login bug" }, // 0/3 terms
+      { index: 3, role: "assistant", summary: "Review policy and update document" }, // 2/3 terms
+    ];
+    const govMsgs: Message[] = [
+      { role: "user", content: "Review the policy document" } as any,
+      { role: "assistant", content: [{ type: "text", text: "Checking policy" }] } as any,
+      { role: "user", content: "Fix login bug" } as any,
+      { role: "assistant", content: [{ type: "text", text: "Review policy and update document" }] } as any,
+    ];
+    // "review policy document" = 3 terms → requires ≥2 matches
+    // #0 matches all 3, #1 matches only "policy" (1 term → filtered), #3 matches "review" + "document" (2 terms → kept)
+    const r = searchEntries(govEntries, govMsgs, "review policy document");
+    expect(r.length).toBe(2);
+    const indices = r.map((h) => h.index).sort();
+    expect(indices).toContain(0);
+    expect(indices).toContain(3);
+  });
+
+  it("hard caps regex search results", () => {
+    // Build many entries that all match the same regex
+    const manyEntries: RenderedEntry[] = Array.from({ length: 100 }, (_, i) => ({
+      index: i, role: "user" as const, summary: `document ${i} review`,
+    }));
+    const manyMsgs: Message[] = Array.from({ length: 100 }, (_, i) => ({
+      role: "user" as const, content: `document ${i} review`,
+    } as any));
+    const r = searchEntries(manyEntries, manyMsgs, "document.*review");
+    expect(r.length).toBeLessThanOrEqual(50); // MAX_SEARCH_RESULTS
+  });
+});

package/tests/support/load-session.ts

@@ -0,0 +1,23 @@
+import { buildSessionContext, loadEntriesFromFile } from "../../node_modules/@earendil-works/pi-coding-agent/dist/core/session-manager.js";
+import type { Message } from "@earendil-works/pi-ai";
+
+export interface LoadedSession {
+  messageCount: number;
+  skippedCount: number;
+  messages: Message[];
+}
+
+export const loadSessionMessages = (file: string): LoadedSession => {
+  const entries = loadEntriesFromFile(file);
+  const sessionEntries = entries.filter((entry) => entry.type !== "header");
+  const context = buildSessionContext(sessionEntries as any);
+  const messages = (context.messages as any[]).filter(
+    (msg): msg is Message =>
+      msg && typeof msg.role === "string" && "content" in msg,
+  );
+  return {
+    messageCount: messages.length,
+    skippedCount: context.messages.length - messages.length,
+    messages,
+  };
+};

package/tests/support/real-sessions.ts

@@ -0,0 +1,51 @@
+import { mkdir, mkdtemp, copyFile, chmod, readdir, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, basename } from "node:path";
+
+const SESSION_ROOT = join(process.env.HOME ?? "", ".pi/agent/sessions");
+
+export interface SessionSample {
+  source: string;
+  copy: string;
+  size: number;
+  mtimeMs: number;
+}
+
+const walk = async (dir: string): Promise<string[]> => {
+  const names = await readdir(dir, { withFileTypes: true });
+  const out: string[] = [];
+  for (const name of names) {
+    const path = join(dir, name.name);
+    if (name.isDirectory()) out.push(...await walk(path));
+    else if (name.isFile() && path.endsWith(".jsonl")) out.push(path);
+  }
+  return out;
+};
+
+const pickLargest = async (limit: number): Promise<string[]> => {
+  const files = await walk(SESSION_ROOT);
+  const sized = await Promise.all(
+    files.map(async (file) => ({ file, size: (await stat(file)).size })),
+  );
+  return sized.sort((a, b) => b.size - a.size).slice(0, limit).map((x) => x.file);
+};
+
+export const prepareSessionSamples = async (limit = 2): Promise<SessionSample[]> => {
+  const selected = await pickLargest(limit);
+  const dir = await mkdtemp(join(tmpdir(), "pi-vcc-sessions-"));
+  await mkdir(dir, { recursive: true });
+  const samples: SessionSample[] = [];
+  for (const source of selected) {
+    const srcStat = await stat(source);
+    const copy = join(dir, basename(source));
+    await copyFile(source, copy);
+    await chmod(copy, 0o444);
+    samples.push({ source, copy, size: srcStat.size, mtimeMs: srcStat.mtimeMs });
+  }
+  return samples;
+};
+
+export const readSourceStat = async (sample: SessionSample) => {
+  const s = await stat(sample.source);
+  return { size: s.size, mtimeMs: s.mtimeMs };
+};