pi-tuck 1.0.1 → 1.0.3

package/index.ts

@@ -2,6 +2,7 @@ import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil
 import { readFileSync, realpathSync } from "node:fs";
 import { join, sep } from "node:path";
 import { installCompaction } from "./src/compaction";
+import { validCutAt } from "./src/budget";
 import { createSemanticRecall } from "./src/semantic-recall";
 import { defaultRoot } from "./src/assets";
 import { ensureSemanticRuntime } from "./src/setup";
@@ -14,13 +15,14 @@ export type { SemanticRecallConfig, PriorResult, SemanticState } from "./src/sem
 export { ensureSemanticRuntime } from "./src/setup";
 
 /** pi-tuck as a Pi extension: compaction and history recall always; semantic recall too, unless `pi-tuck.json` in Pi's agent folder
- * says `{"semanticRecall": false}`. Its runtime is set up in the background the first time a session starts. */
+ * says `{"semanticRecall": false}`. Its runtime is set up in the background the first time a session starts. The same file's `"cutAt"`
+ * (a number above 0 and at most 1) is the fraction of the input room a cut is triggered at, 1 by default. */
 export default async function (pi: ExtensionAPI) {
 	const semanticRecall = createSemanticRecall();
 	// `/tuck-semantic off` holds for the rest of the session, including over a setup that finishes later.
 	let off = false;
-	const handle = await installCompaction(pi, { semanticRecall, onSemanticSetting: async enabled => { off = !enabled; } });
 	const settings = readSettings(join(getAgentDir(), "pi-tuck.json"));
+	const handle = await installCompaction(pi, { semanticRecall, cutAt: settings.cutAt, onSemanticSetting: async enabled => { off = !enabled; } });
 	if (settings.semanticRecall === false) return;
 	let session = 0, said = "", setup: Promise<unknown> | undefined;
 	// A context outlives its session (a setup can finish after /new); a notice to an ended session is dropped.
@@ -55,14 +57,15 @@ export default async function (pi: ExtensionAPI) {
 	});
 }
 
-function readSettings(path: string): { semanticRecall?: boolean; error?: string } {
+function readSettings(path: string): { semanticRecall?: boolean; cutAt?: number; error?: string } {
 	let text: string;
 	try { text = readFileSync(path, "utf8"); } catch { return {}; }
 	try {
 		const value = JSON.parse(text);
-		if (value && typeof value === "object" && (value.semanticRecall === undefined || typeof value.semanticRecall === "boolean")) return value;
+		if (value && typeof value === "object" && (value.semanticRecall === undefined || typeof value.semanticRecall === "boolean") &&
+			(value.cutAt === undefined || validCutAt(value.cutAt))) return value;
 	} catch { /* reported below */ }
-	return { error: `${path} should be a JSON object like {"semanticRecall": false}` };
+	return { error: `${path} should be a JSON object like {"semanticRecall": false, "cutAt": 0.8}, with cutAt a number above 0 and at most 1` };
 }
 
 const reason = (error: unknown) => error instanceof Error ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tuck",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Deterministic compaction for Pi: compact summaries that keep the dialogue and the files touched, plus history recall by keyword and by meaning, all local.",
   "keywords": [
     "pi-package",

package/src/budget.ts

@@ -16,8 +16,20 @@ export interface ToolShape { name: string; description: string; parameters: unkn
 
 /** Triggers fire this fraction of the room early. The margin absorbs request growth a boundary cannot see; it never enters the calibration factor. */
 export const TRIGGER_MARGIN_FRACTION = 0.02;
-/** The limit a cut is triggered at and preferably planned to; the exact room stays the limit of every throw and fault. */
-export const bandOf = (room: number): number => room - Math.ceil(Math.max(0, room) * TRIGGER_MARGIN_FRACTION);
+/** Whether `value` is a cut point: a fraction of the room above 0 and at most 1. */
+export const validCutAt = (value: unknown): value is number => typeof value === "number" && value > 0 && value <= 1;
+/**
+ * The one owner of the band: the limit a cut is triggered at and preferably planned to. It is the room less the margin, or the cut point
+ * `cutAt` (a fraction of the room) when that is lower. The exact room stays the limit of every throw, fault and the complete-context guard,
+ * whatever the cut point. With `cutAt` 1 the band is the room less the margin alone.
+ */
+/** The default cut point: a cut once a request passes 60% of the room. Measured against 1 with paired replays (no answer loss) and billed
+ * input under automatic and explicit prompt caching (about 17% less at 128k, 10-14% at 32k). */
+export const DEFAULT_CUT_AT = 0.6;
+export const bandOf = (room: number, cutAt = 1): number => {
+	const positive = Math.max(0, room);
+	return Math.min(room - Math.ceil(positive * TRIGGER_MARGIN_FRACTION), Math.floor(positive * cutAt));
+};
 
 /** The APIs whose request converter (pi-ai openai-responses-shared) sends each signed thinking block back as an input reasoning item. */
 const REPLAYING_APIS: ReadonlySet<string> = new Set(["openai-responses", "azure-openai-responses", "openai-codex-responses"]);
@@ -78,7 +90,7 @@ export const planningReserve = (window: number, targetRoom: number, factor: numb
 	window - Math.floor(targetRoom / factor) + mandatory;
 
 export type Target = "band" | "room";
-/** A planned cut: the conversation it leaves, and the summary view that produced it (whole dialogue or ranked). */
+/** A planned cut: the conversation it leaves, and the summary view that produced it (whole dialogue or shrunk). */
 export type Plan<D extends object = {}> = ({ draft: true; after: number; mode: string } & D) | { draft: false; capacityRejected: boolean; reason: string };
 export type Decision<D extends object = {}> =
 	/** The request fits below the band, or an opportunistic cut cannot help: no cut and no fault; the request goes to the guard. */
@@ -105,26 +117,34 @@ export interface CutInput<D extends object = {}> {
 export type Verdict<D extends object = {}> = Exclude<Decision<D>, { kind: "defer" }>;
 /**
  * Rule 4. The exact room is planned first. When its plan already lands below the band it is taken as it is (target "room"): it keeps the
- * room plan's content exactly, because every allowance of the planner is derived from the reserve and the band's is 2% smaller. Only
+ * room plan's content exactly, because every allowance of the planner is derived from the reserve and the band's is smaller. Only
  * otherwise is the band planned. Inside the band a cut is opportunistic, so a failed plan is never a fault and never falls back to the
  * room (a cut that still lands in the band would trigger again every round); the exact room would cut nothing there, so a band cut is
  * taken only when the room can plan a cut too and with the same mode (a lossy view the room could not even plan is a quality change with
  * no fault to prevent). At or above the room, where a cut is due, a band plan of another mode gives way to the room plan (today's
  * view), and a band plan stands when the room has none (a cut instead of a fault).
+ * A lean band, one the cut point binds (`band < bandOf(room)`), is planned first and the room plan landing below it is not taken for that:
+ * the room plan keeps a native tail of up to half the room, so it can land just under a band that far below the room, and the next round
+ * would cut again, freeing little. The room is planned only where the rules above use it: to compare the mode, or when the band has no plan
+ * and a cut is due. With the default cut point the band is never lean and the order and the decisions are those above.
  * The margin adds no new decision fault. Exceptions thrown by `plan` are not caught here: they are faults, and they now surface at
  * boundaries inside the band too, where no planner ran before the margin.
  */
 export function chooseCut<D extends object = {}>(input: CutInput<D> & { opportunistic: boolean }): Verdict<D> {
 	const { before, mandatory, room, band, fits, plan, unreduced } = input;
-	const exact = plan("room");
-	if (exact.draft && exact.after < before && fits(exact.after + mandatory, band)) return { kind: "cut", target: "room", plan: exact };
+	const lands = (p: Plan<D>): p is Extract<Plan<D>, { draft: true }> => p.draft && p.after < before && fits(p.after + mandatory, band);
+	let roomPlan: Plan<D> | undefined;
+	const exact = () => roomPlan ??= plan("room");
+	if (band >= bandOf(room)) { const e = exact(); if (lands(e)) return { kind: "cut", target: "room", plan: e }; }
 	const preferred = plan("band");
 	if (input.opportunistic) {
-		if (!(preferred.draft && preferred.after < before && fits(preferred.after + mandatory, band))) return { kind: "none" };
-		return exact.draft && exact.mode === preferred.mode ? { kind: "cut", target: "band", plan: preferred } : { kind: "none" };
+		if (!lands(preferred)) return { kind: "none" };
+		const e = exact();
+		return e.draft && e.mode === preferred.mode ? { kind: "cut", target: "band", plan: preferred } : { kind: "none" };
 	}
+	const e = exact();
 	let chosen: Plan<D> = preferred, target: Target = "band";
-	if (!preferred.draft || (exact.draft && exact.mode !== preferred.mode)) { chosen = exact; target = "room"; }
+	if (!preferred.draft || (e.draft && e.mode !== preferred.mode)) { chosen = e; target = "room"; }
 	if (!chosen.draft) return { kind: "fault", capacity: chosen.capacityRejected, message: chosen.reason };
 	if (chosen.after >= before || !fits(chosen.after + mandatory, room))
 		return { kind: "fault", capacity: !fits(chosen.after + mandatory, room), message: unreduced };

package/src/build-id.ts

@@ -1 +1 @@
-export const BUILD_ID = "2a0ebe00760f2226d888fbca503dbde44d32623cb644186a6dd2eef59b65fbe5";
+export const BUILD_ID = "72d28833b7180debd3ea6a7ca0308b000f8d27671b42c4d2b73dfaaa7bbdad59";

package/src/compaction.ts

@@ -5,7 +5,7 @@ import { exportSource } from "./source-export.js";
 import { isDeepStrictEqual } from "node:util";
 import { assertNativeToolRounds } from "./protocol.js";
 import { projectedMessages } from "./omissions.js";
-import { bandOf, chooseCut, conversationTokens, decideCut, gateCut, incomingEventTokens, incomingTokens, measurableConversationTokens, planningReserve, projectedConversationTokens, requestTokens, systemPart,
+import { DEFAULT_CUT_AT, bandOf, chooseCut, conversationTokens, decideCut, gateCut, incomingEventTokens, incomingTokens, measurableConversationTokens, planningReserve, projectedConversationTokens, requestTokens, systemPart, validCutAt,
     type AgentMessage, type Messages, type Plan, type Target, type ToolShape } from "./budget.js";
 import { isContextOverflow } from "@earendil-works/pi-ai";
 import { convertToLlm, SessionManager, SettingsManager, type ExtensionAPI, type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
@@ -83,6 +83,10 @@ export interface CompactionOptions {
 	/** Optional estimated complete-input ceiling, separate from physical output reservation.
 	 * The host owns final serialization/transport counting; this is not an exact wire-token cap. */
 	activeInputTokens?: number | ((ctx: ExtensionContext) => number);
+	/** The cut point: a fraction of the input room, above 0 and at most 1 (default 1). A cut is triggered at, and preferably planned to, the band,
+	 * which is the room less 2% of it, or this fraction of the room when that is lower; a lower value cuts earlier and leaves less. The exact room
+	 * stays the limit of every throw, fault and the complete-context guard. Anything else is rejected when the compactor is installed. */
+	cutAt?: number;
 	/** The response reserve: the input room is the context window less this. By default the room never exceeds the window less the model's
 	 * catalogue maximum output, because a transport may omit the output cap and the reply can then grow to that maximum. A host that knows its
 	 * transport's behavior declares an exact reserve with `responseExact: true`, and the room is then the window less `response` exactly. */
@@ -101,6 +105,8 @@ export interface CompactionOptions {
 }
 
 export async function installCompaction(pi: ExtensionAPI, options: CompactionOptions = {}) {
+    const cutAt = options.cutAt ?? DEFAULT_CUT_AT;
+    if (!validCutAt(cutAt)) throw new Error("Invalid cut point: cutAt must be a number above 0 and at most 1");
     const semantic = options.semanticRecall ?? createSemanticRecall();
     let semanticTransition: Promise<void> = Promise.resolve();
     let semanticRequest = 0;
@@ -115,7 +121,7 @@ export async function installCompaction(pi: ExtensionAPI, options: CompactionOpt
         if (found) { recorder.capture("observed-entry", "current-native-branch-memory-not-durable", { entryId: found.id, diagnosticReceiptId: proposalId, details: found.type === "compaction" ? found.details : undefined }); recorder.cut(); proposalId = undefined; }
     });
     const captureDraft = (draft: NonNullable<ReturnType<typeof tuckDraft>["compaction"]>, ctx: ExtensionContext, reserve: number, reason: string, tokensBefore: number, retainCurrentInput: boolean, operatorManual: boolean, previousSummary?: string, budget?: { response: number; host: number; mandatory: number; target: Target; margin: number }) => recorder.measureInline(() => {
-        const attached = attachReceipt(draft, reason, reserve, ctx.model?.contextWindow ?? 0, { responseReserveTokens: budget?.response, hostInputTokens: budget?.host, mandatoryInputTokens: budget?.mandatory, target: budget?.target, triggerMarginTokens: budget?.margin, calibrationFactor: factor, calibrationWindow: [...ratios], calibrationIdentity: identity, activeInputCeilingTokens: lastCeiling });
+        const attached = attachReceipt(draft, reason, reserve, ctx.model?.contextWindow ?? 0, { responseReserveTokens: budget?.response, hostInputTokens: budget?.host, mandatoryInputTokens: budget?.mandatory, target: budget?.target, triggerMarginTokens: budget?.margin, ...(cutAt === 1 ? {} : { cutAt }), calibrationFactor: factor, calibrationWindow: [...ratios], calibrationIdentity: identity, activeInputCeilingTokens: lastCeiling });
         proposalId = receiptId(attached);
         if (recorder.enabled) { try {
             const filtered = permittedEntries(ctx.sessionManager.getEntries(), options.recallPolicy);
@@ -186,7 +192,7 @@ export async function installCompaction(pi: ExtensionAPI, options: CompactionOpt
     // The cut planner's raw reserve for the target limit, on the same factor as every other consumer.
     const planReserve = (target: Target, room: number, mandatory: number, ctx: ExtensionContext) => {
         identityFor(ctx);
-        return planningReserve(ctx.model?.contextWindow ?? 0, target === "band" ? bandOf(room) : room, factor, mandatory);
+        return planningReserve(ctx.model?.contextWindow ?? 0, target === "band" ? bandOf(room, cutAt) : room, factor, mandatory);
     };
     pi.on("message_end", (event, ctx) => {
         if (event.message.role !== "assistant") return;
@@ -237,10 +243,10 @@ export async function installCompaction(pi: ExtensionAPI, options: CompactionOpt
             throw new Error("Invalid active-input token ceiling");
         return Math.min((ctx.model?.contextWindow ?? 0) - response, ceiling ?? Infinity);
     };
-    // The exact room, and the band a cut is triggered at (budget.ts); every throw and every fault uses the exact room.
+    // The exact room, and the band a cut is triggered at (budget.ts, from this session's cutAt); every throw and every fault uses the exact room.
     const limits = (ctx: ExtensionContext) => {
         const { response } = requestReserve(ctx), room = inputRoom(response, ctx);
-        return { response, room, band: bandOf(room) };
+        return { response, room, band: bandOf(room, cutAt) };
     };
     const fits = (tokens: number, limit: number, ctx: ExtensionContext) => corrected(tokens, ctx) < limit;
     // The saved conversation and a cut's quantities are counted by the one function the guard counts with (strict, as the context hook is).

package/src/diagnostics.ts

@@ -7,7 +7,7 @@ import { homedir } from 'node:os';
 import { createRecall, type RecallPolicy } from './recall.js';
 import type { SessionEntry } from '@earendil-works/pi-coding-agent';
 export const DIAGNOSTIC_BUILD = BUILD_ID;
-export interface Receipt { id: string; build: string; reason: string; selectedView: string; boundary: string; settings: { draftReservedTokens: number; contextWindow: number; responseReserveTokens?: number; hostInputTokens?: number; mandatoryInputTokens?: number; target?: 'band' | 'room'; triggerMarginTokens?: number; calibrationFactor?: number; calibrationWindow?: number[]; calibrationIdentity?: string; activeInputCeilingTokens?: number | null }; before: { value: number; unit: 'estimated-input-tokens'; scope: 'native-preparation' | 'public-conversation' }; after: { value: number | null; unit: 'estimated-input-tokens'; scope: 'draft-preview' }; }
+export interface Receipt { id: string; build: string; reason: string; selectedView: string; boundary: string; settings: { draftReservedTokens: number; contextWindow: number; responseReserveTokens?: number; hostInputTokens?: number; mandatoryInputTokens?: number; target?: 'band' | 'room'; triggerMarginTokens?: number; cutAt?: number; calibrationFactor?: number; calibrationWindow?: number[]; calibrationIdentity?: string; activeInputCeilingTokens?: number | null }; before: { value: number; unit: 'estimated-input-tokens'; scope: 'native-preparation' | 'public-conversation' }; after: { value: number | null; unit: 'estimated-input-tokens'; scope: 'draft-preview' }; }
 export function attachReceipt<T extends { details?: unknown; firstKeptEntryId: string; tokensBefore: number }>(draft: T, reason: string, reserveTokens: number, contextWindow: number, resolved: Partial<Receipt['settings']> = {}): T & { details: Record<string, unknown> & { diagnosticReceipt: Receipt } } {
  const details = draft.details && typeof draft.details === 'object' ? draft.details as Record<string, unknown> : {};
  const receipt: Receipt = { id: randomUUID(), build: DIAGNOSTIC_BUILD, reason, selectedView: typeof details.view === 'string' ? details.view : 'deterministic-selected-draft', boundary: draft.firstKeptEntryId, settings: { draftReservedTokens: reserveTokens, contextWindow, ...resolved }, before: { value: draft.tokensBefore, unit: 'estimated-input-tokens', scope: reason === 'tool-loop' ? 'public-conversation' : 'native-preparation' }, after: { value: typeof details.tokensAfter === 'number' ? details.tokensAfter : null, unit: 'estimated-input-tokens', scope: 'draft-preview' } };

package/src/omissions.ts

@@ -1,6 +1,6 @@
 import type { ExtensionContext, SessionEntry } from '@earendil-works/pi-coding-agent';
 import { buildGlobalIndexById } from './tuck/core/global-indices';
-import { TRANSCRIPT_HEADER, parseRecords, splitSummary } from './tuck/core/transcript';
+import { parseRecords, splitSummary, transcriptHeader } from './tuck/core/transcript';
 import { createRecall, type RecallPolicy } from './recall';
 /** Native branch edits supply exclusion; original global indices supply provenance. */
 export function omittedSourceIndices(entries: readonly SessionEntry[], branch: readonly SessionEntry[]): ReadonlySet<number> {
@@ -12,30 +12,30 @@ export function omittedSourceIndices(entries: readonly SessionEntry[], branch: r
  }
  return new Set([...edits].flatMap(([id, omitted]) => omitted && indices.has(id) ? [indices.get(id)!] : []));
 }
-/** Preserve surviving record bytes/order. No text matching or semantic inference. */
+/** Preserve surviving record bytes/order, and the summary's format (a v1 summary stays v1). No text matching or semantic inference. */
 export function filterOmittedSummary(summary: string, omitted: ReadonlySet<number>): string {
  if (!omitted.size) return summary;
  const split = splitSummary(summary);
  if (!split) throw new Error('Cannot apply native source omission to an unsupported compaction summary');
- const { body, closing } = split;
- const records = parseRecords(body), lines = body ? body.split('\n') : [];
+ const { body, closing, version } = split;
+ const records = parseRecords(body, version), lines = body ? body.split('\n') : [];
  const retained = records.flatMap((record, i) =>
   (record.sourceIndex !== undefined && omitted.has(record.sourceIndex)) || record.sourceIndices?.some(index => omitted.has(index)) ? [] : [lines[i]!]);
- return TRANSCRIPT_HEADER + '\n' + retained.join('\n') + closing;
+ return transcriptHeader(version) + '\n' + retained.join('\n') + closing;
 }
 
 /** Custom quotes carry native entry identity; no text matching or legacy fallback. */
 export function filterCustomQuotes(summary: string, entries: readonly SessionEntry[], branch: readonly SessionEntry[], policy: RecallPolicy = {}): string {
  const split = splitSummary(summary);
  if (!split) throw new Error('Cannot resolve custom sources in an unsupported compaction summary');
- const { body, closing } = split;
+ const { body, closing, version } = split;
  const omitted = new Set(branch.flatMap(entry => entry.type === 'context_edit' && entry.replacement === null ? [entry.targetId] : []));
  const eligible = createRecall(policy).isHistorySource, indices = buildGlobalIndexById(entries);
  const globalCounts = new Map<string, number>(), branchSources = new Map<string, SessionEntry[]>();
  for (const entry of entries) globalCounts.set(entry.id, (globalCounts.get(entry.id) ?? 0) + 1);
  for (const entry of branch) { const found = branchSources.get(entry.id) ?? []; found.push(entry); branchSources.set(entry.id, found); }
  const lines = body ? body.split('\n') : [];
- const records = parseRecords(body);
+ const records = parseRecords(body, version);
  const retained = records.flatMap((record, i) => {
   if (record.role !== 'custom') return [lines[i]!];
   const id = record.sourceEntryId, source = id === undefined ? undefined : branchSources.get(id);
@@ -45,7 +45,7 @@ export function filterCustomQuotes(summary: string, entries: readonly SessionEnt
   if (!(entry.type === 'custom_message' || entry.type === 'message' && entry.message.role === 'custom') || !eligible(entry)) return [];
   return [lines[i]!];
  });
- return TRANSCRIPT_HEADER + '\n' + retained.join('\n') + closing;
+ return transcriptHeader(version) + '\n' + retained.join('\n') + closing;
 }
 type ProjectedMessages = ReturnType<ExtensionContext['sessionManager']['buildSessionProjection']>['messages'];
 /** The saved conversation as this compactor delivers it: native omissions and ineligible custom quotes removed from summaries. */