pi-openai-toolkit 0.23.2 → 0.24.1

package/src/config/migration.ts

@@ -1,103 +1,115 @@
-import { resolveToolkitConfig } from "../config";
-import type { LoadedToolkitConfig } from "../types";
-import { RETIRED_AUTO_MODE_ISSUE, RETIRED_AUTO_MODE_MESSAGE, type ConfigOrigin } from "./policy";
-import { resolveV2Config } from "./v2";
-
-export type MigrationPreview = {
-	status: "ready" | "needs-review" | "already-v2" | "unavailable";
-	candidate?: Record<string, unknown>;
-	/** Controlled explanations, never arbitrary raw input values. */
-	reasons: string[];
-	/** Unknown names are masked; paths never expose unknown values. */
-	unmappedPaths: string[];
-	/** Candidate leaf -> origin in the unchanged legacy source (or built-in). */
-	origins?: Record<string, ConfigOrigin>;
-};
-
-function modelRef(key: string): { provider: string; id: string; api: string } {
-	const slash = key.indexOf("/");
-	return { provider: key.slice(0, slash), id: key.slice(slash + 1), api: "openai-responses" };
-}
-
-/** Read-only analysis: never edits a source file or claims a lossy candidate is equivalent. */
-export function previewToolkitMigration(loaded: LoadedToolkitConfig): MigrationPreview {
-	if (loaded.document?.format === "v2") {
-		const retired = resolveToolkitConfig(loaded).issues.filter((issue) => issue.code === RETIRED_AUTO_MODE_ISSUE);
-		return { status: "already-v2", reasons: ["The document already uses schemaVersion 2.",
-			...(retired.length ? [RETIRED_AUTO_MODE_MESSAGE] : [])], unmappedPaths: retired.map((issue) => issue.path) };
-	}
-	if (loaded.document?.format === "invalid" || loaded.document?.format === "missing") {
-		return { status: "unavailable", reasons: ["A readable legacy document is required; no candidate was produced."], unmappedPaths: [] };
-	}
-	const baseline = resolveToolkitConfig(loaded);
-	const legacy = baseline.config;
-	const { compatibility: _compatibility, diagnostics, ...defaults } = structuredClone(baseline.policy);
-	const models: Record<string, unknown> = Object.create(null);
-	const origins: Record<string, ConfigOrigin> = Object.create(null);
-	const unmappedPaths = new Set(baseline.issues.map((issue) => issue.path));
-	for (const [leaf, origin] of Object.entries(baseline.origins)) {
-		if (leaf.startsWith("compatibility.")) continue;
-		origins[leaf.startsWith("diagnostics.") ? leaf : `defaults.${leaf}`] = origin;
-	}
-	const keys = new Set([
-		...legacy.webSearch.models,
-		...Object.keys(legacy.webSearch.routes ?? {}),
-		...legacy.compaction.gatewayContextModels,
-	]);
-	for (const key of keys) {
-		const resolved = resolveToolkitConfig(loaded, modelRef(key));
-		const override: Record<string, unknown> = {};
-		if (resolved.policy.webSearch.route !== defaults.webSearch.route) override.webSearch = resolved.policy.webSearch;
-		if (resolved.policy.compatibility.transport !== "standard") override.compatibility = resolved.policy.compatibility;
-		if (Object.keys(override).length > 0) {
-			models[key] = override;
-			for (const [feature, fields] of Object.entries(override)) {
-				for (const field of Object.keys(fields as Record<string, unknown>)) {
-					const leaf = `${feature}.${field}`;
-					origins[`models[${JSON.stringify(key)}].${leaf}`] = resolved.origins[leaf];
-				}
-			}
-		}
-	}
-	const candidate = { schemaVersion: 2, defaults, models, diagnostics };
-	const reasons: string[] = [];
-	// Retired sections are never migrated; their presence is a controlled removal reason.
-	if (baseline.issues.some((issue) => issue.code === RETIRED_AUTO_MODE_ISSUE)) {
-		reasons.push(RETIRED_AUTO_MODE_MESSAGE + " No Auto Mode settings were migrated; review the removal before applying this candidate.");
-		unmappedPaths.add("autoMode");
-	}
-	if (loaded.warnings.length || baseline.issues.length) {
-		reasons.push("Legacy warnings, unknown fields or normalized invalid values require review. Their original contents remain in the untouched source file.");
-	}
-	if (legacy.webSearch.enabled && legacy.webSearch.defaultRoute === undefined &&
-		legacy.webSearch.models.some((key) => !Object.prototype.hasOwnProperty.call(legacy.webSearch.routes ?? {}, key))) {
-		reasons.push("Legacy hosted allowlists ignore unsupported APIs and malformed payloads; explicit v2 hosted routes fail closed. This candidate is not behavior-equivalent on those paths.");
-	}
-	if (!legacy.webSearch.enabled && (legacy.webSearch.models.length || Object.keys(legacy.webSearch.routes ?? {}).length || legacy.webSearch.defaultRoute)) {
-		reasons.push("Disabled legacy search contains dormant routes or a model list; simplified v2 policy does not retain that enable-later intent.");
-		if (legacy.webSearch.models.length) unmappedPaths.add("webSearch.models");
-		if (Object.keys(legacy.webSearch.routes ?? {}).length) unmappedPaths.add("webSearch.routes");
-		if (legacy.webSearch.defaultRoute) unmappedPaths.add("webSearch.defaultRoute");
-	}
-	if (legacy.webSearch.models.length && (legacy.webSearch.defaultRoute !== undefined ||
-		legacy.webSearch.models.some((key) => Object.hasOwn(legacy.webSearch.routes ?? {}, key)))) {
-		unmappedPaths.add("webSearch.models");
-	}
-	if (!legacy.compaction.enabled && legacy.compaction.contextManagement === "remote") {
-		reasons.push("Disabled legacy context management retains a dormant remote mode; the candidate selects Pi ownership.");
-		unmappedPaths.add("compaction.contextManagement");
-	}
-	// Gateway affinity was previously context-mode gated for compaction, and not used by image.
-	if (legacy.compaction.gatewayContextModels.length) {
-		reasons.push("Gateway compatibility is now shared across features; review synthetic compaction/image affinity before using this candidate.");
-	}
-	const candidateChecks = [resolveV2Config(candidate, undefined), ...[...keys].map((key) => resolveV2Config(candidate, key))];
-	if (candidateChecks.some((resolved) => resolved.issues.length)) reasons.push("The candidate has v2 validation issues; it cannot be applied as-is.");
-	return {
-		status: reasons.length ? "needs-review" : "ready",
-		candidate,
-		origins,
-		unmappedPaths: [...unmappedPaths],
-		reasons: reasons.length ? reasons : ["Recognized active policies map without a known semantic difference. Preview only; no source file was changed."],
-	};
-}
+import { resolveToolkitConfig } from "../config";
+import type { LoadedToolkitConfig } from "../types";
+import {
+	RETIRED_AUTO_MODE_ISSUE, RETIRED_AUTO_MODE_MESSAGE,
+	RETIRED_REMOTE_WINDOWS_ISSUE, RETIRED_REMOTE_WINDOWS_MODE_ISSUE,
+	RETIRED_REMOTE_WINDOWS_CONFIG_MESSAGE, RETIRED_REMOTE_WINDOWS_MODE_MESSAGE,
+	type ConfigOrigin,
+} from "./policy";
+import { resolveV2Config } from "./v2";
+
+export type MigrationPreview = {
+	status: "ready" | "needs-review" | "already-v2" | "unavailable";
+	candidate?: Record<string, unknown>;
+	/** Controlled explanations, never arbitrary raw input values. */
+	reasons: string[];
+	/** Unknown names are masked; paths never expose unknown values. */
+	unmappedPaths: string[];
+	/** Candidate leaf -> origin in the unchanged legacy source (or built-in). */
+	origins?: Record<string, ConfigOrigin>;
+};
+
+function modelRef(key: string): { provider: string; id: string; api: string } {
+	const slash = key.indexOf("/");
+	return { provider: key.slice(0, slash), id: key.slice(slash + 1), api: "openai-responses" };
+}
+
+/** Read-only analysis: never edits a source file or claims a lossy candidate is equivalent. */
+export function previewToolkitMigration(loaded: LoadedToolkitConfig): MigrationPreview {
+	if (loaded.document?.format === "v2") {
+		const retired = resolveToolkitConfig(loaded).issues.filter((issue) =>
+			[RETIRED_AUTO_MODE_ISSUE, RETIRED_REMOTE_WINDOWS_ISSUE, RETIRED_REMOTE_WINDOWS_MODE_ISSUE].some((code) => code === issue.code));
+		const removedMode = retired.some((issue) => issue.code === RETIRED_REMOTE_WINDOWS_MODE_ISSUE);
+		return { status: removedMode ? "needs-review" : "already-v2", reasons: ["The document already uses schemaVersion 2.",
+			...(retired.some((issue) => issue.code === RETIRED_AUTO_MODE_ISSUE) ? [RETIRED_AUTO_MODE_MESSAGE] : []),
+			...(retired.some((issue) => issue.code === RETIRED_REMOTE_WINDOWS_ISSUE) ? [RETIRED_REMOTE_WINDOWS_CONFIG_MESSAGE] : []),
+			...(removedMode ? [RETIRED_REMOTE_WINDOWS_MODE_MESSAGE] : [])], unmappedPaths: retired.map((issue) => issue.path) };
+	}
+	if (loaded.document?.format === "invalid" || loaded.document?.format === "missing") {
+		return { status: "unavailable", reasons: ["A readable legacy document is required; no candidate was produced."], unmappedPaths: [] };
+	}
+	const baseline = resolveToolkitConfig(loaded);
+	const legacy = baseline.config;
+	const { compatibility: _compatibility, diagnostics, ...defaults } = structuredClone(baseline.policy);
+	const models: Record<string, unknown> = Object.create(null);
+	const origins: Record<string, ConfigOrigin> = Object.create(null);
+	const unmappedPaths = new Set(baseline.issues.map((issue) => issue.path));
+	for (const [leaf, origin] of Object.entries(baseline.origins)) {
+		if (leaf.startsWith("compatibility.")) continue;
+		origins[leaf.startsWith("diagnostics.") ? leaf : `defaults.${leaf}`] = origin;
+	}
+	const keys = new Set([
+		...legacy.webSearch.models,
+		...Object.keys(legacy.webSearch.routes ?? {}),
+		...legacy.compaction.gatewayContextModels,
+	]);
+	for (const key of keys) {
+		const resolved = resolveToolkitConfig(loaded, modelRef(key));
+		const override: Record<string, unknown> = {};
+		if (resolved.policy.webSearch.route !== defaults.webSearch.route) override.webSearch = resolved.policy.webSearch;
+		if (resolved.policy.compatibility.transport !== "standard") override.compatibility = resolved.policy.compatibility;
+		if (Object.keys(override).length > 0) {
+			models[key] = override;
+			for (const [feature, fields] of Object.entries(override)) {
+				for (const field of Object.keys(fields as Record<string, unknown>)) {
+					const leaf = `${feature}.${field}`;
+					origins[`models[${JSON.stringify(key)}].${leaf}`] = resolved.origins[leaf];
+				}
+			}
+		}
+	}
+	const candidate = { schemaVersion: 2, defaults, models, diagnostics };
+	const reasons: string[] = [];
+	// Retired sections are never migrated; their presence is a controlled removal reason.
+	if (baseline.issues.some((issue) => issue.code === RETIRED_AUTO_MODE_ISSUE)) {
+		reasons.push(RETIRED_AUTO_MODE_MESSAGE + " No Auto Mode settings were migrated; review the removal before applying this candidate.");
+		unmappedPaths.add("autoMode");
+	}
+	if (loaded.warnings.length || baseline.issues.length) {
+		reasons.push("Legacy warnings, unknown fields or normalized invalid values require review. Their original contents remain in the untouched source file.");
+	}
+	if (legacy.webSearch.enabled && legacy.webSearch.defaultRoute === undefined &&
+		legacy.webSearch.models.some((key) => !Object.prototype.hasOwnProperty.call(legacy.webSearch.routes ?? {}, key))) {
+		reasons.push("Legacy hosted allowlists ignore unsupported APIs and malformed payloads; explicit v2 hosted routes fail closed. This candidate is not behavior-equivalent on those paths.");
+	}
+	if (!legacy.webSearch.enabled && (legacy.webSearch.models.length || Object.keys(legacy.webSearch.routes ?? {}).length || legacy.webSearch.defaultRoute)) {
+		reasons.push("Disabled legacy search contains dormant routes or a model list; simplified v2 policy does not retain that enable-later intent.");
+		if (legacy.webSearch.models.length) unmappedPaths.add("webSearch.models");
+		if (Object.keys(legacy.webSearch.routes ?? {}).length) unmappedPaths.add("webSearch.routes");
+		if (legacy.webSearch.defaultRoute) unmappedPaths.add("webSearch.defaultRoute");
+	}
+	if (legacy.webSearch.models.length && (legacy.webSearch.defaultRoute !== undefined ||
+		legacy.webSearch.models.some((key) => Object.hasOwn(legacy.webSearch.routes ?? {}, key)))) {
+		unmappedPaths.add("webSearch.models");
+	}
+	if (baseline.issues.some((issue) => issue.code === RETIRED_REMOTE_WINDOWS_MODE_ISSUE)) {
+		reasons.push(`${RETIRED_REMOTE_WINDOWS_MODE_MESSAGE} The preview uses Pi ownership only as a safe review placeholder; it is not behavior-equivalent. Choose a supported mode explicitly before any manual apply.`);
+		unmappedPaths.add("compaction.contextManagement");
+	}
+	if (baseline.issues.some((issue) => issue.code === RETIRED_REMOTE_WINDOWS_ISSUE)) {
+		reasons.push(`${RETIRED_REMOTE_WINDOWS_CONFIG_MESSAGE} No retired ancillary settings were migrated; review their removal.`);
+	}
+	// Gateway affinity is shared across retained compaction and image features.
+	if (legacy.compaction.gatewayContextModels.length) {
+		reasons.push("Gateway compatibility is now shared across features; review synthetic compaction/image affinity before using this candidate.");
+	}
+	const candidateChecks = [resolveV2Config(candidate, undefined), ...[...keys].map((key) => resolveV2Config(candidate, key))];
+	if (candidateChecks.some((resolved) => resolved.issues.length)) reasons.push("The candidate has v2 validation issues; it cannot be applied as-is.");
+	return {
+		status: reasons.length ? "needs-review" : "ready",
+		candidate,
+		origins,
+		unmappedPaths: [...unmappedPaths],
+		reasons: reasons.length ? reasons : ["Recognized active policies map without a known semantic difference. Preview only; no source file was changed."],
+	};
+}

package/src/config/notifications.ts

@@ -1,36 +1,46 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { ResolvedToolkitConfig } from "../config";
-import { RETIRED_AUTO_MODE_ISSUE, RETIRED_AUTO_MODE_MESSAGE, type ConfigIssue } from "./policy";
-import { redactValue } from "../debug";
-
-const lastNotice = new WeakMap<object, string>();
-
-/** Controlled human text for a known code; never built from user-supplied configuration values. */
-function issueExplanation(issue: ConfigIssue): string {
-	return issue.code === RETIRED_AUTO_MODE_ISSUE
-		? RETIRED_AUTO_MODE_MESSAGE
-		: issue.code;
-}
-
-export function formatConfigIssues(issues: readonly ConfigIssue[], limit = 12): string {
-	const lines = issues.slice(0, limit).map((issue) =>
-		`${issue.severity}: ${issue.path.slice(0, 220)} — ${issueExplanation(issue)}`);
-	if (issues.length > limit) lines.push(`${issues.length - limit} more issue(s); inspect the configuration file.`);
-	return String(redactValue(lines.join("\n")));
-}
-
-/** Per-session bounded notice, independent of feature enablement/debug. Never logs raw config. */
-export function notifyConfigIssues(ctx: ExtensionContext, resolved: ResolvedToolkitConfig): void {
-	const owner = ctx.sessionManager ?? ctx;
-	if (resolved.issues.length === 0) {
-		lastNotice.delete(owner);
-		return;
-	}
-	if (!ctx.hasUI || typeof ctx.ui?.notify !== "function") return;
-	const message = formatConfigIssues(resolved.issues, 4);
-	const fingerprint = `${resolved.source ?? "defaults"}\n${resolved.modelKey ?? ""}\n${message}`;
-	if (lastNotice.get(owner) === fingerprint) return;
-	lastNotice.set(owner, fingerprint);
-	ctx.ui.notify(`Toolkit configuration:\n${message}\nUse /toolkit-config validate for details.`,
-		resolved.issues.some((issue) => issue.severity === "error") ? "error" : "warning");
-}
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ResolvedToolkitConfig } from "../config";
+import {
+	RETIRED_AUTO_MODE_ISSUE, RETIRED_AUTO_MODE_MESSAGE,
+	RETIRED_REMOTE_WINDOWS_ISSUE, RETIRED_REMOTE_WINDOWS_MODE_ISSUE,
+	RETIRED_REMOTE_WINDOWS_CONFIG_MESSAGE, RETIRED_REMOTE_WINDOWS_MODE_MESSAGE,
+	type ConfigIssue,
+} from "./policy";
+import { redactValue } from "../debug";
+import { detectRetiredRemoteWindows } from "../retired-remote-windows";
+
+const lastNotice = new WeakMap<object, string>();
+
+/** Controlled human text for a known code; never built from user-supplied configuration values. */
+function issueExplanation(issue: ConfigIssue): string {
+	if (issue.code === RETIRED_AUTO_MODE_ISSUE) return RETIRED_AUTO_MODE_MESSAGE;
+	if (issue.code === RETIRED_REMOTE_WINDOWS_ISSUE) return RETIRED_REMOTE_WINDOWS_CONFIG_MESSAGE;
+	if (issue.code === RETIRED_REMOTE_WINDOWS_MODE_ISSUE) return RETIRED_REMOTE_WINDOWS_MODE_MESSAGE;
+	return issue.code;
+}
+
+export function formatConfigIssues(issues: readonly ConfigIssue[], limit = 12): string {
+	const lines = issues.slice(0, limit).map((issue) =>
+		`${issue.severity}: ${issue.path.slice(0, 220)} — ${issueExplanation(issue)}`);
+	if (issues.length > limit) lines.push(`${issues.length - limit} more issue(s); inspect the configuration file.`);
+	return String(redactValue(lines.join("\n")));
+}
+
+/** Per-session bounded notice, independent of feature enablement/debug. Never logs raw config. */
+export function notifyConfigIssues(ctx: ExtensionContext, resolved: ResolvedToolkitConfig): void {
+	const owner = ctx.sessionManager ?? ctx;
+	if (!ctx.hasUI || typeof ctx.ui?.notify !== "function") return;
+	const hasRetiredWindows = resolved.issues.some((issue) => issue.code === RETIRED_REMOTE_WINDOWS_ISSUE)
+		&& detectRetiredRemoteWindows(ctx.sessionManager.getBranch()) !== undefined;
+	const issues = resolved.issues.filter((issue) => issue.code !== RETIRED_REMOTE_WINDOWS_ISSUE || hasRetiredWindows);
+	if (issues.length === 0) {
+		lastNotice.delete(owner);
+		return;
+	}
+	const message = formatConfigIssues(issues, 4);
+	const fingerprint = `${resolved.source ?? "defaults"}\n${resolved.modelKey ?? ""}\n${message}`;
+	if (lastNotice.get(owner) === fingerprint) return;
+	lastNotice.set(owner, fingerprint);
+	ctx.ui.notify(`Toolkit configuration:\n${message}\nUse /toolkit-config validate for details.`,
+		issues.some((issue) => issue.severity === "error") ? "error" : "warning");
+}

package/src/config/policy.ts

@@ -1,116 +1,115 @@
-import {
-	DEFAULT_COMPACTION_CONFIG,
-	DEFAULT_IMAGE_GENERATION_MODEL,
-	type LeaveManagedModePolicy,
-	type NativeFallbackConfig,
-	type RemoteV2ContextSource,
-} from "../types";
-
-export type ConfigFeature = "context" | "webSearch" | "imageGeneration" | "compatibility" | "responsesWebSocket" | "diagnostics";
-export type SearchRoute = "unmanaged" | "local" | "hosted" | "standalone-alpha";
-export type DiagnosticsConfig = {
-	level: "error" | "warn" | "info" | "debug";
-	notifyOnLoad: boolean;
-	captureRequests: boolean;
-	/** Captures compact responses, not ordinary conversation responses. */
-	captureResponses: boolean;
-	redactSensitiveData: boolean;
-	artifactRoot: string;
-};
-export type ContextPolicy = {
-	mode: "pi" | "remote-compaction" | "remote-windows";
-	remoteCompaction: {
-		model: string | null;
-		inputSource: RemoteV2ContextSource;
-		allowContinuityBreak: boolean;
-		apis: string[];
-	};
-	nativeFallback: Omit<NativeFallbackConfig, "model"> & { model: string | null };
-	remoteWindows: {
-		leaveManagedMode: LeaveManagedModePolicy;
-		reminderThresholdPercent: number;
-	};
-};
-export type EffectiveToolkitPolicy = {
-	context: ContextPolicy;
-	webSearch: { route: SearchRoute };
-	imageGeneration: { enabled: boolean; defaultModel: string; allowedModels: string[] };
-	responsesWebSocket: { enabled: boolean };
-	compatibility: { transport: "standard" | "codex-gateway" };
-	diagnostics: DiagnosticsConfig;
-};
-export type ConfigOrigin = {
-	kind: "builtin" | "defaults" | "model" | "legacy";
-	path?: string;
-	source?: string;
-};
-export type ConfigIssue = {
-	severity: "error" | "warning";
-	/** Controlled code; do not include raw input values in messages. */
-	code: string;
-	path: string;
-	feature: ConfigFeature | "document";
-	/** Issues for a different model do not invalidate the selected model. */
-	modelKey?: string;
-};
-/**
- * Stable code for a configuration section that was removed from the Toolkit. A retired section is
- * ignored in any shape and must never invalidate another feature, so it is reported as a warning.
- */
-export const RETIRED_AUTO_MODE_ISSUE = "retired.autoMode" as const;
-/** Controlled explanation of the retirement; never contains user-supplied values. */
-export const RETIRED_AUTO_MODE_MESSAGE =
-	"Auto Mode has been removed; these settings are ignored and tool calls are no longer reviewed by it.";
-export type ResolvedToolkitPolicy = {
-	policy: EffectiveToolkitPolicy;
-	origins: Record<string, ConfigOrigin>;
-	issues: ConfigIssue[];
-	invalidFeatures: ConfigFeature[];
-};
-export type ConfigDocumentSnapshot = {
-	format: "legacy" | "v2" | "missing" | "invalid";
-	configPath: string;
-	/** In-memory only; never render arbitrary raw configuration values. */
-	raw?: unknown;
-	issues: ConfigIssue[];
-};
-export const CONFIG_FEATURES: readonly ConfigFeature[] = [
-	"context", "webSearch", "imageGeneration", "compatibility", "responsesWebSocket", "diagnostics",
-];
-
-/** Independent per-operation defaults, preserving the existing shipped policy. */
-export function createPolicyDefaults(): EffectiveToolkitPolicy {
-	const context = DEFAULT_COMPACTION_CONFIG;
-	return {
-		context: {
-			mode: "remote-compaction",
-			remoteCompaction: {
-				model: null,
-				inputSource: context.remoteV2ContextSource,
-				allowContinuityBreak: context.allowCompactionContinuityBreak,
-				apis: [...context.responsesApis],
-			},
-			nativeFallback: { ...context.nativeFallback, model: null },
-			remoteWindows: {
-				leaveManagedMode: context.leaveManagedMode,
-				reminderThresholdPercent: context.contextReminderThresholdPercent,
-			},
-		},
-		webSearch: { route: "unmanaged" },
-		imageGeneration: {
-			enabled: false,
-			defaultModel: DEFAULT_IMAGE_GENERATION_MODEL,
-			allowedModels: [DEFAULT_IMAGE_GENERATION_MODEL],
-		},
-		responsesWebSocket: { enabled: false },
-		compatibility: { transport: "standard" },
-		diagnostics: {
-			level: "info",
-			notifyOnLoad: context.notifyOnLoad,
-			captureRequests: context.logProviderPayloads,
-			captureResponses: context.logCompactResponses,
-			redactSensitiveData: context.redactSensitiveData,
-			artifactRoot: context.artifactRoot,
-		},
-	};
-}
+import {
+	DEFAULT_COMPACTION_CONFIG,
+	DEFAULT_IMAGE_GENERATION_MODEL,
+	type NativeFallbackConfig,
+	type RemoteV2ContextSource,
+} from "../types";
+
+export type ConfigFeature = "context" | "webSearch" | "imageGeneration" | "compatibility" | "responsesWebSocket" | "diagnostics";
+export type SearchRoute = "unmanaged" | "local" | "hosted" | "standalone-alpha";
+export type DiagnosticsConfig = {
+	level: "error" | "warn" | "info" | "debug";
+	notifyOnLoad: boolean;
+	captureRequests: boolean;
+	/** Captures compact responses, not ordinary conversation responses. */
+	captureResponses: boolean;
+	redactSensitiveData: boolean;
+	artifactRoot: string;
+};
+export type ContextPolicy = {
+	mode: "pi" | "remote-compaction";
+	remoteCompaction: {
+		model: string | null;
+		inputSource: RemoteV2ContextSource;
+		allowContinuityBreak: boolean;
+		apis: string[];
+	};
+	nativeFallback: Omit<NativeFallbackConfig, "model"> & { model: string | null };
+};
+export type EffectiveToolkitPolicy = {
+	context: ContextPolicy;
+	webSearch: { route: SearchRoute };
+	imageGeneration: { enabled: boolean; defaultModel: string; allowedModels: string[] };
+	responsesWebSocket: { enabled: boolean };
+	compatibility: { transport: "standard" | "codex-gateway" };
+	diagnostics: DiagnosticsConfig;
+};
+export type ConfigOrigin = {
+	kind: "builtin" | "defaults" | "model" | "legacy";
+	path?: string;
+	source?: string;
+};
+export type ConfigIssue = {
+	severity: "error" | "warning";
+	/** Controlled code; do not include raw input values in messages. */
+	code: string;
+	path: string;
+	feature: ConfigFeature | "document";
+	/** Issues for a different model do not invalidate the selected model. */
+	modelKey?: string;
+};
+/**
+ * Stable code for a configuration section that was removed from the Toolkit. A retired section is
+ * ignored in any shape and must never invalidate another feature, so it is reported as a warning.
+ */
+export const RETIRED_AUTO_MODE_ISSUE = "retired.autoMode" as const;
+/** Controlled explanation of the retirement; never contains user-supplied values. */
+export const RETIRED_AUTO_MODE_MESSAGE =
+	"Auto Mode has been removed; these settings are ignored and tool calls are no longer reviewed by it.";
+/** Opaque ancillary settings are warning-only; explicitly selected retired modes block context. */
+export const RETIRED_REMOTE_WINDOWS_ISSUE = "retired.remoteWindows" as const;
+export const RETIRED_REMOTE_WINDOWS_MODE_ISSUE = "retired.remoteWindows.mode" as const;
+export const RETIRED_REMOTE_WINDOWS_CONFIG_MESSAGE =
+	"Remote Windows has been removed; these settings are ignored. No window behavior or automatic migration is available.";
+export const RETIRED_REMOTE_WINDOWS_MODE_MESSAGE =
+	"Remote Windows has been removed. Context operations are blocked until you explicitly select pi or remote-compaction. No replacement mode was activated.";
+
+export type ResolvedToolkitPolicy = {
+	policy: EffectiveToolkitPolicy;
+	origins: Record<string, ConfigOrigin>;
+	issues: ConfigIssue[];
+	invalidFeatures: ConfigFeature[];
+};
+export type ConfigDocumentSnapshot = {
+	format: "legacy" | "v2" | "missing" | "invalid";
+	configPath: string;
+	/** In-memory only; never render arbitrary raw configuration values. */
+	raw?: unknown;
+	issues: ConfigIssue[];
+};
+export const CONFIG_FEATURES: readonly ConfigFeature[] = [
+	"context", "webSearch", "imageGeneration", "compatibility", "responsesWebSocket", "diagnostics",
+];
+
+/** Independent per-operation defaults, preserving the existing shipped policy. */
+export function createPolicyDefaults(): EffectiveToolkitPolicy {
+	const context = DEFAULT_COMPACTION_CONFIG;
+	return {
+		context: {
+			mode: "remote-compaction",
+			remoteCompaction: {
+				model: null,
+				inputSource: context.remoteV2ContextSource,
+				allowContinuityBreak: context.allowCompactionContinuityBreak,
+				apis: [...context.responsesApis],
+			},
+			nativeFallback: { ...context.nativeFallback, model: null },
+		},
+		webSearch: { route: "unmanaged" },
+		imageGeneration: {
+			enabled: false,
+			defaultModel: DEFAULT_IMAGE_GENERATION_MODEL,
+			allowedModels: [DEFAULT_IMAGE_GENERATION_MODEL],
+		},
+		responsesWebSocket: { enabled: false },
+		compatibility: { transport: "standard" },
+		diagnostics: {
+			level: "info",
+			notifyOnLoad: context.notifyOnLoad,
+			captureRequests: context.logProviderPayloads,
+			captureResponses: context.logCompactResponses,
+			redactSensitiveData: context.redactSensitiveData,
+			artifactRoot: context.artifactRoot,
+		},
+	};
+}