pi-openai-toolkit 0.3.0

package/src/types.ts

@@ -0,0 +1,333 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { CompactionEntry, CompactionResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const TOOLKIT_ID = "pi-openai-toolkit";
+export const COMPACTION_EXTENSION_ID = `${TOOLKIT_ID}:compaction`;
+export const WEB_SEARCH_EXTENSION_ID = `${TOOLKIT_ID}:web-search`;
+export const DEFAULT_ARTIFACT_ROOT = "~/.pi/agent/artifacts/pi-openai-toolkit/compaction";
+export const REDACTED_VALUE = "[REDACTED]";
+/**
+ * APIs the extension knows how to build a `/responses/compact` URL for.
+ * `compaction.responsesApis` in config.json may only narrow this set.
+ */
+export const RESPONSES_COMPACT_CAPABLE_APIS = ["openai-responses", "openai-codex-responses"] as const;
+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;
+/**
+ * Pi currently requires CompactionResult.summary to be text. This marker is only a
+ * replay shim; the provider receives the opaque item from details.compactedWindow.
+ */
+export const NATIVE_COMPACTION_FALLBACK_SUMMARY = "[OpenAI remote v2 opaque compaction checkpoint]";
+
+export const THINKING_LEVELS: readonly ThinkingLevel[] = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+];
+
+export type DebugArtifactKind =
+	| "provider-request"
+	| "compact-response"
+	| "compaction-event"
+	| "lifecycle";
+
+export type CompactionConfig = {
+	enabled: boolean;
+	/**
+	 * Allow a Responses session whose latest compaction was not created by this extension
+	 * to restart native compaction from Pi's current serialized session context.
+	 */
+	allowCompactionContinuityBreak: boolean;
+	/**
+	 * "provider/model-id" used for native-method fallback compaction (non-Responses APIs,
+	 * or when the compact endpoint fails). Unset = current model via pi's default path.
+	 */
+	model?: string;
+	/** Thinking level passed to pi's native compact() when the fallback model runs. */
+	thinkingLevel: ThinkingLevel;
+	/** Subset of RESPONSES_COMPACT_CAPABLE_APIS that should use remote compaction. */
+	responsesApis: string[];
+	notifyOnLoad: boolean;
+	debug: boolean;
+	logProviderPayloads: boolean;
+	logCompactResponses: boolean;
+	redactSensitiveData: boolean;
+	artifactRoot: string;
+};
+
+export type WebSearchConfig = {
+	enabled: boolean;
+	/** Exact provider/model keys allowed to use toolkit-native Web Search. */
+	models: string[];
+};
+
+export type ToolkitConfig = {
+	compaction: CompactionConfig;
+	webSearch: WebSearchConfig;
+};
+
+export type LoadedToolkitConfig = {
+	config: ToolkitConfig;
+	/** Path of the config file that was applied, if it existed and parsed. */
+	source?: string;
+	warnings: string[];
+};
+
+export type ArtifactPaths = {
+	rootDir: string;
+	sessionDir: string;
+	providerRequestsDir: string;
+	compactResponsesDir: string;
+	compactionDir: string;
+	lifecycleDir: string;
+};
+
+export type ArtifactSessionInfo = {
+	cwd: string;
+	sessionId?: string;
+	sessionFile?: string;
+	sessionDir?: string;
+};
+
+export type ArtifactContext = ArtifactSessionInfo | Pick<ExtensionContext, "cwd" | "sessionManager">;
+
+export type DebugArtifactEnvelope = {
+	extension: string;
+	kind: DebugArtifactKind;
+	timestamp: string;
+	cwd: string;
+	sessionId?: string;
+	sessionFile?: string;
+	sessionDir?: string;
+	redaction: {
+		enabled: boolean;
+	};
+	data: unknown;
+};
+
+export type RedactOptions = {
+	placeholder?: string;
+};
+
+export type NativeCompactionStrategy =
+	| typeof LEGACY_NATIVE_COMPACTION_STRATEGY
+	| typeof REMOTE_V2_COMPACTION_STRATEGY;
+
+export type NativeCompactionRequestMeta = {
+	tokensBefore?: number;
+	previousSummaryPresent?: boolean;
+};
+
+export type NativeCompactionIdentity = {
+	provider: string;
+	api: string;
+	model: string;
+	baseUrl: string;
+};
+
+export type NativeCompactionDetails = NativeCompactionIdentity & {
+	strategy: NativeCompactionStrategy;
+	compactedWindow: unknown[];
+	compactResponseId?: string;
+	createdAt: string;
+	requestMeta?: NativeCompactionRequestMeta;
+};
+
+export type NativeCompactionEntry = CompactionEntry<NativeCompactionDetails>;
+
+export type CreateNativeCompactionDetailsInput = NativeCompactionIdentity & {
+	compactedWindow: unknown[];
+	compactResponseId?: string;
+	createdAt?: string;
+	requestMeta?: NativeCompactionRequestMeta;
+};
+
+export type CreateNativeCompactionResultInput = {
+	firstKeptEntryId: string;
+	tokensBefore: number;
+	details: NativeCompactionDetails;
+	/**
+	 * Summary text extracted from the compact response. Stored as the entry summary so
+	 * pi's default replay still has real context after switching to an unsupported model.
+	 */
+	summary?: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isFiniteNonNegativeNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function normalizeString(value: string): string {
+	return value.trim();
+}
+
+function isStructuredValue(value: unknown): boolean {
+	if (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean"
+	) {
+		return true;
+	}
+
+	if (Array.isArray(value)) {
+		return value.every(isStructuredValue);
+	}
+
+	if (isRecord(value)) {
+		return Object.values(value).every(isStructuredValue);
+	}
+
+	return false;
+}
+
+function cloneStructuredValue(value: unknown): unknown {
+	if (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean"
+	) {
+		return value;
+	}
+
+	if (Array.isArray(value)) {
+		return value.map(cloneStructuredValue);
+	}
+
+	if (isRecord(value)) {
+		const clone: Record<string, unknown> = {};
+		for (const [key, nested] of Object.entries(value)) {
+			clone[key] = cloneStructuredValue(nested);
+		}
+		return clone;
+	}
+
+	throw new Error(`Unsupported structured value: ${typeof value}`);
+}
+
+function isCompactedWindowItem(value: unknown): value is Record<string, unknown> {
+	return isRecord(value) && Object.values(value).every(isStructuredValue);
+}
+
+export function isNativeCompactionRequestMeta(value: unknown): value is NativeCompactionRequestMeta {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	const { tokensBefore, previousSummaryPresent } = value;
+	if (tokensBefore !== undefined && !isFiniteNonNegativeNumber(tokensBefore)) {
+		return false;
+	}
+
+	if (previousSummaryPresent !== undefined && typeof previousSummaryPresent !== "boolean") {
+		return false;
+	}
+
+	return true;
+}
+
+export function isNativeCompactionIdentity(value: unknown): value is NativeCompactionIdentity {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	return (
+		isNonEmptyString(value.provider) &&
+		isNonEmptyString(value.api) &&
+		isNonEmptyString(value.model) &&
+		isNonEmptyString(value.baseUrl)
+	);
+}
+
+export function isNativeCompactionDetails(value: unknown): value is NativeCompactionDetails {
+	if (!isRecord(value) || !isNativeCompactionIdentity(value)) {
+		return false;
+	}
+
+	const candidate = value as Record<string, unknown>;
+	return (
+		(candidate.strategy === LEGACY_NATIVE_COMPACTION_STRATEGY ||
+			candidate.strategy === REMOTE_V2_COMPACTION_STRATEGY) &&
+		Array.isArray(candidate.compactedWindow) &&
+		candidate.compactedWindow.every(isCompactedWindowItem) &&
+		isNonEmptyString(candidate.createdAt) &&
+		(candidate.compactResponseId === undefined || isNonEmptyString(candidate.compactResponseId)) &&
+		(candidate.requestMeta === undefined || isNativeCompactionRequestMeta(candidate.requestMeta))
+	);
+}
+
+export function isNativeCompactionEntry(value: unknown): value is NativeCompactionEntry {
+	return isRecord(value) && value.type === "compaction" && isNativeCompactionDetails(value.details);
+}
+
+export function createNativeCompactionDetails(input: CreateNativeCompactionDetailsInput): NativeCompactionDetails {
+	return {
+		strategy: NATIVE_COMPACTION_STRATEGY,
+		provider: normalizeString(input.provider),
+		api: normalizeString(input.api),
+		model: normalizeString(input.model),
+		baseUrl: normalizeString(input.baseUrl),
+		compactedWindow: input.compactedWindow.map((item) => cloneStructuredValue(item)),
+		compactResponseId: isNonEmptyString(input.compactResponseId) ? normalizeString(input.compactResponseId) : undefined,
+		createdAt: isNonEmptyString(input.createdAt) ? normalizeString(input.createdAt) : new Date().toISOString(),
+		requestMeta: input.requestMeta
+			? {
+				...(input.requestMeta.tokensBefore !== undefined ? { tokensBefore: input.requestMeta.tokensBefore } : {}),
+				...(input.requestMeta.previousSummaryPresent !== undefined
+					? { previousSummaryPresent: input.requestMeta.previousSummaryPresent }
+					: {}),
+			}
+			: undefined,
+	};
+}
+
+export function createNativeCompactionResult(
+	input: CreateNativeCompactionResultInput,
+): CompactionResult<NativeCompactionDetails> {
+	const summary = input.summary?.trim();
+	return {
+		summary: summary && summary.length > 0 ? summary : NATIVE_COMPACTION_FALLBACK_SUMMARY,
+		firstKeptEntryId: input.firstKeptEntryId,
+		tokensBefore: input.tokensBefore,
+		details: input.details,
+	};
+}
+
+export const DEFAULT_COMPACTION_CONFIG: CompactionConfig = {
+	enabled: true,
+	allowCompactionContinuityBreak: false,
+	model: undefined,
+	thinkingLevel: "off",
+	responsesApis: [...RESPONSES_COMPACT_CAPABLE_APIS],
+	notifyOnLoad: false,
+	debug: false,
+	logProviderPayloads: false,
+	logCompactResponses: false,
+	redactSensitiveData: true,
+	artifactRoot: DEFAULT_ARTIFACT_ROOT,
+};
+
+export const DEFAULT_WEB_SEARCH_CONFIG: WebSearchConfig = {
+	enabled: true,
+	models: [],
+};
+
+export const DEFAULT_TOOLKIT_CONFIG: ToolkitConfig = {
+	compaction: DEFAULT_COMPACTION_CONFIG,
+	webSearch: DEFAULT_WEB_SEARCH_CONFIG,
+};

package/src/web-search/extension.ts

@@ -0,0 +1,80 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadToolkitConfig } from "../config";
+import { transformWebSearchPayload } from "./payload";
+import { appendWebSearchPrompt } from "./prompt";
+import { isWebSearchEnabledForModel, type WebSearchModel } from "./types";
+
+function syncLocalWebSearchTool(
+	pi: ExtensionAPI,
+	model: WebSearchModel | undefined,
+	config: Parameters<typeof isWebSearchEnabledForModel>[1],
+	state: { wasActiveBeforeOwnership?: boolean; toolkitOwnsTool: boolean },
+): void {
+	const eligible = isWebSearchEnabledForModel(model, config);
+	const activeTools = pi.getActiveTools();
+
+	if (eligible) {
+		if (!state.toolkitOwnsTool) {
+			state.wasActiveBeforeOwnership = activeTools.includes("web_search");
+			state.toolkitOwnsTool = true;
+		}
+
+		if (activeTools.includes("web_search")) {
+			pi.setActiveTools(activeTools.filter((name) => name !== "web_search"));
+		}
+		return;
+	}
+
+	if (!state.toolkitOwnsTool) return;
+
+	if (state.wasActiveBeforeOwnership && !activeTools.includes("web_search")) {
+		pi.setActiveTools([...activeTools, "web_search"]);
+	}
+	state.wasActiveBeforeOwnership = undefined;
+	state.toolkitOwnsTool = false;
+}
+
+export function registerWebSearchExtension(
+	pi: ExtensionAPI,
+	loadConfig: typeof loadToolkitConfig = loadToolkitConfig,
+): void {
+	const toolState = { wasActiveBeforeOwnership: undefined as boolean | undefined, toolkitOwnsTool: false };
+
+	pi.on("session_start", (_event, ctx) => {
+		const { config } = loadConfig();
+		syncLocalWebSearchTool(pi, ctx.model, config.webSearch, toolState);
+	});
+
+	pi.on("model_select", (event) => {
+		const { config } = loadConfig();
+		syncLocalWebSearchTool(pi, event.model, config.webSearch, toolState);
+	});
+
+	pi.on("before_agent_start", (event, ctx) => {
+		const { config } = loadConfig();
+		syncLocalWebSearchTool(pi, ctx.model, config.webSearch, toolState);
+		const systemPrompt = appendWebSearchPrompt({
+			model: ctx.model,
+			config: config.webSearch,
+			systemPrompt: event.systemPrompt,
+		});
+
+		return systemPrompt === event.systemPrompt ? undefined : { systemPrompt };
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		const { config } = loadConfig();
+		syncLocalWebSearchTool(pi, ctx.model, config.webSearch, toolState);
+		const transformed = transformWebSearchPayload({
+			model: ctx.model,
+			config: config.webSearch,
+			payload: event.payload,
+		});
+
+		return transformed.changed ? transformed.payload : undefined;
+	});
+}
+
+export default function webSearchExtension(pi: ExtensionAPI): void {
+	registerWebSearchExtension(pi);
+}

package/src/web-search/payload.ts

@@ -0,0 +1,96 @@
+import type { WebSearchConfig } from "../types";
+import {
+	WEB_SEARCH_SOURCE_INCLUDE,
+	isWebSearchEnabledForModel,
+	type WebSearchModel,
+	type WebSearchPayloadTransform,
+} from "./types";
+
+type JsonObject = Record<string, unknown>;
+
+function isRecord(value: unknown): value is JsonObject {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isLocalWebSearchFunction(tool: unknown): boolean {
+	return isRecord(tool) && tool.type === "function" && tool.name === "web_search";
+}
+
+function isNativeWebSearchTool(tool: unknown): boolean {
+	return isRecord(tool) && (tool.type === "web_search" || tool.type === "web_search_preview");
+}
+
+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 };
+	}
+	if (!isWebSearchEnabledForModel(model, config)) {
+		return { payload, outcome: "unsupported-model", changed: false };
+	}
+	if (!isRecord(payload)) {
+		return { payload, outcome: "non-object-payload", changed: false };
+	}
+
+	const toolsValue = payload.tools;
+	if (toolsValue !== undefined && !Array.isArray(toolsValue)) {
+		return { payload, outcome: "invalid-tools", changed: false };
+	}
+	const tools = toolsValue ?? [];
+	const includeValue = payload.include;
+	if (includeValue !== undefined && !Array.isArray(includeValue)) {
+		return { payload, outcome: "invalid-include", changed: false };
+	}
+	const include = includeValue ?? [];
+	const normalizedTools: unknown[] = [];
+	let nativeToolCount = 0;
+	let localToolRemoved = false;
+	for (const tool of tools) {
+		if (isLocalWebSearchFunction(tool)) {
+			localToolRemoved = true;
+			continue;
+		}
+		if (isNativeWebSearchTool(tool)) {
+			nativeToolCount += 1;
+			if (nativeToolCount > 1) continue;
+		}
+		normalizedTools.push(tool);
+	}
+	const hasNativeTool = nativeToolCount > 0;
+	if (!hasNativeTool) {
+		normalizedTools.push({ type: "web_search" });
+	}
+
+	const normalizedInclude: unknown[] = [];
+	let sourceIncludeCount = 0;
+	for (const item of include) {
+		if (item === WEB_SEARCH_SOURCE_INCLUDE) {
+			sourceIncludeCount += 1;
+			if (sourceIncludeCount > 1) continue;
+		}
+		normalizedInclude.push(item);
+	}
+	if (sourceIncludeCount === 0) {
+		normalizedInclude.push(WEB_SEARCH_SOURCE_INCLUDE);
+	}
+
+	const toolsChanged = localToolRemoved || !hasNativeTool || nativeToolCount > 1;
+	const includeChanged = sourceIncludeCount !== 1;
+	if (!toolsChanged && !includeChanged) {
+		return { payload, outcome: "existing-native-tool", changed: false };
+	}
+
+	return {
+		payload: {
+			...payload,
+			...(toolsChanged ? { tools: normalizedTools } : {}),
+			...(includeChanged ? { include: normalizedInclude } : {}),
+		},
+		outcome: hasNativeTool ? "existing-native-tool" : "injected-native-tool",
+		changed: true,
+	};
+}

package/src/web-search/prompt.ts

@@ -0,0 +1,20 @@
+import type { WebSearchConfig } from "../types";
+import { isWebSearchEnabledForModel, WEB_SEARCH_PROMPT_MARKER, type WebSearchModel } from "./types";
+
+export const WEB_SEARCH_PROMPT_SECTION = `${WEB_SEARCH_PROMPT_MARKER}
+## Web Search
+
+Native OpenAI Web Search is available for this turn. Use it for current or online information when freshness matters instead of guessing, and cite the returned sources in the answer.`;
+
+export function appendWebSearchPrompt(args: {
+	model: WebSearchModel | undefined;
+	config: WebSearchConfig;
+	systemPrompt: string;
+}): string {
+	const { model, config, systemPrompt } = args;
+	if (!isWebSearchEnabledForModel(model, config) || systemPrompt.includes(WEB_SEARCH_PROMPT_MARKER)) {
+		return systemPrompt;
+	}
+
+	return `${systemPrompt.trimEnd()}\n\n${WEB_SEARCH_PROMPT_SECTION}`;
+}

package/src/web-search/types.ts

@@ -0,0 +1,47 @@
+import type { WebSearchConfig } 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 type WebSearchCapableApi = (typeof WEB_SEARCH_CAPABLE_APIS)[number];
+
+export type WebSearchModel = {
+	api?: string;
+	provider?: string;
+	id?: string;
+};
+
+export type WebSearchPayloadOutcome =
+	| "disabled"
+	| "unsupported-model"
+	| "non-object-payload"
+	| "invalid-tools"
+	| "invalid-include"
+	| "existing-native-tool"
+	| "injected-native-tool";
+
+export type WebSearchPayloadTransform = {
+	payload: unknown;
+	outcome: WebSearchPayloadOutcome;
+	changed: boolean;
+};
+
+export function getWebSearchModelKey(model: WebSearchModel | undefined): string | undefined {
+	if (!model?.provider || !model.id) return undefined;
+	return `${model.provider}/${model.id}`;
+}
+
+export function isWebSearchEnabledForModel(
+	model: WebSearchModel | undefined,
+	config: WebSearchConfig,
+): boolean {
+	const modelKey = getWebSearchModelKey(model);
+	return (
+		config.enabled &&
+		typeof model?.api === "string" &&
+		(WEB_SEARCH_CAPABLE_APIS as readonly string[]).includes(model.api) &&
+		modelKey !== undefined &&
+		config.models.includes(modelKey)
+	);
+}

package/tsconfig.check.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "strict": true,
+    "baseUrl": ".",
+    "typeRoots": ["./node_modules/@types"]
+  },
+  "include": [
+    "extensions/compaction.ts",
+    "extensions/web-search.ts",
+    "src/compact-client.ts",
+    "src/config.ts",
+    "src/debug.ts",
+    "src/details-store.ts",
+    "src/extension-runtime.ts",
+    "src/native-fallback.ts",
+    "src/payload-rewrite.ts",
+    "src/provider-headers.ts",
+    "src/remote-v2-client.ts",
+    "src/request-context-cache.ts",
+    "src/runtime.ts",
+    "src/serializer.ts",
+    "src/supported-environment.ts",
+    "src/types.ts",
+    "src/web-search/extension.ts",
+    "src/web-search/payload.ts",
+    "src/web-search/prompt.ts",
+    "src/web-search/types.ts"
+  ]
+}