pi-tuck 1.0.1 → 1.0.4

package/dist/src/compaction.js

@@ -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 } from "./budget.js";
+import { DEFAULT_CUT_AT, bandOf, chooseCut, conversationTokens, decideCut, gateCut, incomingEventTokens, incomingTokens, measurableConversationTokens, planningReserve, projectedConversationTokens, requestTokens, systemPart, validCutAt } from "./budget.js";
 import { isContextOverflow } from "@earendil-works/pi-ai";
 import { convertToLlm, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -36,8 +36,18 @@ const RecallInput = Type.Union([
 ]);
 const SearchInput = Type.Object({ query, priorResults: Type.Optional(Type.Array(Type.Object({ entryId, sourceSha: Type.String({ minLength: 64, maxLength: 64 }), start: Type.Integer({ minimum: 0 }), end: Type.Integer({ minimum: 0 }) }, { additionalProperties: false }), { maxItems: 20 })) }, { additionalProperties: false });
 const reply = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }], details: {} });
-class CapacityError extends Error {
+/** The compactor's verdict that this attempt cannot be made: the cut it needs cannot be made, or the request cannot fit. It is a decision about the
+ * state as it was, so it ends with the attempt (`forgetRefusal`) and the next attempt decides afresh. Any other failure is a fault in the compactor
+ * or its host, and stays until the session restarts. */
+class Refusal extends Error {
 }
+/** A refusal for want of room, which the user can remedy: it carries advice. */
+class CapacityError extends Refusal {
+}
+/** What a capacity refusal tells the operator. When the provider has counted far more input than pi-tuck's estimate, the refusal most
+ * likely comes from that counting (an upstream behind a router can spend much more context on tool schemas), so the notice says so. */
+export const refusalNotice = (message, factor) => message + "; shorten the input, use a model with a larger window, or lower Pi's compaction.reserveTokens, then retry." +
+    (factor >= 1.5 ? ` This provider has counted up to ${factor.toFixed(1)}x the input pi-tuck estimates; through a router such as OpenRouter, a different upstream may count less.` : "");
 /** The most a seed or an overflow raise may set the calibration factor to. A paired reply's own ratio is not bounded by it. */
 export const CALIBRATION_CEILING = 1.5;
 /** How many recent paired replies (and overflow bounds, and the seed while it is among them) the calibration factor is the maximum of. */
@@ -81,6 +91,9 @@ export function seedWindow(branch, key) {
     return initialWindow(key);
 }
 export async function installCompaction(pi, options = {}) {
+    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.resolve();
     let semanticRequest = 0;
@@ -101,7 +114,7 @@ export async function installCompaction(pi, options = {}) {
         }
     });
     const captureDraft = (draft, ctx, reserve, reason, tokensBefore, retainCurrentInput, operatorManual, previousSummary, budget) => 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 {
@@ -204,7 +217,7 @@ export async function installCompaction(pi, options = {}) {
     // The cut planner's raw reserve for the target limit, on the same factor as every other consumer.
     const planReserve = (target, room, mandatory, ctx) => {
         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")
@@ -246,7 +259,7 @@ export async function installCompaction(pi, options = {}) {
             learn(ratio);
     });
     pi.on("agent_start", () => { admittedRun = true; pending = undefined; phase = "idle"; });
-    pi.on("agent_settled", () => { admittedRun = false; pending = undefined; phase = "idle"; });
+    pi.on("agent_settled", () => { admittedRun = false; pending = undefined; phase = "idle"; forgetRefusal(); });
     const active = () => options.active?.() ?? true;
     const settingsFor = () => options.settings ?? SettingsManager.inMemory(pi.getSettings());
     // The standalone default reserves the model's catalogue maximum output: a transport may omit the output cap, and then only that
@@ -268,10 +281,10 @@ export async function installCompaction(pi, options = {}) {
             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) => {
         const { response } = requestReserve(ctx), room = inputRoom(response, ctx);
-        return { response, room, band: bandOf(room) };
+        return { response, room, band: bandOf(room, cutAt) };
     };
     const fits = (tokens, limit, ctx) => 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).
@@ -304,13 +317,17 @@ export async function installCompaction(pi, options = {}) {
         finally {
             try {
                 if (notify)
-                    ctx.ui.notify(failure.message + "; shorten the input, use a model with a larger window, or lower Pi's compaction.reserveTokens, then retry.", "error");
+                    ctx.ui.notify(refusalNotice(failure.message, factor), "error");
             }
             finally {
                 ctx.abort();
             }
         }
     };
+    // The one place a refusal is dropped: when its attempt has settled, when a prompt arrives, and when the operator asks for a cut. A run that no
+    // input started (a custom message) has only the first of these.
+    const forgetRefusal = () => { if (failure instanceof Refusal)
+        failure = undefined; };
     const access = () => {
         if (failure)
             throw failure;
@@ -326,8 +343,7 @@ export async function installCompaction(pi, options = {}) {
     pi.on("input", async (event, ctx) => {
         if (!ctx.isIdle() || phase === "starting")
             return; // a steering or follow-up message joins the running request
-        if (failure instanceof CapacityError)
-            failure = undefined;
+        forgetRefusal();
         phase = "decided";
         try {
             await preflight(ctx, incomingTokens(event.text, event.images), ctx.getSystemPrompt(), pi.getActiveTools());
@@ -401,8 +417,8 @@ export async function installCompaction(pi, options = {}) {
             // Pi also labels the awaited idle incoming preflight "manual".
             const incoming = pendingCut;
             const operatorManual = event.reason === "manual" && !(incoming && !admittedRun);
-            if (operatorManual && !admittedRun && failure instanceof CapacityError)
-                failure = undefined;
+            if (operatorManual && !admittedRun)
+                forgetRefusal();
             access();
             if (event.customInstructions?.trim()) {
                 recorder.stop("no-cut-custom-instructions");
@@ -453,7 +469,7 @@ export async function installCompaction(pi, options = {}) {
             recorder.stop("no-cut");
             ctx.ui.notify(decision.message, "warning");
             if (!operatorManual)
-                fail(decision.capacity ? new CapacityError(decision.message) : new Error(decision.message), ctx);
+                fail(new (decision.capacity ? CapacityError : Refusal)(decision.message), ctx);
             return { cancel: true };
         }
         catch (error) {
@@ -513,7 +529,7 @@ export async function installCompaction(pi, options = {}) {
                     if (cut.opportunistic && !failure && !cut.proposed)
                         resolve();
                     else
-                        reject(error.message === "Compaction cancelled" && failure instanceof CapacityError ? failure : error);
+                        reject(error.message === "Compaction cancelled" && failure instanceof Refusal ? failure : error);
                 } }));
         }
         finally {
@@ -523,7 +539,7 @@ export async function installCompaction(pi, options = {}) {
         // The cut awaited: take the snapshot again. An opportunistic cut never throws; the request is not over the room, and the guard decides.
         const next = snapshot(), after = next.before + next.mandatory, afterFits = fits(after, limits(ctx).room, ctx);
         if (!cut.opportunistic && (after >= total || !afterFits))
-            throw new (afterFits ? Error : CapacityError)("Incoming Pi preflight compaction did not reduce context within the estimated request budget");
+            throw new (afterFits ? Refusal : CapacityError)("Incoming Pi preflight compaction did not reduce context within the estimated request budget");
     };
     pi.on("before_agent_start", async (event, ctx) => {
         const prompted = phase === "decided";
@@ -580,7 +596,7 @@ export async function installCompaction(pi, options = {}) {
                 },
             });
             if (decision.kind === "fault")
-                throw new (decision.capacity ? CapacityError : Error)(decision.message);
+                throw new (decision.capacity ? CapacityError : Refusal)(decision.message);
             if (decision.kind !== "cut")
                 return;
             const compaction = captureDraft(decision.plan.compaction, ctx, decision.plan.reserve, "tool-loop", before, true, false, previousSummary, { response, host, mandatory, target: decision.target, margin: room - band });

package/dist/src/diagnostics.d.ts

@@ -1,6 +1,6 @@
 import { type RecallPolicy } from './recall.js';
 import type { SessionEntry } from '@earendil-works/pi-coding-agent';
-export declare const DIAGNOSTIC_BUILD = "2a0ebe00760f2226d888fbca503dbde44d32623cb644186a6dd2eef59b65fbe5";
+export declare const DIAGNOSTIC_BUILD = "fb0ab667f5bfcd22fd5cc6edb89cd859426fd7c28bb58c2bc7b9fbec6fcdd3da";
 export interface Receipt {
     id: string;
     build: string;
@@ -15,6 +15,7 @@ export interface Receipt {
         mandatoryInputTokens?: number;
         target?: 'band' | 'room';
         triggerMarginTokens?: number;
+        cutAt?: number;
         calibrationFactor?: number;
         calibrationWindow?: number[];
         calibrationIdentity?: string;

package/dist/src/omissions.d.ts

@@ -2,7 +2,7 @@ import type { ExtensionContext, SessionEntry } from '@earendil-works/pi-coding-a
 import { type RecallPolicy } from './recall.js';
 /** Native branch edits supply exclusion; original global indices supply provenance. */
 export declare function omittedSourceIndices(entries: readonly SessionEntry[], branch: readonly SessionEntry[]): ReadonlySet<number>;
-/** 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 declare function filterOmittedSummary(summary: string, omitted: ReadonlySet<number>): string;
 /** Custom quotes carry native entry identity; no text matching or legacy fallback. */
 export declare function filterCustomQuotes(summary: string, entries: readonly SessionEntry[], branch: readonly SessionEntry[], policy?: RecallPolicy): string;

package/dist/src/omissions.js

@@ -1,5 +1,5 @@
 import { buildGlobalIndexById } from './tuck/core/global-indices.js';
-import { TRANSCRIPT_HEADER, parseRecords, splitSummary } from './tuck/core/transcript.js';
+import { parseRecords, splitSummary, transcriptHeader } from './tuck/core/transcript.js';
 import { createRecall } from './recall.js';
 /** Native branch edits supply exclusion; original global indices supply provenance. */
 export function omittedSourceIndices(entries, branch) {
@@ -13,24 +13,24 @@ export function omittedSourceIndices(entries, branch) {
         }
     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, omitted) {
     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, entries, branch, policy = {}) {
     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(), branchSources = new Map();
@@ -42,7 +42,7 @@ export function filterCustomQuotes(summary, entries, branch, policy = {}) {
         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]];
@@ -56,7 +56,7 @@ export function filterCustomQuotes(summary, entries, branch, policy = {}) {
             return [];
         return [lines[i]];
     });
-    return TRANSCRIPT_HEADER + '\n' + retained.join('\n') + closing;
+    return transcriptHeader(version) + '\n' + retained.join('\n') + closing;
 }
 /** The saved conversation as this compactor delivers it: native omissions and ineligible custom quotes removed from summaries. */
 export function projectedMessages(messages, ctx, policy) {

package/dist/src/tuck/core/brief.d.ts

@@ -1,49 +1,19 @@
 import type { NormalizedBlock } from "../types.js";
-import type { SourceTime } from "./source-time.js";
 import { type TranscriptRecord } from "./transcript.js";
-export declare const isSegmentClosingAssistant: (blocks: NormalizedBlock[], index: number) => boolean;
-export declare const HEREDOC_OPEN_RE: RegExp;
-/**
- * If `lines[i]` opens a heredoc whose terminator actually appears on a later
- * line, return that terminator's line index; otherwise -1. Callers use -1 to
- * leave following lines intact instead of treating a stray `<<` (a shift op, a
- * quoted string, or a truncated body) as a heredoc and skipping real commands.
- */
-export declare const heredocCloseIndex: (lines: string[], i: number) => number;
-export type CallRecord = Extract<TranscriptRecord, {
-    kind: "tool_call";
+/** The user, assistant and notice blocks of a dialogue; tool blocks are never rendered. */
+export type DialogueBlock = Extract<NormalizedBlock, {
+    kind: "user" | "assistant" | "notice";
 }>;
-/** One record is independently decodable; source text cannot create structure. */
-export type ExcerptCache = WeakMap<NormalizedBlock, Map<string, TranscriptRecord[]>>;
-/** The assistant texts that close a segment: no further text before the next user turn or the end of the chronology. */
-export declare const segmentClosing: (chronology: NormalizedBlock[]) => Set<NormalizedBlock>;
+export declare const isDialogue: (block: NormalizedBlock) => block is DialogueBlock;
 /** A user or assistant text block the omission notices count when it is unselected: non-empty, and not rendered in the mandatory base. */
 export declare const isOmittable: (block: NormalizedBlock, mandatorySources?: ReadonlySet<number>) => boolean;
-/** `sources` are the distinct locators of the omitted blocks in ascending order; at most the first 9 decide the notice. */
+/** `sources` are the distinct locators of the omitted blocks in ascending order; at most the first 9 decide the notice. They are written
+ * as "#N" on the record's line. */
 export declare const omissionRecord: (role: "user" | "assistant", count: number, sources: number[], unlocated: boolean) => TranscriptRecord;
-export declare const planBrief: (blocks: NormalizedBlock[], full: Set<NormalizedBlock>, chronology: NormalizedBlock[], mandatorySources?: ReadonlySet<number>, includeOmissions?: boolean) => void;
-/** The original call that a selected complete receipt quotes; that call's own overview is then redundant. */
-export declare const receiptKey: (b: NormalizedBlock) => string | undefined;
-/** The receipt that would make this call redundant, when the call and its single receipt are fully identified. */
-export declare const coveredCallKey: (b: NormalizedBlock) => string | undefined;
-/** What one block renders in this brief, set by the plan and by the selected array around it. */
-export interface BlockView {
-    full: boolean;
-    closing: boolean;
-    mandatory?: ReadonlySet<number>;
-    bounded: boolean;
-    covered: boolean;
-}
-/** The records of one block alone: before identical calls merge and before source times are attached. */
-export declare const blockRecords: (b: NormalizedBlock, view: BlockView, cache?: ExcerptCache) => TranscriptRecord[];
-/** Whether `record` is the same call as the `previous` record, shown a second time. */
-export declare const repeatsCall: (previous: TranscriptRecord | undefined, record: TranscriptRecord) => previous is CallRecord & {
-    sourceIndex: number;
-};
-/** The earlier record of a repeated call, now also locating the later one. */
-export declare const absorbCall: (previous: TranscriptRecord, record: TranscriptRecord) => TranscriptRecord;
-/** A source time for each locator the record names; only briefs of times-carrying blocks have them. */
-export declare const noticeTimes: (blocks: NormalizedBlock[]) => Map<string, SourceTime>;
-export declare const decorateRecord: (record: TranscriptRecord, times: NormalizedBlock["sourceTimes"], entryTimes: ReadonlyMap<string, SourceTime>) => TranscriptRecord;
-export declare const buildBriefRecords: (blocks: NormalizedBlock[], cache?: ExcerptCache) => TranscriptRecord[];
-export declare const compileBrief: (blocks: NormalizedBlock[], cache?: ExcerptCache) => string;
+/** The word budgets of a clipped excerpt: the passages kept from the start of the text, and from its end. */
+export type Clip = readonly [headWords: number, tailWords: number];
+/** The records of one dialogue block alone, before source times are attached: its whole original text, or, with a `clip`, the excerpts
+ * that keep their sanitized-block spans around an omission. A mandatory source renders nothing: the adapter quotes it in its base. */
+export declare const blockRecords: (b: DialogueBlock, mandatory: ReadonlySet<number> | undefined, clip?: Clip) => TranscriptRecord[];
+/** A source time for each locator a user record names; only briefs of times-carrying blocks have them. */
+export declare const decorateRecord: (record: TranscriptRecord, times: NormalizedBlock["sourceTimes"]) => TranscriptRecord;