pi-openai-toolkit 0.14.7 → 0.14.8

package/src/pi-context-hook.ts

@@ -0,0 +1,116 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { ExtensionRunner, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Context property added by the toolkit's host patch. */
+export const PI_CONTEXT_PROJECTOR_FIELD = "projectContextForCompaction" as const;
+const PI_CONTEXT_PROJECTION_REPORTER_FIELD = "__piOpenAiToolkitReportContextProjectionFailure" as const;
+const PATCH_MARKER_FIELD = "__piOpenAiToolkitContextHookPatch" as const;
+
+type ProjectionState = {
+	failure?: string;
+};
+
+const activeProjectionByRunner = new WeakMap<ExtensionRunner, ProjectionState>();
+
+type PatchedExtensionContext = ExtensionContext & {
+	[PI_CONTEXT_PROJECTOR_FIELD]?: PiContextHookProjector;
+	[PI_CONTEXT_PROJECTION_REPORTER_FIELD]?: (reason: string) => void;
+};
+
+type MarkedCreateContext = typeof ExtensionRunner.prototype.createContext & {
+	[PATCH_MARKER_FIELD]?: true;
+};
+
+/** The ordered context-hook chain, applied to a cloned compaction context. */
+export type PiContextHookProjector = (
+	messages: readonly AgentMessage[],
+) => Promise<readonly AgentMessage[]>;
+
+export type PiContextHookPatchResult =
+	| { ok: true; installed: boolean; reason?: "already-installed" }
+	| { ok: false; reason: "emit-context-unavailable" | "create-context-unavailable" };
+
+/**
+ * Add a narrow projection method to every ExtensionContext created by Pi.
+ *
+ * Pi 0.85.1 already has the ordered `ExtensionRunner.emitContext()` method,
+ * but the event-level ExtensionContext does not expose the runner. The patch
+ * bridges only the method needed by Remote V2; it does not expose the runner
+ * or alter Pi's scheduler.
+ */
+export function installPiContextHookPatch(): PiContextHookPatchResult {
+	const prototype = ExtensionRunner.prototype;
+	if (typeof prototype.emitContext !== "function") {
+		return { ok: false, reason: "emit-context-unavailable" };
+	}
+
+	const original = prototype.createContext;
+	if (typeof original !== "function") {
+		return { ok: false, reason: "create-context-unavailable" };
+	}
+
+	const markedOriginal = original as MarkedCreateContext;
+	if (markedOriginal[PATCH_MARKER_FIELD] === true) {
+		return { ok: true, installed: false, reason: "already-installed" };
+	}
+
+	const patched = function patchedCreateContext(this: ExtensionRunner): ExtensionContext {
+		const context = original.call(this) as PatchedExtensionContext;
+		if (!(PI_CONTEXT_PROJECTOR_FIELD in context)) {
+			Object.defineProperty(context, PI_CONTEXT_PROJECTOR_FIELD, {
+				configurable: false,
+				enumerable: false,
+				writable: false,
+				value: async (messages: readonly AgentMessage[]) => {
+					const state: ProjectionState = {};
+					activeProjectionByRunner.set(this, state);
+					try {
+						const projected = await this.emitContext([...messages]);
+						if (state.failure) {
+							throw new Error(`context projection failed: ${state.failure}`);
+						}
+						return projected;
+					} finally {
+						if (activeProjectionByRunner.get(this) === state) {
+							activeProjectionByRunner.delete(this);
+						}
+					}
+				},
+			});
+		}
+		if (!(PI_CONTEXT_PROJECTION_REPORTER_FIELD in context)) {
+			Object.defineProperty(context, PI_CONTEXT_PROJECTION_REPORTER_FIELD, {
+				configurable: false,
+				enumerable: false,
+				writable: false,
+				value: (reason: string) => {
+					const state = activeProjectionByRunner.get(this);
+					if (state) state.failure = reason;
+				},
+			});
+		}
+		return context;
+	};
+
+	Object.defineProperty(patched, PATCH_MARKER_FIELD, {
+		configurable: false,
+		enumerable: false,
+		writable: false,
+		value: true,
+	});
+	prototype.createContext = patched;
+	return { ok: true, installed: true };
+}
+
+/** Return the patched projection method, if this Pi process supports it. */
+export function getPiContextHookProjector(
+	ctx: ExtensionContext,
+): PiContextHookProjector | undefined {
+	const candidate = (ctx as PatchedExtensionContext)[PI_CONTEXT_PROJECTOR_FIELD];
+	return typeof candidate === "function" ? candidate : undefined;
+}
+
+/** Preserve fail-closed context-hook errors across Pi's emitContext boundary. */
+export function reportPiContextHookFailure(ctx: ExtensionContext, reason: string): void {
+	(ctx as PatchedExtensionContext)[PI_CONTEXT_PROJECTION_REPORTER_FIELD]?.(reason);
+}

package/src/request-context-cache.ts

@@ -30,12 +30,23 @@ type CachedRequestContext = {
 	extras: CompactionRequestExtras;
 };
 
+export type RequestContextCaptureOptions = {
+	/** Standalone Web Search is a local tool and must not enter synthetic compact requests. */
+	excludeWebSearchTools?: boolean;
+};
+
 let cached: CachedRequestContext | undefined;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+function isWebSearchTool(value: unknown): boolean {
+	if (!isRecord(value)) return false;
+	if (value.type === "web_search" || value.type === "web_search_preview") return true;
+	return value.type === "function" && (value.name === "web_search" || value.name === "web.run");
+}
+
 function sameIdentity(cachedIdentity: RequestContextIdentity, current: RequestContextIdentity): boolean {
 	return (
 		cachedIdentity.provider === current.provider &&
@@ -54,6 +65,7 @@ function sameIdentity(cachedIdentity: RequestContextIdentity, current: RequestCo
 export function rememberRequestContext(
 	payload: ResponsesCompatibleRequestPayload,
 	identity: RequestContextIdentity,
+	options: RequestContextCaptureOptions = {},
 ): void {
 	try {
 		if (payload.model !== identity.model) {
@@ -63,7 +75,10 @@ export function rememberRequestContext(
 
 		const extras: CompactionRequestExtras = {};
 		if (Array.isArray(payload.tools)) {
-			extras.tools = structuredClone(payload.tools);
+			const tools = options.excludeWebSearchTools
+				? payload.tools.filter((tool) => !isWebSearchTool(tool))
+				: payload.tools;
+			extras.tools = structuredClone(tools);
 		}
 		if (typeof payload.parallel_tool_calls === "boolean") {
 			extras.parallel_tool_calls = payload.parallel_tool_calls;

package/src/runtime.ts

@@ -11,6 +11,7 @@ const OPENAI_RESPONSES_PATH = "responses";
 const CODEX_RESPONSES_PATH = "codex/responses";
 const OPENAI_COMPACT_PATH = "responses/compact";
 const CODEX_COMPACT_PATH = "codex/responses/compact";
+const ALPHA_SEARCH_PATH = "alpha/search";
 
 export type ResponsesApi = (typeof RESPONSES_COMPACT_CAPABLE_APIS)[number];
 
@@ -215,6 +216,57 @@ export function buildCompactPath(api: ResponsesCompactApi): string {
 	return api === "openai-codex-responses" ? CODEX_COMPACT_PATH : OPENAI_COMPACT_PATH;
 }
 
+/**
+ * Build the provider-relative standalone-search endpoint. This deliberately
+ * rejects a full Responses endpoint so an already-resolved URL cannot become
+ * `/responses/alpha/search` or `/codex/responses/alpha/search` by accident.
+ */
+export function buildAlphaSearchUrl(baseUrl: string): string | undefined {
+	const normalized = normalizeBaseUrl(baseUrl);
+	if (!normalized) return undefined;
+
+	let parsed: URL;
+	try {
+		parsed = new URL(normalized);
+	} catch {
+		return undefined;
+	}
+	if (
+		(parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+		parsed.username ||
+		parsed.password ||
+		parsed.search ||
+		parsed.hash
+	) {
+		return undefined;
+	}
+
+	const pathname = parsed.pathname.replace(/\/+$/, "");
+	if (
+		pathname.endsWith("/responses/alpha/search") ||
+		pathname.endsWith("/codex/responses/alpha/search") ||
+		pathname.endsWith("/responses/compact/alpha/search") ||
+		pathname.endsWith("/codex/responses/compact/alpha/search")
+	) {
+		return undefined;
+	}
+	if (pathname.endsWith("/alpha/search")) {
+		parsed.pathname = pathname;
+		return parsed.toString();
+	}
+	if (
+		pathname.endsWith("/responses") ||
+		pathname.endsWith("/codex/responses") ||
+		pathname.endsWith("/responses/compact") ||
+		pathname.endsWith("/codex/responses/compact")
+	) {
+		return undefined;
+	}
+
+	parsed.pathname = `${pathname}/${ALPHA_SEARCH_PATH}`.replace(/^\/\//, "/");
+	return parsed.toString();
+}
+
 async function resolveRequestAuth(ctx: ExtensionContext, model: RuntimeModel): Promise<ResolvedRequestAuth> {
 	const modelRegistry = ctx.modelRegistry as {
 		getApiKeyAndHeaders?: (currentModel: RuntimeModel) => Promise<ResolvedRequestAuth>;

package/src/types.ts

@@ -22,6 +22,17 @@ export const ASTRA_MODEL_ID = "gpt-6-astra";
 export const LEGACY_NATIVE_COMPACTION_STRATEGY = "openai-native-compact-v1";
 export const REMOTE_V2_COMPACTION_STRATEGY = "openai-remote-compaction-v2";
 export const NATIVE_COMPACTION_STRATEGY = REMOTE_V2_COMPACTION_STRATEGY;
+/**
+ * Provenance recorded when the checkpoint input came from Pi's ordered context
+ * hook projection. Older persisted entries may omit it and must not be
+ * replayed by Remote V2.
+ */
+export const NATIVE_COMPACTION_INPUT_PROVENANCE = "pi-context-hook-v1" as const;
+/** Explicit opt-in marker for the pre-projection raw session/branch chain. */
+export const LEGACY_REMOTE_V2_INPUT_PROVENANCE = "legacy-raw-context-v1" as const;
+export type NativeCompactionInputProvenance =
+	| typeof NATIVE_COMPACTION_INPUT_PROVENANCE
+	| typeof LEGACY_REMOTE_V2_INPUT_PROVENANCE;
 /**
  * Pi currently requires CompactionResult.summary to be text. This marker is only a
  * replay shim; the provider receives the opaque item from details.compactedWindow.
@@ -46,6 +57,9 @@ export type DebugArtifactKind =
 
 export type ContextManagementMode = "off" | "remote";
 
+/** How Remote V2 obtains the history it sends to the compaction endpoint. */
+export type RemoteV2ContextSource = "pi-context-hook" | "legacy";
+
 /** Native-method fallback compaction: which model runs pi's compact() and how deeply. */
 export type NativeFallbackConfig = {
 	enabled: boolean;
@@ -74,6 +88,11 @@ export type CompactionConfig = {
 	 * remains the checkpoint consumer and continues handling normal requests.
 	 */
 	remoteCompactModel?: string;
+	/**
+	 * Remote V2 input source. Pi's patched context hook preserves the normal
+	 * provider-visible projection; legacy keeps the pre-patch raw session/branch chain.
+	 */
+	remoteV2ContextSource: RemoteV2ContextSource;
 	/** Native-method fallback compaction policy (non-Responses APIs, or when the compact endpoint fails). */
 	nativeFallback: NativeFallbackConfig;
 	/**
@@ -99,10 +118,16 @@ export type CompactionConfig = {
 	artifactRoot: string;
 };
 
+export type WebSearchRoute = "local" | "hosted" | "standalone-alpha";
+
 export type WebSearchConfig = {
 	enabled: boolean;
 	/** Exact provider/model keys allowed to use toolkit-native Web Search. */
 	models: string[];
+	/** Explicit route for every model not matched by `routes`. */
+	defaultRoute?: WebSearchRoute;
+	/** Exact `provider/model-id` overrides; no globs or fuzzy matching. */
+	routes?: Record<string, WebSearchRoute>;
 };
 
 export type ImageGenerationConfig = {
@@ -252,6 +277,12 @@ export type DeferredToolCarryoverV1 = {
 
 export type NativeCompactionDetails = NativeCompactionIdentity & {
 	strategy: NativeCompactionStrategy;
+	/**
+	 * Input source recorded for checkpoints created by this extension. Older
+	 * persisted entries may omit it and must not be treated as verified for
+	 * Remote V2 replay.
+	 */
+	inputProvenance?: NativeCompactionInputProvenance;
 	/** Actual producer of the opaque checkpoint; absent on legacy same-model entries. */
 	compactionModel?: NativeCompactionIdentity;
 	/** Cache-stack activation state captured at this opaque checkpoint. */
@@ -265,6 +296,7 @@ export type NativeCompactionDetails = NativeCompactionIdentity & {
 export type NativeCompactionEntry = CompactionEntry<NativeCompactionDetails>;
 
 export type CreateNativeCompactionDetailsInput = NativeCompactionIdentity & {
+	inputProvenance: NativeCompactionInputProvenance;
 	compactionModel?: NativeCompactionIdentity;
 	deferredToolCarryover?: DeferredToolCarryoverV1;
 	compactedWindow: unknown[];
@@ -380,6 +412,16 @@ export function isNativeCompactionIdentity(value: unknown): value is NativeCompa
 	);
 }
 
+export function isNativeCompactionInputProvenance(value: unknown): value is NativeCompactionInputProvenance {
+	return value === NATIVE_COMPACTION_INPUT_PROVENANCE || value === LEGACY_REMOTE_V2_INPUT_PROVENANCE;
+}
+
+export function getRemoteV2InputProvenance(source: RemoteV2ContextSource): NativeCompactionInputProvenance {
+	return source === "pi-context-hook"
+		? NATIVE_COMPACTION_INPUT_PROVENANCE
+		: LEGACY_REMOTE_V2_INPUT_PROVENANCE;
+}
+
 export function isDeferredToolCarryover(value: unknown): value is DeferredToolCarryoverV1 {
 	if (!isRecord(value) || value.version !== 1 || value.source !== CACHE_STACK_ACTIVATION_ENTRY_TYPE) {
 		return false;
@@ -447,6 +489,7 @@ export function isNativeCompactionDetails(value: unknown): value is NativeCompac
 	return (
 		(candidate.strategy === LEGACY_NATIVE_COMPACTION_STRATEGY ||
 			candidate.strategy === REMOTE_V2_COMPACTION_STRATEGY) &&
+		(candidate.inputProvenance === undefined || isNativeCompactionInputProvenance(candidate.inputProvenance)) &&
 		(candidate.compactionModel === undefined || isNativeCompactionIdentity(candidate.compactionModel)) &&
 		(candidate.deferredToolCarryover === undefined || isDeferredToolCarryover(candidate.deferredToolCarryover)) &&
 		Array.isArray(candidate.compactedWindow) &&
@@ -464,6 +507,7 @@ export function isNativeCompactionEntry(value: unknown): value is NativeCompacti
 export function createNativeCompactionDetails(input: CreateNativeCompactionDetailsInput): NativeCompactionDetails {
 	return {
 		strategy: NATIVE_COMPACTION_STRATEGY,
+		inputProvenance: input.inputProvenance,
 		provider: normalizeString(input.provider),
 		api: normalizeString(input.api),
 		model: normalizeString(input.model),
@@ -516,6 +560,8 @@ export const DEFAULT_COMPACTION_CONFIG: CompactionConfig = {
 	contextManagement: "off",
 	allowCompactionContinuityBreak: false,
 	remoteCompactModel: undefined,
+	remoteV2ContextSource: "legacy",
+
 	nativeFallback: { ...DEFAULT_NATIVE_FALLBACK_CONFIG },
 	responsesApis: [...RESPONSES_COMPACT_CAPABLE_APIS],
 	gatewayContextModels: [],