pi-openai-toolkit 0.20.8 → 0.21.0

package/src/config/migration.ts

@@ -1,100 +1,103 @@
-import { resolveToolkitConfig } from "../config";
-import type { LoadedToolkitConfig } from "../types";
-import 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") return { status: "already-v2", reasons: ["The document already uses schemaVersion 2."], unmappedPaths: [] };
-	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.autoMode.models,
-		...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.autoMode.available !== defaults.autoMode.available) override.autoMode = { available: resolved.policy.autoMode.available };
-		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[] = [];
-	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.autoMode.enabled && legacy.autoMode.models.length) {
-		reasons.push("Disabled legacy auto mode contains a dormant eligibility list; keep the original file for review.");
-		unmappedPaths.add("autoMode.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, 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."],
+	};
+}

package/src/config/notifications.ts

@@ -1,28 +1,36 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { ResolvedToolkitConfig } from "../config";
-import type { ConfigIssue } from "./policy";
-import { redactValue } from "../debug";
-
-const lastNotice = new WeakMap<object, string>();
-
-export function formatConfigIssues(issues: readonly ConfigIssue[], limit = 12): string {
-	const lines = issues.slice(0, limit).map((issue) => `${issue.severity}: ${issue.path.slice(0, 220)} — ${issue.code}`);
-	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, 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");
+}

package/src/config/policy.ts

@@ -1,14 +1,12 @@
 import {
-	DEFAULT_AUTO_MODE_CONFIG,
 	DEFAULT_COMPACTION_CONFIG,
 	DEFAULT_IMAGE_GENERATION_MODEL,
-	type AutoModeConfig,
 	type LeaveManagedModePolicy,
 	type NativeFallbackConfig,
 	type RemoteV2ContextSource,
 } from "../types";
 
-export type ConfigFeature = "context" | "webSearch" | "imageGeneration" | "autoMode" | "compatibility" | "responsesWebSocket" | "diagnostics";
+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";
@@ -33,17 +31,11 @@ export type ContextPolicy = {
 		reminderThresholdPercent: number;
 	};
 };
-export type AutoModePolicy = Omit<AutoModeConfig, "enabled" | "models" | "reviewerModel" | "classifier"> & {
-	available: boolean;
-	reviewerModel: string | null;
-	classifier: Omit<AutoModeConfig["classifier"], "model"> & { model: string | null };
-};
 export type EffectiveToolkitPolicy = {
 	context: ContextPolicy;
 	webSearch: { route: SearchRoute };
 	imageGeneration: { enabled: boolean; defaultModel: string; allowedModels: string[] };
 	responsesWebSocket: { enabled: boolean };
-	autoMode: AutoModePolicy;
 	compatibility: { transport: "standard" | "codex-gateway" };
 	diagnostics: DiagnosticsConfig;
 };
@@ -61,6 +53,14 @@ export type ConfigIssue = {
 	/** 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>;
@@ -75,14 +75,12 @@ export type ConfigDocumentSnapshot = {
 	issues: ConfigIssue[];
 };
 export const CONFIG_FEATURES: readonly ConfigFeature[] = [
-	"context", "webSearch", "imageGeneration", "autoMode", "compatibility", "responsesWebSocket", "diagnostics",
+	"context", "webSearch", "imageGeneration", "compatibility", "responsesWebSocket", "diagnostics",
 ];
 
 /** Independent per-operation defaults, preserving the existing shipped policy. */
 export function createPolicyDefaults(): EffectiveToolkitPolicy {
 	const context = DEFAULT_COMPACTION_CONFIG;
-	const auto = structuredClone(DEFAULT_AUTO_MODE_CONFIG);
-	const { enabled: _enabled, models: _models, reviewerModel, classifier, ...autoOptions } = auto;
 	return {
 		context: {
 			mode: "remote-compaction",
@@ -105,12 +103,6 @@ export function createPolicyDefaults(): EffectiveToolkitPolicy {
 			allowedModels: [DEFAULT_IMAGE_GENERATION_MODEL],
 		},
 		responsesWebSocket: { enabled: false },
-		autoMode: {
-			...autoOptions,
-			available: false,
-			reviewerModel: reviewerModel ?? null,
-			classifier: { ...classifier, model: classifier.model ?? null },
-		},
 		compatibility: { transport: "standard" },
 		diagnostics: {
 			level: "info",