pi-openai-toolkit 0.14.11 → 0.14.13

package/src/context-management/messages.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { getCurrentSystemMessage, getCurrentTools } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
 	CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
@@ -113,3 +114,125 @@ export function sendContextWindowMessage(
 		? { deliverAs: "steer", triggerTurn: true }
 		: { triggerTurn: false });
 }
+
+/** Whether a transcript message is a Pi system message (prompt sections and tool deltas). */
+export function isSystemTranscriptMessage(message: AgentMessage): boolean {
+	return (message as unknown as { role?: string }).role === "system";
+}
+
+/** Tool names the provider would send for this message list, after replaying every delta. */
+export function declaredToolNames(messages: readonly AgentMessage[]): string[] {
+	return getCurrentTools(messages).map((tool) => tool.name);
+}
+
+export type SystemHeadRepair<TMessage extends AgentMessage = AgentMessage> = {
+	/** The window to send: trimmed, trimmed plus a rebuilt head, or untrimmed when the trim is unsafe. */
+	readonly messages: readonly TMessage[];
+	/** A head from before the boundary was re-anchored at the front of the window. */
+	repaired: boolean;
+	/** The trim was refused because the window would lose declared tools. */
+	shrinkRejected: boolean;
+	/** Tool names the trimmed window would have lost; empty on every safe path. */
+	lostToolNames: string[];
+	/** The system message this window anchors on, when one could be determined. */
+	head: AgentMessage | undefined;
+};
+
+/**
+ * Keep Pi 0.86's prompt and tool head alive across a context-window trim.
+ *
+ * Pi 0.86 no longer sends the system prompt and the tool loadout beside the
+ * transcript: `Agent#createContextSnapshot()` hands over messages only, and the
+ * Responses transport rebuilds `params.tools` from the `system` messages inside the
+ * message list (`resolveTranscriptTools(getInitialSystemMessage(messages))`). Trimming
+ * everything before a window boundary therefore deletes the one message that declares
+ * every tool, and Pi does not re-declare it because the persisted transcript still looks
+ * unchanged. The result is a window the model can only answer from memory.
+ *
+ * The merged state of the trimmed-away system messages is re-anchored as the leading
+ * message of the window. When even that would lose declared tools, the trim is refused:
+ * a window that still carries the previous turns beats a window with no tools at all.
+ */
+export function preserveSystemHead<TMessage extends AgentMessage>(args: {
+	readonly messages: readonly TMessage[];
+	boundaryIndex: number;
+	/**
+	 * Head observed in an earlier projection. A durable compaction can drop the original
+	 * declaration from the branch, leaving nothing to rebuild from, so the last known head
+	 * is re-anchored instead of sending a window with no tools.
+	 */
+	fallbackHead?: AgentMessage;
+}): SystemHeadRepair<TMessage> {
+	const { messages, boundaryIndex, fallbackHead } = args;
+	const window = messages.slice(Math.max(boundaryIndex, 0));
+	const prefix = messages.slice(0, Math.max(boundaryIndex, 0));
+
+	const anchorFallback = (): SystemHeadRepair<TMessage> | undefined => {
+		if (!fallbackHead || messages.some(isSystemTranscriptMessage)) return undefined;
+		// A boundary compaction can retire the entry that declared the tools, leaving a
+		// branch whose only system state is gone. Nothing in the list can be rebuilt, so
+		// the head remembered from an earlier projection is re-anchored instead.
+		const reused: readonly TMessage[] = [
+			fallbackHead as unknown as TMessage,
+			...window.filter((message) => !isSystemTranscriptMessage(message)),
+		];
+		return { messages: reused, repaired: true, shrinkRejected: false, lostToolNames: [], head: fallbackHead };
+	};
+
+	if (boundaryIndex <= 0 || prefix.length === 0) {
+		return anchorFallback() ?? {
+			messages: window,
+			repaired: false,
+			shrinkRejected: false,
+			lostToolNames: [],
+			head: getCurrentSystemMessage(messages) ?? fallbackHead,
+		};
+	}
+
+	const declared = declaredToolNames(messages);
+	const completeHead = getCurrentSystemMessage(messages);
+	if (!completeHead) {
+		const reused = anchorFallback();
+		if (reused) return reused;
+		if (!messages.some(isSystemTranscriptMessage) && declared.length === 0) {
+			// Pre-0.86 transcripts carry no system messages: the trim stays exactly as before.
+			return { messages: window, repaired: false, shrinkRejected: false, lostToolNames: [], head: undefined };
+		}
+		return { messages, repaired: false, shrinkRejected: true, lostToolNames: declared, head: undefined };
+	}
+
+	const windowFirst = window[0];
+	if (windowFirst && isSystemTranscriptMessage(windowFirst)) {
+		const kept = new Set(declaredToolNames(window));
+		const lostFromWindow = declared.filter((name) => !kept.has(name));
+		if (lostFromWindow.length === 0) {
+			return {
+				messages: window,
+				repaired: false,
+				shrinkRejected: false,
+				lostToolNames: [],
+				head: windowFirst as unknown as AgentMessage,
+			};
+		}
+		return {
+			messages,
+			repaired: false,
+			shrinkRejected: true,
+			lostToolNames: lostFromWindow,
+			head: windowFirst as unknown as AgentMessage,
+		};
+	}
+
+	// Later system messages are folded into the rebuilt head, so a patch cannot be read
+	// as a complete declaration by a transport that only anchors the first one.
+	const rebuilt: readonly TMessage[] = [
+		completeHead as unknown as TMessage,
+		...window.filter((message) => !isSystemTranscriptMessage(message)),
+	];
+	const after = new Set(declaredToolNames(rebuilt));
+	const lostToolNames = declared.filter((name) => !after.has(name));
+	if (lostToolNames.length > 0) {
+		return { messages, repaired: false, shrinkRejected: true, lostToolNames, head: completeHead };
+	}
+	return { messages: rebuilt, repaired: true, shrinkRejected: false, lostToolNames: [], head: completeHead };
+}

package/src/context-management/tools.ts

@@ -77,6 +77,11 @@ export const NEW_CONTEXT_CHECKPOINT_REQUIRED_MESSAGE =
 	+ "Write the active request, decisions, progress and next steps with notes append_to_file or write_file, "
 	+ "wait until that notes result is persisted, then retry new_context in a later tool turn. "
 	+ "Do not pass force arguments and do not repeat new_context while a rollover is already scheduled.";
+
+export const NEW_CONTEXT_COOLDOWN_MESSAGE =
+	"new_context refused: this window was entered by a context switch and has not run any substantive "
+	+ "tool yet. Read the checkpoint receipt with notes read_file, continue the active task with real "
+	+ "tools, and call new_context only once this window has produced tool activity.";
 export interface ContextRemainingDetails {
 	remainingTokens?: number;
 	windowId?: string;
@@ -120,6 +125,12 @@ export function createContextManagementTools(
 					details: { started: false },
 				};
 			}
+			if (!manager.canRolloverFromCurrentWindow(ctx)) {
+				return {
+					content: [{ type: "text", text: NEW_CONTEXT_COOLDOWN_MESSAGE }],
+					details: { started: false },
+				};
+			}
 			if (!manager.hasNotesCheckpointSinceBoundary(ctx)) {
 				throw new Error(NEW_CONTEXT_CHECKPOINT_REQUIRED_MESSAGE);
 			}

package/src/context-management/window-bulk.ts

@@ -0,0 +1,149 @@
+import {
+	buildSessionContext,
+	estimateTokens,
+	type ExtensionContext,
+	type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { LeaveManagedModePolicy } from "../types";
+import { isContextWindowBoundary } from "./messages";
+
+/**
+ * Share of the target model's context window above which a projection is considered
+ * over budget. Estimates are conservative (`estimateTokens` is chars/4 and overestimates),
+ * so the trigger fires slightly early rather than after a hard provider failure.
+ */
+export const BULK_CLIFF_RATIO = 0.8;
+
+/** How much larger the durable view must be than the windowed view to call it a cliff. */
+export const BULK_EXPANSION_RATIO = 2;
+
+export type WindowBulkReport = {
+	/** The window the durable view is measured against; a notice is surfaced once per window and model. */
+	readonly windowId: string | undefined;
+	/** Tokens an uncovered model would receive: the whole branch, markers filtered. */
+	readonly unmanagedTokens: number;
+	/** Tokens a covered model receives: the current window only. */
+	readonly managedTokens: number;
+	readonly targetContextWindow: number;
+	/** The durable view exceeds `BULK_CLIFF_RATIO` of the model that would receive it. */
+	readonly overBudget: boolean;
+	/** The durable view is at least `BULK_EXPANSION_RATIO` times the windowed view. */
+	readonly expanded: boolean;
+};
+
+/** What the runtime should do about a measured cliff. */
+export type BulkCliffAction = "ignore" | "warn" | "compact";
+
+/**
+ * `warn` is the default because an automatic compaction costs a real model call. `compact`
+ * only acts when the durable transcript is also past the target window: a session that is
+ * merely bigger than its windowed view still fits, and compacting it would be pure loss.
+ */
+export function decideBulkCliffAction(
+	report: WindowBulkReport,
+	policy: LeaveManagedModePolicy,
+): BulkCliffAction {
+	if (!report.expanded) return "ignore";
+	if (policy === "compact" && report.overBudget) return "compact";
+	return "warn";
+}
+
+export type BulkCloseOutContext = {
+	/** What the policy decided for this report. */
+	action: BulkCliffAction;
+	/** Pi's run mode: print sessions exit with the turn, so they cannot await a compaction. */
+	mode: string;
+	/** When the measurement happened. */
+	trigger: "model-switch" | "turn-end";
+	/** Whether a rollover trim is queued for the next eligible compaction. */
+	hasPendingTrim: boolean;
+};
+
+/**
+ * Turn a decided action into one that is safe to execute here.
+ *
+ * `ExtensionContext.compact()` is fire-and-forget and aborts the running turn. In print mode
+ * the process exits with the turn, so the summary would be killed mid-request; a turn-end
+ * close-out on a covered model is also pointless unless a rollover trim is queued, because
+ * the window policy cancels any other compaction. Both cases degrade to the warning.
+ */
+export function decideBulkCloseOut(context: BulkCloseOutContext): BulkCliffAction {
+	if (context.action !== "compact") return context.action;
+	if (context.mode === "print") return "warn";
+	if (context.trigger === "turn-end" && !context.hasPendingTrim) return "warn";
+	return "compact";
+}
+
+function sumTokens(messages: readonly AgentMessage[]): number {
+	let tokens = 0;
+	for (const message of messages) tokens += estimateTokens(message as never);
+	return tokens;
+}
+
+/**
+ * Measure the gap between the durable transcript and the remote window view.
+ *
+ * Remote context management retires previous windows *in the request projection*; the
+ * session branch keeps them, and a boundary compaction only lands when a compaction
+ * attempt consumes the scheduled trim. That asymmetry is invisible while a covered model
+ * runs and becomes a cliff the moment the session talks to a model without remote context:
+ * a window that streamed 25k tokens per request can hand over 400k tokens of history that
+ * no model has ever been shown, blowing past the new window and making the first manual
+ * `/compact` summarize the whole pile.
+ *
+ * Returns `undefined` when nothing has been retired yet, so young sessions and plain
+ * Pi transcripts never see a report.
+ */
+export function measureWindowBulk(args: {
+	readonly messages: readonly AgentMessage[];
+	contextWindow: number | undefined;
+}): WindowBulkReport | undefined {
+	const { messages, contextWindow } = args;
+	let boundaryIndex = -1;
+	for (let index = 0; index < messages.length; index += 1) {
+		if (isContextWindowBoundary(messages[index]!)) boundaryIndex = index;
+	}
+	if (boundaryIndex < 1) return undefined;
+
+	const boundaryMessage = messages[boundaryIndex]!;
+	const windowId = isContextWindowBoundary(boundaryMessage)
+		? boundaryMessage.details.contextManagement.currentWindowId
+		: undefined;
+	const window = messages.slice(boundaryIndex);
+	const managedTokens = sumTokens(window);
+	const unmanagedTokens = managedTokens + sumTokens(
+		messages
+			.slice(0, boundaryIndex)
+			.filter((message) => !isContextWindowBoundary(message)),
+	);
+	const targetContextWindow = typeof contextWindow === "number" && contextWindow > 0 ? contextWindow : 0;
+	return {
+		windowId,
+		unmanagedTokens,
+		managedTokens,
+		targetContextWindow,
+		overBudget: targetContextWindow > 0 && unmanagedTokens > targetContextWindow * BULK_CLIFF_RATIO,
+		expanded: unmanagedTokens > managedTokens * BULK_EXPANSION_RATIO,
+	};
+}
+
+/**
+ * The provider-visible message list for the current branch: Pi's compaction-anchored
+ * context, exactly as an uncovered model would receive it before the toolkit trims.
+ */
+export function durableContextMessages(entries: readonly SessionEntry[]): AgentMessage[] {
+	return buildSessionContext(entries as never[]).messages as unknown as AgentMessage[];
+}
+
+/**
+ * Measure the current branch for a bulk cliff. Returns `undefined` when the session has
+ * no window state, cannot report a target window, or has retired nothing.
+ */
+export function evaluateWindowBulk(ctx: Pick<ExtensionContext, "sessionManager" | "model">): WindowBulkReport | undefined {
+	const contextWindow = ctx.model?.contextWindow;
+	if (typeof contextWindow !== "number" || contextWindow <= 0) return undefined;
+	const messages = durableContextMessages(ctx.sessionManager.getBranch() as never[]);
+	if (!messages.some(isContextWindowBoundary)) return undefined;
+	return measureWindowBulk({ messages, contextWindow });
+}