pi-condense 2.10.0 → 2.10.1

package/CHANGELOG.md

@@ -7,6 +7,10 @@ Published to npm as [`pi-condense`](https://www.npmjs.com/package/pi-condense) (
 Pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which runs the tests and
 publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
+## [2.10.1] - 2026-09-02
+
+- **Spill sidecar basenames capped at 255 bytes ([#14](https://github.com/jjuraszek/pi-condense/issues/14)).** Providers emitting 300+ char tool-call ids drove `blobPathFor` past the filesystem basename limit: eager spill failed silently (`ENAMETOOLONG` caught, oversized result stayed inline and bloated context) and the deterministic backfill aborted fail-closed. Fitting names stay byte-identical; over-limit names become `<234-byte sanitized prefix>.<16-hex sha1 of the unsanitized occurrence key>.txt` (exactly 255 bytes). The `.` separator is unreachable by `sanitizeId`, so capped names are namespace-disjoint from short-key names by construction - no probe, no migration, persisted `spillPath` read-back unchanged. Spec: `doc/specs/2026-09-02-gh-14-spill-filename-cap.md` (partially supersedes the 2026-06-02 spill spec's filename derivation).
+
 ## [2.10.0] - 2026-09-01
 
 - **Custom-message chain anchors ([#13](https://github.com/jjuraszek/pi-condense/issues/13)).** A non-pruner `role: "custom"` message (`customType` not prefixed `context-prune-`) can now open a chain, but only while the chain detector is idle - a non-pruner custom seen mid-chain stays passthrough, not a new anchor. `resolveRange` accepts these as start anchors fail-closed; persisted `custom_message` steers reach chain detection through a shared projection (`src/batch-capture.ts` `projectBranchMessages`); in `agent-message` batching, eligible customs also bound summary groups.

package/PRUNING.md

@@ -630,7 +630,7 @@ Names and patterns that don't match any captured tool call are silently ignored.
 
 `spillThreshold: number` (default `65536`) is a capture-time safeguard for outsized single tool results (e.g. a 1 MB web fetch, a full binary diff). When a single `ToolResultMessage`'s `resultText.length` reaches the threshold, the result is spilled immediately at `turn_end` — before the pending-queue trim and before any LLM call.
 
-**Sidecar location:** `<sessionDir>/<sessionId>-blobs/<sanitizedToolCallId>.txt`.
+**Sidecar location:** `<sessionDir>/<sessionId>-blobs/<sanitizedToolCallId>.txt`. When that basename would exceed 255 bytes (very long provider tool-call ids), it is capped to exactly 255 bytes as `<first 234 bytes of the sanitized key>.<16-hex sha1 of the unsanitized occurrence key>.txt`; names that already fit are unchanged.
 
 **Index entry:** `addBatch` is called synchronously with the spilled body (no LLM round-trip). The record is immediately `isSummarized = true`; the pruner emits a mechanical file-pointer stub:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.10.0",
+  "version": "2.10.1",
   "description": "Pi coding-agent extension that summarizes completed tool-call batches, replaces raw outputs with short stubs, compresses closed tool-call chains, and recovers any original on demand via context_tree_query.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/oversized-spill.integration.test.ts

@@ -1,8 +1,9 @@
 import { describe, it, expect } from "bun:test";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { ToolCallIndexer } from "./indexer.js";
+import { occKey } from "./occurrence-key.js";
 import { spillOversizedBatch, blobPathFor } from "./spill.js";
 import { pruneMessages } from "./pruner.js";
 import type { CapturedBatch } from "./types.js";
@@ -75,4 +76,51 @@ describe("oversized spill end-to-end", () => {
       await rm(dir, { recursive: true, force: true });
     }
   });
+
+  it("long-id record survives the backfill -> restart round trip (AC4)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-e2e-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const entries: any[] = [];
+      const appendEntry = (customType: string, data?: unknown) => {
+        entries.push({ type: "custom", customType, data });
+      };
+      const longId = "toolu_" + "q".repeat(494); // 500 chars
+      const body = "BACKFILL BODY\n".repeat(200);
+      const rec: any = {
+        toolCallId: longId, toolName: "bash", args: { command: "ls" },
+        resultText: body, isError: false, turnIndex: -1, timestamp: 1000, resultTimestamp: 1000,
+      };
+
+      // 1. backfill write: must not throw (fail-closed path), basename capped
+      await indexer.backfillChainRecords([rec], {
+        spillThreshold: 10, spillPreviewBytes: 16, sessionDir: dir, sessionId: "sid", appendEntry,
+      });
+      expect(rec.spillPath).toBeTruthy();
+      expect(Buffer.byteLength(basename(rec.spillPath), "utf8")).toBeLessThanOrEqual(255);
+
+      // 2. persisted index entry exists (backfilled shape)
+      expect(entries.some((e) => e.customType === CUSTOM_TYPE_INDEX && e.data.backfilled)).toBe(true);
+
+      // 3. restart: fresh indexer reconstructs from persisted entries only
+      const rebuilt = new ToolCallIndexer();
+      rebuilt.reconstructFromSession({ sessionManager: { getBranch: () => entries } } as any);
+      const restored = rebuilt.getRecord(occKey(longId, 1000))!;
+      expect(restored.spillPath).toBe(rec.spillPath);
+
+      // 4. read-back of the restored persisted path equals the original body
+      expect(await readFile(restored.spillPath!, "utf-8")).toBe(body);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("capped names are namespace-disjoint from short-key names", () => {
+    const cappedPath = blobPathFor("/s", "sid", "a".repeat(300));
+    const stem = basename(cappedPath).slice(0, -".txt".length);
+    // sanitizeId can never emit ".", so no short key maps onto a capped name -
+    // even the short key spelled exactly like the capped stem.
+    expect(stem).toContain(".");
+    expect(blobPathFor("/s", "sid", stem)).not.toBe(cappedPath);
+  });
 });

package/src/spill.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "bun:test";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { sanitizeId, blobDirFor, blobPathFor, headPreview, spillOversizedBatch } from "./spill.js";
 import { ToolCallIndexer } from "./indexer.js";
 import { registerQueryTool } from "./query-tool.js";
@@ -24,6 +24,41 @@ describe("blobDirFor / blobPathFor", () => {
   });
 });
 
+describe("blobPathFor byte cap (gh-14)", () => {
+  const nameBytes = (p: string) => Buffer.byteLength(basename(p), "utf8");
+
+  it("251-byte sanitized base keeps today's formula (AC5 boundary, just-under)", () => {
+    const id = "a".repeat(251);
+    const p = blobPathFor("/s", "sid", id);
+    expect(p).toBe(join("/s", "sid-blobs", `${id}.txt`));
+    expect(nameBytes(p)).toBe(255);
+  });
+
+  it("252-byte sanitized base is capped to exactly 255 bytes (AC5 boundary, just-over)", () => {
+    const p = blobPathFor("/s", "sid", "a".repeat(252));
+    expect(nameBytes(p)).toBe(255);
+    expect(basename(p)).toMatch(/^a{234}\.[0-9a-f]{16}\.txt$/);
+  });
+
+  it("is deterministic: same long key -> identical path", () => {
+    const key = "x".repeat(500);
+    expect(blobPathFor("/s", "sid", key)).toBe(blobPathFor("/s", "sid", key));
+  });
+
+  it("two long ids sharing the first 300 chars map to distinct filenames (AC3)", () => {
+    const a = "t".repeat(300) + "A".repeat(200);
+    const b = "t".repeat(300) + "B".repeat(200);
+    expect(blobPathFor("/s", "sid", a)).not.toBe(blobPathFor("/s", "sid", b));
+  });
+
+  it("hashes the unsanitized key: long ids that sanitize identically stay distinct", () => {
+    const a = "p".repeat(300) + "/x";
+    const b = "p".repeat(300) + "\\x";
+    expect(sanitizeId(a)).toBe(sanitizeId(b));
+    expect(blobPathFor("/s", "sid", a)).not.toBe(blobPathFor("/s", "sid", b));
+  });
+});
+
 describe("headPreview", () => {
   it("returns the whole string when under the byte cap", () => {
     expect(headPreview("hello", 1024)).toBe("hello");
@@ -206,4 +241,39 @@ describe("spillOversizedBatch", () => {
       await expect(readFile(blobPathFor(dir, "sid", "tc2"), "utf-8")).rejects.toBeDefined();
     } finally { await rm(dir, { recursive: true, force: true }); }
   });
+
+  it("spills a 500-char tool-call id: file created, capped basename, record mutated (AC1)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const longId = "toolu_" + "k".repeat(494); // 500 chars
+      const body = "LONG-ID BODY ".repeat(10);
+      const batch = mkBatch([{ toolCallId: longId, toolName: "fetch", args: {}, resultText: body, isError: false, resultTimestamp: 1150 }]);
+      const spilled = await spillOversizedBatch({ batch, indexer, config: cfg, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      expect(spilled.has(longId)).toBe(true);
+      const rec = indexer.getRecord(occKey(longId, 1150))!;
+      expect(rec.resultText).toBe("");
+      expect(rec.resultPreview!.length).toBeGreaterThan(0);
+      expect(Buffer.byteLength(basename(rec.spillPath!), "utf8")).toBeLessThanOrEqual(255);
+      expect(await readFile(rec.spillPath!, "utf-8")).toBe(body);
+    } finally { await rm(dir, { recursive: true, force: true }); }
+  });
+
+  it("same 500-char id at two occurrences spills to two distinct files (AC2)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const longId = "toolu_" + "k".repeat(494);
+      const noDedup = { ...cfg, dedupByContentHash: false };
+      const b1 = mkBatch([{ toolCallId: longId, toolName: "bash", args: {}, resultText: "FIRST".repeat(20), isError: false, resultTimestamp: 1150 }]);
+      const b2 = mkBatch([{ toolCallId: longId, toolName: "bash", args: {}, resultText: "SECOND".repeat(20), isError: false, resultTimestamp: 3150 }]);
+      await spillOversizedBatch({ batch: b1, indexer, config: noDedup, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      await spillOversizedBatch({ batch: b2, indexer, config: noDedup, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      const rec1 = indexer.getRecord(occKey(longId, 1150))!;
+      const rec2 = indexer.getRecord(occKey(longId, 3150))!;
+      expect(rec1.spillPath).not.toBe(rec2.spillPath);
+      expect(await readFile(rec1.spillPath!, "utf-8")).toBe("FIRST".repeat(20));
+      expect(await readFile(rec2.spillPath!, "utf-8")).toBe("SECOND".repeat(20));
+    } finally { await rm(dir, { recursive: true, force: true }); }
+  });
 });

package/src/spill.ts

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
 import type { CapturedBatch, CapturedToolCall } from "./types.js";
 import type { ToolCallIndexer } from "./indexer.js";
 import { hashToolResult } from "./content-hash.js";
@@ -15,7 +16,18 @@ export function blobDirFor(sessionDir: string, sessionId: string): string {
 }
 
 export function blobPathFor(sessionDir: string, sessionId: string, toolCallId: string): string {
-  return join(blobDirFor(sessionDir, sessionId), `${sanitizeId(toolCallId)}.txt`);
+  const base = sanitizeId(toolCallId);
+  // 255-byte basename cap (gh-14). Uncapped budget: 255 - ".txt" = 251.
+  // Capped: 234-byte prefix + "." + 16-hex sha1 + ".txt" = 255 exactly.
+  // sanitizeId output is ASCII, so slice counts bytes. The "." separator is
+  // unreachable by sanitizeId, keeping capped names disjoint from short-key
+  // names. The hash covers the UNsanitized key so ids that sanitize
+  // identically stay distinct.
+  const name =
+    Buffer.byteLength(base, "utf8") <= 251
+      ? `${base}.txt`
+      : `${base.slice(0, 234)}.${createHash("sha1").update(toolCallId).digest("hex").slice(0, 16)}.txt`;
+  return join(blobDirFor(sessionDir, sessionId), name);
 }
 
 /** Head of `text` capped at `maxBytes` (UTF-8 safe), preferring a line boundary. */