pi-tuck 1.0.17 → 1.0.19

package/dist/src/compaction.js

@@ -6,15 +6,17 @@ import { isDeepStrictEqual } from "node:util";
 import { assertNativeToolRounds } from "./protocol.js";
 import { projectedMessages } from "./omissions.js";
 import { applyClips, clipBudgets, clipFor } from "./clip.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 { DEFAULT_CUT_AT, bandOf, chooseCut, conversationTokens, gateCut, incomingEventTokens, incomingTokens, measurableConversationTokens, planningReserve, projectedConversationTokens, systemPart, validCutAt } from "./budget.js";
+import { getCurrentSystemMessage, isContextOverflow } from "@earendil-works/pi-ai";
+import { calculateContextTokens, convertToLlm, estimateTokens, shouldCompact, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Check } from "typebox/value";
 import { MAX_RECALL_CHARACTERS, MAX_RECALL_ENTRY_ID_CHARACTERS, MAX_RECALL_QUERY_CHARACTERS } from "./recall.js";
 import { tuck, tuckDraft, tuckObservedDraft, tuckRecall } from "./tuck.js";
+import { LOADED_VERSION, statusText } from "./status.js";
 import { ImageRecallInput, historyImage, historyAround } from "./history-image.js";
 import { eligibilityKey, eligibilityKeyMoved, memoizedEligibleSources } from "./eligibility-cache.js";
+import { applyHistoryTools, hasTuckCut, historyToolDeclarations, historyToolNames, stageHistoryTools } from "./history-tools.js";
 const query = Type.String({ minLength: 1, maxLength: MAX_RECALL_QUERY_CHARACTERS });
 const entryId = Type.String({ minLength: 1, maxLength: MAX_RECALL_ENTRY_ID_CHARACTERS });
 const paging = {
@@ -208,6 +210,10 @@ export async function installCompaction(pi, options = {}) {
             }
             ctx.ui.notify(JSON.stringify({ ...semanticStatus(), ...(errors.length ? { errors } : {}) }), errors.length ? "warning" : "info");
         } });
+    pi.registerCommand("tuck", { description: "pi-tuck's state in this session: version, cuts, cut point, search", handler: async (_args, ctx) => {
+            const { state, lastError } = semantic.status();
+            ctx.ui.notify(statusText({ version: LOADED_VERSION, active: active(), branch: ctx.sessionManager.getBranch(), cutAt: options.cutAt, search, semantic: { state, lastError } }), "info");
+        } });
     // Pi's native start/settled events bracket the run and its post-turn cuts.
     let admittedRun = false;
     // One serial request, one accounting identity; observations never certify new content. A new identity (the first request after a session
@@ -319,12 +325,20 @@ export async function installCompaction(pi, options = {}) {
     const measureFor = (ctx) => (messages) => projectedConversationTokens(applyClips(messages, clips), ctx, options.recallPolicy);
     // The planner counts with the same function, except that it does not fail on a summary in another format: a cut can replace one
     // (an operator's /compact repairs a session whose saved summary is foreign). Identical to the strict one for this compactor's summaries.
-    const plannerMeasureFor = (ctx) => (messages) => measurableConversationTokens(applyClips(messages, clips), ctx, options.recallPolicy);
+    const plannerMeasureFor = (ctx) => Object.assign((messages) => measurableConversationTokens(applyClips(messages, clips), ctx, options.recallPolicy), { messageTokens: (message) => conversationTokens(applyClips([message], clips)) });
     const hostTokens = (ctx) => options.hostMessages ? conversationTokens(options.hostMessages(ctx)) : 0;
     const toolShapes = (names) => {
         const selected = new Set(names);
         return pi.getAllTools().filter(tool => selected.has(tool.name)).map(tool => ({ name: tool.name, description: tool.description, parameters: tool.parameters }));
     };
+    // Every decision prices the declaration set a cut must carry, even before the first cut enables our tools on the wire.
+    const requestSystemPart = (observedPrompt, names, saved, guardPrompt) => {
+        const shapes = toolShapes(historyToolNames(pi, names, true));
+        // Keep the guard's observed schemas (Pi may enrich a host tool's schema), and add our future declarations to that same view.
+        // Taking max(current guard, future raw shapes) alone could lose the enrichment when the future shapes are larger.
+        const future = saved.some(message => message.role === "system") ? historyToolDeclarations(saved, shapes, true) : saved;
+        return systemPart(observedPrompt, shapes, future, guardPrompt);
+    };
     // Pi reports a manual cut with nothing to do as a failed compaction; the thrown error lacks the event's "Compaction failed: " prefix.
     const isNoWork = (message) => ["Already compacted", "Nothing to compact (session too small)"].includes(message?.replace(/^Compaction failed: /, "") ?? "");
     // A missing model is configuration, not capacity.
@@ -385,7 +399,9 @@ export async function installCompaction(pi, options = {}) {
         forgetFailure();
         phase = "decided";
         try {
+            syncHistoryTools(ctx);
             await preflight(ctx, incomingTokens(event.text, event.images), ctx.getSystemPrompt(), pi.getActiveTools());
+            syncHistoryTools(ctx);
         }
         catch (error) {
             fail(error, ctx);
@@ -466,18 +482,17 @@ export async function installCompaction(pi, options = {}) {
             if (operatorManual && !admittedRun)
                 forgetFailure();
             access();
-            if (event.customInstructions?.trim()) {
-                recorder.stop("no-cut-custom-instructions");
-                ctx.ui.notify("pi-tuck does not accept summarization instructions; use /compact without arguments.", "warning");
-                return { cancel: true };
-            }
+            // pi-tuck's summary is built from the session itself, so text after /compact cannot steer it. The operator asked for a cut: make the one
+            // plain /compact makes and say the text was not used, rather than cancel (which Pi shows as an error, with no cut).
+            if (event.customInstructions?.trim())
+                ctx.ui.notify("pi-tuck: /compact ignores the text after it, since pi-tuck builds its summary from the session itself. Cutting as plain /compact does.", "info");
             const { response, room } = limits(ctx);
             const retain = operatorManual || admittedRun;
             // A cut Pi asks for (an operator's /compact, Pi's threshold or overflow recovery) charges what the request must carry whatever is
             // cut: the system part and the host input. A prompt's cut is pi-tuck's own and never comes here.
             const saved = ctx.sessionManager.buildSessionProjection().messages;
             const host = hostTokens(ctx);
-            const system = systemPart(ctx.getSystemPrompt(), toolShapes(pi.getActiveTools()), saved, ctx.getSystemPrompt());
+            const system = requestSystemPart(ctx.getSystemPrompt(), pi.getActiveTools(), saved, ctx.getSystemPrompt());
             const mandatory = system + host, band = decisionBand(ctx, room, system);
             const before = plannerMeasureFor(ctx)(saved);
             // Pi's own usage threshold (reason "threshold") counts the last reply's output tokens, reasoning included, plus the messages after
@@ -528,6 +543,15 @@ export async function installCompaction(pi, options = {}) {
     });
     pi.on("session_before_tree", (event) => event.preparation.userWantsSummary ? { cancel: true } : undefined);
     pi.on("session_start", () => { clips.clear(); promptCut = undefined; recorder.stop("session-transition"); proposalId = undefined; failure = undefined; admittedRun = false; pendingBoundaryCommit = false; identity = ""; factor = 1; pending = undefined; phase = "idle"; });
+    const historyToolsEnabled = (ctx) => Boolean(promptCut) || hasTuckCut(ctx.sessionManager.getBranch());
+    const syncHistoryTools = (ctx) => { if (active())
+        applyHistoryTools(pi, historyToolsEnabled(ctx)); };
+    pi.on("session_start", (_event, ctx) => syncHistoryTools(ctx));
+    pi.on("session_tree", (_event, ctx) => syncHistoryTools(ctx));
+    pi.on("session_compact", (_event, ctx) => { if (!admittedRun)
+        syncHistoryTools(ctx); });
+    pi.on("turn_start", (_event, ctx) => syncHistoryTools(ctx));
+    pi.on("agent_settled", (_event, ctx) => syncHistoryTools(ctx));
     // The session as it will be once a cut that is not saved yet is saved, and its conversation as the next request carries it.
     const cutSession = (ctx, cut) => {
         const header = ctx.sessionManager.getHeader();
@@ -542,7 +566,7 @@ export async function installCompaction(pi, options = {}) {
     // custom message starts). The cut is pi-tuck's own, planned as at a tool boundary. It is not Pi's: Pi's cut finder keeps the last
     // keepRecentTokens, and where those are the whole conversation it has nothing to cut, so every later prompt was refused for good (t06 at
     // Pi's defaults on a 32k window). Each request of the run carries the cut, and the run's first boundary saves it.
-    const preflight = (ctx, incomingPart, observedPrompt, tools) => {
+    const preflight = (ctx, incomingPart, observedPrompt, tools, hostSnapshot) => {
         promptCut = undefined;
         promptCutAt = ctx.sessionManager.getBranch().length;
         if (!active())
@@ -555,9 +579,9 @@ export async function installCompaction(pi, options = {}) {
         const { response, room } = limits(ctx);
         // Public early view only: later handlers, image normalization and tool-loop growth remain the complete-context guard's responsibility.
         const saved = ctx.sessionManager.buildSessionProjection().messages;
-        const system = systemPart(observedPrompt, toolShapes(tools), saved, ctx.getSystemPrompt());
+        const system = requestSystemPart(observedPrompt, tools, saved, ctx.getSystemPrompt());
         const band = decisionBand(ctx, room, system);
-        const host = hostTokens(ctx), measure = measureFor(ctx), before = measure(saved);
+        const host = hostSnapshot ?? hostTokens(ctx), measure = measureFor(ctx), before = measure(saved);
         const incoming = incomingPart + system, mandatory = incoming + host;
         if (!fits(incoming, room, ctx))
             throw new CapacityError("Incoming Pi prompt and response reserve cannot fit the estimated request budget");
@@ -594,10 +618,43 @@ export async function installCompaction(pi, options = {}) {
         const prompted = phase === "decided";
         phase = "starting";
         try {
+            syncHistoryTools(ctx);
             if (prompted)
                 access(); // decided on input; a failure latched there still stops the run
             else
-                await preflight(ctx, incomingEventTokens(event), event.systemPrompt, event.systemPromptOptions.selectedTools);
+                await preflight(ctx, incomingEventTokens(event), event.systemPrompt, historyToolNames(pi, event.systemPromptOptions.selectedTools, historyToolsEnabled(ctx)));
+            // Pi declares tool changes before turn_start, then snapshots executable tools in prepareRequest. Introduce our tools in
+            // the request projection: recording an activation message here would shift every later session-global recall index.
+            if (historyToolsEnabled(ctx))
+                stageHistoryTools(pi, ctx.sessionManager.buildSessionProjection().messages);
+            else
+                applyHistoryTools(pi, false);
+            const staged = pi.getActiveTools();
+            event.systemPromptOptions.selectedTools = historyToolNames(pi, event.systemPromptOptions.selectedTools, true).filter(name => name !== "tuck_recall" && name !== "tuck_search" || staged.includes(name));
+        }
+        catch (error) {
+            fail(error, ctx);
+        }
+    });
+    // The incoming user message is about to be appended (including steering inside a run), and later before_agent_start/turn_start
+    // handlers have run. Pi's prepareRequest has not yet snapshotted executable tools. A first cut discovered in context_with_system
+    // would be too late for that snapshot, even if its declarations were repaired there, so make the late prompt decision here.
+    pi.on("message_end", (event, ctx) => {
+        if (event.message.role !== "user" || !active() || !admittedRun || promptCut)
+            return;
+        try {
+            access();
+            if (!ctx.model)
+                throw missingModel();
+            const message = event.message;
+            const incoming = incomingTokens(typeof message.content === "string" ? message.content : message.content.flatMap(b => b.type === "text" ? [b.text] : []).join("\n"), typeof message.content === "string" ? [] : message.content.filter((b) => b.type === "image"));
+            const saved = ctx.sessionManager.buildSessionProjection().messages;
+            const host = hostTokens(ctx);
+            const system = requestSystemPart(ctx.getSystemPrompt(), pi.getActiveTools(), saved, ctx.getSystemPrompt());
+            if (fits(conversationTokens(saved) + system + incoming + host, limits(ctx).room, ctx))
+                return;
+            preflight(ctx, incoming, ctx.getSystemPrompt(), pi.getActiveTools(), host);
+            syncHistoryTools(ctx);
         }
         catch (error) {
             fail(error, ctx);
@@ -620,11 +677,28 @@ export async function installCompaction(pi, options = {}) {
         // One snapshot per decision. Messages queued for the next request (steering, follow-ups) are in that request but not in the
         // saved conversation. Pi's peek returns the steering queue, else the follow-up queue; a follow-up is not in the very next
         // request while tools still run, so it can be counted early: conservative, and nothing else would cut at that later boundary.
-        const system = systemPart(ctx.getSystemPrompt(), toolShapes(pi.getActiveTools()), saved, ctx.getSystemPrompt());
+        const system = requestSystemPart(ctx.getSystemPrompt(), pi.getActiveTools(), saved, ctx.getSystemPrompt());
         const band = decisionBand(ctx, room, system);
         const host = hostTokens(ctx);
         const queued = event.context.pendingMessages.length ? conversationTokens(event.context.pendingMessages) : 0;
         const mandatory = system + host + queued;
+        // Without usable provider usage, Pi's own threshold uses its unwrapped message estimate as the compiler's density input.
+        // Our declarations are request-only, so Pi can miss that threshold. Preserve the same density input at settlement; every
+        // budget decision below still uses `system` and the complete conversation measure, including the summary envelope.
+        let densityTokens;
+        const lastAssistant = saved.findLast(message => message.role === "assistant");
+        const lastCut = ctx.sessionManager.getBranch().findLast(entry => entry.type === "compaction");
+        if (reason === "run-end" && lastAssistant && (!lastCut || lastAssistant.timestamp > Date.parse(lastCut.timestamp)) &&
+            !saved.some(message => message.role === "assistant" &&
+                !["error", "aborted"].includes(message.stopReason) && message.usage && calculateContextTokens(message.usage) > 0)) {
+            const forecast = historyToolDeclarations(saved, toolShapes(historyToolNames(pi, pi.getActiveTools(), true)), true);
+            if (forecast !== saved) {
+                const head = getCurrentSystemMessage(convertToLlm(forecast));
+                const native = (head ? estimateTokens(head) : 0) + saved.reduce((sum, message) => sum + (message.role === "system" ? 0 : estimateTokens(message)), 0);
+                if (shouldCompact(native, ctx.model.contextWindow, settingsFor().getCompactionSettings(ctx.model)))
+                    densityTokens = native;
+            }
+        }
         const previousSummary = saved.find(message => message.role === "compactionSummary")?.summary;
         // The cut previews this decision has built, in the order it built them. The clip retry below measures them for what a cut leaves the
         // request besides the fresh results. Reset per decision, so a retry sizes itself against the cut it is retrying, not an earlier attempt's.
@@ -634,18 +708,22 @@ export async function installCompaction(pi, options = {}) {
             previews = [];
             floorKept = undefined;
             const before = measure(saved);
-            return decideCut({
-                total: before + mandatory, mandatory, before, room, band, fits: (tokens, limit) => fits(tokens, limit, ctx), usefulOnly: options.cutAt === undefined,
+            const gate = gateCut({ total: before + mandatory, mandatory, room, band, fits: (tokens, limit) => fits(tokens, limit, ctx) });
+            if (gate.kind !== "plan")
+                return gate;
+            return chooseCut({
+                opportunistic: gate.opportunistic, mandatory, before, room, band, fits: (tokens, limit) => fits(tokens, limit, ctx), usefulOnly: options.cutAt === undefined,
                 unreduced: "Tool-loop preflight compaction did not reduce context within the estimated request budget",
                 plan: (target) => {
                     const reserve = planReserve(target, room, band, mandatory, ctx);
-                    const draft = tuckObservedDraft(tuck, { branchEntries: ctx.sessionManager.getBranch(), tokensBefore: before, previousSummary }, ctx, reserve, plannerMeasureFor(ctx), options.recallPolicy, true);
+                    const draft = tuckObservedDraft(tuck, { branchEntries: ctx.sessionManager.getBranch(), tokensBefore: densityTokens ?? before, previousSummary }, ctx, reserve, plannerMeasureFor(ctx), options.recallPolicy, true);
                     if (!draft.compaction) {
                         // The planner's own floor, so a clip's second budget is measured against what the smallest cut really keeps.
                         if (draft.floorMessages && event.toolResults) {
                             const fresh = new Set(event.toolResults.map(result => result.toolCallId));
                             const kept = measure(draft.floorMessages.filter(message => !(message.role === "toolResult" && fresh.has(message.toolCallId))));
-                            floorKept = Math.min(floorKept ?? kept, kept);
+                            // Both targets must leave their protected openings beside the clip.
+                            floorKept = Math.max(floorKept ?? kept, kept);
                         }
                         return { draft: false, capacityRejected: Boolean(draft.capacityRejected), reason: draft.unavailable };
                     }
@@ -671,7 +749,7 @@ export async function installCompaction(pi, options = {}) {
             const branch = ctx.sessionManager.getBranch();
             const entryIdOf = (toolCallId) => branch.findLast(entry => entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolCallId === toolCallId)?.id;
             const fresh = new Set(event.toolResults.map(result => result.toolCallId));
-            const kept = previews.length ? Math.min(...previews.map(preview => measure(preview.filter(message => !(message.role === "toolResult" && fresh.has(message.toolCallId)))))) : floorKept;
+            const kept = previews.length ? Math.max(...previews.map(preview => measure(preview.filter(message => !(message.role === "toolResult" && fresh.has(message.toolCallId)))))) : floorKept;
             for (const budget of clipBudgets(room, factor, mandatory, kept)) {
                 const round = clipFor(event.toolResults, entryIdOf, budget);
                 if (!round.length)
@@ -720,13 +798,24 @@ export async function installCompaction(pi, options = {}) {
             if (!promptCut && !decide)
                 return;
             const result = atBoundary(event, ctx, "tool-loop", decide);
-            if (result)
+            if (result) {
                 pendingBoundaryCommit = true;
+            }
             return result;
         }
         catch (error) {
             fail(error, ctx);
         }
+        finally {
+            // Keep our part of Pi's next declaration snapshot unchanged; turn_start restores the branch-derived executable set before
+            // prepareRequest. This avoids an extra persisted system message at the first cut and on later rounds/runs.
+            if (active()) {
+                if (historyToolsEnabled(ctx))
+                    stageHistoryTools(pi, ctx.sessionManager.buildSessionProjection().messages);
+                else
+                    applyHistoryTools(pi, false);
+            }
+        }
     });
     // A request of a run whose prompt's cut is not saved yet: the saved conversation in it, which other handlers may surround, is replaced by
     // the conversation with the cut applied. Pi sends the saved system message apart from the request's messages, so neither side carries it
@@ -743,6 +832,9 @@ export async function installCompaction(pi, options = {}) {
         try {
             if (!active())
                 return;
+            // Before a cut, Pi owns the whole request, including its object identities and system-message serialization.
+            if (!historyToolsEnabled(ctx))
+                return clips.size ? { messages: applyClips(event.messages, clips) } : undefined;
             access();
             return { messages: applyClips(projectedMessages(promptCut ? cutRequest(event.messages, ctx, promptCut) : event.messages, ctx, options.recallPolicy), clips) };
         }
@@ -751,7 +843,7 @@ export async function installCompaction(pi, options = {}) {
                 fail(error, ctx);
             }
             finally {
-                return { messages: [] };
+                return historyToolsEnabled(ctx) ? { messages: [] } : undefined;
             }
         }
     });
@@ -807,24 +899,10 @@ export async function installCompaction(pi, options = {}) {
                 throw missingModel();
             // The complete request, counted after Pi's conversion (summary/custom/bash envelopes), with the effective system once.
             // Pi applies a forced prompt after this hook; the public prompt already observes it.
-            let messages = event.messages, tokens = requestTokens(messages, ctx.getSystemPrompt());
-            // The run's first request is over the room although the prompt's decision found it fit: something changed the request after that decision
-            // (another extension patching the system prompt in before_agent_start, whatever the load order). Reduce here rather than refuse: plan the
-            // prompt's cut against the request as it now is, carry it in memory, and save it at the first boundary, as any prompt's cut is saved.
-            if (!fits(tokens, limits(ctx).room, ctx) && !promptCut) {
-                const branch = ctx.sessionManager.getBranch(), last = branch.at(-1);
-                if (last?.type === "message" && last.message.role === "user") {
-                    const header = ctx.sessionManager.getHeader();
-                    const before = header && SessionManager.inMemory(ctx.cwd, undefined, [header, ...branch.slice(0, -1)]);
-                    if (before) {
-                        preflight(Object.create(ctx, { sessionManager: { value: before } }), incomingTokens(typeof last.message.content === "string" ? last.message.content : last.message.content.flatMap(b => b.type === "text" ? [b.text] : []).join("\n"), typeof last.message.content === "string" ? [] : last.message.content.filter((b) => b.type === "image")), ctx.getSystemPrompt(), pi.getActiveTools());
-                        if (promptCut) {
-                            messages = cutRequest(event.messages, ctx, promptCut);
-                            tokens = requestTokens(messages, ctx.getSystemPrompt());
-                        }
-                    }
-                }
-            }
+            syncHistoryTools(ctx);
+            const messages = historyToolsEnabled(ctx) ? historyToolDeclarations(event.messages, toolShapes(pi.getActiveTools()), true) : event.messages;
+            const system = requestSystemPart(ctx.getSystemPrompt(), pi.getActiveTools(), messages, ctx.getSystemPrompt());
+            const tokens = system + conversationTokens(messages);
             if (!fits(tokens, limits(ctx).room, ctx))
                 throw new CapacityError("Complete Pi context and response reserve exceed the estimated request budget");
             if (recorder.enabled && !recorder.waitingForCut)

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 = "27bb99fa3ca595dac73089d18c4c3506073c5d3e3f778ea572708f6e7a49ffc3";
+export declare const DIAGNOSTIC_BUILD = "3bbefa84bf1600296d12131a405f9feaa8fb1ea26ca1a85f5292b40a0a57333f";
 export interface Receipt {
     id: string;
     build: string;

package/dist/src/history-tools.d.ts

@@ -0,0 +1,16 @@
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Messages, ToolShape } from "./budget.js";
+/** Native Pi compactions do not make pi-tuck history available. No session-wide activation state. */
+export declare const hasTuckCut: (branch: readonly {
+    type: string;
+    details?: unknown;
+}[]) => boolean;
+/** Preserve the host's loadout and its order; only our registered tools may change. */
+export declare function historyToolNames(pi: ExtensionAPI, names: readonly string[], enabled: boolean): string[];
+export declare function applyHistoryTools(pi: ExtensionAPI, enabled: boolean): void;
+/** Match only our part of Pi's saved declaration snapshot, so its loop records no activation/removal message. Legacy sessions can
+ * already declare our tools; new sessions declare them only in the request projection. Executable tools are restored at turn_start. */
+export declare function stageHistoryTools(pi: ExtensionAPI, messages: Messages): string[];
+/** Pi has already declared the request's tools before queued user messages are appended. A prompt cut planned on such a message needs its declarations
+ * in that very request. Change only our declarations, leaving all other system content and tools in their original places. */
+export declare function historyToolDeclarations(messages: Messages, tools: readonly ToolShape[], enabled: boolean): Messages;

package/dist/src/history-tools.js

@@ -0,0 +1,59 @@
+import { getCurrentTools } from "@earendil-works/pi-ai";
+import { convertToLlm } from "@earendil-works/pi-coding-agent";
+const own = (name) => name === "tuck_recall" || name === "tuck_search";
+/** Native Pi compactions do not make pi-tuck history available. No session-wide activation state. */
+export const hasTuckCut = (branch) => branch.some(entry => entry.type === "compaction" && entry.details?.compactor === "pi-tuck");
+/** Preserve the host's loadout and its order; only our registered tools may change. */
+export function historyToolNames(pi, names, enabled) {
+    if (!enabled)
+        return names.filter(name => !own(name));
+    const registered = new Set(pi.getAllTools().map(tool => tool.name));
+    return [...names, ...["tuck_recall", "tuck_search"].filter(name => registered.has(name) && !names.includes(name))];
+}
+export function applyHistoryTools(pi, enabled) {
+    const current = pi.getActiveTools(), next = historyToolNames(pi, current, enabled);
+    if (current.length !== next.length || current.some((name, index) => name !== next[index]))
+        pi.setActiveTools(next);
+}
+/** Match only our part of Pi's saved declaration snapshot, so its loop records no activation/removal message. Legacy sessions can
+ * already declare our tools; new sessions declare them only in the request projection. Executable tools are restored at turn_start. */
+export function stageHistoryTools(pi, messages) {
+    const declared = new Set(getCurrentTools(convertToLlm(messages)).map(tool => tool.name));
+    const current = pi.getActiveTools();
+    const next = historyToolNames(pi, current, true).filter(name => !own(name) || declared.has(name));
+    if (current.length !== next.length || current.some((name, index) => name !== next[index]))
+        pi.setActiveTools(next);
+    return next;
+}
+/** Pi has already declared the request's tools before queued user messages are appended. A prompt cut planned on such a message needs its declarations
+ * in that very request. Change only our declarations, leaving all other system content and tools in their original places. */
+export function historyToolDeclarations(messages, tools, enabled) {
+    let changed = false;
+    const filtered = messages.map(message => {
+        if (message.role !== "system")
+            return message;
+        const added = message.toolsAdded?.filter(tool => !own(tool.name));
+        const removed = message.toolsRemoved?.filter(tool => !own(tool.name));
+        if (added?.length === message.toolsAdded?.length && removed?.length === message.toolsRemoved?.length)
+            return message;
+        changed = true;
+        const { toolsAdded: _, toolsRemoved: __, ...rest } = message;
+        return { ...rest, ...(added?.length ? { toolsAdded: added } : {}), ...(removed?.length ? { toolsRemoved: removed } : {}) };
+    });
+    // Leave an already-correct transcript byte-identical, including the original placement of our declarations.
+    const declared = getCurrentTools(convertToLlm(messages));
+    const wanted = enabled ? tools.filter(tool => own(tool.name)) : [];
+    if (enabled && wanted.every(tool => declared.some(current => own(current.name) && current.name === tool.name)) &&
+        declared.filter(tool => own(tool.name)).length === wanted.length)
+        return messages;
+    if (!enabled || !wanted.length)
+        return changed ? filtered : messages;
+    const at = filtered.findLastIndex(message => message.role === "system");
+    if (at < 0)
+        throw new Error("Missing Pi system message for history tool declarations");
+    const system = filtered[at];
+    if (system.role !== "system")
+        throw new Error("Missing Pi system message");
+    filtered[at] = { ...system, toolsAdded: [...(system.toolsAdded ?? []), ...wanted] };
+    return filtered;
+}

package/dist/src/ledger.d.ts

@@ -1,7 +1,5 @@
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { TranscriptRecord } from "./tuck/core/transcript.js";
-/** The initiating prompt is quoted whole up to this many characters; the rest stays readable through tuck_recall. */
-export declare const MAX_TASK_CONTRACT_CHARACTERS = 12000;
 /** Owner default; older distinct paths are counted, not listed. */
 export declare const MAX_LEDGER_LINES = 60;
 export declare const LEDGER_HEADING = "Files touched by read, write and edit before this summary, newest first, with the last operation:";

package/dist/src/ledger.js

@@ -1,8 +1,6 @@
 import { isLookupTool } from "./tuck/core/recall-operation.js";
 import { isDiscardedResponse } from "./protocol.js";
 import { extractPath } from "./tuck/core/tool-args.js";
-/** The initiating prompt is quoted whole up to this many characters; the rest stays readable through tuck_recall. */
-export const MAX_TASK_CONTRACT_CHARACTERS = 12000;
 /** Owner default; older distinct paths are counted, not listed. */
 export const MAX_LEDGER_LINES = 60;
 const LEDGER_TITLE = "Files";

package/dist/src/omissions.d.ts

@@ -3,7 +3,7 @@ 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, 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;
+export declare function filterOmittedSummary(summary: string, omitted: ReadonlySet<number>, sources?: readonly SessionEntry[], rangeOmitted?: 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;
 type ProjectedMessages = ReturnType<ExtensionContext['sessionManager']['buildSessionProjection']>['messages'];

package/dist/src/omissions.js

@@ -1,9 +1,10 @@
 import { buildGlobalIndexById } from './tuck/core/global-indices.js';
-import { parseRecords, splitSummary, transcriptHeader } from './tuck/core/transcript.js';
+import { parseRecords, serializeRecord, splitSummary, transcriptHeader } from './tuck/core/transcript.js';
+import { textOf } from "./tuck/core/content.js";
+import { isDiscardedResponse } from "./protocol.js";
 import { createRecall } from './recall.js';
 /** Native branch edits supply exclusion; original global indices supply provenance. */
 export function omittedSourceIndices(entries, branch) {
-    const indices = buildGlobalIndexById(entries);
     const edits = new Set();
     for (const entry of branch)
         if (entry.type === 'context_edit') {
@@ -11,10 +12,13 @@ export function omittedSourceIndices(entries, branch) {
                 throw new Error('pi-tuck does not support replacement context edits');
             edits.add(entry.targetId);
         }
+    if (!edits.size)
+        return new Set();
+    const indices = buildGlobalIndexById(entries);
     return new Set([...edits].flatMap(id => indices.has(id) ? [indices.get(id)] : []));
 }
 /** 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) {
+export function filterOmittedSummary(summary, omitted, sources, rangeOmitted = omitted) {
     if (!omitted.size)
         return summary;
     const split = splitSummary(summary);
@@ -22,7 +26,71 @@ export function filterOmittedSummary(summary, omitted) {
         throw new Error('Cannot apply native source omission to an unsupported compaction summary');
     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]]);
+    // A broad range does not identify the role of an intervening source. Without
+    // original sources there is no evidence that an edit removes a counted unit.
+    const indices = sources && rangeOmitted.size && records.some(record => record.sourceRange) ? buildGlobalIndexById(sources) : undefined;
+    const sourceUnits = new Map();
+    const shownBySource = new Map();
+    for (const record of records)
+        if (record.kind === 'excerpt' && record.sourceIndex !== undefined && !record.span) {
+            const key = `${record.role}:${record.sourceIndex}`, shown = shownBySource.get(key) ?? [];
+            shown.push(record.text);
+            shownBySource.set(key, shown);
+        }
+    if (indices && sources)
+        for (const entry of sources) {
+            if (entry.type !== 'message')
+                continue;
+            const index = indices.get(entry.id);
+            if (index === undefined)
+                continue;
+            const message = entry.message;
+            const shown = shownBySource.get(`${message.role}:${index}`) ?? [];
+            if (message.role === 'user') {
+                const text = textOf(message.content);
+                sourceUnits.set(index, { role: 'user', missing: Number(Boolean(text.length) && !shown.includes(text)) });
+            }
+            else if (message.role === 'assistant' && !isDiscardedResponse(message)) {
+                const available = [...shown];
+                let missing = 0;
+                for (const part of message.content)
+                    if (part.type === 'text' && part.text.trim()) {
+                        const at = available.indexOf(part.text);
+                        if (at < 0)
+                            missing++;
+                        else
+                            available.splice(at, 1);
+                    }
+                sourceUnits.set(index, { role: 'assistant', missing });
+            }
+            else if (message.role === 'toolResult')
+                sourceUnits.set(index, { role: 'toolResult', missing: 1 });
+        }
+    const retained = records.flatMap((record, at) => {
+        if ((record.sourceIndex !== undefined && omitted.has(record.sourceIndex)) || record.sourceIndices?.some(index => omitted.has(index)))
+            return [];
+        if (!record.sourceRange || !indices || record.count === undefined)
+            return [lines[at]];
+        const range = record.sourceRange;
+        let removed = 0;
+        const remaining = [];
+        for (const [index, unit] of sourceUnits) {
+            if (index < range.start || index > range.end || unit.role !== record.role || !unit.missing)
+                continue;
+            if (rangeOmitted.has(index))
+                removed += unit.missing;
+            else if (!omitted.has(index))
+                remaining.push(index);
+        }
+        if (!removed)
+            return [lines[at]];
+        const count = record.count - removed;
+        if (count <= 0)
+            return [];
+        const sourceRange = remaining.length ? { start: Math.min(...remaining), end: Math.max(...remaining) } : range;
+        const adjusted = { ...record, count, sourceRange };
+        return [version === 1 ? JSON.stringify(adjusted) : serializeRecord(adjusted)];
+    });
     return transcriptHeader(version) + '\n' + retained.join('\n') + closing;
 }
 /** Custom quotes carry native entry identity; no text matching or legacy fallback. */
@@ -31,6 +99,9 @@ export function filterCustomQuotes(summary, entries, branch, policy = {}) {
     if (!split)
         throw new Error('Cannot resolve custom sources in an unsupported compaction summary');
     const { body, closing, version } = split;
+    const records = parseRecords(body, version);
+    if (!records.some(record => record.role === "custom"))
+        return summary;
     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 +113,6 @@ export function filterCustomQuotes(summary, entries, branch, policy = {}) {
         branchSources.set(entry.id, found);
     }
     const lines = body ? body.split('\n') : [];
-    const records = parseRecords(body, version);
     const retained = records.flatMap((record, i) => {
         if (record.role !== 'custom')
             return [lines[i]];
@@ -62,8 +132,20 @@ export function filterCustomQuotes(summary, entries, branch, policy = {}) {
 function projectMessages(messages, ctx, policy, allowForeign) {
     const entries = ctx.sessionManager.getEntries(), branch = ctx.sessionManager.getBranch();
     const omitted = omittedSourceIndices(entries, branch);
+    const lastCut = branch.findLastIndex(entry => entry.type === 'compaction');
+    const cut = branch[lastCut];
+    const afterCut = new Set();
+    if (omitted.size && cut?.type === 'compaction') {
+        const indices = buildGlobalIndexById(entries);
+        for (const entry of branch.slice(lastCut + 1))
+            if (entry.type === 'context_edit' && entry.replacement === null) {
+                const index = indices.get(entry.targetId);
+                if (index !== undefined)
+                    afterCut.add(index);
+            }
+    }
     return messages.map(message => message.role === 'compactionSummary' && (!allowForeign || splitSummary(message.summary) !== undefined)
-        ? { ...message, summary: filterCustomQuotes(filterOmittedSummary(message.summary, omitted), entries, branch, policy) } : message);
+        ? { ...message, summary: filterCustomQuotes(filterOmittedSummary(message.summary, omitted, entries, cut?.type === 'compaction' && cut.summary === message.summary ? afterCut : new Set()), entries, branch, policy) } : message);
 }
 export function projectedMessages(messages, ctx, policy) {
     return projectMessages(messages, ctx, policy, false);

package/dist/src/status.d.ts

@@ -0,0 +1,19 @@
+import type { SemanticState } from "./semantic-recall.js";
+/** The version of the package this code was loaded from: the open session keeps it until Pi restarts, whatever is installed since. */
+export declare const LOADED_VERSION: string;
+/** `/tuck`: what an operator needs to know in words, from what is already recorded. It reads; it changes nothing the model sees. */
+export declare function statusText(input: {
+    version: string;
+    active: boolean;
+    branch: readonly {
+        type: string;
+        tokensBefore?: unknown;
+        details?: unknown;
+    }[];
+    cutAt: number | undefined;
+    search: boolean;
+    semantic: {
+        state: SemanticState;
+        lastError: string | null;
+    };
+}): string;

package/dist/src/status.js

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** The version of the package this code was loaded from: the open session keeps it until Pi restarts, whatever is installed since. */
+export const LOADED_VERSION = (() => {
+    try {
+        const path = fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "../package.json" : "../../package.json", import.meta.url));
+        const version = JSON.parse(readFileSync(path, "utf8")).version;
+        return typeof version === "string" ? version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+})();
+/** `/tuck`: what an operator needs to know in words, from what is already recorded. It reads; it changes nothing the model sees. */
+export function statusText(input) {
+    if (!input.active)
+        return `pi-tuck ${input.version} is loaded but inactive in this host; Pi's own compaction runs.`;
+    const cuts = input.branch.filter(e => e.type === "compaction"), ours = cuts.filter(e => e.details?.compactor === "pi-tuck");
+    const last = ours.at(-1), before = last?.tokensBefore, after = last?.details?.tokensAfter;
+    const count = (n) => n.toLocaleString("en-US");
+    const cutLine = ours.length === 0 ? "Cuts: none yet in this session. The recall tools appear after the first cut."
+        : `Cuts: ${ours.length} by pi-tuck in this session` + (typeof before === "number" && typeof after === "number" ? `, the last from ${count(before)} to ${count(after)} tokens.` : ".");
+    const native = cuts.length - ours.length;
+    const searchLine = !input.search ? "Search: by keyword (search by meaning needs macOS on Apple silicon)."
+        : input.semantic.state === "ready" || input.semantic.state === "waiting" ? "Search: by meaning and keyword."
+            : input.semantic.state === "preparing" ? "Search: by meaning and keyword; indexing history in the background."
+                : `Search: by keyword; ${lower(input.semantic.lastError ?? "semantic recall is off in this session (/tuck-semantic on)")}.`.replace(/\.\.$/, ".");
+    return [
+        `pi-tuck ${input.version} (the version this session loaded; restart Pi after an update).`,
+        cutLine,
+        ...(native > 0 ? [`Pi's own compaction cut ${native} time${native === 1 ? "" : "s"} in this session.`] : []),
+        input.cutAt === undefined ? "Cut point: adapts by itself." : `Cut point: fixed at cutAt ${input.cutAt} of the input room. Remove cutAt from pi-tuck.json to let it adapt.`,
+        searchLine,
+    ].join("\n");
+}
+const lower = (text) => text.charAt(0).toLowerCase() + text.slice(1);