pi-openai-toolkit 0.11.1 → 0.13.0

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

@@ -0,0 +1,261 @@
+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_CLIENT_VERSION } from "../responses-headers";
+import { normalizeBaseUrl } from "../runtime";
+import {
+	isNonEmptyString,
+	type CodexContextProvider,
+	type CodexContextProviderResolution,
+} from "./types";
+
+const CODEX_PROVIDER = "openai-codex";
+const CODEX_API = "openai-codex-responses";
+const GATEWAY_PROVIDER = "uwoacrimson";
+const GATEWAY_API = "openai-responses";
+const CODEX_TOOL_ORIGINATOR = "codex_cli_rs";
+const CODEX_GATEWAY_ORIGINATOR = "codex_cli_rs";
+const CODEX_TOOL_VERSION = "0.0.0";
+const CODEX_SESSION_ID_MAX_LENGTH = 64;
+
+export const CODEX_AFFINITY_SCOPE = "codex-session-v1";
+
+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,
+	allowlist: readonly string[] = [],
+): boolean {
+	if (!model || model.provider !== GATEWAY_PROVIDER || model.api !== GATEWAY_API) return false;
+	const spec = `${model.provider}/${model.id}`;
+	return allowlist.some((entry) => entry.trim() === spec);
+}
+
+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 {
+	const platform = typeof process !== "undefined" ? process.platform : "unknown";
+	const arch = typeof process !== "undefined" ? process.arch : "unknown";
+	return `codex_cli_rs/${version} (${platform}; ${arch})`;
+}
+
+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 removeSensitiveGatewayHeaders(headers: ProviderHeaders): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const [name, value] of Object.entries(headers)) {
+		if (typeof value !== "string") continue;
+		const lower = name.toLowerCase();
+		if (lower === "authorization" || lower === "cookie" || lower === "chatgpt-account-id" || lower === "x-api-key") {
+			continue;
+		}
+		result[name] = value;
+	}
+	return result;
+}
+
+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));
+		headers.set("version", 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));
+		headers.set("version", CODEX_CLIENT_VERSION);
+		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", options.clientRequestId?.trim() || sessionId);
+	}
+	headers.set("content-type", "application/json");
+	return headers;
+}
+
+export async function resolveCodexContextProvider(
+	ctx: ExtensionContext,
+	modelOverride: ExtensionContext["model"] = ctx.model,
+	gatewayAllowlist: readonly string[] = [],
+): Promise<CodexContextProviderResolution> {
+	const model = modelOverride;
+	const descriptor = {
+		provider: model?.provider,
+		api: model?.api,
+		model: model?.id,
+		baseUrl: normalizeBaseUrl(model?.baseUrl),
+	};
+	if (!model) return { ok: false, reason: "unsupported-model" };
+
+	const isNative = isNativeCodexModel(model);
+	const isGateway = isCodexGatewayModel(model, gatewayAllowlist);
+	if (!isNative && !isGateway) {
+		return {
+			ok: false,
+			reason: model.provider === GATEWAY_PROVIDER ? "unsupported-model" : "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) {
+		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: GATEWAY_PROVIDER,
+				api: GATEWAY_API,
+				model: model.id,
+				baseUrl: rawBaseUrl,
+				apiKey,
+				headers: removeSensitiveGatewayHeaders(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

@@ -0,0 +1,325 @@
+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>;
+
+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>;
+}
+
+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,
+	},
+	gatewayAllowlist: 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, gatewayAllowlist);
+	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,
+	gatewayAllowlist: 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, gatewayAllowlist).then(
+			(value) => finish(value),
+			() => finish({ ok: false, reason: "auth-resolution-failed" }),
+		);
+	});
+}
+
+export async function loadHistoryNotesThreadHint(
+	ctx: ExtensionContext,
+	signal?: AbortSignal,
+	gatewayAllowlist: readonly string[] = [],
+): Promise<string | undefined> {
+	const result = await callHistoryNotesBackend(
+		THREAD_HINT_ENDPOINT,
+		{},
+		ctx,
+		signal,
+		{ mode: "bytes", limit: THREAD_HINT_MAX_BYTES },
+		gatewayAllowlist,
+	);
+	if (!result.ok) {
+		if (result.reason === "aborted") throw new Error("Remote context hint request was aborted");
+		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,
+	gatewayAllowlist: 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,
+		gatewayAllowlist,
+	);
+	if (!result.ok) throw new Error(formatHistoryNotesFailure(result.reason, result.status));
+	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 "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`);
+	}
+}

package/src/context-management/messages.ts

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
+	CONTEXT_MANAGEMENT_PROTOCOL,
+	CONTEXT_WINDOW_COMPACTION_STRATEGY,
+	CONTEXT_WINDOW_FALLBACK_BUFFER,
+	CONTEXT_WINDOW_REMINDER_THRESHOLD,
+	type CodexContextManagementMessageDetails,
+	type ContextManagementMessageKind,
+	type ContextWindowCompactionDetails,
+	type ContextWindowIdentity,
+	isCodexContextManagementMessageDetails,
+	isContextWindowCompactionDetails,
+} from "./types";
+
+export {
+	CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
+	CONTEXT_WINDOW_COMPACTION_STRATEGY,
+	CONTEXT_WINDOW_FALLBACK_BUFFER,
+	CONTEXT_WINDOW_REMINDER_THRESHOLD,
+	isCodexContextManagementMessageDetails,
+	isContextWindowCompactionDetails,
+};
+export type {
+	CodexContextManagementMessageDetails,
+	ContextManagementMessageKind,
+	ContextWindowCompactionDetails,
+	ContextWindowIdentity,
+};
+
+export const CONTEXT_WINDOW_COMPACTION_SUMMARY =
+	"[Pi Codex context-window boundary; no conversation summary was generated.]";
+
+const CONTEXT_WINDOW_GUIDANCE = `<context_window_guidance>
+Checkpoint the active request, known history IDs, decisions, progress, learnings and next steps in notes before new_context; no summary carries over. After rollover, read hinted notes. Use history only for a missing detail.
+</context_window_guidance>`;
+
+export function renderContextWindowMessage(
+	identity: ContextWindowIdentity,
+	threadHint?: string,
+): string {
+	const lines = [
+		"<context_window>",
+		"Agent name: /root",
+		`First context window id: ${identity.firstWindowId}`,
+		`Current context window id: ${identity.currentWindowId}`,
+	];
+	if (identity.previousWindowId) lines.push(`Previous context window id: ${identity.previousWindowId}`);
+	if (threadHint) lines.push(threadHint);
+	lines.push("</context_window>");
+	return `${CONTEXT_WINDOW_GUIDANCE}\n\n${lines.join("\n")}`;
+}
+
+export function renderContextWindowReminder(remainingTokens: number): string {
+	return `<context_window_reminder>
+Only ${Math.max(0, Math.floor(remainingTokens))} context tokens remain. Checkpoint the active request, state and known history IDs in notes, then call new_context; no conversation summary carries over.
+</context_window_reminder>`;
+}
+
+export const CONTEXT_WINDOW_FALLBACK_MESSAGE = `<context_window_reminder>
+Context exhausted. Do not continue or answer. Make exactly one notes write or append call that checkpoints the active request, state and known history IDs, then call new_context. Use no other tools before rollover.
+</context_window_reminder>`;
+
+export function isContextWindowBoundary(
+	message: AgentMessage,
+): message is Extract<AgentMessage, { role: "custom" }> & {
+	details: CodexContextManagementMessageDetails;
+} {
+	return (
+		message.role === "custom" &&
+		message.customType === CODEX_CONTEXT_WINDOW_MESSAGE_TYPE &&
+		isCodexContextManagementMessageDetails(message.details) &&
+		message.details.contextManagement.kind === "window"
+	);
+}
+
+export function sendContextWindowMessage(
+	pi: ExtensionAPI,
+	content: string,
+	kind: ContextManagementMessageKind,
+	identity: ContextWindowIdentity,
+	options: { triggerTurn: boolean; sessionId?: string },
+	trimPreviousWindow = false,
+): void {
+	const details: CodexContextManagementMessageDetails = {
+		protocol: CONTEXT_MANAGEMENT_PROTOCOL,
+		id: randomUUID(),
+		...(options.sessionId ? { sessionId: options.sessionId } : {}),
+		contextManagement: {
+			protocol: CONTEXT_MANAGEMENT_PROTOCOL,
+			kind,
+			...identity,
+			...(trimPreviousWindow ? { trimPreviousWindow: true as const } : {}),
+		},
+	};
+	pi.sendMessage({
+		customType: CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
+		content,
+		display: true,
+		details,
+	}, options.triggerTurn
+		? { deliverAs: "steer", triggerTurn: true }
+		: { triggerTurn: false });
+}