pi-openai-toolkit 0.14.6 → 0.14.8

package/src/web-search/payload.ts

@@ -1,7 +1,10 @@
 import type { WebSearchConfig } from "../types";
 import {
+	LOCAL_WEB_SEARCH_TOOL_NAME,
+	resolveWebSearchRoute,
+	WEB_RUN_TOOL_NAME,
 	WEB_SEARCH_SOURCE_INCLUDE,
-	isWebSearchEnabledForModel,
+	isWebSearchRoute,
 	type WebSearchModel,
 	type WebSearchPayloadTransform,
 } from "./types";
@@ -13,47 +16,236 @@ function isRecord(value: unknown): value is JsonObject {
 }
 
 function isLocalWebSearchFunction(tool: unknown): boolean {
-	return isRecord(tool) && tool.type === "function" && tool.name === "web_search";
+	return isRecord(tool) && tool.type === "function" && tool.name === LOCAL_WEB_SEARCH_TOOL_NAME;
+}
+
+function isStandaloneWebRunFunction(tool: unknown): boolean {
+	return isRecord(tool) && tool.type === "function" && tool.name === WEB_RUN_TOOL_NAME;
 }
 
 function isNativeWebSearchTool(tool: unknown): boolean {
 	return isRecord(tool) && (tool.type === "web_search" || tool.type === "web_search_preview");
 }
 
+function explicitRouteFailure(resolution: ReturnType<typeof resolveWebSearchRoute>): WebSearchPayloadTransform {
+	const reason = resolution.route === "none" ? resolution.reason : resolution.reason;
+	return {
+		payload: undefined,
+		outcome: "unavailable-route",
+		changed: false,
+		fatal: true,
+		errorMessage: `Web Search route is unavailable${reason ? ` (${reason})` : ""}; request aborted without fallback.`,
+	};
+}
+
+function unavailableRouteTransform(
+	payload: unknown,
+	resolution: ReturnType<typeof resolveWebSearchRoute>,
+): WebSearchPayloadTransform {
+	const base = explicitRouteFailure(resolution);
+	return { ...base, payload };
+}
+
+function transformStandalonePayload(args: {
+	payload: JsonObject;
+	resolution: ReturnType<typeof resolveWebSearchRoute>;
+}): WebSearchPayloadTransform {
+	const { payload, resolution } = args;
+	const toolsValue = payload.tools;
+	if (toolsValue !== undefined && !Array.isArray(toolsValue)) {
+		return {
+			payload,
+			outcome: "invalid-tools",
+			changed: false,
+			fatal: resolution.source !== "legacy",
+			errorMessage: "Standalone Web Search requires a provider payload tools array.",
+		};
+	}
+	const includeValue = payload.include;
+	if (includeValue !== undefined && !Array.isArray(includeValue)) {
+		return {
+			payload,
+			outcome: "invalid-include",
+			changed: false,
+			fatal: resolution.source !== "legacy",
+			errorMessage: "Standalone Web Search requires a provider payload include array.",
+		};
+	}
+
+	const tools = toolsValue ?? [];
+	let standaloneToolCount = 0;
+	const normalizedTools = tools.filter((tool) => {
+		if (isLocalWebSearchFunction(tool) || isNativeWebSearchTool(tool)) return false;
+		if (!isStandaloneWebRunFunction(tool)) return true;
+		standaloneToolCount += 1;
+		return standaloneToolCount === 1;
+	});
+	const include = includeValue ?? [];
+	const normalizedInclude = include.filter((item) => item !== WEB_SEARCH_SOURCE_INCLUDE);
+	const toolsChanged = normalizedTools.length !== tools.length;
+	const includeChanged = normalizedInclude.length !== include.length;
+	if (toolsValue !== undefined && !normalizedTools.some(isStandaloneWebRunFunction)) {
+		return {
+			payload,
+			outcome: "unavailable-route",
+			changed: false,
+			fatal: resolution.source !== "legacy",
+			errorMessage: "Standalone Web Search requires the registered web.run tool in the provider payload.",
+		};
+	}
+	if (!toolsChanged && !includeChanged) {
+		return { payload, outcome: "standalone-route", changed: false };
+	}
+
+	return {
+		payload: {
+			...payload,
+			...(toolsChanged ? { tools: normalizedTools } : {}),
+			...(includeChanged ? { include: normalizedInclude } : {}),
+		},
+		outcome: "removed-conflicting-tools",
+		changed: true,
+	};
+}
+
+function transformLocalPayload(args: {
+	payload: JsonObject;
+	resolution: ReturnType<typeof resolveWebSearchRoute>;
+}): WebSearchPayloadTransform {
+	const { payload, resolution } = args;
+	const toolsValue = payload.tools;
+	if (toolsValue !== undefined && !Array.isArray(toolsValue)) {
+		return {
+			payload,
+			outcome: "invalid-tools",
+			changed: false,
+			fatal: resolution.source !== "legacy",
+			errorMessage: "Local Web Search requires a provider payload tools array.",
+		};
+	}
+	const includeValue = payload.include;
+	if (includeValue !== undefined && !Array.isArray(includeValue)) {
+		return {
+			payload,
+			outcome: "invalid-include",
+			changed: false,
+			fatal: resolution.source !== "legacy",
+			errorMessage: "Local Web Search requires a provider payload include array.",
+		};
+	}
+
+	const tools = toolsValue ?? [];
+	const normalizedTools = tools.filter(
+		(tool) => !isStandaloneWebRunFunction(tool) && !isNativeWebSearchTool(tool),
+	);
+	const include = includeValue ?? [];
+	const normalizedInclude = include.filter((item) => item !== WEB_SEARCH_SOURCE_INCLUDE);
+	const toolsChanged = normalizedTools.length !== tools.length;
+	const includeChanged = normalizedInclude.length !== include.length;
+	if (!toolsChanged && !includeChanged) return { payload, outcome: "local-route", changed: false };
+
+	return {
+		payload: {
+			...payload,
+			...(toolsChanged ? { tools: normalizedTools } : {}),
+			...(includeChanged ? { include: normalizedInclude } : {}),
+		},
+		outcome: "removed-conflicting-tools",
+		changed: true,
+	};
+}
+
 export function transformWebSearchPayload(args: {
 	model: WebSearchModel | undefined;
 	config: WebSearchConfig;
 	payload: unknown;
 }): WebSearchPayloadTransform {
 	const { model, config, payload } = args;
-	if (!config.enabled) {
-		return { payload, outcome: "disabled", changed: false };
+	const resolution = resolveWebSearchRoute({ model, config });
+
+	if (resolution.route === "none") {
+		return {
+			payload,
+			outcome: resolution.reason === "disabled" ? "disabled" : "unsupported-model",
+			changed: false,
+		};
 	}
-	if (!isWebSearchEnabledForModel(model, config)) {
-		return { payload, outcome: "unsupported-model", changed: false };
+	if (!resolution.available) {
+		return unavailableRouteTransform(payload, resolution);
 	}
+	if (resolution.route === "local") {
+		if (!isRecord(payload)) {
+			return {
+				payload,
+				outcome: "non-object-payload",
+				changed: false,
+				fatal: resolution.source !== "legacy",
+				errorMessage: "Local Web Search requires an object provider payload.",
+			};
+		}
+		return transformLocalPayload({ payload, resolution });
+	}
+	if (resolution.route === "standalone-alpha") {
+		if (!isRecord(payload)) {
+			return {
+				payload,
+				outcome: "non-object-payload",
+				changed: false,
+				fatal: resolution.source !== "legacy",
+				errorMessage: "Standalone Web Search requires an object provider payload.",
+			};
+		}
+		return transformStandalonePayload({ payload, resolution });
+	}
+
 	if (!isRecord(payload)) {
-		return { payload, outcome: "non-object-payload", changed: false };
+		return {
+			payload,
+			outcome: "non-object-payload",
+			changed: false,
+			...(resolution.source !== "legacy"
+				? { fatal: true, errorMessage: "Hosted Web Search requires an object provider payload." }
+				: {}),
+		};
 	}
 
 	const toolsValue = payload.tools;
 	if (toolsValue !== undefined && !Array.isArray(toolsValue)) {
-		return { payload, outcome: "invalid-tools", changed: false };
+		return {
+			payload,
+			outcome: "invalid-tools",
+			changed: false,
+			...(resolution.source !== "legacy"
+				? { fatal: true, errorMessage: "Hosted Web Search requires a provider payload tools array." }
+				: {}),
+		};
 	}
 	const tools = toolsValue ?? [];
 	const includeValue = payload.include;
 	if (includeValue !== undefined && !Array.isArray(includeValue)) {
-		return { payload, outcome: "invalid-include", changed: false };
+		return {
+			payload,
+			outcome: "invalid-include",
+			changed: false,
+			...(resolution.source !== "legacy"
+				? { fatal: true, errorMessage: "Hosted Web Search requires a provider payload include array." }
+				: {}),
+		};
 	}
 	const include = includeValue ?? [];
 	const normalizedTools: unknown[] = [];
 	let nativeToolCount = 0;
 	let localToolRemoved = false;
+	let standaloneToolRemoved = false;
 	for (const tool of tools) {
 		if (isLocalWebSearchFunction(tool)) {
 			localToolRemoved = true;
 			continue;
 		}
+		if (isStandaloneWebRunFunction(tool)) {
+			standaloneToolRemoved = true;
+			continue;
+		}
 		if (isNativeWebSearchTool(tool)) {
 			nativeToolCount += 1;
 			if (nativeToolCount > 1) continue;
@@ -78,7 +270,7 @@ export function transformWebSearchPayload(args: {
 		normalizedInclude.push(WEB_SEARCH_SOURCE_INCLUDE);
 	}
 
-	const toolsChanged = localToolRemoved || !hasNativeTool || nativeToolCount > 1;
+	const toolsChanged = localToolRemoved || standaloneToolRemoved || !hasNativeTool || nativeToolCount > 1;
 	const includeChanged = sourceIncludeCount !== 1;
 	if (!toolsChanged && !includeChanged) {
 		return { payload, outcome: "existing-native-tool", changed: false };
@@ -94,3 +286,10 @@ export function transformWebSearchPayload(args: {
 		changed: true,
 	};
 }
+
+export const _payloadTest = {
+	isLocalWebSearchFunction,
+	isNativeWebSearchTool,
+	isStandaloneWebRunFunction,
+	isWebSearchRoute,
+};

package/src/web-search/prompt.ts

@@ -1,20 +1,59 @@
 import type { WebSearchConfig } from "../types";
-import { isWebSearchEnabledForModel, WEB_SEARCH_PROMPT_MARKER, type WebSearchModel } from "./types";
+import {
+	resolveWebSearchRoute,
+	WEB_SEARCH_PROMPT_MARKER,
+	type WebSearchModel,
+} from "./types";
 
 export const WEB_SEARCH_PROMPT_SECTION = `${WEB_SEARCH_PROMPT_MARKER}
 ## Web Search
 
 The hosted \`web_search\` tool is part of your tool list for this model. The API executes it server-side: it is a real callable tool even though no client-side function schema or description accompanies it. Call it whenever current or online information matters instead of guessing, cite the returned sources in the answer, and never claim that web search or internet access is unavailable while this section is present.`;
 
+export const LOCAL_WEB_SEARCH_PROMPT_SECTION = `${WEB_SEARCH_PROMPT_MARKER}
+## Web Search
+
+The local \`web_search\` tool is available for this model. Use it when current or online information matters, and cite the sources returned by that tool. Do not claim that the provider API executes this local tool server-side.`;
+
+export const STANDALONE_ALPHA_WEB_SEARCH_PROMPT_SECTION = `${WEB_SEARCH_PROMPT_MARKER}
+## Web Search
+
+The \`web.run\` tool is available for this model. It is a sequential local wrapper backed by CPA/Codex standalone search at the provider's \`/alpha/search\` endpoint. It supports \`search_query\`, \`image_query\`, \`open\`, \`click\`, \`find\`, \`screenshot\`, \`finance\`, \`weather\`, \`sports\`, and \`time\`. Use it for current or online information, preserve reference ids when following results, and cite the returned sources.`;
+
+function removeToolkitWebSearchPrompt(systemPrompt: string): string {
+	const markerIndex = systemPrompt.indexOf(WEB_SEARCH_PROMPT_MARKER);
+	if (markerIndex < 0) return systemPrompt;
+	return systemPrompt.slice(0, markerIndex).trimEnd();
+}
+
+function promptSectionForRoute(route: "local" | "hosted" | "standalone-alpha"): string {
+	switch (route) {
+		case "local":
+			return LOCAL_WEB_SEARCH_PROMPT_SECTION;
+		case "hosted":
+			return WEB_SEARCH_PROMPT_SECTION;
+		case "standalone-alpha":
+			return STANDALONE_ALPHA_WEB_SEARCH_PROMPT_SECTION;
+	}
+}
+
 export function appendWebSearchPrompt(args: {
 	model: WebSearchModel | undefined;
 	config: WebSearchConfig;
 	systemPrompt: string;
+	/** Lifecycle registration can override this when the selected local wrapper is unavailable. */
+	routeAvailable?: boolean;
 }): string {
 	const { model, config, systemPrompt } = args;
-	if (!isWebSearchEnabledForModel(model, config) || systemPrompt.includes(WEB_SEARCH_PROMPT_MARKER)) {
-		return systemPrompt;
-	}
+	const basePrompt = removeToolkitWebSearchPrompt(systemPrompt);
+	const resolution = resolveWebSearchRoute({ model, config });
+	if (args.routeAvailable === false || resolution.route === "none" || !resolution.available) return basePrompt;
 
-	return `${systemPrompt.trimEnd()}\n\n${WEB_SEARCH_PROMPT_SECTION}`;
+	const section = promptSectionForRoute(resolution.route);
+	return `${basePrompt.trimEnd()}\n\n${section}`;
 }
+
+export const _promptTest = {
+	removeToolkitWebSearchPrompt,
+	promptSectionForRoute,
+};

package/src/web-search/types.ts

@@ -1,11 +1,15 @@
 import { getExactModelKey, isExactModelAllowed } from "../model-scope";
-import type { WebSearchConfig } from "../types";
+import type { WebSearchConfig, WebSearchRoute } from "../types";
 
 export const WEB_SEARCH_CAPABLE_APIS = ["openai-responses", "openai-codex-responses"] as const;
 export const WEB_SEARCH_SOURCE_INCLUDE = "web_search_call.action.sources";
 export const WEB_SEARCH_PROMPT_MARKER = "<!-- pi-openai-toolkit:web-search -->";
+export const WEB_RUN_TOOL_NAME = "web.run";
+export const LOCAL_WEB_SEARCH_TOOL_NAME = "web_search";
 
 export type WebSearchCapableApi = (typeof WEB_SEARCH_CAPABLE_APIS)[number];
+export type WebSearchRouteSource = "exact" | "default" | "legacy" | "none";
+export type WebSearchRouteUnavailableReason = "missing-model" | "unsupported-api" | "invalid-route";
 
 export type WebSearchModel = {
 	api?: string;
@@ -13,6 +17,21 @@ export type WebSearchModel = {
 	id?: string;
 };
 
+export type WebSearchRouteResolution =
+	| {
+			route: "none";
+			source: "none";
+			modelKey?: string;
+			reason: "disabled" | "unconfigured";
+	  }
+	| {
+			route: WebSearchRoute;
+			source: Exclude<WebSearchRouteSource, "none">;
+			modelKey?: string;
+			available: boolean;
+			reason?: WebSearchRouteUnavailableReason;
+	  };
+
 export type WebSearchPayloadOutcome =
 	| "disabled"
 	| "unsupported-model"
@@ -20,26 +39,106 @@ export type WebSearchPayloadOutcome =
 	| "invalid-tools"
 	| "invalid-include"
 	| "existing-native-tool"
-	| "injected-native-tool";
+	| "injected-native-tool"
+	| "local-route"
+	| "standalone-route"
+	| "removed-conflicting-tools"
+	| "unavailable-route";
 
 export type WebSearchPayloadTransform = {
 	payload: unknown;
 	outcome: WebSearchPayloadOutcome;
 	changed: boolean;
+	/** Explicit route failures must abort rather than silently select another search path. */
+	fatal?: boolean;
+	errorMessage?: string;
 };
 
 export function getWebSearchModelKey(model: WebSearchModel | undefined): string | undefined {
 	return getExactModelKey(model);
 }
 
+export function isWebSearchRoute(value: unknown): value is WebSearchRoute {
+	return value === "local" || value === "hosted" || value === "standalone-alpha";
+}
+
+function selectedRoute(args: {
+	route: WebSearchRoute;
+	source: Exclude<WebSearchRouteSource, "none">;
+	model: WebSearchModel | undefined;
+	modelKey: string | undefined;
+}): WebSearchRouteResolution {
+	if (!args.modelKey) {
+		return {
+			route: args.route,
+			source: args.source,
+			available: false,
+			reason: "missing-model",
+		};
+	}
+	if (args.route !== "local" && !isWebSearchCapableApi(args.model?.api)) {
+		return {
+			route: args.route,
+			source: args.source,
+			modelKey: args.modelKey,
+			available: false,
+			reason: "unsupported-api",
+		};
+	}
+	return {
+		route: args.route,
+		source: args.source,
+		modelKey: args.modelKey,
+		available: true,
+	};
+}
+
+export function isWebSearchCapableApi(api: unknown): api is WebSearchCapableApi {
+	return typeof api === "string" && (WEB_SEARCH_CAPABLE_APIS as readonly string[]).includes(api);
+}
+
+/**
+ * Resolve exactly one configured Web Search route. The legacy model allowlist is
+ * deliberately consulted only after explicit route fields so old configs retain
+ * hosted behavior without becoming an implicit alpha-search opt-in.
+ */
+export function resolveWebSearchRoute(args: {
+	model: WebSearchModel | undefined;
+	config: WebSearchConfig;
+}): WebSearchRouteResolution {
+	const { model, config } = args;
+	const modelKey = getWebSearchModelKey(model);
+	if (!config.enabled) {
+		return { route: "none", source: "none", modelKey, reason: "disabled" };
+	}
+
+	const exactRoute = modelKey ? config.routes?.[modelKey] : undefined;
+	if (exactRoute !== undefined) {
+		if (!isWebSearchRoute(exactRoute)) {
+			return { route: "none", source: "none", modelKey, reason: "unconfigured" };
+		}
+		return selectedRoute({ route: exactRoute, source: "exact", model, modelKey });
+	}
+
+	if (config.defaultRoute !== undefined) {
+		if (!isWebSearchRoute(config.defaultRoute)) {
+			return { route: "none", source: "none", modelKey, reason: "unconfigured" };
+		}
+		return selectedRoute({ route: config.defaultRoute, source: "default", model, modelKey });
+	}
+
+	if (modelKey && isExactModelAllowed(model, config.models) && isWebSearchCapableApi(model?.api)) {
+		return selectedRoute({ route: "hosted", source: "legacy", model, modelKey });
+	}
+
+	return { route: "none", source: "none", modelKey, reason: "unconfigured" };
+}
+
+/** Compatibility predicate for callers that specifically need the hosted path. */
 export function isWebSearchEnabledForModel(
 	model: WebSearchModel | undefined,
 	config: WebSearchConfig,
 ): boolean {
-	return (
-		config.enabled &&
-		typeof model?.api === "string" &&
-		(WEB_SEARCH_CAPABLE_APIS as readonly string[]).includes(model.api) &&
-		isExactModelAllowed(model, config.models)
-	);
+	const resolution = resolveWebSearchRoute({ model, config });
+	return resolution.route === "hosted" && resolution.available;
 }

package/tsconfig.check.json

@@ -17,6 +17,8 @@
     "extensions/image-generation.ts",
     "extensions/auto-mode.ts",
     "src/compact-client.ts",
+    "src/compaction-projection.ts",
+    "src/pi-context-hook.ts",
     "src/config.ts",
     "src/debug.ts",
     "src/details-store.ts",