pi-openai-toolkit 0.23.1 → 0.24.0

package/src/context-management/codex-provider.ts

@@ -1,270 +0,0 @@
-import type { Api, Model, ProviderHeaders } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { mergeProviderHeaders } from "../provider-headers";
-import {
-	CODEX_AFFINITY_SCOPE,
-	CODEX_CLIENT_VERSION,
-	CODEX_GATEWAY_ORIGINATOR,
-	buildCodexCliUserAgent,
-	filterCodexGatewayHeaders,
-} from "../responses-headers";
-export { CODEX_AFFINITY_SCOPE } from "../responses-headers";
-import { normalizeBaseUrl, resolveEffectiveModel, VIRTUAL_MODEL_API } from "../runtime";
-import { isExactModelAllowed } from "../model-scope";
-import {
-	isNonEmptyString,
-	type CodexContextProvider,
-	type CodexContextProviderResolution,
-} from "./types";
-
-const CODEX_PROVIDER = "openai-codex";
-const CODEX_API = "openai-codex-responses";
-const GATEWAY_API = "openai-responses";
-const CODEX_TOOL_ORIGINATOR = CODEX_GATEWAY_ORIGINATOR;
-const CODEX_TOOL_VERSION = "0.0.0";
-const CODEX_SESSION_ID_MAX_LENGTH = 64;
-
-export const CODEX_CONTEXT_PROVIDER_ERROR =
-	"Remote Context management requires a configured Codex-compatible backend";
-
-export function isNativeCodexModel(
-	model: ExtensionContext["model"] | undefined,
-): boolean {
-	return model?.provider === CODEX_PROVIDER && model.api === CODEX_API;
-}
-
-export function isCodexGatewayModel(
-	model: ExtensionContext["model"] | undefined,
-	gatewayModels: readonly string[] = [],
-): boolean {
-	// Gateway coverage is an operator allowlist of exact "provider/model" keys
-	// (compaction.gatewayContextModels). The backend relay must actually pass
-	// hosted window markers through; models outside the list stay on remote
-	// compaction v2.
-	if (!model || model.api !== GATEWAY_API) return false;
-	return isExactModelAllowed(model, gatewayModels);
-}
-
-export function normalizeCodexBackendBaseUrl(baseUrl: string | undefined | null): string | undefined {
-	const normalized = normalizeBaseUrl(baseUrl);
-	if (!normalized) return undefined;
-	try {
-		const url = new URL(normalized);
-		const pathname = url.pathname.replace(/\/+$/, "");
-		if (pathname.endsWith("/codex/responses")) {
-			url.pathname = pathname.slice(0, -"/responses".length);
-			return url.toString().replace(/\/$/, "");
-		}
-		if (pathname.endsWith("/codex")) return normalized;
-		if (pathname.endsWith("/backend-api") || pathname.endsWith("/api")) {
-			return `${normalized}/codex`;
-		}
-		if (pathname === "") return `${normalized}/api/codex`;
-		if (pathname === "/") return `${normalized}/api/codex`;
-		return undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-function headerValue(headers: ProviderHeaders | undefined, name: string): string | undefined {
-	const wanted = name.toLowerCase();
-	for (const [key, value] of Object.entries(headers ?? {})) {
-		if (key.toLowerCase() === wanted && typeof value === "string" && value.trim()) {
-			return value.trim();
-		}
-	}
-	return undefined;
-}
-
-function bearerToken(value: string | undefined): string | undefined {
-	if (!value) return undefined;
-	const match = value.trim().match(/^Bearer\s+(.+)$/i);
-	return (match?.[1] ?? value).trim() || undefined;
-}
-
-function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
-	const parts = token.split(".");
-	if (parts.length !== 3) return undefined;
-	try {
-		const value: unknown = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf8"));
-		return value && typeof value === "object" && !Array.isArray(value)
-			? value as Record<string, unknown>
-			: undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-function accountIdFromToken(token: string): string | undefined {
-	const payload = decodeJwtPayload(token);
-	const direct = payload?.chatgpt_account_id;
-	if (isNonEmptyString(direct)) return direct.trim();
-	const auth = payload?.["https://api.openai.com/auth"];
-	if (!auth || typeof auth !== "object" || Array.isArray(auth)) return undefined;
-	const nested = (auth as Record<string, unknown>).chatgpt_account_id;
-	return isNonEmptyString(nested) ? nested.trim() : undefined;
-}
-
-function userAgent(version: string): string {
-	return buildCodexCliUserAgent(version);
-}
-
-function clampSessionId(value: string | undefined): string | undefined {
-	if (!value) return undefined;
-	const chars = Array.from(value.trim());
-	if (chars.length === 0) return undefined;
-	return chars.length <= CODEX_SESSION_ID_MAX_LENGTH
-		? chars.join("")
-		: chars.slice(0, CODEX_SESSION_ID_MAX_LENGTH).join("");
-}
-
-function resolveContextSessionId(ctx: ExtensionContext): string | undefined {
-	try {
-		return clampSessionId(ctx.sessionManager.getSessionId());
-	} catch {
-		return undefined;
-	}
-}
-
-export type CodexContextProviderHeaderOptions = {
-	sessionId?: string;
-	clientRequestId?: string;
-};
-
-export function codexContextProviderHeaders(
-	provider: CodexContextProvider,
-	options: CodexContextProviderHeaderOptions = {},
-): Headers {
-	const headers = new Headers();
-	for (const [name, value] of Object.entries(provider.headers)) {
-		if (typeof value === "string") headers.set(name, value);
-	}
-
-	if (provider.kind === "native-codex") {
-		headers.set("Authorization", `Bearer ${provider.token}`);
-		headers.set("ChatGPT-Account-ID", provider.accountId);
-		headers.set("originator", CODEX_TOOL_ORIGINATOR);
-		headers.set("User-Agent", userAgent(CODEX_TOOL_VERSION));
-	} else {
-		headers.set("Authorization", `Bearer ${provider.apiKey}`);
-		headers.delete("ChatGPT-Account-ID");
-		headers.delete("Cookie");
-		headers.set("originator", CODEX_GATEWAY_ORIGINATOR);
-		headers.set("User-Agent", userAgent(CODEX_CLIENT_VERSION));
-		// Let the gateway own its version policy; preserve an explicitly configured
-		// version already copied from provider.headers above.
-		headers.set("X-Codex-Affinity-Scope", CODEX_AFFINITY_SCOPE);
-		headers.set("X-Codex-Model", provider.model);
-	}
-
-	const sessionId = clampSessionId(options.sessionId);
-	if (sessionId) {
-		headers.set("Session-Id", sessionId);
-		headers.set("X-Client-Request-Id", clampSessionId(options.clientRequestId) ?? sessionId);
-	}
-	headers.set("content-type", "application/json");
-	return headers;
-}
-
-export async function resolveCodexContextProvider(
-	ctx: ExtensionContext,
-	modelOverride: ExtensionContext["model"] = ctx.model,
-	gatewayModels: readonly string[] = [],
-): Promise<CodexContextProviderResolution> {
-	const selectedModel = modelOverride;
-	const selectedDescriptor = {
-		provider: selectedModel?.provider,
-		api: selectedModel?.api,
-		model: selectedModel?.id,
-		baseUrl: normalizeBaseUrl(selectedModel?.baseUrl),
-	};
-	const effective = await resolveEffectiveModel(ctx, selectedModel);
-	if (!effective.ok) return { ok: false, reason: "unsupported-model", ...selectedDescriptor };
-	const model = effective.model;
-	const descriptor = {
-		provider: model.provider,
-		api: model.api,
-		model: model.id,
-		baseUrl: normalizeBaseUrl(model.baseUrl),
-	};
-
-	const isNative = isNativeCodexModel(model);
-	const isLogicalVirtualGateway = selectedModel?.api === VIRTUAL_MODEL_API && isExactModelAllowed(selectedModel, gatewayModels);
-	const isGateway = isCodexGatewayModel(model, gatewayModels) ||
-		(isLogicalVirtualGateway && model.api === GATEWAY_API);
-	if (!isNative && !isGateway) {
-		return { ok: false, reason: "unsupported-model", ...descriptor };
-	}
-	if (!isNative && model.api !== GATEWAY_API) {
-		return { ok: false, reason: "unsupported-api", ...descriptor };
-	}
-	if (isNative && model.api !== CODEX_API) {
-		return { ok: false, reason: "unsupported-api", ...descriptor };
-	}
-
-	let auth: Awaited<ReturnType<typeof ctx.modelRegistry.getApiKeyAndHeaders>>;
-	try {
-		auth = await ctx.modelRegistry.getApiKeyAndHeaders(model as Model<Api>);
-	} catch {
-		return { ok: false, reason: "auth-resolution-failed", ...descriptor };
-	}
-	if (!auth.ok) return { ok: false, reason: "auth-resolution-failed", ...descriptor };
-
-	const rawBaseUrl = normalizeBaseUrl(auth.baseUrl) ?? normalizeBaseUrl(model.baseUrl);
-	if (!rawBaseUrl) return { ok: false, reason: "missing-base-url", ...descriptor };
-
-	if (isGateway) {
-		if (!resolveContextSessionId(ctx)) {
-			return { ok: false, reason: "missing-session-id", ...descriptor, baseUrl: rawBaseUrl };
-		}
-		const apiKey = bearerToken(auth.apiKey) ?? bearerToken(headerValue(auth.headers, "authorization"));
-		if (!apiKey) return { ok: false, reason: "missing-api-key", ...descriptor, baseUrl: rawBaseUrl };
-		return {
-			ok: true,
-			provider: {
-				kind: "codex-gateway",
-				route: "codex-gateway",
-				provider: model.provider,
-				api: GATEWAY_API,
-				model: model.id,
-				baseUrl: rawBaseUrl,
-				apiKey,
-				headers: filterCodexGatewayHeaders(mergeProviderHeaders(model.headers, auth.headers)),
-			},
-		};
-	}
-
-	const token = bearerToken(auth.apiKey) ?? bearerToken(headerValue(auth.headers, "authorization"));
-	if (!token) return { ok: false, reason: "missing-token", ...descriptor };
-	const accountId = headerValue(auth.headers, "chatgpt-account-id") ?? accountIdFromToken(token);
-	if (!accountId) return { ok: false, reason: "missing-account-id", ...descriptor };
-	const baseUrl = normalizeCodexBackendBaseUrl(rawBaseUrl);
-	if (!baseUrl) return { ok: false, reason: "unsupported-backend", ...descriptor };
-
-	const headers = mergeProviderHeaders(model.headers, auth.headers);
-	return {
-		ok: true,
-		provider: {
-			kind: "native-codex",
-			route: "openai-codex",
-			provider: CODEX_PROVIDER,
-			api: CODEX_API,
-			model: model.id,
-			baseUrl,
-			token,
-			accountId,
-			headers,
-		},
-	};
-}
-
-export const _codexProviderTest = {
-	accountIdFromToken,
-	bearerToken,
-	clampSessionId,
-	decodeJwtPayload,
-	headerValue,
-	isCodexGatewayModel,
-	userAgent,
-};

package/src/context-management/history-notes.ts

@@ -1,357 +0,0 @@
-import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import {
-	codexContextProviderHeaders,
-	resolveCodexContextProvider,
-} from "./codex-provider";
-import {
-	isRecord,
-	type HistoryAction,
-	type HistoryNotesResponse,
-	type HistoryNotesResult,
-	type NotesAction,
-} from "./types";
-
-export const BACKEND_TIMEOUT_MS = 35_000;
-export const THREAD_HINT_MAX_BYTES = 4_000;
-export const TOOL_OUTPUT_TOKEN_LIMIT = 10_000;
-export const CODEX_ENCRYPTED_OUTPUT_CONTEXT_MARKER = "\u0000pi-openai-toolkit:encrypted-output:";
-
-export function encodeEncryptedOutputForContext(value: string): string {
-	return `${CODEX_ENCRYPTED_OUTPUT_CONTEXT_MARKER}${JSON.stringify(value)}`;
-}
-
-export const HISTORY_ENDPOINTS = {
-	list_windows: "alpha/history/v2/list_windows",
-	list_items: "alpha/history/v2/list_items",
-	read_item: "alpha/history/v2/read_item",
-	search_contents: "alpha/history/v2/search_contents",
-} as const satisfies Record<HistoryAction, string>;
-
-export const THREAD_HINT_ENDPOINT = "alpha/notes/v2/thread_hint";
-
-export const NOTES_ENDPOINTS = {
-	list_files_by_prefix: "alpha/notes/v2/list_files_by_prefix",
-	read_file: "alpha/notes/v2/read_file",
-	search_contents: "alpha/notes/v2/search_contents",
-	append_to_file: "alpha/notes/v2/append_to_file",
-	write_file: "alpha/notes/v2/write_file",
-} as const satisfies Record<NotesAction, string>;
-
-const NOTES_WRITE_ENDPOINTS = new Set<string>([
-	NOTES_ENDPOINTS.append_to_file,
-	NOTES_ENDPOINTS.write_file,
-]);
-
-export const ENCRYPTED_ARGUMENT_ENDPOINTS = new Set<string>([
-	HISTORY_ENDPOINTS.search_contents,
-	NOTES_ENDPOINTS.search_contents,
-	NOTES_ENDPOINTS.append_to_file,
-	NOTES_ENDPOINTS.write_file,
-]);
-
-export const HISTORY_ACTION_FIELDS: Record<HistoryAction, readonly string[]> = {
-	list_windows: ["agent_name", "limit", "recent_first"],
-	list_items: [
-		"agent_name", "limit", "max_chars_per_item", "recent_first", "role",
-		"tool_name", "tool_namespace", "window_id",
-	],
-	read_item: ["agent_name", "item_id", "limit_chars", "offset_chars", "window_id"],
-	search_contents: [
-		"agent_name", "limit", "query", "recent_first", "role", "tool_name",
-		"tool_namespace", "window_id",
-	],
-};
-
-export const NOTES_ACTION_FIELDS: Record<NotesAction, readonly string[]> = {
-	list_files_by_prefix: ["file_order", "file_order_by", "max_results", "prefix"],
-	read_file: ["path", "start_line", "stop_line"],
-	search_contents: ["max_files", "max_matches_per_file", "path_prefix", "query", "recent_file_first"],
-	append_to_file: ["path", "text"],
-	write_file: ["path", "text"],
-};
-
-export interface CodexHistoryNotesDetails {
-	codexHistoryNotes: Record<string, unknown>;
-}
-
-/**
- * Optional backend status flags are accepted only when explicitly affirmative;
- * an omitted flag is compatible with older response shapes.
- */
-export function isSuccessfulHistoryNotesResponse(value: unknown): value is HistoryNotesResponse {
-	return isRecord(value) && isAffirmativeOptionalBoolean(value.ok) && isAffirmativeOptionalBoolean(value.success);
-}
-
-/** Validate persisted tool-result details before using them as a checkpoint. */
-export function isSuccessfulHistoryNotesToolResult(details: unknown): details is CodexHistoryNotesDetails {
-	if (!isRecord(details) || !isRecord(details.codexHistoryNotes)) return false;
-	return isSuccessfulHistoryNotesResponse(details.codexHistoryNotes);
-}
-
-function isAffirmativeOptionalBoolean(value: unknown): boolean {
-	return value === undefined || value === true;
-}
-
-function isRejectedNotesWriteResponse(value: HistoryNotesResponse): boolean {
-	return value.ok === false || value.success === false;
-}
-
-export async function callHistoryNotesBackend(
-	endpoint: string,
-	arguments_: Record<string, unknown>,
-	ctx: ExtensionContext,
-	signal?: AbortSignal,
-	truncationPolicy: { mode: "bytes" | "tokens"; limit: number } = {
-		mode: "tokens",
-		limit: TOOL_OUTPUT_TOKEN_LIMIT,
-	},
-	gatewayModels: readonly string[] = [],
-): Promise<HistoryNotesResult> {
-	const timeoutSignal = AbortSignal.timeout(BACKEND_TIMEOUT_MS);
-	if (signal?.aborted) return { ok: false, reason: "aborted" };
-	const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
-	const providerResult = await resolveProviderWithDeadline(ctx, requestSignal, timeoutSignal, gatewayModels);
-	if (providerResult === "aborted") return { ok: false, reason: "aborted" };
-	if (providerResult === "timeout") return { ok: false, reason: "backend-timeout" };
-	const provider = providerResult;
-	if (!provider.ok) {
-		const reason = provider.reason === "unsupported-model" || provider.reason === "unsupported-api" || provider.reason === "context-management-inactive"
-			? "unsupported-backend"
-			: provider.reason;
-		return { ok: false, reason };
-	}
-	const sessionId = ctx.sessionManager.getSessionId();
-	const headers = codexContextProviderHeaders(provider.provider, {
-		sessionId,
-		clientRequestId: sessionId,
-	});
-	headers.set("x-openai-tool-output-truncation-policy", JSON.stringify(truncationPolicy));
-	if (ENCRYPTED_ARGUMENT_ENDPOINTS.has(endpoint)) {
-		headers.set("x-openai-encrypted-tool-arguments", "true");
-	}
-	try {
-		const response = await fetch(`${provider.provider.baseUrl}/${endpoint}`, {
-			method: "POST",
-			headers,
-			signal: requestSignal,
-			body: JSON.stringify({
-				...arguments_,
-				context: {
-					session_id: ctx.sessionManager.getSessionId(),
-					current_agent_name: "/root",
-				},
-			}),
-		});
-		if (!response.ok) return { ok: false, reason: "http-error", status: response.status };
-		let parsed: unknown;
-		try {
-			parsed = JSON.parse(await response.text()) as unknown;
-		} catch {
-			return { ok: false, reason: "invalid-json", status: response.status };
-		}
-		if (!isHistoryNotesResponse(parsed, endpoint)) return { ok: false, reason: "invalid-response", status: response.status };
-		return { ok: true, value: parsed };
-	} catch {
-		if (signal?.aborted) return { ok: false, reason: "aborted" };
-		if (timeoutSignal.aborted) return { ok: false, reason: "backend-timeout" };
-		return { ok: false, reason: "protocol-error" };
-	}
-}
-
-async function resolveProviderWithDeadline(
-	ctx: ExtensionContext,
-	requestSignal: AbortSignal,
-	timeoutSignal: AbortSignal,
-	gatewayModels: readonly string[] = [],
-): Promise<Awaited<ReturnType<typeof resolveCodexContextProvider>> | "aborted" | "timeout"> {
-	if (requestSignal.aborted) return timeoutSignal.aborted ? "timeout" : "aborted";
-	return new Promise((resolve) => {
-		let settled = false;
-		const finish = (value: Awaited<ReturnType<typeof resolveCodexContextProvider>> | "aborted" | "timeout") => {
-			if (settled) return;
-			settled = true;
-			requestSignal.removeEventListener("abort", onAbort);
-			resolve(value);
-		};
-		const onAbort = () => finish(timeoutSignal.aborted ? "timeout" : "aborted");
-		requestSignal.addEventListener("abort", onAbort, { once: true });
-		resolveCodexContextProvider(ctx, ctx.model, gatewayModels).then(
-			(value) => finish(value),
-			() => finish({ ok: false, reason: "auth-resolution-failed" }),
-		);
-	});
-}
-
-export async function loadHistoryNotesThreadHint(
-	ctx: ExtensionContext,
-	signal?: AbortSignal,
-	gatewayModels: readonly string[] = [],
-): Promise<string | undefined> {
-	const result = await callHistoryNotesBackend(
-		THREAD_HINT_ENDPOINT,
-		{},
-		ctx,
-		signal,
-		{ mode: "bytes", limit: THREAD_HINT_MAX_BYTES },
-		gatewayModels,
-	);
-	if (!result.ok) {
-		if (result.reason === "aborted") throw new Error("Remote context hint request was aborted");
-		return undefined;
-	}
-	if (!isSuccessfulHistoryNotesResponse(result.value)) return undefined;
-	const text = result.value.text;
-	return typeof text === "string" && Buffer.byteLength(text, "utf8") <= THREAD_HINT_MAX_BYTES ? text : undefined;
-}
-
-export async function executeHistoryNotesTool(
-	namespace: "history" | "notes",
-	action: HistoryAction | NotesAction,
-	params: Record<string, unknown>,
-	ctx: ExtensionContext,
-	signal?: AbortSignal,
-	gatewayModels: readonly string[] = [],
-): Promise<AgentToolResult<CodexHistoryNotesDetails>> {
-	const endpoint = namespace === "history"
-		? HISTORY_ENDPOINTS[action as HistoryAction]
-		: NOTES_ENDPOINTS[action as NotesAction];
-	if (!endpoint) throw new Error(`Unsupported ${namespace} action`);
-	validateAction(namespace, action, params);
-	const result = await callHistoryNotesBackend(
-		endpoint,
-		stripAction(params),
-		ctx,
-		signal,
-		undefined,
-		gatewayModels,
-	);
-	if (!result.ok) throw new Error(formatHistoryNotesFailure(result.reason, result.status));
-	if (NOTES_WRITE_ENDPOINTS.has(endpoint) && isRejectedNotesWriteResponse(result.value)) {
-		throw new Error("Remote notes write was rejected");
-	}
-	const modelResult = { ...result.value };
-	delete modelResult.images;
-	const content: AgentToolResult<CodexHistoryNotesDetails>["content"] = [
-		{
-			type: "text",
-			text: typeof modelResult.encrypted_output === "string"
-				? `${namespace} operation completed`
-				: JSON.stringify(modelResult),
-		},
-	];
-	for (const image of parseBackendImages(result.value.images)) content.push(image);
-	return { content, details: { codexHistoryNotes: modelResult } };
-}
-
-export function formatHistoryNotesFailure(
-	reason: Exclude<HistoryNotesResult, { ok: true }>["reason"],
-	status?: number,
-): string {
-	switch (reason) {
-		case "aborted": return "Remote history/notes request was aborted";
-		case "backend-timeout": return "Remote history/notes backend timed out";
-		case "http-error": return `Remote history/notes backend returned HTTP ${status ?? "error"}`;
-		case "invalid-json": return "Remote history/notes backend returned invalid JSON";
-		case "invalid-response": return "Remote history/notes backend returned an invalid response";
-		case "auth-resolution-failed": return "Remote history/notes authentication could not be resolved";
-		case "missing-token": return "Remote history/notes authentication is missing a token";
-		case "missing-api-key": return "Remote history/notes gateway authentication is missing an API key";
-		case "missing-account-id": return "Remote history/notes authentication is missing an account id";
-		case "missing-base-url": return "Remote history/notes backend is missing a base URL";
-		case "missing-session-id": return "Remote history/notes request is missing a session id";
-		case "unsupported-backend": return "Remote history/notes require the native Codex backend";
-		case "protocol-error": return "Remote history/notes request failed";
-		case "invalid-account-token": return "Remote history/notes authentication token is invalid";
-		default: return "Remote history/notes request failed";
-	}
-}
-
-const RESPONSE_KEYS_BY_ENDPOINT: Record<string, readonly string[]> = {
-	[HISTORY_ENDPOINTS.list_windows]: ["windows", "items", "results", "data", "output", "encrypted_output"],
-	[HISTORY_ENDPOINTS.list_items]: ["items", "results", "data", "output", "encrypted_output"],
-	[HISTORY_ENDPOINTS.read_item]: ["item", "content", "text", "data", "output", "encrypted_output"],
-	[HISTORY_ENDPOINTS.search_contents]: ["matches", "items", "results", "data", "output", "encrypted_output"],
-	[NOTES_ENDPOINTS.list_files_by_prefix]: ["files", "items", "results", "data", "output", "encrypted_output"],
-	[NOTES_ENDPOINTS.read_file]: ["file", "content", "text", "data", "output", "encrypted_output"],
-	[NOTES_ENDPOINTS.search_contents]: ["matches", "items", "results", "data", "output", "encrypted_output"],
-	[NOTES_ENDPOINTS.append_to_file]: ["ok", "success", "file", "content", "data", "output", "encrypted_output"],
-	[NOTES_ENDPOINTS.write_file]: ["ok", "success", "file", "content", "data", "output", "encrypted_output"],
-	[THREAD_HINT_ENDPOINT]: ["text", "data", "output"],
-};
-
-const ARRAY_RESPONSE_KEYS = new Set(["windows", "items", "results", "matches", "files"]);
-
-function isHistoryNotesResponse(value: unknown, endpoint: string): value is HistoryNotesResponse {
-	if (!isRecord(value) || Object.keys(value).length === 0) return false;
-	if (value.encrypted_output !== undefined &&
-		(typeof value.encrypted_output !== "string" || value.encrypted_output.length === 0)) return false;
-	if (value.images !== undefined && !isValidImages(value.images)) return false;
-	if (value.ok !== undefined && typeof value.ok !== "boolean") return false;
-	if (value.success !== undefined && typeof value.success !== "boolean") return false;
-	if (value.text !== undefined && typeof value.text !== "string") return false;
-	for (const key of ARRAY_RESPONSE_KEYS) {
-		if (value[key] !== undefined && !Array.isArray(value[key])) return false;
-	}
-	const expectedKeys = RESPONSE_KEYS_BY_ENDPOINT[endpoint];
-	return expectedKeys ? expectedKeys.some((key) => key in value) : false;
-}
-
-type BackendImage = {
-	data: string;
-	mime_type: string;
-	detail?: "auto" | "high" | "original" | null;
-};
-
-function isValidImages(value: unknown): value is BackendImage[] {
-	return Array.isArray(value) && value.every((item): item is BackendImage => {
-		if (!isRecord(item) || typeof item.data !== "string" || typeof item.mime_type !== "string") return false;
-		return item.detail === undefined || item.detail === null || item.detail === "auto" || item.detail === "high" || item.detail === "original";
-	});
-}
-
-function parseBackendImages(value: unknown): Array<{
-	type: "image";
-	data: string;
-	mimeType: string;
-	detail?: "auto" | "high" | "original";
-}> {
-	if (value === undefined) return [];
-	if (!isValidImages(value)) throw new Error("Remote history backend returned invalid image content");
-	return value.map((item) => ({
-		type: "image" as const,
-		data: item.data,
-		mimeType: item.mime_type,
-		...(item.detail ? { detail: item.detail } : {}),
-	}));
-}
-
-function stripAction(params: Record<string, unknown>): Record<string, unknown> {
-	const result = { ...params };
-	delete result.action;
-	return result;
-}
-
-function validateAction(
-	namespace: "history" | "notes",
-	action: HistoryAction | NotesAction,
-	params: Record<string, unknown>,
-): void {
-	const fields = namespace === "history"
-		? HISTORY_ACTION_FIELDS[action as HistoryAction]
-		: NOTES_ACTION_FIELDS[action as NotesAction];
-	if (!fields) throw new Error(`Unsupported ${namespace} action`);
-	const unexpected = Object.keys(params).find((field) => field !== "action" && !fields.includes(field));
-	if (unexpected) throw new Error(`${namespace} ${action} does not accept ${unexpected}`);
-	if (action === "read_item" && (typeof params.item_id !== "string" || !params.item_id || typeof params.window_id !== "string" || !params.window_id)) {
-		throw new Error("history read_item requires item_id and window_id");
-	}
-	if (action === "search_contents" && (typeof params.query !== "string" || !params.query)) {
-		throw new Error(`${namespace} search_contents requires query`);
-	}
-	if ((action === "read_file" || action === "append_to_file" || action === "write_file") && (typeof params.path !== "string" || !params.path)) {
-		throw new Error(`notes ${action} requires path`);
-	}
-	if ((action === "append_to_file" || action === "write_file") && typeof params.text !== "string") {
-		throw new Error(`notes ${action} requires text`);
-	}
-}