@oh-my-pi/pi-coding-agent 16.2.2 → 16.2.4

package/src/cli/update-cli.ts

@@ -272,6 +272,252 @@ function compareVersions(a: string, b: string): number {
 	return 0;
 }
 
+interface BunInstallCachePruneResult {
+	scannedPackages: number;
+	removedEntries: number;
+}
+
+interface BunCachePackageGroup {
+	actualDirs: Map<string, string[]>;
+	markerDir?: string;
+	markerEntries: Map<string, string[]>;
+}
+
+function stripBunCacheVersionSuffix(name: string): string {
+	const metadataIndex = name.indexOf("@@");
+	return metadataIndex === -1 ? name : name.slice(0, metadataIndex);
+}
+
+function compareSemverIdentifier(a: string, b: string): number {
+	const aNumber = /^\d+$/.test(a);
+	const bNumber = /^\d+$/.test(b);
+	if (aNumber && bNumber) return Number(a) - Number(b);
+	if (aNumber) return -1;
+	if (bNumber) return 1;
+	return a.localeCompare(b);
+}
+
+function compareSemverLikeVersions(a: string, b: string): number {
+	const [aCoreWithPrerelease] = a.split("+", 1);
+	const [bCoreWithPrerelease] = b.split("+", 1);
+	const [aCore, aPrerelease] = aCoreWithPrerelease.split("-", 2);
+	const [bCore, bPrerelease] = bCoreWithPrerelease.split("-", 2);
+	const aParts = aCore.split(".");
+	const bParts = bCore.split(".");
+	for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+		const diff = Number(aParts[i] ?? 0) - Number(bParts[i] ?? 0);
+		if (diff !== 0 && Number.isFinite(diff)) return diff;
+	}
+	if (!aPrerelease && !bPrerelease) return 0;
+	if (!aPrerelease) return 1;
+	if (!bPrerelease) return -1;
+	const aPrereleaseParts = aPrerelease.split(".");
+	const bPrereleaseParts = bPrerelease.split(".");
+	for (let i = 0; i < Math.max(aPrereleaseParts.length, bPrereleaseParts.length); i++) {
+		const aPart = aPrereleaseParts[i];
+		const bPart = bPrereleaseParts[i];
+		if (aPart === undefined) return -1;
+		if (bPart === undefined) return 1;
+		const diff = compareSemverIdentifier(aPart, bPart);
+		if (diff !== 0) return diff;
+	}
+	return 0;
+}
+
+async function readdirIfExists(dir: string): Promise<fs.Dirent[]> {
+	try {
+		return await fs.promises.readdir(dir, { withFileTypes: true });
+	} catch (err) {
+		if (isEnoent(err)) return [];
+		throw err;
+	}
+}
+
+function getBunCacheGroup(groups: Map<string, BunCachePackageGroup>, packageName: string): BunCachePackageGroup {
+	let group = groups.get(packageName);
+	if (!group) {
+		group = { actualDirs: new Map(), markerEntries: new Map() };
+		groups.set(packageName, group);
+	}
+	return group;
+}
+
+function addVersionPath(entries: Map<string, string[]>, version: string, entryPath: string): void {
+	const paths = entries.get(version);
+	if (paths) {
+		paths.push(entryPath);
+		return;
+	}
+	entries.set(version, [entryPath]);
+}
+
+async function addBunCacheActualDir(
+	groups: Map<string, BunCachePackageGroup>,
+	dirPath: string,
+	packageNames: Set<string> | undefined,
+): Promise<void> {
+	try {
+		const manifest = (await Bun.file(path.join(dirPath, "package.json")).json()) as Partial<
+			Record<"name" | "version", unknown>
+		>;
+		if (typeof manifest.name !== "string" || typeof manifest.version !== "string") return;
+		if (packageNames && !packageNames.has(manifest.name)) return;
+		const group = getBunCacheGroup(groups, manifest.name);
+		addVersionPath(group.actualDirs, manifest.version, dirPath);
+	} catch (err) {
+		if (isEnoent(err)) return;
+		throw err;
+	}
+}
+
+async function addBunCacheMarkerDir(
+	groups: Map<string, BunCachePackageGroup>,
+	packageName: string,
+	markerDir: string,
+	packageNames: Set<string> | undefined,
+): Promise<void> {
+	if (packageNames && !packageNames.has(packageName)) return;
+	const markerEntries = await readdirIfExists(markerDir);
+	const group = getBunCacheGroup(groups, packageName);
+	group.markerDir = markerDir;
+	for (const entry of markerEntries) {
+		const cacheVersion = stripBunCacheVersionSuffix(entry.name);
+		addVersionPath(group.markerEntries, cacheVersion, path.join(markerDir, entry.name));
+	}
+}
+
+async function collectBunCacheGroups(
+	cacheDir: string,
+	packageNames: Set<string> | undefined,
+): Promise<Map<string, BunCachePackageGroup>> {
+	const groups = new Map<string, BunCachePackageGroup>();
+	for (const entry of await readdirIfExists(cacheDir)) {
+		if (!entry.isDirectory()) continue;
+		const entryPath = path.join(cacheDir, entry.name);
+		if (entry.name.startsWith("@")) {
+			for (const scopedEntry of await readdirIfExists(entryPath)) {
+				if (!scopedEntry.isDirectory()) continue;
+				const scopedEntryPath = path.join(entryPath, scopedEntry.name);
+				const versionSeparator = scopedEntry.name.lastIndexOf("@");
+				if (versionSeparator === -1) {
+					await addBunCacheMarkerDir(groups, `${entry.name}/${scopedEntry.name}`, scopedEntryPath, packageNames);
+				} else {
+					await addBunCacheActualDir(groups, scopedEntryPath, packageNames);
+				}
+			}
+			continue;
+		}
+		const versionSeparator = entry.name.lastIndexOf("@");
+		if (versionSeparator === -1) {
+			await addBunCacheMarkerDir(groups, entry.name, entryPath, packageNames);
+		} else {
+			await addBunCacheActualDir(groups, entryPath, packageNames);
+		}
+	}
+	return groups;
+}
+
+async function removeCacheEntries(paths: string[]): Promise<number> {
+	for (const entryPath of paths) {
+		await fs.promises.rm(entryPath, { recursive: true, force: true });
+	}
+	return paths.length;
+}
+
+/**
+ * Prune Bun's package cache so each package keeps only its newest cached version.
+ *
+ * Bun stores package cache entries as both a package marker directory
+ * (`react/19.2.6@@@1`) and a materialized package directory
+ * (`react@19.2.6@@@1`). Global `omp` updates can leave one full copy per
+ * release. The marker and materialized entries are removed together so the
+ * cache stays internally consistent.
+ */
+export async function pruneBunInstallCache(
+	cacheDir: string,
+	packageNames?: Set<string>,
+): Promise<BunInstallCachePruneResult> {
+	const groups = await collectBunCacheGroups(cacheDir, packageNames);
+	let scannedPackages = 0;
+	let removedEntries = 0;
+	for (const group of groups.values()) {
+		if (group.actualDirs.size === 0) continue;
+		scannedPackages++;
+		let latestVersion: string | undefined;
+		for (const version of group.actualDirs.keys()) {
+			if (!latestVersion || compareSemverLikeVersions(version, latestVersion) > 0) latestVersion = version;
+		}
+		if (!latestVersion) continue;
+		for (const [version, paths] of group.actualDirs) {
+			if (version !== latestVersion) removedEntries += await removeCacheEntries(paths);
+		}
+		for (const [version, paths] of group.markerEntries) {
+			if (version !== latestVersion) removedEntries += await removeCacheEntries(paths);
+		}
+	}
+	return { scannedPackages, removedEntries };
+}
+
+async function resolveBunInstallCacheDir(): Promise<string | undefined> {
+	try {
+		const result = await $`bun pm cache`.quiet().nothrow();
+		if (result.exitCode !== 0) return undefined;
+		const output = result.text().trim();
+		return output.length > 0 ? output : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function resolveBunGlobalNodeModulesDirFromLocations(
+	globalBinDir: string | undefined,
+	cacheDir: string | undefined,
+): string | undefined {
+	if (globalBinDir && globalBinDir.length > 0) {
+		return path.join(path.dirname(globalBinDir), "install", "global", "node_modules");
+	}
+	if (cacheDir && cacheDir.length > 0) {
+		return path.join(path.dirname(cacheDir), "global", "node_modules");
+	}
+	return undefined;
+}
+
+async function resolveBunGlobalNodeModulesDir(cacheDir: string): Promise<string | undefined> {
+	try {
+		const result = await $`bun pm bin -g`.quiet().nothrow();
+		const globalBinDir = result.exitCode === 0 ? result.text().trim() : undefined;
+		return resolveBunGlobalNodeModulesDirFromLocations(globalBinDir, cacheDir);
+	} catch {
+		return resolveBunGlobalNodeModulesDirFromLocations(undefined, cacheDir);
+	}
+}
+
+async function collectInstalledPackageNames(nodeModulesDir: string): Promise<Set<string>> {
+	const packageNames = new Set<string>();
+	for (const entry of await readdirIfExists(nodeModulesDir)) {
+		if (!entry.isDirectory() || entry.name === ".bin") continue;
+		if (entry.name.startsWith("@")) {
+			for (const scopedEntry of await readdirIfExists(path.join(nodeModulesDir, entry.name))) {
+				if (scopedEntry.isDirectory()) packageNames.add(`${entry.name}/${scopedEntry.name}`);
+			}
+			continue;
+		}
+		packageNames.add(entry.name);
+	}
+	return packageNames;
+}
+
+async function pruneBunCacheAfterGlobalInstall(): Promise<BunInstallCachePruneResult | undefined> {
+	const cacheDir = await resolveBunInstallCacheDir();
+	if (!cacheDir) return undefined;
+	const globalNodeModulesDir = await resolveBunGlobalNodeModulesDir(cacheDir);
+	const packageNames = globalNodeModulesDir
+		? await collectInstalledPackageNames(globalNodeModulesDir)
+		: new Set<string>();
+	if (packageNames.size === 0 && !path.basename(cacheDir).toLowerCase().includes("omp")) return undefined;
+	return await pruneBunInstallCache(cacheDir, packageNames.size === 0 ? undefined : packageNames);
+}
+
 /**
  * Get the appropriate binary name for this platform.
  */
@@ -524,6 +770,14 @@ async function updateViaBun(expectedVersion: string): Promise<void> {
 	}
 
 	await printVerification(expectedVersion);
+	try {
+		const pruneResult = await pruneBunCacheAfterGlobalInstall();
+		if (pruneResult && pruneResult.removedEntries > 0) {
+			console.log(chalk.dim(`Pruned ${pruneResult.removedEntries} stale Bun cache entries`));
+		}
+	} catch (err) {
+		console.log(chalk.yellow(`Warning: could not prune stale Bun cache entries: ${err}`));
+	}
 }
 
 async function updateViaHomebrew(expectedVersion: string, force: boolean): Promise<void> {

package/src/collab/guest.ts

@@ -78,6 +78,46 @@ interface PendingSnapshot {
 	isResync: boolean;
 }
 
+/** Minimal context surface the idle-state reconciler mutates. */
+export interface GuestIdleReconcilerCtx {
+	statusLine: { markActivityEnd: () => void };
+	loadingAnimation: { stop: () => void } | undefined;
+}
+
+/**
+ * Close the guest UI state held open by an earlier `agent_start` whose
+ * matching `agent_end` never reached us — most often because a reconnect
+ * dropped the event mid-stream. Triggered from {@link CollabGuestLink}'s
+ * `state` reconciler when the host reports `isStreaming === false`:
+ * folds the in-flight active-time window into the per-session meter (so
+ * `time_spent` stops ticking) and stops the `Working…` loader if one is
+ * still animating. No-op when the host is still streaming.
+ *
+ * Exported for direct unit testing; mutates the loader field on `ctx` so
+ * the same loader is not stopped twice on subsequent reconciliations.
+ */
+export function reconcileGuestIdleHostState(ctx: GuestIdleReconcilerCtx, isStreaming: boolean): void {
+	if (isStreaming) return;
+	ctx.statusLine.markActivityEnd();
+	if (ctx.loadingAnimation) {
+		ctx.loadingAnimation.stop();
+		ctx.loadingAnimation = undefined;
+	}
+}
+
+/** Reconcile a welcome/resync snapshot's host activity state into the guest meter. */
+export interface GuestSnapshotActivityReconcilerCtx extends GuestIdleReconcilerCtx {
+	statusLine: GuestIdleReconcilerCtx["statusLine"] & { markActivityStart: () => void };
+}
+
+export function reconcileGuestSnapshotHostState(ctx: GuestSnapshotActivityReconcilerCtx, isStreaming: boolean): void {
+	if (isStreaming) {
+		ctx.statusLine.markActivityStart();
+		return;
+	}
+	reconcileGuestIdleHostState(ctx, false);
+}
+
 export class CollabGuestLink {
 	#ctx: InteractiveModeContext;
 	#socket: CollabSocket | null = null;
@@ -355,6 +395,7 @@ export class CollabGuestLink {
 		this.#clearAgentMirror();
 		await this.#ctx.session.switchSession(replicaPath);
 		this.state = pending.state;
+		reconcileGuestSnapshotHostState(this.#ctx, pending.state.isStreaming);
 		this.#applyHostState(pending.state);
 		this.#ctx.resetObserverRegistry();
 		this.#applyAgentSnapshots(pending.agents);
@@ -425,12 +466,7 @@ export class CollabGuestLink {
 				this.#applyHostState(frame.state);
 				setSessionTerminalTitle(frame.state.sessionName, frame.state.cwd);
 				this.#updateStatusSegment();
-				// Reconciler: events normally drive the loader; clear a stale one if
-				// the host reports idle (e.g. events lost across a reconnect).
-				if (!frame.state.isStreaming && this.#ctx.loadingAnimation) {
-					this.#ctx.loadingAnimation.stop();
-					this.#ctx.loadingAnimation = undefined;
-				}
+				reconcileGuestIdleHostState(this.#ctx, frame.state.isStreaming);
 				this.#ctx.statusLine.invalidate();
 				this.#ctx.ui.requestRender();
 				break;
@@ -588,7 +624,7 @@ export class CollabGuestLink {
 		await this.#ctx.session.newSession();
 		setSessionTerminalTitle(this.#ctx.sessionManager.getSessionName(), this.#ctx.sessionManager.getCwd());
 		this.#ctx.statusLine.invalidate();
-		this.#ctx.statusLine.setSessionStartTime(Date.now());
+		this.#ctx.statusLine.resetActiveTime();
 		this.#ctx.updateEditorTopBorder();
 		this.#ctx.updateEditorBorderColor();
 		this.#ctx.renderInitialMessages({ clearTerminalHistory: true });

package/src/collab/host.ts

@@ -37,6 +37,7 @@ import {
 	parseCollabLink,
 } from "./protocol";
 import { CollabSocket } from "./relay-client";
+import { shrinkForReplication } from "./replication-shrink";
 
 /** Events that change the footer state guests render. */
 const STATE_TRIGGER_EVENTS: Record<string, true> = {
@@ -212,7 +213,7 @@ export class CollabHost {
 		}
 
 		this.#unsubscribe = this.#ctx.session.subscribe(event => {
-			if (isWireAgentEvent(event)) this.#broadcast({ t: "event", event });
+			if (isWireAgentEvent(event)) this.#broadcast({ t: "event", event: shrinkForReplication(event) });
 			this.#onEventForState(event);
 		});
 		const bus = this.#ctx.eventBus;
@@ -223,7 +224,7 @@ export class CollabHost {
 		}
 		this.#registryUnsubscribe = AgentRegistry.global().onChange(() => this.#scheduleAgentsBroadcast());
 		this.#ctx.sessionManager.onEntryAppended = entry => {
-			if (isWireSessionEntry(entry)) this.#broadcast({ t: "entry", entry });
+			if (isWireSessionEntry(entry)) this.#broadcast({ t: "entry", entry: shrinkForReplication(entry) });
 			// Model/thinking/title changes land as entries while idle; refresh
 			// guest state promptly (debounce + JSON diff dedupe).
 			this.#scheduleStateBroadcast();
@@ -358,10 +359,13 @@ export class CollabHost {
 
 	/**
 	 * Slice {@link entries} into byte-bounded `snapshot-chunk` frames targeted
-	 * at {@link fromPeer}. Every batch carries at least one entry (a single
-	 * oversize entry ships alone), and the last batch is tagged `final: true`
-	 * so the guest can finalize the replica. An empty snapshot still emits one
-	 * `final` chunk so the guest never blocks on a missing terminator.
+	 * at {@link fromPeer}. Each entry is first run through
+	 * {@link shrinkForReplication} so a single oversized tool-result entry
+	 * cannot ship as an oversized chunk that trips the relay's per-frame
+	 * `maxPayloadLength` (issue #3739). Every batch carries at least one
+	 * entry, and the last batch is tagged `final: true` so the guest can
+	 * finalize the replica. An empty snapshot still emits one `final` chunk
+	 * so the guest never blocks on a missing terminator.
 	 */
 	#sendSnapshotChunks(entries: (StoredSessionEntry & WireSessionEntry)[], fromPeer: number): void {
 		const socket = this.#socket;
@@ -377,9 +381,10 @@ export class CollabHost {
 			while (i < entries.length) {
 				const entry = entries[i];
 				if (!entry) break;
-				const entryBytes = JSON.stringify(entry).length;
+				const shrunk = shrinkForReplication(entry);
+				const entryBytes = JSON.stringify(shrunk).length;
 				if (batch.length > 0 && batchBytes + entryBytes > SNAPSHOT_CHUNK_BYTES) break;
-				batch.push(entry);
+				batch.push(shrunk);
 				batchBytes += entryBytes;
 				i++;
 			}

package/src/collab/replication-shrink.ts

@@ -0,0 +1,111 @@
+/**
+ * Hard-cap helper for host→guest collab frames.
+ *
+ * The host wraps every {@link CollabFrame} in an AES-GCM envelope and ships it
+ * through the relay's WebSocket. WebSocket servers enforce a per-frame
+ * `maxPayloadLength` (Bun's default is 16 MB; many proxies cap lower). A
+ * single oversized payload — typically a `read`/`bash`/`search` tool result
+ * captured as one multi-megabyte string, or a tool result whose `content`
+ * array holds thousands of small blocks — would otherwise ship as its own
+ * oversized frame and trip that limit, killing the host's WebSocket with
+ * `1006 Received too big message`. `CollabSocket` treats 1006 as transient
+ * and reconnects, the next guest hello triggers the same oversized send, and
+ * the loop never breaks (issue #3739).
+ *
+ * This helper bounds any JSON-serializable payload below
+ * {@link MAX_REPLICATED_PAYLOAD_BYTES}. Already-small payloads pass through
+ * untouched; oversized ones are returned as a deep-cloned shadow where long
+ * strings are head-truncated AND long arrays are head-clipped, with
+ * `[…N chars elided for collab session]` / `[…N items elided for collab
+ * session]` markers. Both axes are needed: string truncation alone leaves
+ * the cap unenforced for a payload built of many short strings, where no
+ * field exceeds the per-string floor.
+ */
+
+/**
+ * Per-payload ceiling for host→guest frames. Bun's default WebSocket
+ * `maxPayloadLength` is 16 MB; we leave a generous margin so the AES-GCM
+ * envelope (+ IV + tag), the 4-byte peer header, and the outer wire wrapper
+ * fit comfortably under that on every reasonable relay.
+ */
+export const MAX_REPLICATED_PAYLOAD_BYTES = 1 * 1024 * 1024;
+
+/**
+ * Progressive shrink passes. Each pass tightens both the per-string cap and
+ * the per-array head limit; the loop stops at the first pass whose output
+ * fits {@link MAX_REPLICATED_PAYLOAD_BYTES}. The schedule is concrete (not
+ * recomputed) so the failure modes the helper guards against are visible:
+ *
+ * - One giant string → the first pass already truncates it under 64 KB.
+ * - Array of many small blocks (e.g. a tool result with thousands of
+ *   `{type:"text", text:"..."}` content items) → later passes head-clip the
+ *   array to a small sample with a `[…N items elided]` summary element.
+ *
+ * The final pass clamps every string to 64 B and every array to one element,
+ * so even pathological mixes converge.
+ */
+interface ShrinkPass {
+	stringCap: number;
+	arrayLimit: number;
+}
+
+const SHRINK_PASSES: readonly ShrinkPass[] = [
+	{ stringCap: 64 * 1024, arrayLimit: 256 },
+	{ stringCap: 16 * 1024, arrayLimit: 128 },
+	{ stringCap: 4 * 1024, arrayLimit: 64 },
+	{ stringCap: 1 * 1024, arrayLimit: 32 },
+	{ stringCap: 256, arrayLimit: 16 },
+	{ stringCap: 256, arrayLimit: 4 },
+	{ stringCap: 64, arrayLimit: 1 },
+];
+
+const STRING_ELISION_RESERVE = 80;
+
+/**
+ * Recursively walk `value`, head-truncating any string longer than
+ * `stringCap` and head-clipping any array longer than `arrayLimit`. Returns
+ * a freshly built deep clone — every object/array is rebuilt so the
+ * recursive output can be safely serialized in isolation. Cheap to call on
+ * small values: short strings, numbers, and booleans pass through without
+ * allocation.
+ */
+function shrinkWalk(value: unknown, stringCap: number, arrayLimit: number): unknown {
+	if (typeof value === "string") {
+		if (value.length <= stringCap) return value;
+		const headLen = Math.max(0, stringCap - STRING_ELISION_RESERVE);
+		return `${value.slice(0, headLen)}\n…[${value.length - headLen} chars elided for collab session]`;
+	}
+	if (Array.isArray(value)) {
+		const keep = Math.min(value.length, arrayLimit);
+		const elided = value.length - keep;
+		const out: unknown[] = new Array(elided > 0 ? keep + 1 : keep);
+		for (let i = 0; i < keep; i++) out[i] = shrinkWalk(value[i], stringCap, arrayLimit);
+		if (elided > 0) out[keep] = `…[${elided} items elided for collab session]`;
+		return out;
+	}
+	if (value && typeof value === "object") {
+		const src = value as Record<string, unknown>;
+		const out: Record<string, unknown> = {};
+		for (const k in src) out[k] = shrinkWalk(src[k], stringCap, arrayLimit);
+		return out;
+	}
+	return value;
+}
+
+/**
+ * Return `value` unchanged when its JSON serialization already fits
+ * {@link MAX_REPLICATED_PAYLOAD_BYTES}; otherwise return a deep-cloned
+ * shadow shrunk along both string and array axes until the payload fits.
+ * The function is generic over `T` because the wire shape is preserved:
+ * only string leaves and array tails change; discriminator fields, ids, and
+ * other small metadata pass through untouched.
+ */
+export function shrinkForReplication<T>(value: T): T {
+	if (JSON.stringify(value).length <= MAX_REPLICATED_PAYLOAD_BYTES) return value;
+	let shrunk: unknown = value;
+	for (const pass of SHRINK_PASSES) {
+		shrunk = shrinkWalk(value, pass.stringCap, pass.arrayLimit);
+		if (JSON.stringify(shrunk).length <= MAX_REPLICATED_PAYLOAD_BYTES) return shrunk as T;
+	}
+	return shrunk as T;
+}

package/src/config/model-registry.ts

@@ -303,16 +303,82 @@ function resolveConfigValue(valueConfig: string): string | undefined {
 	return valueConfig;
 }
 
-function resolveConfigHeaders(headers: Record<string, string> | undefined): Record<string, string> | undefined {
-	if (!headers) return undefined;
+type HeaderSource = Record<string, string> | undefined;
+
+interface HeaderResolutionOptions {
+	authHeader?: boolean;
+	apiKeyConfig?: string;
+}
+
+function materializeConfigHeaderSources(
+	sources: readonly HeaderSource[],
+	options?: HeaderResolutionOptions,
+): Record<string, string> | undefined {
 	const resolved: Record<string, string> = {};
-	for (const [key, value] of Object.entries(headers)) {
-		const next = resolveConfigValue(value);
-		if (next) resolved[key] = next;
+	for (const source of sources) {
+		if (!source) continue;
+		for (const [key, value] of Object.entries(source)) {
+			const next = resolveConfigValue(value);
+			if (next) resolved[key] = next;
+		}
+	}
+	if (options?.authHeader && options.apiKeyConfig) {
+		const resolvedKey = resolveConfigValue(options.apiKeyConfig);
+		if (resolvedKey) resolved.Authorization = `Bearer ${resolvedKey}`;
 	}
 	return Object.keys(resolved).length > 0 ? resolved : undefined;
 }
 
+function createLiveConfigHeaders(
+	sources: readonly HeaderSource[],
+	options?: HeaderResolutionOptions,
+): Record<string, string> | undefined {
+	const liveSources = sources.filter((source): source is Record<string, string> => source !== undefined);
+	if (liveSources.length === 0 && (!options?.authHeader || !options.apiKeyConfig)) return undefined;
+
+	const localHeaders: Record<string, string> = {};
+	const allSources = [...liveSources, localHeaders];
+	const current = () => materializeConfigHeaderSources(allSources, options) ?? {};
+	return new Proxy(localHeaders, {
+		get(target, property, receiver) {
+			if (typeof property !== "string") return Reflect.get(target, property, receiver);
+			return current()[property];
+		},
+		set(target, property, value) {
+			if (typeof property !== "string" || typeof value !== "string") return false;
+			target[property] = value;
+			return true;
+		},
+		deleteProperty(target, property) {
+			if (typeof property !== "string") return false;
+			delete target[property];
+			return true;
+		},
+		has(_target, property) {
+			if (typeof property !== "string") return false;
+			return Object.hasOwn(current(), property);
+		},
+		ownKeys() {
+			return Reflect.ownKeys(current());
+		},
+		getOwnPropertyDescriptor(_target, property) {
+			if (typeof property !== "string") return undefined;
+			const headers = current();
+			if (!Object.hasOwn(headers, property)) return undefined;
+			return {
+				configurable: true,
+				enumerable: true,
+				value: headers[property],
+				writable: true,
+			};
+		},
+	});
+}
+
+function resolveConfigHeaders(headers: Record<string, string> | undefined): Record<string, string> | undefined {
+	return materializeConfigHeaderSources([headers]);
+}
+
 function extractGoogleOAuthToken(value: string | undefined): string | undefined {
 	if (!isAuthenticated(value)) return undefined;
 	try {
@@ -495,21 +561,15 @@ function mergeCustomModelHeaders(
 	authHeader: boolean | undefined,
 	apiKeyConfig: string | undefined,
 ): Record<string, string> | undefined {
-	const resolvedModelHeaders = resolveConfigHeaders(modelHeaders);
-	return mergeAuthHeader({ ...providerHeaders, ...resolvedModelHeaders }, authHeader, apiKeyConfig);
+	return createLiveConfigHeaders([providerHeaders, modelHeaders], { authHeader, apiKeyConfig });
 }
 
-function mergeAuthHeader(
-	headers: Record<string, string> | undefined,
+function mergeAuthHeaderSources(
+	sources: readonly HeaderSource[],
 	authHeader: boolean | undefined,
 	apiKeyConfig: string | undefined,
 ): Record<string, string> | undefined {
-	const nextHeaders = headers && Object.keys(headers).length > 0 ? { ...headers } : undefined;
-	if (!authHeader || !apiKeyConfig) {
-		return nextHeaders;
-	}
-	const resolvedKey = resolveConfigValue(apiKeyConfig);
-	return resolvedKey ? { ...nextHeaders, Authorization: `Bearer ${resolvedKey}` } : nextHeaders;
+	return createLiveConfigHeaders(sources, { authHeader, apiKeyConfig });
 }
 
 /**
@@ -1661,7 +1721,9 @@ export class ModelRegistry {
 			baseUrl: override.baseUrl ?? baseOverride?.baseUrl,
 			apiKey: override.apiKey ?? baseOverride?.apiKey,
 			authHeader: override.authHeader ?? baseOverride?.authHeader,
-			headers: override.headers ? { ...(baseOverride?.headers ?? {}), ...override.headers } : baseOverride?.headers,
+			headers: override.headers
+				? createLiveConfigHeaders([baseOverride?.headers, override.headers])
+				: baseOverride?.headers,
 			compat: override.compat ? mergeCompat(baseOverride?.compat, override.compat) : baseOverride?.compat,
 			remoteCompaction: mergeRemoteCompactionConfig(baseOverride?.remoteCompaction, override.remoteCompaction),
 			transport: override.transport ?? baseOverride?.transport,
@@ -1676,8 +1738,8 @@ export class ModelRegistry {
 			"baseUrl" | "headers" | "authHeader" | "apiKey" | "remoteCompaction" | "transport"
 		>,
 	): T {
-		const headers = mergeAuthHeader(
-			override.headers ? { ...entry.headers, ...override.headers } : entry.headers,
+		const headers = mergeAuthHeaderSources(
+			override.headers ? [entry.headers, override.headers] : [entry.headers],
 			override.authHeader,
 			override.apiKey,
 		);

package/src/config/provider-globals.ts

@@ -0,0 +1,25 @@
+import * as imageGen from "../tools/image-gen";
+import * as webSearch from "../web/search";
+
+interface ProviderGlobalSettings {
+	get(path: "providers.webSearchExclude"): unknown;
+	get(path: "providers.webSearch"): unknown;
+	get(path: "providers.image"): unknown;
+}
+
+export function applyProviderGlobalsFromSettings(settings: ProviderGlobalSettings): void {
+	const excludedWebSearchProviders = settings.get("providers.webSearchExclude");
+	if (Array.isArray(excludedWebSearchProviders)) {
+		webSearch.setExcludedSearchProviders(excludedWebSearchProviders.filter(webSearch.isSearchProviderId));
+	}
+
+	const webSearchProvider = settings.get("providers.webSearch");
+	if (typeof webSearchProvider === "string" && webSearch.isSearchProviderPreference(webSearchProvider)) {
+		webSearch.setPreferredSearchProvider(webSearchProvider);
+	}
+
+	const imageProvider = settings.get("providers.image");
+	if (imageGen.isImageProviderPreference(imageProvider)) {
+		imageGen.setPreferredImageProvider(imageProvider);
+	}
+}