pi-condense 2.0.0

package/src/query-tool.ts

@@ -0,0 +1,78 @@
+import { readFile } from "node:fs/promises";
+import { Type } from "@sinclair/typebox";
+import { truncateHead, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ToolCallIndexer } from "./indexer.js";
+
+export function registerQueryTool(pi: ExtensionAPI, indexer: ToolCallIndexer): void {
+  pi.registerTool({
+    name: "context_tree_query",
+    label: "Query Original Tool History",
+    description:
+      "Retrieve original tool call results that have been pruned from active context. Pass the short refs from a pruner-summary message to get back the full original outputs.",
+    promptSnippet: "Retrieve original pruned tool outputs by short ref",
+    promptGuidelines: [
+      "When you need the full output of a tool call that was summarized and pruned from context, use context_tree_query with the short refs listed in the relevant pruner-summary message.",
+    ],
+    parameters: Type.Object({
+      toolCallIds: Type.Array(Type.String({ description: "One or more short refs or tool call IDs to retrieve" }), {
+        description: "List of short refs or toolCallIds to look up",
+      }),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const foundRecords: Record<string, any> = {};
+      const blocks: string[] = [];
+
+      for (const id of params.toolCallIds) {
+        const record = indexer.getRecord(id);
+
+        if (!record) {
+          blocks.push(`## toolRef: ${id}\n(not found in index — may not have been summarized yet)`);
+          continue;
+        }
+
+        foundRecords[id] = record;
+
+        const status = record.isError ? "ERROR" : "OK";
+        const header = [
+          `## toolRef: ${id}`,
+          `Tool: ${record.toolName}`,
+          `Args: ${JSON.stringify(record.args, null, 2)}`,
+          `Status: ${status}`,
+          `Turn: ${record.turnIndex}`,
+          "",
+        ].join("\n");
+
+        let raw = record.resultText;
+        if (record.spillPath) {
+          try {
+            raw = await readFile(record.spillPath, "utf-8");
+          } catch (err) {
+            console.error(`context_tree_query: failed to read spilled output at ${record.spillPath}:`, err);
+            raw = record.resultPreview ?? "(spilled output unavailable — sidecar file missing)";
+          }
+        }
+
+        const t = truncateHead(raw, {
+          maxLines: DEFAULT_MAX_LINES,
+          maxBytes: DEFAULT_MAX_BYTES,
+        });
+
+        let body = t.content;
+        if (t.truncated) {
+          body += `\n[Output truncated: ${t.outputLines}/${t.totalLines} lines shown]`;
+        }
+
+        blocks.push(`${header}\n${body}`);
+      }
+
+      const combined = blocks.join("\n\n---\n\n");
+
+      return {
+        content: [{ type: "text", text: combined }],
+        details: { results: foundRecords },
+      };
+    },
+  });
+}

package/src/range-compression.integration.test.ts

@@ -0,0 +1,252 @@
+import { describe, expect, test } from "bun:test";
+import { ToolCallIndexer } from "./indexer.js";
+import { BlockRefIssuer } from "./block-refs.js";
+import { compressEligible } from "./chain-compressor.js";
+import { pruneMessages } from "./pruner.js";
+import { detectChains } from "./chain-detector.js";
+import { isProtected } from "./protected.js";
+import type { ChainRange, ChainCompressionConfig } from "./types.js";
+
+// End-to-end of the in-memory B path (everything except the LLM call, which is
+// the shared runSummarization already exercised live): a span's per-batch
+// summaries are fused by compressEligible, the entry lands in the real indexer's
+// chain registry, and pruneMessages renders the fused text as the synthetic body.
+describe("range compression integration", () => {
+  test("fused range summary flows compressEligible → registry → render", async () => {
+    const indexer = new ToolCallIndexer();
+    const blockRefs = new BlockRefIssuer();
+
+    // Two per-batch summaries covering the span's two tool calls.
+    indexer.registerSummaryRefs([
+      { shortId: "t1", toolCallId: "tc1" },
+      { shortId: "t2", toolCallId: "tc2" },
+    ]);
+    indexer.registerSummaryBody(["tc1"], "summary of batch 1");
+    indexer.registerSummaryBody(["tc2"], "summary of batch 2");
+
+    const chain: ChainRange = {
+      startUserTimestamp: 100,
+      middleToolCallIds: ["tc1", "tc2"],
+      finalAssistantTimestamp: 400,
+    };
+
+    const fuseInputs: string[] = [];
+    const { compressedEntries } = await compressEligible([chain], 0, {
+      indexer,
+      blockRefs,
+      appendEntry: () => {},
+      now: () => 999,
+      fuseRange: async (text) => {
+        fuseInputs.push(text);
+        return "FUSED COHESIVE SUMMARY";
+      },
+    });
+
+    // Fusion received the concatenated per-batch summaries and stored its result.
+    expect(fuseInputs).toEqual(["summary of batch 1\n\nsummary of batch 2"]);
+    expect(compressedEntries).toHaveLength(1);
+    expect(compressedEntries[0].rangeSummaryText).toBe("FUSED COHESIVE SUMMARY");
+    // Entry is now in the real registry (what the renderer reads).
+    expect(indexer.getChainEntries()[0].rangeSummaryText).toBe("FUSED COHESIVE SUMMARY");
+
+    const messages: any[] = [
+      { role: "user", content: [{ type: "text", text: "go" }], timestamp: 100 },
+      { role: "assistant", content: [{ type: "toolCall", id: "tc1", name: "bash", arguments: {} }], timestamp: 200, usage: {}, stopReason: "tool_use" },
+      { role: "toolResult", toolCallId: "tc1", toolName: "bash", content: [{ type: "text", text: "o1" }], isError: false, timestamp: 210 },
+      { role: "assistant", content: [{ type: "toolCall", id: "tc2", name: "bash", arguments: {} }], timestamp: 300, usage: {}, stopReason: "tool_use" },
+      { role: "toolResult", toolCallId: "tc2", toolName: "bash", content: [{ type: "text", text: "o2" }], isError: false, timestamp: 310 },
+      { role: "assistant", content: [{ type: "text", text: "done" }], timestamp: 400, usage: {}, stopReason: "end_turn" },
+    ];
+
+    const cc: ChainCompressionConfig = {
+      enabled: true,
+      rollingWindow: 0,
+      stripFinalAssistantThinking: true,
+      fuseRangeSummary: true,
+    };
+    const { messages: out, pruned } = pruneMessages(messages, indexer, cc);
+    expect(pruned).toBe(true);
+
+    const synthetic = out.find(
+      (m: any) => m.role === "user" && typeof m.content?.[0]?.text === "string" && m.content[0].text.startsWith("<compressed-chain"),
+    );
+    expect(synthetic).toBeDefined();
+    // Renderer used the fused summary, not the per-batch concatenation.
+    expect(synthetic.content[0].text).toContain("FUSED COHESIVE SUMMARY");
+    expect(synthetic.content[0].text).not.toContain("summary of batch 1");
+    expect(synthetic.content[0].text).toContain('tools="t1,t2"');
+
+    // Middle tool turns + their results dropped; tool outputs still recoverable via the index entries (added below).
+    expect(out.filter((m: any) => m.role === "toolResult")).toHaveLength(0);
+  });
+
+  test("protected tool output is relocated into synthetic block", async () => {
+    const indexer = new ToolCallIndexer();
+    const blockRefs = new BlockRefIssuer();
+
+    // tc1 = bash (non-protected), tc2 = todowrite (protected)
+    indexer.registerSummaryRefs([{ shortId: "t1", toolCallId: "tc1" }]);
+    indexer.registerSummaryBody(["tc1"], "bash output summary");
+
+    const chain: ChainRange = {
+      startUserTimestamp: 100,
+      middleToolCallIds: ["tc1", "tc2"],
+      finalAssistantTimestamp: 400,
+      protectedToolCallIds: ["tc2"],
+    };
+
+    const { compressedEntries } = await compressEligible([chain], 0, {
+      indexer,
+      blockRefs,
+      appendEntry: () => {},
+      now: () => 999,
+    });
+
+    expect(compressedEntries).toHaveLength(1);
+    // protectedToolCallIds round-trips through the real registry
+    expect(indexer.getChainEntries()[0].protectedToolCallIds).toEqual(["tc2"]);
+
+    const messages: any[] = [
+      { role: "user", content: [{ type: "text", text: "go" }], timestamp: 100 },
+      { role: "assistant", content: [{ type: "toolCall", id: "tc1", name: "bash", arguments: {} }], timestamp: 200, usage: {}, stopReason: "tool_use" },
+      { role: "toolResult", toolCallId: "tc1", toolName: "bash", content: [{ type: "text", text: "bash-result" }], isError: false, timestamp: 210 },
+      { role: "assistant", content: [{ type: "toolCall", id: "tc2", name: "todowrite", arguments: {} }], timestamp: 300, usage: {}, stopReason: "tool_use" },
+      { role: "toolResult", toolCallId: "tc2", toolName: "todowrite", content: [{ type: "text", text: "PLAN-STATE-XYZ" }], isError: false, timestamp: 310 },
+      { role: "assistant", content: [{ type: "text", text: "done" }], timestamp: 400, usage: {}, stopReason: "end_turn" },
+    ];
+
+    const cc: ChainCompressionConfig = {
+      enabled: true,
+      rollingWindow: 0,
+      stripFinalAssistantThinking: true,
+      fuseRangeSummary: false,
+    };
+    const { messages: out, pruned } = pruneMessages(messages, indexer, cc);
+    expect(pruned).toBe(true);
+
+    const synthetic = out.find(
+      (m: any) => m.role === "user" && typeof m.content?.[0]?.text === "string" && m.content[0].text.startsWith("<compressed-chain"),
+    );
+    expect(synthetic).toBeDefined();
+    // Protected output is embedded in the synthetic block
+    expect(synthetic.content[0].text).toContain('<protected-output tool="todowrite">');
+    expect(synthetic.content[0].text).toContain("PLAN-STATE-XYZ");
+    // Protected toolResult is no longer a standalone message
+    expect(out.filter((m: any) => m.role === "toolResult")).toHaveLength(0);
+    // protected tool has no short ref in production → absent from the tools= attribute
+    expect(synthetic.content[0].text).not.toContain("t2");
+  });
+
+  test("path-protected output is relocated via detectChains predicate", async () => {
+    const indexer = new ToolCallIndexer();
+    const blockRefs = new BlockRefIssuer();
+
+    // tc1 = read /h/src/app.ts (unprotected), tc2 = read /h/skills/x/SKILL.md (protected)
+    const messages: any[] = [
+      { role: "user", content: [{ type: "text", text: "go" }], timestamp: 100 },
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "tc1", name: "read", input: { path: "/h/src/app.ts" } }],
+        timestamp: 200,
+        usage: {},
+        stopReason: "tool_use",
+      },
+      {
+        role: "toolResult",
+        toolCallId: "tc1",
+        toolName: "read",
+        content: [{ type: "text", text: "app-source-code" }],
+        isError: false,
+        timestamp: 210,
+      },
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "tc2", name: "read", input: { path: "/h/skills/x/SKILL.md" } }],
+        timestamp: 300,
+        usage: {},
+        stopReason: "tool_use",
+      },
+      {
+        role: "toolResult",
+        toolCallId: "tc2",
+        toolName: "read",
+        content: [{ type: "text", text: "SKILL-VERBATIM-CONTENT" }],
+        isError: false,
+        timestamp: 310,
+      },
+      { role: "assistant", content: [{ type: "text", text: "done" }], timestamp: 400, usage: {}, stopReason: "end_turn" },
+    ];
+
+    const pred = (name: string, args: unknown) =>
+      isProtected(name, args, { protectedTools: [], protectedPaths: ["**/skills/**/*.md"] });
+    const chains = detectChains(messages, pred);
+
+    expect(chains).toHaveLength(1);
+    expect(chains[0].protectedToolCallIds).toEqual(["tc2"]);
+
+    // Only unprotected tc1 has a per-batch summary; tc2 is protected, no short ref.
+    indexer.registerSummaryRefs([{ shortId: "t1", toolCallId: "tc1" }]);
+    indexer.registerSummaryBody(["tc1"], "read app.ts summary");
+
+    const { compressedEntries } = await compressEligible(chains, 0, {
+      indexer,
+      blockRefs,
+      appendEntry: () => {},
+      now: () => 999,
+    });
+
+    expect(compressedEntries).toHaveLength(1);
+    expect(indexer.getChainEntries()[0].protectedToolCallIds).toEqual(["tc2"]);
+
+    const cc: ChainCompressionConfig = {
+      enabled: true,
+      rollingWindow: 0,
+      stripFinalAssistantThinking: true,
+      fuseRangeSummary: false,
+    };
+    const { messages: out, pruned } = pruneMessages(messages, indexer, cc);
+    expect(pruned).toBe(true);
+
+    const synthetic = out.find(
+      (m: any) => m.role === "user" && typeof m.content?.[0]?.text === "string" && m.content[0].text.startsWith("<compressed-chain"),
+    );
+    expect(synthetic).toBeDefined();
+    // Protected SKILL.md output is embedded verbatim
+    expect(synthetic.content[0].text).toContain('<protected-output tool="read">');
+    expect(synthetic.content[0].text).toContain("SKILL-VERBATIM-CONTENT");
+    // Unprotected result text is not present in the synthetic block
+    expect(synthetic.content[0].text).not.toContain("app-source-code");
+    // No standalone toolResult messages remain
+    expect(out.filter((m: any) => m.role === "toolResult")).toHaveLength(0);
+    // Protected tc2 has no short ref → absent from the tools= attribute
+    expect(synthetic.content[0].text).not.toContain("t2");
+  });
+
+  test("falls back to per-batch concat when fuseRange is absent", async () => {
+    const indexer = new ToolCallIndexer();
+    const blockRefs = new BlockRefIssuer();
+    indexer.registerSummaryRefs([
+      { shortId: "t1", toolCallId: "tc1" },
+      { shortId: "t2", toolCallId: "tc2" },
+    ]);
+    indexer.registerSummaryBody(["tc1"], "batch one body");
+    indexer.registerSummaryBody(["tc2"], "batch two body");
+
+    const chain: ChainRange = { startUserTimestamp: 100, middleToolCallIds: ["tc1", "tc2"], finalAssistantTimestamp: 400 };
+    await compressEligible([chain], 0, { indexer, blockRefs, appendEntry: () => {}, now: () => 1 });
+
+    const messages: any[] = [
+      { role: "user", content: [{ type: "text", text: "go" }], timestamp: 100 },
+      { role: "assistant", content: [{ type: "toolCall", id: "tc1", name: "bash", arguments: {} }], timestamp: 200, usage: {}, stopReason: "tool_use" },
+      { role: "toolResult", toolCallId: "tc1", toolName: "bash", content: [{ type: "text", text: "o1" }], isError: false, timestamp: 210 },
+      { role: "assistant", content: [{ type: "toolCall", id: "tc2", name: "bash", arguments: {} }], timestamp: 300, usage: {}, stopReason: "tool_use" },
+      { role: "toolResult", toolCallId: "tc2", toolName: "bash", content: [{ type: "text", text: "o2" }], isError: false, timestamp: 310 },
+      { role: "assistant", content: [{ type: "text", text: "done" }], timestamp: 400, usage: {}, stopReason: "end_turn" },
+    ];
+    const cc: ChainCompressionConfig = { enabled: true, rollingWindow: 0, stripFinalAssistantThinking: true, fuseRangeSummary: false };
+    const { messages: out } = pruneMessages(messages, indexer, cc);
+    const synthetic = out.find((m: any) => m.role === "user" && m.content?.[0]?.text?.startsWith("<compressed-chain"));
+    expect(synthetic.content[0].text).toContain("batch one body");
+    expect(synthetic.content[0].text).toContain("batch two body");
+  });
+});

package/src/spill.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "bun:test";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { sanitizeId, blobDirFor, blobPathFor, headPreview, spillOversizedBatch } from "./spill.js";
+import { ToolCallIndexer } from "./indexer.js";
+import type { CapturedBatch } from "./types.js";
+
+describe("sanitizeId", () => {
+  it("replaces path separators and unsafe chars", () => {
+    expect(sanitizeId("toolu_abc-123")).toBe("toolu_abc-123");
+    expect(sanitizeId("../../etc/passwd")).toBe("______etc_passwd");
+    expect(sanitizeId("a/b\\c")).toBe("a_b_c");
+  });
+});
+
+describe("blobDirFor / blobPathFor", () => {
+  it("builds <sessionDir>/<sessionId>-blobs/<id>.txt", () => {
+    expect(blobDirFor("/s", "sid")).toBe(join("/s", "sid-blobs"));
+    expect(blobPathFor("/s", "sid", "tc1")).toBe(join("/s", "sid-blobs", "tc1.txt"));
+  });
+});
+
+describe("headPreview", () => {
+  it("returns the whole string when under the byte cap", () => {
+    expect(headPreview("hello", 1024)).toBe("hello");
+  });
+  it("cuts at a line boundary when one exists in budget", () => {
+    expect(headPreview("aaaa\nbbbb\ncccc", 7)).toBe("aaaa");
+  });
+  it("never exceeds the byte cap and stays valid UTF-8", () => {
+    const s = "é".repeat(100);
+    const out = headPreview(s, 11);
+    expect(Buffer.byteLength(out, "utf8")).toBeLessThanOrEqual(11);
+    expect(() => Buffer.from(out, "utf8").toString("utf8")).not.toThrow();
+  });
+});
+
+describe("spillOversizedBatch", () => {
+  const cfg = { spillThreshold: 10, spillPreviewBytes: 8, dedupByContentHash: true };
+  const mkBatch = (toolCalls: any[]): CapturedBatch => ({ turnIndex: 0, timestamp: 1, assistantText: "", toolCalls });
+
+  it("spills an oversized result: writes file, mutates record, indexes it", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const batch = mkBatch([{ toolCallId: "tc1", toolName: "fetch", args: {}, resultText: "X".repeat(50), isError: false }]);
+      const spilled = await spillOversizedBatch({ batch, indexer, config: cfg, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      expect(spilled.has("tc1")).toBe(true);
+      const rec = indexer.getRecord("tc1")!;
+      expect(rec.spillPath).toBe(blobPathFor(dir, "sid", "tc1"));
+      expect(rec.spillBytes).toBe(50);
+      expect(rec.resultText).toBe("");
+      expect(rec.resultPreview!.length).toBeGreaterThan(0);
+      expect(await readFile(rec.spillPath!, "utf-8")).toBe("X".repeat(50));
+      expect(indexer.isSummarized("tc1")).toBe(true);
+    } finally { await rm(dir, { recursive: true, force: true }); }
+  });
+
+  it("leaves a small result untouched (not spilled)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const batch = mkBatch([{ toolCallId: "tc1", toolName: "bash", args: {}, resultText: "tiny", isError: false }]);
+      const spilled = await spillOversizedBatch({ batch, indexer, config: cfg, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      expect(spilled.size).toBe(0);
+      expect(indexer.isSummarized("tc1")).toBe(false);
+    } finally { await rm(dir, { recursive: true, force: true }); }
+  });
+
+  it("leaves the tool call untouched when the sidecar write fails", async () => {
+    const base = await mkdtemp(join(tmpdir(), "spill-"));
+    const filePath = join(base, "not-a-dir");
+    await writeFile(filePath, "x"); // sessionDir is a FILE → mkdir under it throws
+    try {
+      const indexer = new ToolCallIndexer();
+      const big = "Z".repeat(50);
+      const batch = mkBatch([{ toolCallId: "tc1", toolName: "fetch", args: {}, resultText: big, isError: false }]);
+      const spilled = await spillOversizedBatch({ batch, indexer, config: cfg, sessionDir: filePath, sessionId: "sid", appendEntry: () => {} });
+      expect(spilled.size).toBe(0);
+      expect(indexer.isSummarized("tc1")).toBe(false);
+      expect(batch.toolCalls[0].resultText).toBe(big); // untouched
+    } finally {
+      await rm(base, { recursive: true, force: true });
+    }
+  });
+
+  it("dedups an oversized duplicate to the original without a second file", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const body = "Y".repeat(50);
+      const append = () => {};
+      await spillOversizedBatch({ batch: mkBatch([{ toolCallId: "tc1", toolName: "fetch", args: {}, resultText: body, isError: false }]), indexer, config: cfg, sessionDir: dir, sessionId: "sid", appendEntry: append });
+      const spilled2 = await spillOversizedBatch({ batch: mkBatch([{ toolCallId: "tc2", toolName: "fetch", args: {}, resultText: body, isError: false }]), indexer, config: cfg, sessionDir: dir, sessionId: "sid", appendEntry: append });
+      expect(spilled2.has("tc2")).toBe(true);
+      expect(indexer.isSummarized("tc2")).toBe(true);
+      expect(indexer.getRecord("tc2")!.toolCallId).toBe("tc1");
+      await expect(readFile(blobPathFor(dir, "sid", "tc2"), "utf-8")).rejects.toBeDefined();
+    } finally { await rm(dir, { recursive: true, force: true }); }
+  });
+});

package/src/spill.ts

@@ -0,0 +1,90 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { CapturedBatch, CapturedToolCall } from "./types.js";
+import type { ToolCallIndexer } from "./indexer.js";
+import { hashToolResult } from "./content-hash.js";
+
+/** Replace anything outside [A-Za-z0-9_-] so the id can't escape the blob dir. */
+export function sanitizeId(toolCallId: string): string {
+  return toolCallId.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+
+export function blobDirFor(sessionDir: string, sessionId: string): string {
+  return join(sessionDir, `${sessionId}-blobs`);
+}
+
+export function blobPathFor(sessionDir: string, sessionId: string, toolCallId: string): string {
+  return join(blobDirFor(sessionDir, sessionId), `${sanitizeId(toolCallId)}.txt`);
+}
+
+/** Head of `text` capped at `maxBytes` (UTF-8 safe), preferring a line boundary. */
+export function headPreview(text: string, maxBytes: number): string {
+  const buf = Buffer.from(text, "utf8");
+  if (buf.length <= maxBytes) return text;
+  let end = maxBytes;
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end--;
+  let slice = buf.subarray(0, end).toString("utf8");
+  const lastNl = slice.lastIndexOf("\n");
+  if (lastNl > 0) slice = slice.slice(0, lastNl);
+  return slice;
+}
+
+interface SpillConfig {
+  spillThreshold: number;
+  spillPreviewBytes: number;
+  dedupByContentHash: boolean;
+}
+
+export async function spillOversizedBatch(args: {
+  batch: CapturedBatch;
+  indexer: ToolCallIndexer;
+  config: SpillConfig;
+  sessionDir: string;
+  sessionId: string;
+  appendEntry: (customType: string, data?: unknown) => void;
+}): Promise<Set<string>> {
+  const { batch, indexer, config, sessionDir, sessionId, appendEntry } = args;
+  const handled = new Set<string>();
+  const toIndex: CapturedToolCall[] = [];
+
+  for (const tc of batch.toolCalls) {
+    if (tc.resultText.length < config.spillThreshold) continue;
+
+    const hash = hashToolResult(tc.toolName, tc.resultText);
+
+    if (config.dedupByContentHash) {
+      const original = indexer.lookupByContent(tc.toolName, tc.resultText);
+      if (original && original !== tc.toolCallId) {
+        indexer.registerDuplicate(tc.toolCallId, original, appendEntry);
+        handled.add(tc.toolCallId);
+        continue;
+      }
+    }
+
+    const path = blobPathFor(sessionDir, sessionId, tc.toolCallId);
+    try {
+      await mkdir(blobDirFor(sessionDir, sessionId), { recursive: true });
+      await writeFile(path, tc.resultText, "utf-8");
+    } catch (err) {
+      console.error(`spill: failed to write sidecar for ${tc.toolCallId} at ${path}:`, err);
+      continue;
+    }
+
+    tc.spillBytes = Buffer.byteLength(tc.resultText, "utf8");
+    tc.resultPreview = headPreview(tc.resultText, config.spillPreviewBytes);
+    tc.spillPath = path;
+    tc.contentHash = hash;
+    tc.resultText = "";
+    toIndex.push(tc);
+    handled.add(tc.toolCallId);
+  }
+
+  if (toIndex.length > 0) {
+    indexer.addBatch(
+      { turnIndex: batch.turnIndex, timestamp: batch.timestamp, assistantText: "", toolCalls: toIndex },
+      appendEntry,
+    );
+  }
+
+  return handled;
+}

package/src/stats.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "bun:test";
+import {
+  StatsAccumulator,
+  emitExternalCost,
+} from "./stats.js";
+import {
+  CUSTOM_TYPE_STATS,
+  EXTERNAL_COST_CHANNEL,
+  EXTERNAL_COST_SOURCE,
+} from "./types.js";
+
+// Minimal Usage shape matching the private interface in stats.ts
+function makeUsage(input: number, output: number, costTotal: number) {
+  return {
+    input,
+    output,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: input + output,
+    cost: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      total: costTotal,
+    },
+  };
+}
+
+describe("StatsAccumulator.getSessionDelta", () => {
+  it("(a) fresh accumulator: delta equals what was added", () => {
+    const acc = new StatsAccumulator();
+    acc.add(makeUsage(100, 50, 0.01));
+    const delta = acc.getSessionDelta();
+    expect(delta.totalCost).toBeCloseTo(0.01);
+    expect(delta.inputTokens).toBe(100);
+    expect(delta.outputTokens).toBe(50);
+  });
+
+  it("(b) after reconstructFromSession, prior totals are excluded from delta", () => {
+    const acc = new StatsAccumulator();
+
+    // Build a mock ctx that returns one CUSTOM_TYPE_STATS entry with prior totals
+    const priorStats = {
+      totalInputTokens: 500,
+      totalOutputTokens: 250,
+      totalCost: 0.05,
+      callCount: 3,
+      chainsCompressed: 1,
+      rangesSummarized: 0,
+    };
+    const mockCtx = {
+      sessionManager: {
+        getBranch: () => [
+          {
+            type: "custom",
+            customType: CUSTOM_TYPE_STATS,
+            data: priorStats,
+          },
+        ],
+      },
+    } as any;
+
+    acc.reconstructFromSession(mockCtx);
+
+    // Delta should be zero right after reconstruction
+    const deltaAfterRecon = acc.getSessionDelta();
+    expect(deltaAfterRecon.totalCost).toBeCloseTo(0);
+    expect(deltaAfterRecon.inputTokens).toBe(0);
+    expect(deltaAfterRecon.outputTokens).toBe(0);
+
+    // A subsequent add should show only the new spend
+    acc.add(makeUsage(200, 80, 0.02));
+    const deltaAfterAdd = acc.getSessionDelta();
+    expect(deltaAfterAdd.totalCost).toBeCloseTo(0.02);
+    expect(deltaAfterAdd.inputTokens).toBe(200);
+    expect(deltaAfterAdd.outputTokens).toBe(80);
+  });
+});
+
+describe("StatsAccumulator.getLiveReclaim / setLiveReclaim", () => {
+  it("(c) undefined initially; round-trips after set", () => {
+    const acc = new StatsAccumulator();
+    expect(acc.getLiveReclaim()).toBeUndefined();
+    acc.setLiveReclaim(1000, 200);
+    expect(acc.getLiveReclaim()).toEqual({ beforeChars: 1000, afterChars: 200 });
+  });
+});
+
+describe("emitExternalCost", () => {
+  it("(d) emits exactly one event on EXTERNAL_COST_CHANNEL with session delta", () => {
+    const acc = new StatsAccumulator();
+    acc.add(makeUsage(100, 50, 0.01));
+
+    const calls: Array<{ channel: string; data: unknown }> = [];
+    const fakePi = {
+      events: {
+        emit: (channel: string, data: unknown) => {
+          calls.push({ channel, data });
+        },
+      },
+    } as any;
+
+    emitExternalCost(fakePi, acc);
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].channel).toBe(EXTERNAL_COST_CHANNEL);
+    const payload = calls[0].data as any;
+    expect(payload.source).toBe(EXTERNAL_COST_SOURCE);
+    expect(payload.totalCost).toBeCloseTo(0.01);
+    expect(payload.inputTokens).toBe(100);
+    expect(payload.outputTokens).toBe(50);
+  });
+});