pi-cliffcompaction 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.0
+
+Tests live in `tests/`. Public docs use `--`. `bench/` stays local.
+
 ## 0.1.0
 
 First release. Port of CliffCompaction (Nguyen, Cho, Chen & Dettmers,

package/README.md

@@ -23,7 +23,7 @@ After install, **fully restart** Pi/OMP. `/reload` can keep old JavaScript modul
 
 ---
 
-## Why use it
+## Compared to Pi compact
 
 Default Pi compact asks a model to write a structured memo (`Goal`, `Progress`, `Key Decisions`, file lists). Tool dumps are truncated for that summarizer, then rewritten. The last ~20k tokens stay verbatim. The previous memo is fed into the next one.
 
@@ -49,11 +49,6 @@ This package keeps the same *when* (token window, overflow, `/compact`) and repl
 
 ## Install
 
-```bash
-pi install npm:pi-cliffcompaction
-omp install npm:pi-cliffcompaction
-```
-
 From a clone of [AdityaVG13/pi-stack](https://github.com/AdityaVG13/pi-stack), inside the repo:
 
 ```bash
@@ -201,7 +196,7 @@ Override path: `PI_CLIFF_CONFIG` / `OMP_CLIFF_CONFIG`, or `PI_CONFIG_DIR` / `OMP
 | `keepThinking` | `true` | Fold thinking as text; `false` drops it |
 | `cmdMaxChars` | `150` | Tool-call signature budget |
 | `resultMaxChars` | `500` | Longer tool results are dropped |
-| `humanMaxChars` | `20000` | Sanity cap on user text in the summary |
+| `humanMaxChars` | `20000` | Cap on summarized middle user text; not the protected live head |
 | `shadow` | `false` | Cancel compaction; log what would have happened |
 | `strict` | `false` | Walk summary truncation (rung 3) when still over the library threshold |
 | `thresholdTokens` | `200000` | Engine/library trigger (chars/4). Pi's own trigger is separate |
@@ -235,7 +230,9 @@ The Pi extension is a thin adapter. The algorithm is importable with no Pi host:
 | `Engine.reactive(ctx)` | Context-length error ladder. |
 | Dialects | `anthropic`, `openai` (Chat Completions), `openai-responses`, `pi` |
 
-Token estimate is chars/4 on `json.dumps`-style serialization, except images which are priced from PNG/JPEG/GIF/WebP dimensions (Anthropic 28x28 patches, cap 4784).
+Token estimates use the floor of serialized UTF-16 code units / 4, with Python-style separators but JavaScript number/string semantics. This is not a tokenizer. Images use PNG/JPEG/GIF/WebP dimensions (28x28 patches, capped at 4784); raw base64, data URLs and Pi image blocks are recognized. Unknown dimensions conservatively cost 4784 without fetching remote URLs.
+
+Digests are implementation-local: key ordering, floating-point formatting and Unicode counts can differ from CPython. The shared ASCII reference fixtures do not establish general cross-language hash compatibility. Library inputs must be JSON data.
 
 ---
 
@@ -244,15 +241,20 @@ Token estimate is chars/4 on `json.dumps`-style serialization, except images whi
 - Summaries contain only excerpts of original text, never a paraphrase.
 - Exactly one summary header after compaction; re-compaction does not nest.
 - Head messages and kept tail messages are identity-equal to the input objects (library `compact` / `Engine`).
-- A mutated history fails to match the prefix store and is forwarded verbatim.
+- `Engine.prepare` validates every message against its current serialized content, including nested in-place edits. Only identical content can reuse a digest/cost; hash-chain prefixes are reused only while canonical digests agree. The engine retains snapshots for its latest request, not every visited branch.
+- Cached summaries are scoped to the dialect, configuration and fixed request budget. Emergency escalation/truncation stays request-local. Changed canonical content cannot reuse a summary covering the old content.
+- Prefix-store entry and serialized UTF-8 byte caps are hard admission limits. Oversized entries are not cached and do not evict useful entries; zero capacity disables admission. These are not total heap limits.
+- OpenAI Chat summary keys include the effective `reasoning_content` / `reasoning` text so reasoning redactions invalidate old summaries.
 - Image token cost does not track base64 length.
 
 ## Error model
 
 - `compact` returns `null` when there is no assistant turn, not enough turns to keep, or the rewrite would not shrink the list.
 - `Engine.prepare` never throws on a well-formed body; store misses and inconsistent entries fail-open to passthrough.
-- The Pi hook catches handler errors and returns undefined (Pi default compaction).
-- `strict: true` on the engine marks `overBudget` after the ladder; the Pi hook uses rung 3 truncation when `strict` is set.
+- The Pi hook catches handler errors and returns undefined (Pi default compaction). Protected heads containing images or other non-text content also use this fallback, rather than silently losing attachments. The fallback may use an LLM and does not preserve image bytes verbatim.
+- Pi compaction keeps the original head across successive cliffs, without recycling an old summary or retaining the discarded middle. Protected head text is not trimmed, truncated or interpreted as a summary marker.
+- Strict truncation packs against the actual local billable estimate, including escaping and the kept tail. Library head messages and the Pi hook's folded live head text are protected, even when that floor cannot fit.
+- The engine exposes `overBudget`; the Pi hook persists `details.overBudget` with its estimate. Neither silently drops the protected task or tail to force a fit.
 
 ## Tests
 
@@ -260,16 +262,15 @@ Token estimate is chars/4 on `json.dumps`-style serialization, except images whi
 npm test --prefix packages/pi-cliffcompaction
 ```
 
-119 tests, including `test/reference-gold.test.mjs`: bit-level checks against the Python reference on shared fixtures (compact output, hash chains, billable chars, `Engine.prepare` cuts/estimates, published image-token table).
+Tests cover content-validated caching/redaction, warm/cold equivalence, escaped budget boundaries, cache admission, image accounting and protected Pi task text. `tests/reference-gold.test.mjs` checks the shared reference fixtures; `tests/json.test.mjs` records the JavaScript-local compatibility boundaries.
 
 ## No-claim boundaries
 
 - This package does **not** claim the paper's SWE-bench / Terminal-Bench / KernelBench scores. Those were measured on other scaffolds with this algorithm.
 - Trigger timing is Pi's (`compaction.reserveTokens`). The GitHub proxy default of 200k tokens is a library default, not what Pi uses unless you set Pi's reserve so the remaining window matches.
 - Selector / Soft Group Verification from the paper is out of scope.
-
-## Gotchas
-
+- Model-level hash identity is conditional on collision freedom for the compared inputs. No global fixed-length hash injectivity, SHA-256 collision proof, or Lean-to-TypeScript refinement proof is claimed.
+- Redacting a request prevents stale-summary reuse for that history; it does not securely erase older prefix-store entries from memory before eviction.
 - Other extensions that also handle `session_before_compact` will race. Load one.
 - `/compact` with extra instructions is ignored.
 - Shadow mode on overflow cancels recovery compaction; the overflowing request is left as-is (fail-open).

package/index.ts

@@ -15,7 +15,14 @@ import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent
 import { convertToLlm } from "@earendil-works/pi-coding-agent";
 import { loadConfig, type Config } from "./lib/config.ts";
 import { isRecord, type JsonObject, type JsonValue } from "./lib/decode.ts";
-import { compactSession, liveFromEntries, type CliffDetails, type HookEntry } from "./lib/pi-hook.ts";
+import {
+  compactSession,
+  liveFromEntries,
+  resolveCompactReason,
+  type CliffDetails,
+  type CompactReason,
+  type HookEntry,
+} from "./lib/pi-hook.ts";
 
 type LastCliff = {
   reason: string;
@@ -23,6 +30,10 @@ type LastCliff = {
   details: CliffDetails;
 };
 
+function eventReason(event: object): unknown {
+  return Object.prototype.hasOwnProperty.call(event, "reason") ? (event as { reason?: unknown }).reason : undefined;
+}
+
 function jsonObjectFrom(value: JsonValue): JsonObject {
   // SAFETY: LLM Message is JSON-serializable; reparse to JsonObject.
   const parsed: JsonValue = JSON.parse(JSON.stringify(value));
@@ -61,6 +72,15 @@ function hookEntriesFromBranch(branchEntries: readonly SessionEntry[]): HookEntr
       continue;
     }
 
+    if (entry.type === "branch_summary" && entry.summary) {
+      out.push({
+        id: entry.id,
+        kind: "branch_summary",
+        summary: entry.summary,
+      });
+      continue;
+    }
+
     if (entry.type === "compaction") {
       out.push({
         id: entry.id,
@@ -102,6 +122,7 @@ function formatStatus(cfg: Config, last: LastCliff | null): string {
 export default function registerCliffCompaction(pi: ExtensionAPI) {
   let cfg = loadConfig();
   let last: LastCliff | null = null;
+  let pendingReason: CompactReason = "manual";
 
   pi.registerCommand("cliff", {
     description: "CliffCompaction status and config (mechanical autocompaction)",
@@ -125,12 +146,24 @@ export default function registerCliffCompaction(pi: ExtensionAPI) {
     },
   });
 
+  // session_before_compact has no reason. Auto-compaction emits this first.
+  pi.on("auto_compaction_start", (event) => {
+    pendingReason = resolveCompactReason(eventReason(event));
+  });
+
+  pi.on("auto_compaction_end", () => {
+    pendingReason = "manual";
+  });
+
   pi.on("session_before_compact", async (event, ctx) => {
     if (!cfg.enabled) {
       return;
     }
 
-    const { preparation, branchEntries, reason } = event;
+    const { preparation, branchEntries } = event;
+    const fromEvent = resolveCompactReason(eventReason(event));
+    const reason = fromEvent !== "manual" ? fromEvent : pendingReason;
+    pendingReason = "manual";
 
     try {
       const entries = hookEntriesFromBranch(branchEntries);
@@ -180,6 +213,6 @@ export default function registerCliffCompaction(pi: ExtensionAPI) {
       return;
     }
 
-    ctx.ui.setStatus("cliff", "cliff · compacted (" + event.reason + ")");
+    ctx.ui.setStatus("cliff", "cliff · compacted (" + (last?.reason ?? "done") + ")");
   });
 }

package/lib/cliff.ts

@@ -70,6 +70,15 @@ export function compact(
 
   let headLen = firstAssistant;
 
+  // A cliff followed by another user prompt is no longer the final head item.
+  // Only the original prefix before that cliff remains protected on a recap.
+  for (let i = 0; i < firstAssistant; i++) {
+    if (dialect.isSummaryMessage(messages[i])) {
+      headLen = i;
+      break;
+    }
+  }
+
   while (
     headLen > 0 &&
     (dialect.isSummaryMessage(messages[headLen - 1]) ||
@@ -124,11 +133,32 @@ export function compact(
     newMessages.push(msg);
   }
 
-  if (newMessages.length >= messages.length) {
+  const cut = messages.length - kept.length;
+
+  if (newMessages.length > messages.length) {
     return null;
   }
 
-  const cut = messages.length - kept.length;
+  // keepRecent 0 replaces a one-message body with one summary. Message count
+  // stays the same; thought/result caps can still shrink the payload.
+  // Do not treat "drop the previous summary, keep the same tail" as gain:
+  // that is a same-length rewrite that throws away compacted history.
+  if (newMessages.length === messages.length) {
+    let onlySummaries = true;
+    let oldChars = 0;
+
+    for (let i = headLen; i < cut; i++) {
+      if (!dialect.isSummaryMessage(messages[i])) {
+        onlySummaries = false;
+      }
+
+      oldChars += JSON.stringify(messages[i]).length;
+    }
+
+    if (onlySummaries || JSON.stringify(summary).length >= oldChars) {
+      return null;
+    }
+  }
 
   return { messages: newMessages, headLen, summary, cut };
 }

package/lib/config.ts

@@ -70,9 +70,15 @@ function envInt(name: string, fallback: number): number {
     return fallback;
   }
 
-  const n = Number.parseInt(raw, 10);
+  const trimmed = raw.trim();
 
-  if (!Number.isFinite(n)) {
+  if (!/^[+-]?\d+$/.test(trimmed)) {
+    return fallback;
+  }
+
+  const n = Number.parseInt(trimmed, 10);
+
+  if (!Number.isSafeInteger(n) || n < 0) {
     return fallback;
   }
 
@@ -116,7 +122,7 @@ export function replaceConfig(cfg: Config, patch: ConfigPatch): Config {
 function intField(obj: JsonObject, snake: string, camel: string, fallback: number): number {
   const raw = obj[snake] ?? obj[camel];
 
-  if (isNumber(raw) && Number.isInteger(raw)) {
+  if (isNumber(raw) && Number.isInteger(raw) && raw >= 0) {
     return raw;
   }
 
@@ -183,6 +189,12 @@ export function defaultConfigPath(): string {
     return explicit;
   }
 
+  const configDir = envRaw("PI_CONFIG_DIR") || envRaw("OMP_CONFIG_DIR");
+
+  if (configDir) {
+    return join(configDir, "cliffcompaction.json");
+  }
+
   const home = homedir();
   const piDir = envRaw("PI_CONFIG_DIR") ?? join(home, ".pi", "agent");
   const ompDir = envRaw("OMP_CONFIG_DIR") ?? join(home, ".omp", "agent");

package/lib/decode.ts

@@ -2,9 +2,9 @@
  * Boundary decoders (anti-slop). JSON request bodies are untyped at the
  * I/O edge; everything inside the engine consumes these predicates.
  *
- * Hot-path checks use constructor identity: JSON.parse and object
- * literals never box primitives. Null-prototype objects still count as
- * records (Object.create(null).constructor is undefined).
+ * Primitive checks use constructor identity: JSON data never boxes
+ * primitives. Records use prototype identity so an own constructor field
+ * remains data. Null-prototype objects also count as records.
  */
 
 export type JsonPrimitive = string | number | boolean | null;
@@ -45,9 +45,9 @@ export function isObject(value: JsonValue | undefined | null): value is JsonObje
     return false;
   }
 
-  const ctor = value.constructor;
+  const proto = Object.getPrototypeOf(value);
 
-  return ctor === Object || ctor === undefined;
+  return proto === Object.prototype || proto === null;
 }
 
 export function isRecord(value: JsonValue | undefined | null): value is JsonObject {

package/lib/dialects/anthropic.ts

@@ -41,6 +41,8 @@ function resultText(content: JsonValue | undefined): string {
     for (const p of content) {
       if (isRecord(p) && asString(p.type) === "text") {
         parts.push(asString(p.text));
+      } else if (isRecord(p) && asString(p.type) === "search_result") {
+        parts.push(resultText(p.content));
       } else if (isString(p)) {
         parts.push(p);
       }
@@ -68,12 +70,25 @@ function canonBlock(block: JsonObject): JsonArray {
   }
 
   if (t === "tool_result") {
-    return [
+    const result: JsonArray = [
       "tool_result",
       asString(block.tool_use_id),
       resultText(block.content),
       asBoolean(block.is_error, false),
     ];
+
+    const attachments: JsonArray = [];
+
+    for (const part of asArray(block.content)) {
+      if (isRecord(part) && (asString(part.type) === "image" || asString(part.type) === "document")) {
+        attachments.push(canonBlock(part));
+      }
+    }
+
+    // Dropped attachment bytes still determine whether the original turn triggers a cliff.
+    if (attachments.length > 0) result.push(attachments);
+
+    return result;
   }
 
   if (t === "thinking") {
@@ -86,6 +101,19 @@ function canonBlock(block: JsonObject): JsonArray {
 
   if (t === "image" || t === "document") {
     const src = asObject(block.source) ?? {};
+
+    if (t === "document" && asString(src.type) === "content") {
+      const blocks: JsonArray = [];
+
+      for (const part of asArray(src.content)) {
+        if (isRecord(part)) {
+          blocks.push(canonBlock(part));
+        }
+      }
+
+      return [t, "content", digestObj(isString(src.content) ? src.content : blocks)];
+    }
+
     const payload = asString(src.data) || asString(src.url);
     const h = digestBytes(payload);
 
@@ -207,9 +235,28 @@ function summarizeAssistant(msg: JsonObject, cfg: Config): string[] {
         if (cfg.keepThinking) {
           thinkings.push(asString(b.thinking));
         }
-      } else if (t === "tool_use") {
+      } else if (t === "tool_use" || t === "server_tool_use" || t === "mcp_tool_use") {
         const args = canonicalJson(b.input ?? {});
         sigs.push("[" + asString(b.name, "?") + "] " + truncate(args, cfg.cmdMaxChars));
+      } else if (t === "mcp_tool_result" || t === "bash_code_execution_tool_result" || t === "code_execution_tool_result"
+        || t === "text_editor_code_execution_tool_result"
+        || (t === "web_search_tool_result" && asString(asObject(b.content)?.type) === "web_search_tool_result_error")
+        || (t === "web_fetch_tool_result" && asString(asObject(b.content)?.type) === "web_fetch_tool_result_error")
+        || (t === "tool_search_tool_result" && asString(asObject(b.content)?.type) === "tool_search_tool_result_error")) {
+        const content = asObject(b.content);
+
+        if (t === "text_editor_code_execution_tool_result"
+          && asString(content?.type) === "text_editor_code_execution_view_result"
+          && asString(content?.file_type) !== "text") {
+          continue;
+        }
+
+        const text = t === "mcp_tool_result"
+          ? resultText(b.content).trim() : canonicalJson(b.content ?? null);
+
+        if (text && text.length <= cfg.resultMaxChars) {
+          sigs.push("result: " + text);
+        }
       }
     }
   }
@@ -293,7 +340,7 @@ function summarizeUser(msg: JsonObject, cfg: Config): string[] {
       }
 
       parts.push("user: " + truncate(text.trim(), cfg.humanMaxChars));
-    } else if (t === "tool_result") {
+    } else if (t === "tool_result" || t === "search_result") {
       const text = resultText(b.content).trim();
 
       if (text && text.length <= cfg.resultMaxChars) {

package/lib/dialects/base.ts

@@ -15,6 +15,12 @@ export const SUMMARY_HEADER =
 export const PI_COMPACTION_PREFIX =
   "The conversation history before this point was compacted into the following summary:";
 
+/** Match Pi's convertToLlm wrapping of /tree branch_summary entries. */
+export const BRANCH_SUMMARY_PREFIX =
+  "The following is a summary of a branch that this conversation came back from:\n\n<summary>\n";
+
+export const BRANCH_SUMMARY_SUFFIX = "</summary>";
+
 const TASK_NOTIFICATION_RE = /<task-notification>[\s\S]*?<\/task-notification>\s*/g;
 
 export function stripTaskNotifications(text: string): string {
@@ -36,6 +42,28 @@ export function startsWithSummaryHeader(text: string): boolean {
   return text.startsWith(SUMMARY_HEADER) || text.startsWith(PI_COMPACTION_PREFIX);
 }
 
+/** Keep the newest contiguous summary parts that fit the caller's wire budget.
+ * The protected prefix survives even when it alone cannot fit.
+ */
+export function fitSummary(prefix: string, parts: string[], fits: (text: string) => boolean): string {
+  let text = prefix;
+  // Header-only prefixes need a blank line before the first part. A prefix that
+  // already holds protected parts (folded Pi head) must keep the --- delimiter.
+  const glue = prefix.includes("\n\n") ? "\n\n---\n\n" : "\n\n";
+
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const candidate = prefix + glue + parts.slice(i).join("\n\n---\n\n");
+
+    if (!fits(candidate)) {
+      break;
+    }
+
+    text = candidate;
+  }
+
+  return text;
+}
+
 export type Dialect = {
   name: string;
   digestMessage: (msg: JsonObject) => string;

package/lib/dialects/index.ts

@@ -11,7 +11,14 @@ import type { Dialect } from "./base.ts";
 
 export type { Dialect } from "./base.ts";
 
-export { SUMMARY_HEADER, PI_COMPACTION_PREFIX, truncate, stripTaskNotifications } from "./base.ts";
+export {
+  SUMMARY_HEADER,
+  PI_COMPACTION_PREFIX,
+  BRANCH_SUMMARY_PREFIX,
+  BRANCH_SUMMARY_SUFFIX,
+  truncate,
+  stripTaskNotifications,
+} from "./base.ts";
 
 export { DIALECT as anthropicDialect } from "./anthropic.ts";
 

package/lib/dialects/openai-chat.ts

@@ -53,8 +53,14 @@ export function contentText(content: JsonValue | undefined): string {
     const parts: string[] = [];
 
     for (const p of content) {
-      if (isRecord(p) && asString(p.type) === "text") {
-        parts.push(asString(p.text));
+      if (isRecord(p)) {
+        const type = asString(p.type);
+
+        if (type === "text") {
+          parts.push(asString(p.text));
+        } else if (type === "refusal") {
+          parts.push(asString(p.refusal));
+        }
       }
     }
 
@@ -68,6 +74,17 @@ export function contentText(content: JsonValue | undefined): string {
   return String(content);
 }
 
+function toolCallsOf(msg: JsonObject): JsonArray {
+  const calls = asArray(msg.tool_calls).slice();
+  const legacy = asObject(msg.function_call);
+
+  if (legacy !== null) {
+    calls.push({ function: legacy });
+  }
+
+  return calls;
+}
+
 export function digestMessage(msg: JsonObject): string {
   const content = msg.content;
   let blocks: JsonArray = [];
@@ -86,15 +103,23 @@ export function digestMessage(msg: JsonObject): string {
     blocks = out;
   }
 
+  // Refusal-only completions have null content but still carry assistant text.
+  const refusal = asString(msg.refusal);
+
+  if (refusal) {
+    blocks.push(["refusal", refusal]);
+  }
+
   const toolCalls: JsonArray = [];
 
-  for (const tc of asArray(msg.tool_calls)) {
+  for (const tc of toolCallsOf(msg)) {
     if (!isRecord(tc)) {
       continue;
     }
 
-    const fn = asObject(tc.function) ?? {};
-    toolCalls.push([asString(tc.id), asString(fn.name), asString(fn.arguments)]);
+    const custom = asString(tc.type) === "custom";
+    const fn = asObject(custom ? tc.custom : tc.function) ?? {};
+    toolCalls.push([asString(tc.id), asString(fn.name), asString(custom ? fn.input : fn.arguments)]);
   }
 
   return digestObj([
@@ -103,6 +128,8 @@ export function digestMessage(msg: JsonObject): string {
     toolCalls,
     asString(msg.tool_call_id),
     asString(msg.name),
+    // Reasoning is summary content, not volatile transport metadata.
+    asString(msg.reasoning_content ?? msg.reasoning),
   ]);
 }
 
@@ -129,16 +156,18 @@ function summarizeAssistant(msg: JsonObject, cfg: Config): string[] {
     }
   }
 
-  const thought = truncate(contentText(msg.content).trim(), cfg.thoughtMaxChars);
+  const text = [contentText(msg.content).trim(), asString(msg.refusal).trim()].filter(Boolean).join("\n");
+  const thought = truncate(text, cfg.thoughtMaxChars);
   const sigs: string[] = [];
 
-  for (const tc of asArray(msg.tool_calls)) {
+  for (const tc of toolCallsOf(msg)) {
     if (!isRecord(tc)) {
       continue;
     }
 
-    const fn = asObject(tc.function) ?? {};
-    let args = fn.arguments;
+    const custom = asString(tc.type) === "custom";
+    const fn = asObject(custom ? tc.custom : tc.function) ?? {};
+    let args = custom ? fn.input : fn.arguments;
 
     if (!isString(args)) {
       args = canonicalJson(args ?? "");
@@ -171,7 +200,7 @@ export function summarizeMessage(msg: JsonObject, cfg: Config): string[] {
     return summarizeAssistant(msg, cfg);
   }
 
-  if (role === "tool") {
+  if (role === "tool" || role === "function") {
     const text = contentText(msg.content).trim();
 
     if (text && text.length <= cfg.resultMaxChars) {