@pi-unipi/compactor 2.5.0 → 2.6.0

package/README.md

@@ -108,6 +108,8 @@ Config-only legacy field: `fts5Index` remains in the schema for compatibility, b
 
 These settings control UniPi-managed percentage auto-compaction. They are separate from Pi core's own `compaction.reserveTokens` behavior.
 
+**Prefix-cache policy:** every compaction replaces provider-visible history and starts a new cache epoch. UniPi therefore keeps this second percentage trigger **off by default** and does not compact repeatedly merely to shorten a cache-hit request. Pi core remains the default safety trigger: with its documented defaults it compacts when estimated context exceeds `contextWindow - 16,384` reserved response tokens, while keeping about 20,000 recent tokens. If you deliberately enable the UniPi percentage trigger, 80% is an earlier explicit boundary and the cooldown/growth guards prevent loops. UniPi's compiler is deterministic and zero-LLM; it does not issue a second summarizer request.
+
 | Setting | Default | Meaning |
 |---|---:|---|
 | `Percentage Trigger` | `off` | When on, UniPi checks context usage at `turn_end` and can call compaction when the threshold is reached. Disabled by default for backward compatibility. |
@@ -157,7 +159,7 @@ The extension registers tools during `session_start` after the session DB is ini
 | Tool | Purpose |
 |---|---|
 | `compact` | Agent-facing compaction request; supports `dryRun: true` preview. Slash command `/unipi:lossless-compact` is the user-facing immediate compaction path. |
-| `session_recall` | Search current session history with BM25 or regex. |
+| `session_recall` | Search current session history with BM25 or regex. Defaults to 10 hits, hard-caps pages at 50, and caps expanded hit text at 16 KiB. |
 | `vcc_recall` | Deprecated alias for `session_recall`. |
 | `sandbox` | Run code in a sandboxed environment. Languages: JavaScript, TypeScript, Python, shell, Ruby, Go, Rust, PHP, Perl, R, Elixir. |
 | `sandbox_file` | Execute a file with its content injected as `FILE_CONTENT`. |
@@ -255,7 +257,7 @@ When UniPi handles `session_before_compact`, it transforms old messages through
 5. **Format** — emit a structured markdown summary.
 6. **Merge** — merge with the previous summary when Pi provides one.
 
-The resulting summary is optimized for continuity, not for perfect archival fidelity. Use `session_recall` when the agent needs details from the raw session branch.
+The resulting summary is optimized for continuity, not for perfect archival fidelity. Use `session_recall` when the agent needs details from the raw session branch. Recall is deliberately paginated: request another offset page or narrow the query instead of injecting an unbounded result set. Even with `expand: true`, each hit is capped at 16 KiB to prevent a single historical message or tool result from dominating future cold-cache requests.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Context engine for Pi — zero-LLM compaction, session continuity, sandbox execution, and tool display optimization",
   "type": "module",
   "main": "src/index.ts",
@@ -34,8 +34,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.5.0",
-    "@pi-unipi/info-screen": "2.5.0",
+    "@pi-unipi/core": "2.6.0",
+    "@pi-unipi/info-screen": "2.6.0",
     "@earendil-works/pi-agent-core": "^0.80.0"
   },
   "peerDependencies": {

package/src/session/snapshot.ts

@@ -257,7 +257,6 @@ export function buildResumeSnapshot(
 ): string {
   const compactCount = opts?.compactCount ?? 1;
   const searchTool = opts?.searchTool ?? "ctx_search";
-  const now = new Date().toISOString();
 
   const fileEvents: StoredEvent[] = [];
   const taskEvents: StoredEvent[] = [];
@@ -316,7 +315,9 @@ export function buildResumeSnapshot(
   const intent = buildIntentSection(intentEvents);
   if (intent) sections.push(intent);
 
-  const header = `<session_resume events="${events.length}" compact_count="${compactCount}" generated_at="${now}">`;
+  // Deliberately omit wall-clock time. This snapshot is model-visible on the
+  // first post-compaction request and must be reproducible from stored events.
+  const header = `<session_resume events="${events.length}" compact_count="${compactCount}">`;
   const footer = `</session_resume>`;
   const body = sections.join("\n\n");
   if (body) {

package/src/tools/register.ts

@@ -16,7 +16,7 @@
 import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { compactTool } from "./compact.js";
-import { vccRecall, type RecallInput } from "./vcc-recall.js";
+import { MAX_RECALL_RESULTS, vccRecall, type RecallInput } from "./vcc-recall.js";
 import { ctxExecute, type CtxExecuteInput } from "./ctx-execute.js";
 import { ctxExecuteFile, type CtxExecuteFileInput } from "./ctx-execute-file.js";
 import { ctxBatchExecute, type BatchItem } from "./ctx-batch-execute.js";
@@ -55,7 +55,11 @@ const RecallParams = Type.Object({
   mode: Type.Optional(Type.Union([Type.Literal("bm25"), Type.Literal("regex")], {
     description: "Search mode: bm25 (default) or regex fallback",
   })),
-  limit: Type.Optional(Type.Number({ description: "Max results to return (default 10)", minimum: 1 })),
+  limit: Type.Optional(Type.Number({
+    description: `Max results to return (default 10, hard cap ${MAX_RECALL_RESULTS})`,
+    minimum: 1,
+    maximum: MAX_RECALL_RESULTS,
+  })),
   offset: Type.Optional(Type.Number({ description: "Pagination offset", minimum: 0 })),
   expand: Type.Optional(Type.Boolean({ description: "Return full message content for hits" })),
 });

package/src/tools/vcc-recall.ts

@@ -5,6 +5,9 @@
 import type { NormalizedBlock } from "../types.js";
 import { searchEntries } from "../compaction/search-entries.js";
 
+export const MAX_RECALL_RESULTS = 50;
+export const MAX_EXPANDED_HIT_BYTES = 16 * 1024;
+
 export interface RecallInput {
   query: string;
   mode?: "bm25" | "regex";
@@ -13,6 +16,14 @@ export interface RecallInput {
   expand?: boolean;
 }
 
+function truncateExpandedHit(text: string): string {
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.byteLength <= MAX_EXPANDED_HIT_BYTES) return text;
+  const omitted = bytes.byteLength - MAX_EXPANDED_HIT_BYTES;
+  const visible = bytes.subarray(0, MAX_EXPANDED_HIT_BYTES).toString("utf8").replace(/\uFFFD+$/u, "");
+  return `${visible}\n… ${omitted} bytes omitted from this hit; narrow the query to inspect more specific context …`;
+}
+
 export interface RecallResult {
   hits: Array<{
     index: number;
@@ -28,7 +39,11 @@ export function vccRecall(
   blocks: NormalizedBlock[],
   input: RecallInput,
 ): RecallResult {
-  const { query, mode = "bm25", limit = 10, offset = 0, expand = false } = input;
+  const { query, mode = "bm25", expand = false } = input;
+  const requestedLimit = Number.isFinite(input.limit) ? Math.floor(input.limit!) : 10;
+  const requestedOffset = Number.isFinite(input.offset) ? Math.floor(input.offset!) : 0;
+  const limit = Math.min(MAX_RECALL_RESULTS, Math.max(1, requestedLimit));
+  const offset = Math.max(0, requestedOffset);
 
   let hits: Array<{ index: number; score: number; text: string; kind: string }> = [];
 
@@ -37,7 +52,7 @@ export function vccRecall(
     hits = results.map((r, i) => ({
       index: r.docId,
       score: r.score,
-      text: expand ? r.text : r.text.slice(0, 200),
+      text: expand ? truncateExpandedHit(r.text) : r.text.slice(0, 200),
       kind: r.kind,
     }));
   } else {
@@ -50,7 +65,7 @@ export function vccRecall(
         hits.push({
           index: i,
           score: 1,
-          text: expand ? text : text.slice(0, 200),
+          text: expand ? truncateExpandedHit(text) : text.slice(0, 200),
           kind: b.kind,
         });
       }