pi-openai-toolkit 0.23.1 → 0.24.0

package/src/context-management/types.ts

@@ -1,168 +0,0 @@
-import type { ContextManagementMode } from "../types";
-
-export type { ContextManagementMode };
-
-export const CONTEXT_MANAGEMENT_PROTOCOL = 1 as const;
-export const CODEX_CONTEXT_WINDOW_MESSAGE_TYPE = "codex-context-window" as const;
-export const CONTEXT_WINDOW_COMPACTION_STRATEGY = "codex-context-window" as const;
-export const CONTEXT_WINDOW_REMINDER_THRESHOLD = 6_144;
-export const CONTEXT_WINDOW_FALLBACK_BUFFER = 16_384;
-
-export type ContextManagementMessageKind = "window" | "reminder" | "fallback";
-
-export type ContextWindowIdentity = {
-	firstWindowId: string;
-	currentWindowId: string;
-	previousWindowId?: string;
-	windowNumber: number;
-};
-
-/** Persisted-session evidence identifying the note that can restore a rollover. */
-export type NotesCheckpointReceipt = {
-	path: string;
-	toolCallId: string;
-};
-
-export type CodexContextManagementMessageDetails = {
-	protocol: typeof CONTEXT_MANAGEMENT_PROTOCOL;
-	id: string;
-	sessionId?: string;
-	contextManagement: ContextWindowIdentity & {
-		protocol: typeof CONTEXT_MANAGEMENT_PROTOCOL;
-		kind: ContextManagementMessageKind;
-		trimPreviousWindow?: true;
-	};
-};
-
-export type ContextWindowCompactionDetails = {
-	protocol: typeof CONTEXT_MANAGEMENT_PROTOCOL;
-	strategy: typeof CONTEXT_WINDOW_COMPACTION_STRATEGY;
-	windowId?: string;
-};
-
-export type RemoteContextFailureReason =
-	| "context-management-inactive"
-	| "unsupported-model"
-	| "unsupported-api"
-	| "unsupported-backend"
-	| "auth-resolution-failed"
-	| "missing-token"
-	| "missing-api-key"
-	| "missing-account-id"
-	| "missing-base-url"
-	| "missing-session-id"
-	| "invalid-account-token"
-	| "backend-timeout"
-	| "aborted"
-	| "http-error"
-	| "invalid-json"
-	| "invalid-response"
-	| "protocol-error";
-
-export type NativeCodexContextProvider = {
-	kind: "native-codex";
-	route: "openai-codex";
-	provider: "openai-codex";
-	api: "openai-codex-responses";
-	model: string;
-	baseUrl: string;
-	token: string;
-	accountId: string;
-	headers: Record<string, string>;
-};
-
-export type GatewayCodexContextProvider = {
-	kind: "codex-gateway";
-	route: "codex-gateway";
-	/** Operator-defined provider name; matched via compaction.gatewayContextModels. */
-	provider: string;
-	api: "openai-responses";
-	model: string;
-	baseUrl: string;
-	apiKey: string;
-	headers: Record<string, string>;
-};
-
-export type CodexContextProvider = NativeCodexContextProvider | GatewayCodexContextProvider;
-
-export type CodexContextProviderResolution =
-	| { ok: true; provider: CodexContextProvider }
-	| {
-			ok: false;
-			reason: RemoteContextFailureReason;
-			provider?: string;
-			api?: string;
-			model?: string;
-			baseUrl?: string;
-		};
-
-export type HistoryAction =
-	| "list_windows"
-	| "list_items"
-	| "read_item"
-	| "search_contents";
-
-export type NotesAction =
-	| "list_files_by_prefix"
-	| "read_file"
-	| "search_contents"
-	| "append_to_file"
-	| "write_file";
-
-export type HistoryNotesResponse = Record<string, unknown>;
-
-export type HistoryNotesResult =
-	| { ok: true; value: HistoryNotesResponse }
-	| {
-			ok: false;
-			reason: Exclude<RemoteContextFailureReason, "context-management-inactive" | "unsupported-model" | "unsupported-api">;
-			status?: number;
-		};
-
-export function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
-export function isNonEmptyString(value: unknown): value is string {
-	return typeof value === "string" && value.trim().length > 0;
-}
-
-export function isContextWindowIdentity(value: unknown): value is ContextWindowIdentity {
-	if (!isRecord(value)) return false;
-	return (
-		isNonEmptyString(value.firstWindowId) &&
-		isNonEmptyString(value.currentWindowId) &&
-		(value.previousWindowId === undefined || isNonEmptyString(value.previousWindowId)) &&
-		Number.isInteger(value.windowNumber) &&
-		(value.windowNumber as number) >= 0
-	);
-}
-
-export function isCodexContextManagementMessageDetails(
-	value: unknown,
-): value is CodexContextManagementMessageDetails {
-	if (!isRecord(value) || value.protocol !== CONTEXT_MANAGEMENT_PROTOCOL || !isNonEmptyString(value.id)) {
-		return false;
-	}
-	if (value.sessionId !== undefined && !isNonEmptyString(value.sessionId)) return false;
-	if (!isRecord(value.contextManagement) || value.contextManagement.protocol !== CONTEXT_MANAGEMENT_PROTOCOL) {
-		return false;
-	}
-	const context = value.contextManagement;
-	if (!isRecord(context)) return false;
-	const trimPreviousWindow = context.trimPreviousWindow;
-	return (
-		(context.kind === "window" || context.kind === "reminder" || context.kind === "fallback") &&
-		isContextWindowIdentity(context) &&
-		(trimPreviousWindow === undefined || trimPreviousWindow === true)
-	);
-}
-
-export function isContextWindowCompactionDetails(value: unknown): value is ContextWindowCompactionDetails {
-	return (
-		isRecord(value) &&
-		value.protocol === CONTEXT_MANAGEMENT_PROTOCOL &&
-		value.strategy === CONTEXT_WINDOW_COMPACTION_STRATEGY &&
-		(value.windowId === undefined || isNonEmptyString(value.windowId))
-	);
-}

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

@@ -1,83 +0,0 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import {
-	CONTEXT_WINDOW_FALLBACK_BUFFER,
-	CONTEXT_WINDOW_FALLBACK_MESSAGE,
-	renderContextWindowReminder,
-	type ContextManagementMessageKind,
-	type ContextWindowIdentity,
-} from "./messages";
-
-export interface ContextRemaining {
-	remainingTokens: number | undefined;
-	windowId: string | undefined;
-	contextWindow: number;
-}
-
-export class ContextWindowBudget {
-	private readonly remindedWindows = new Set<string>();
-	private readonly exhaustedWindows = new Set<string>();
-
-	reset(): void {
-		this.remindedWindows.clear();
-		this.exhaustedWindows.clear();
-	}
-
-	restore(kind: ContextManagementMessageKind, windowId: string): void {
-		if (kind === "reminder") this.remindedWindows.add(windowId);
-		if (kind === "fallback") this.exhaustedWindows.add(windowId);
-	}
-
-	record(
-		ctx: ExtensionContext,
-		identity: ContextWindowIdentity,
-		contextTokens: number | undefined,
-		contextReminderThresholdPercent: number,
-	): { content: string; kind: "fallback" | "reminder" } | undefined {
-		const remaining = this.remaining(ctx, identity, contextTokens);
-		if (remaining.remainingTokens === undefined) return undefined;
-		const windowId = identity.currentWindowId;
-		if (remaining.remainingTokens <= 0 && !this.exhaustedWindows.has(windowId)) {
-			this.exhaustedWindows.add(windowId);
-			return { content: CONTEXT_WINDOW_FALLBACK_MESSAGE, kind: "fallback" };
-		}
-		const reminderThreshold =
-			contextReminderThresholdPercent > 0
-				? Math.floor((remaining.contextWindow * contextReminderThresholdPercent) / 100)
-				: 0;
-		if (
-			contextReminderThresholdPercent > 0 &&
-			remaining.remainingTokens <= reminderThreshold &&
-			!this.remindedWindows.has(windowId)
-		) {
-			this.remindedWindows.add(windowId);
-			return { content: renderContextWindowReminder(remaining.remainingTokens), kind: "reminder" };
-		}
-		return undefined;
-	}
-
-	remaining(
-		ctx: ExtensionContext,
-		identity: ContextWindowIdentity | undefined,
-		contextTokens?: number,
-	): ContextRemaining {
-		const usage = ctx.getContextUsage();
-		const contextWindow = usage?.contextWindow ?? ctx.model?.contextWindow ?? 0;
-		const limit = Math.max(0, contextWindow - CONTEXT_WINDOW_FALLBACK_BUFFER);
-		if (usage === undefined && contextTokens === undefined) {
-			return {
-				remainingTokens: undefined,
-				windowId: identity?.currentWindowId,
-				contextWindow: limit,
-			};
-		}
-		const used = contextTokens ?? usage?.tokens;
-		return {
-			remainingTokens:
-				used === null || used === undefined
-					? undefined
-					: Math.max(0, limit - used),
-			windowId: identity?.currentWindowId,
-			contextWindow: limit,
-		};
-	}
-}

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

@@ -1,155 +0,0 @@
-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";
-
-/**
- * Legacy pure diagnostics retained for config/test compatibility. Runtime model switching no
- * longer calls this module: non-window consumers use the current-local projection instead of
- * measuring or compacting the durable Remote Context branch.
- */
-
-/**
- * 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 });
-}