@linxiraos/pi-catalog 1.0.0

package/src/identity/id.ts

@@ -0,0 +1,81 @@
+const LEADING_BRACKETED_AFFIX_PATTERN = /^(?:\s*(?:\[|【)[^\]】]+(?:\]|】)\s*)+/u;
+const TRAILING_BRACKETED_AFFIX_PATTERN = /(?:\s*(?:\[|【)[^\]】]+(?:\]|】)\s*)+$/u;
+const MODEL_ID_SEGMENT_PATTERN = /[a-z0-9.:-]+/g;
+const MODEL_FAMILY_PREFIX_PATTERN =
+	/^(claude|gemini|gpt|grok|glm|qwen|deepseek|kimi|mimo|doubao|ernie|gpt-oss|gemma|minimax|step|command|jamba|llama|o[1345])/i;
+
+function normalizeModelIdWhitespace(value: string): string {
+	return value.trim().replace(/\s+/g, " ");
+}
+
+/** Ordering for model-like segments: longest first, ties broken lexicographically. */
+function compareSegmentPreference(left: string, right: string): number {
+	return left.length !== right.length ? right.length - left.length : left.localeCompare(right);
+}
+
+export function getModelLikeIdSegments(modelId: string): string[] {
+	const matches = normalizeModelIdWhitespace(modelId).toLowerCase().match(MODEL_ID_SEGMENT_PATTERN);
+	if (!matches) return [];
+	const segments = new Set<string>();
+	for (const segment of matches) {
+		if (MODEL_FAMILY_PREFIX_PATTERN.test(segment) && /\d/.test(segment)) segments.add(segment);
+	}
+	return [...segments].sort(compareSegmentPreference);
+}
+
+export function getLongestModelLikeIdSegment(modelId: string): string | undefined {
+	const matches = normalizeModelIdWhitespace(modelId).toLowerCase().match(MODEL_ID_SEGMENT_PATTERN);
+	if (!matches) return undefined;
+	let best: string | undefined;
+	for (const segment of matches) {
+		if (
+			MODEL_FAMILY_PREFIX_PATTERN.test(segment) &&
+			/\d/.test(segment) &&
+			(best === undefined || compareSegmentPreference(segment, best) < 0)
+		) {
+			best = segment;
+		}
+	}
+	return best;
+}
+
+function hasBracketAffixMarker(value: string): boolean {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code === 91 || code === 93 || code === 0x3010 || code === 0x3011) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Strip reseller / wrapper tags that are injected as bracketed affixes around an
+ * upstream model id, e.g.
+ *   "[Kiro] claude-opus-4-8"                -> "claude-opus-4-8"
+ *   "[gcli转] gemini-3.1-pro-preview [假流]" -> "gemini-3.1-pro-preview"
+ *
+ * Candidates are returned most-stripped first: both ends, then leading-only, then trailing-only.
+ */
+export function getBracketStrippedModelIdCandidates(modelId: string): string[] {
+	if (!hasBracketAffixMarker(modelId)) return [];
+	const normalized = normalizeModelIdWhitespace(modelId);
+	if (!normalized) return [];
+
+	const strippedLeading = normalized.replace(LEADING_BRACKETED_AFFIX_PATTERN, "");
+	const withoutLeading = normalizeModelIdWhitespace(strippedLeading);
+	const withoutTrailing = normalizeModelIdWhitespace(normalized.replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""));
+	const withoutBoth = normalizeModelIdWhitespace(strippedLeading.replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""));
+
+	const candidates = new Set<string>();
+	for (const candidate of [withoutBoth, withoutLeading, withoutTrailing]) {
+		if (candidate && candidate !== normalized) {
+			candidates.add(candidate);
+		}
+	}
+	return [...candidates];
+}
+
+export function stripBracketedModelIdAffixes(modelId: string): string | undefined {
+	return getBracketStrippedModelIdCandidates(modelId)[0];
+}

package/src/identity/index.ts

@@ -0,0 +1,8 @@
+export * from "./bundled";
+export * from "./classify";
+export * from "./dialect";
+export * from "./family";
+export * from "./id";
+export * from "./markers";
+export * from "./priority";
+export * from "./reference";

package/src/identity/markers.ts

@@ -0,0 +1,49 @@
+/**
+ * Trailing-marker vocabulary shared by canonical-id resolution and
+ * proxy-reference lookup. A "marker" is a routing/quantization/effort suffix
+ * a reseller or aggregator appends to an upstream model id
+ * (`-thinking`, `:nitro`, `-fp8`, …) that does not change model identity.
+ */
+const TRAILING_MARKERS = [
+	"thinking",
+	"customtools",
+	"high",
+	"low",
+	"medium",
+	"minimal",
+	"xhigh",
+	"free",
+	"cloud",
+	"exacto",
+	"nitro",
+	"original",
+	"optimized",
+	"nvfp4",
+	"fp8",
+	"fp4",
+	"bf16",
+	"int8",
+	"int4",
+] as const;
+
+/**
+ * Markers treated as identity-preserving ONLY when recovering bundled metadata
+ * for a proxied model id, never during canonical-id coalescing: Perplexity's
+ * `sonar-pro-search` is a distinct model from `sonar-pro`, so canonical
+ * resolution must not strip `search`, while a proxy id like
+ * `claude-opus-4-6-search` should still inherit the upstream pricing/limits.
+ */
+const REFERENCE_ONLY_TRAILING_MARKERS = ["search"] as const;
+
+function buildTrailingMarkerPattern(markers: readonly string[]): RegExp {
+	return new RegExp(`[-:](?:${markers.join("|")})$`, "i");
+}
+
+/** Marker pattern used by canonical-id resolution (`search` excluded). */
+export const CANONICAL_TRAILING_MARKER_PATTERN = buildTrailingMarkerPattern(TRAILING_MARKERS);
+
+/** Marker pattern used by proxy-reference lookup (`search` included). */
+export const REFERENCE_TRAILING_MARKER_PATTERN = buildTrailingMarkerPattern([
+	...TRAILING_MARKERS,
+	...REFERENCE_ONLY_TRAILING_MARKERS,
+]);

package/src/identity/priority.ts

@@ -0,0 +1,59 @@
+const DEFAULT_MODEL_PROVIDER_ORDER = [
+	// First-party / native account providers. Prefer these over relays when the
+	// same upstream model is available in more than one place.
+	"openai-codex",
+	"anthropic",
+	"openai",
+	"google-gemini-cli",
+	"google",
+	"google-vertex",
+	"kimi-code",
+	"moonshot",
+	"qwen-portal",
+	"alibaba-token-plan",
+	"zai",
+	"xai-oauth",
+	"xai",
+	"mistral",
+	"deepseek",
+	"groq",
+
+	// High-quality aggregators / hosted inference providers.
+	"fireworks",
+	"cerebras",
+	"baseten",
+	"openrouter",
+	"aimlapi",
+	"together",
+
+	// Generic gateways and editor/proxy providers. These are useful when picked
+	// explicitly, but should not win ambiguous automatic role selection.
+	"alibaba-coding-plan",
+	"umans",
+	"google-antigravity",
+	"opencode-zen",
+	"gitlab-duo",
+	"opencode-go",
+	"kilo",
+	"vercel-ai-gateway",
+	"cloudflare-ai-gateway",
+	"nanogpt",
+	"github-copilot",
+] as const;
+
+function addProviderRank(rank: Map<string, number>, provider: string): void {
+	const normalized = provider.trim().toLowerCase();
+	if (!normalized || rank.has(normalized)) return;
+	rank.set(normalized, rank.size);
+}
+
+export function buildModelProviderPriorityRank(configuredProviderOrder?: readonly string[]): Map<string, number> {
+	const rank = new Map<string, number>();
+	for (const provider of configuredProviderOrder ?? []) {
+		addProviderRank(rank, provider);
+	}
+	for (const provider of DEFAULT_MODEL_PROVIDER_ORDER) {
+		addProviderRank(rank, provider);
+	}
+	return rank;
+}

package/src/identity/reference.ts

@@ -0,0 +1,167 @@
+/**
+ * Proxy/reseller reference lookup: given a custom model id served through a
+ * proxy (`[Kiro] claude-opus-4-8`, `gpt-5.4:cloud`, `vendor/claude-sonnet-4-6-thinking`),
+ * find the bundled upstream model so missing pricing/capability metadata can be
+ * inherited while keeping the custom transport.
+ *
+ * Kept separate from canonical-id resolution (`./equivalence`): this lookup
+ * may strip `search`-style markers and prefers cache-pricing-complete
+ * references, both of which would be wrong for canonical coalescing.
+ */
+import type { Api, Model, ThinkingConfig } from "../types";
+import { getBracketStrippedModelIdCandidates, getLongestModelLikeIdSegment, getModelLikeIdSegments } from "./id";
+import { REFERENCE_TRAILING_MARKER_PATTERN } from "./markers";
+
+export interface ModelReferenceIndex {
+	exact: Map<string, Model<Api>>;
+	suffixAlias: Map<string, Model<Api>>;
+}
+
+// xai-oauth subscription entries carry zero public pricing and inflated maxTokens;
+// keep them provider-local so they cannot outrank paid/public Grok references.
+export function isZeroCostXaiOAuthReference(candidate: Model<Api>): boolean {
+	return (
+		candidate.provider === "xai-oauth" &&
+		candidate.cost.input === 0 &&
+		candidate.cost.output === 0 &&
+		candidate.cost.cacheRead === 0 &&
+		candidate.cost.cacheWrite === 0
+	);
+}
+
+// Prefer the reference with the largest limits and complete cache pricing, then
+// first-party OpenAI entries.
+function shouldReplaceReference(existing: Model<Api> | undefined, candidate: Model<Api>): boolean {
+	if (!existing) return true;
+	if (candidate.contextWindow !== existing.contextWindow) {
+		return (candidate.contextWindow ?? 0) > (existing.contextWindow ?? 0);
+	}
+	if (candidate.maxTokens !== existing.maxTokens) {
+		return (candidate.maxTokens ?? 0) > (existing.maxTokens ?? 0);
+	}
+	const existingHasCachePricing = existing.cost.cacheRead > 0 || existing.cost.cacheWrite > 0;
+	const candidateHasCachePricing = candidate.cost.cacheRead > 0 || candidate.cost.cacheWrite > 0;
+	if (candidateHasCachePricing !== existingHasCachePricing) {
+		return candidateHasCachePricing;
+	}
+	return existing.provider !== "openai" && candidate.provider === "openai";
+}
+
+function normalizeReferenceKey(value: string): string {
+	return value.trim().toLowerCase();
+}
+
+/**
+ * Build a reference index from a model catalog (typically the bundled models).
+ * Pure: callers are responsible for memoizing the result.
+ */
+export function buildModelReferenceIndex(models: Iterable<Model<Api>>): ModelReferenceIndex {
+	const exact = new Map<string, Model<Api>>();
+	for (const candidate of models) {
+		if (isZeroCostXaiOAuthReference(candidate)) {
+			continue;
+		}
+		const key = normalizeReferenceKey(candidate.id);
+		if (shouldReplaceReference(exact.get(key), candidate)) {
+			exact.set(key, candidate);
+		}
+	}
+	return { exact, suffixAlias: buildSuffixAliasMap(exact) };
+}
+
+function buildSuffixAliasMap(exactReferences: ReadonlyMap<string, Model<Api>>): Map<string, Model<Api>> {
+	const aliases = new Map<string, Model<Api>>();
+	for (const reference of exactReferences.values()) {
+		const slashIndex = reference.id.lastIndexOf("/");
+		if (slashIndex === -1) {
+			continue;
+		}
+		const suffix = reference.id.slice(slashIndex + 1);
+		const alias = getLongestModelLikeIdSegment(suffix);
+		if (!alias) {
+			continue;
+		}
+		if (shouldReplaceReference(aliases.get(alias), reference)) {
+			aliases.set(alias, reference);
+		}
+	}
+	return aliases;
+}
+
+function stripReferenceTrailingMarker(candidate: string): string | undefined {
+	const match = REFERENCE_TRAILING_MARKER_PATTERN.exec(candidate);
+	return match ? candidate.slice(0, match.index) : undefined;
+}
+
+function getReferenceCandidateIds(modelId: string): string[] {
+	const candidates = new Set<string>();
+	const queue = [modelId];
+	for (let index = 0; index < queue.length; index += 1) {
+		const candidate = queue[index]?.trim();
+		if (!candidate || candidates.has(candidate)) continue;
+		candidates.add(candidate);
+
+		for (const stripped of getBracketStrippedModelIdCandidates(candidate)) {
+			queue.push(stripped);
+		}
+		for (const segment of getModelLikeIdSegments(candidate)) {
+			queue.push(segment);
+		}
+
+		for (const suffix of [":cloud", "-cloud"] as const) {
+			if (candidate.toLowerCase().endsWith(suffix)) {
+				queue.push(candidate.slice(0, -suffix.length));
+			}
+		}
+
+		const slashIndex = candidate.lastIndexOf("/");
+		if (slashIndex !== -1) {
+			queue.push(candidate.slice(slashIndex + 1));
+		}
+
+		const colonToDash = candidate.replace(/:/g, "-");
+		if (colonToDash !== candidate) {
+			queue.push(colonToDash);
+		}
+
+		const lowercased = candidate.toLowerCase();
+		if (lowercased !== candidate) {
+			queue.push(lowercased);
+		}
+
+		const strippedMarker = stripReferenceTrailingMarker(candidate);
+		if (strippedMarker) {
+			queue.push(strippedMarker);
+		}
+	}
+	return [...candidates];
+}
+
+/**
+ * Inherit bundled reference thinking only for same-provider matches. Wire routing
+ * (`effortRouting`) is provider-specific; cross-provider inheritance can rewrite
+ * gateway ids (e.g. Portkey `@modal/GLM-5-2-FP8` → devin `glm-5-2`).
+ */
+export function inheritReferenceThinking(
+	modelThinking: ThinkingConfig | undefined,
+	reference: Pick<Model<Api>, "provider" | "thinking"> | undefined,
+	provider: string,
+): ThinkingConfig | undefined {
+	if (modelThinking !== undefined) return modelThinking;
+	if (!reference?.thinking) return undefined;
+	if (reference.provider !== provider) return undefined;
+	return reference.thinking;
+}
+
+/** Resolve a (possibly proxied/affixed) model id to its bundled upstream reference. */
+export function resolveModelReference(modelId: string, index: ModelReferenceIndex): Model<Api> | undefined {
+	// Portkey/gateway wire ids (`@provider/model`) are opaque; fuzzy matching would
+	// map them to unrelated bundled entries (e.g. `@modal/GLM-5-2-FP8` → devin/glm-5-2).
+	if (modelId.startsWith("@")) return undefined;
+	for (const candidate of getReferenceCandidateIds(modelId)) {
+		const key = normalizeReferenceKey(candidate);
+		const reference = index.exact.get(key) ?? index.suffixAlias.get(key);
+		if (reference) return reference;
+	}
+	return undefined;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./compat/openai";
+export * from "./discovery";
+export * from "./effort";
+export * from "./fireworks-model-id";
+export * from "./identity";
+export * from "./model-cache";
+export * from "./model-manager";
+export * from "./model-thinking";
+export * from "./models";
+export * from "./provider-models";
+export * from "./types";
+export * from "./utils";
+export * from "./variant-collapse";
+export * from "./wire/codex";
+export * from "./wire/coreweave";
+export * from "./wire/gemini-headers";
+export * from "./wire/github-copilot";

package/src/model-cache.ts

@@ -0,0 +1,285 @@
+/**
+ * SQLite-backed model cache for atomic cross-process access.
+ * Replaces per-provider JSON files with a single cache.db.
+ */
+import { Database } from "bun:sqlite";
+import { getModelDbPath } from "@linxiraos/pi-utils";
+import type { Api, Model, ModelSpec } from "./types";
+
+// Rows persist ModelSpec JSON (sparse `compat`, never the resolved record);
+// the model manager rebuilds via `buildModel` on load. Request headers are
+// intentionally omitted: arbitrary provider-defined header names can carry
+// credentials. v12 invalidates Kimi Code rows carrying the blanket
+// maxTokens: 32000 that predate per-family output caps (k3/k3-256k -> 131072,
+// kimi-for-coding[-highspeed] -> 32768, #6711); v11 invalidates rows that may
+// persist derived computer-use
+// headers and records which model ids lost headers or cannot be rebuilt.
+// v9 invalidated Kimi Code rows predating live effort and protocol metadata;
+// v8 invalidated Codex discovery rows predating provider-native V2 compaction
+// metadata; v7 invalidated rows predating the Antigravity Gemini budget-mode
+// migration (cached specs still carrying `thinking.mode: "google-level"` and
+// the old 3.5-flash effort routing); v6 invalidated rows that may contain the
+// retired unknown-limit sentinels (222222/8888); v5 invalidated rows predating
+// effort-tier variant collapsing (raw `-low`/`-high`/`-thinking` member ids);
+// v4 dropped the pre-efforts ThinkingConfig shape.
+const CACHE_SCHEMA_VERSION = 12;
+const HEADER_RESTORE_VERSION = 1;
+
+interface CacheRow {
+	provider_id: string;
+	version: number;
+	updated_at: number;
+	authoritative: number;
+	static_fingerprint: string;
+	models: string;
+	header_omitted_model_ids: string;
+	unrestorable_header_model_ids: string;
+	header_restore_version: number;
+}
+
+interface TableInfoRow {
+	name: string;
+}
+
+interface CacheEntry<TApi extends Api = Api> {
+	models: ModelSpec<TApi>[];
+	fresh: boolean;
+	authoritative: boolean;
+	updatedAt: number;
+	/** Model ids whose live headers were intentionally omitted from disk. */
+	headerOmittedModelIds: readonly string[];
+	/** Header-bearing model ids that cannot be rebuilt from the static source. */
+	unrestorableHeaderModelIds: readonly string[];
+	/** Whether unrestorable markers predate request-model header matching. */
+	legacyHeaderRestoreMarkers: boolean;
+	/**
+	 * Hash of the static catalog slice that was merged into `models` when this
+	 * row was written. `resolveProviderModels` compares against the current
+	 * static fingerprint and bypasses the static+cache re-merge when they
+	 * match — the cache already incorporates the same static state.
+	 */
+	staticFingerprint: string;
+}
+
+let sharedDb: Database | null = null;
+let sharedDbPath: string | null = null;
+
+function openDb(resolvedPath: string): Database {
+	const db = new Database(resolvedPath, { create: true });
+	// Install the busy handler BEFORE any lock-taking statement. See
+	// https://github.com/can1357/oh-my-pi/issues/2421.
+	db.run("PRAGMA busy_timeout = 3000");
+	// Schema invalidation can delete rows containing credentials written by old
+	// versions. Overwrite deleted SQLite cells instead of leaving their bytes in
+	// free pages where a raw scan of models.db can still recover them (#5780).
+	db.run("PRAGMA secure_delete = ON");
+	db.run("PRAGMA journal_mode = WAL");
+	db.run(`
+		CREATE TABLE IF NOT EXISTS model_cache (
+			provider_id TEXT PRIMARY KEY,
+			version INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL,
+			authoritative INTEGER NOT NULL DEFAULT 0,
+			static_fingerprint TEXT NOT NULL DEFAULT '',
+			header_omitted_model_ids TEXT NOT NULL DEFAULT '[]',
+			unrestorable_header_model_ids TEXT NOT NULL DEFAULT '[]',
+			header_restore_version INTEGER NOT NULL DEFAULT 0,
+			models TEXT NOT NULL
+		)
+	`);
+	migrateCacheSchema(db);
+	return db;
+}
+
+function getSharedDb(): Database {
+	const resolvedPath = getModelDbPath();
+	if (sharedDb && sharedDbPath === resolvedPath) {
+		return sharedDb;
+	}
+	if (sharedDb) {
+		sharedDb.close();
+	}
+	const db = openDb(resolvedPath);
+	sharedDb = db;
+	sharedDbPath = resolvedPath;
+	return db;
+}
+
+function withModelCacheDb<T>(dbPath: string | undefined, useDb: (db: Database) => T): T {
+	if (!dbPath) return useDb(getSharedDb());
+	const db = openDb(dbPath);
+	try {
+		return useDb(db);
+	} finally {
+		db.close();
+	}
+}
+
+function migrateCacheSchema(db: Database): void {
+	const stmt = db.prepare("PRAGMA table_info(model_cache)");
+	try {
+		const columns = stmt.all() as TableInfoRow[];
+		if (!columns.some(column => column.name === "static_fingerprint")) {
+			db.run("ALTER TABLE model_cache ADD COLUMN static_fingerprint TEXT NOT NULL DEFAULT ''");
+		}
+		if (!columns.some(column => column.name === "header_omitted_model_ids")) {
+			db.run("ALTER TABLE model_cache ADD COLUMN header_omitted_model_ids TEXT NOT NULL DEFAULT '[]'");
+		}
+		if (!columns.some(column => column.name === "unrestorable_header_model_ids")) {
+			db.run("ALTER TABLE model_cache ADD COLUMN unrestorable_header_model_ids TEXT NOT NULL DEFAULT '[]'");
+		}
+		if (!columns.some(column => column.name === "header_restore_version")) {
+			// Existing v10 rows get 0, distinguishing markers produced by the
+			// old id-only header matcher from rows written after request-model
+			// header matching was introduced.
+			db.run("ALTER TABLE model_cache ADD COLUMN header_restore_version INTEGER NOT NULL DEFAULT 0");
+		}
+	} finally {
+		stmt.finalize();
+	}
+	// Delete rows written under any older schema so they cannot be reused. The
+	// legacy `UPDATE ... WHERE version = 2` migration silently promoted the very
+	// first cache version to whatever the current one is, defeating every
+	// subsequent invalidation (see #4146: pre-V2 Codex rows kept the legacy
+	// compaction path even after CACHE_SCHEMA_VERSION was bumped).
+	db.run("DELETE FROM model_cache WHERE version <> ?", [CACHE_SCHEMA_VERSION]);
+}
+
+export function readModelCache<TApi extends Api>(
+	providerId: string,
+	ttlMs: number,
+	now: () => number,
+	dbPath?: string,
+): CacheEntry<TApi> | null {
+	try {
+		return withModelCacheDb(dbPath, db => {
+			const stmt = db.query<CacheRow, [string]>("SELECT * FROM model_cache WHERE provider_id = ?");
+			try {
+				const row = stmt.get(providerId);
+				if (!row || row.version !== CACHE_SCHEMA_VERSION) {
+					return null;
+				}
+				const models = JSON.parse(row.models) as ModelSpec<TApi>[];
+				const parsedHeaderModelIds: unknown = JSON.parse(row.header_omitted_model_ids);
+				const headerOmittedModelIds = Array.isArray(parsedHeaderModelIds)
+					? parsedHeaderModelIds.filter((id): id is string => typeof id === "string")
+					: [];
+				const parsedUnrestorableModelIds: unknown = JSON.parse(row.unrestorable_header_model_ids);
+				const unrestorableHeaderModelIds = Array.isArray(parsedUnrestorableModelIds)
+					? parsedUnrestorableModelIds.filter((id): id is string => typeof id === "string")
+					: [];
+				const ageMs = now() - row.updated_at;
+				const fresh = Number.isFinite(ageMs) && ageMs >= 0 && ageMs <= ttlMs;
+				return {
+					models,
+					fresh,
+					authoritative: row.authoritative === 1,
+					updatedAt: row.updated_at,
+					headerOmittedModelIds,
+					unrestorableHeaderModelIds,
+					legacyHeaderRestoreMarkers: row.header_restore_version < HEADER_RESTORE_VERSION,
+					staticFingerprint: row.static_fingerprint ?? "",
+				};
+			} finally {
+				stmt.finalize();
+			}
+		});
+	} catch {
+		return null;
+	}
+}
+
+/** Whether a live model carries at least one request header. */
+function hasModelHeaders(model: Model<Api>): boolean {
+	const headers = model.headers;
+	if (!headers) return false;
+	for (const _key in headers) return true;
+	return false;
+}
+
+/**
+ * Project a live model to cache-safe metadata.
+ *
+ * Headers are never persisted: custom/runtime providers may use arbitrary
+ * credential header names, so no name-based filter can be complete. The
+ * separately persisted model-id list lets the manager restore matching static
+ * headers and reject/refetch dynamic-only cached models that need live headers.
+ */
+function toCachedModelSpec<TApi extends Api>(model: Model<TApi>): ModelSpec<TApi> {
+	const { headers: _headers, compatConfig, supportsComputerUseConfig, ...rest } = model;
+	return { ...rest, supportsComputerUse: supportsComputerUseConfig, compat: compatConfig };
+}
+
+/** Whether two in-memory header records are byte-for-byte equivalent. */
+function headersEqual(left: Record<string, string> | undefined, right: Record<string, string> | undefined): boolean {
+	if (!left || !right) return left === right;
+	for (const key in left) {
+		if (right[key] !== left[key]) return false;
+	}
+	for (const key in right) {
+		if (!(key in left)) return false;
+	}
+	return true;
+}
+
+export function writeModelCache<TApi extends Api>(
+	providerId: string,
+	updatedAt: number,
+	models: Model<TApi>[],
+	authoritative: boolean,
+	staticFingerprint: string,
+	dbPath?: string,
+	staticHeaderSources: readonly Model<TApi>[] = [],
+	restorableHeaderFallback?: Record<string, string>,
+): void {
+	try {
+		withModelCacheDb(dbPath, db => {
+			const headerOmittedModelIds: string[] = [];
+			const unrestorableHeaderModelIds: string[] = [];
+			const cachedModels: ModelSpec<TApi>[] = [];
+			const staticById = new Map(staticHeaderSources.map(model => [model.id, model]));
+			for (const model of models) {
+				if (hasModelHeaders(model)) {
+					headerOmittedModelIds.push(model.id);
+					// Synthesized variants (e.g. Copilot `-1m`) have no same-id static
+					// entry; their headers come from the `requestModelId` base. Match
+					// against that source too, else they are wrongly flagged
+					// unrestorable and dropped on the next offline read (#6037, #6284).
+					const staticHeaderSource =
+						staticById.get(model.id) ?? (model.requestModelId ? staticById.get(model.requestModelId) : undefined);
+					// A model with no static source is still restorable when its live
+					// headers equal the provider's trusted constant (a compile-time,
+					// non-credential value the reader can reattach by value). This keeps
+					// reference-less Copilot models (e.g. claude-opus-5) alive offline.
+					const matchesStatic = staticHeaderSource
+						? headersEqual(model.headers, staticHeaderSource.headers)
+						: headersEqual(model.headers, restorableHeaderFallback);
+					if (!matchesStatic) {
+						unrestorableHeaderModelIds.push(model.id);
+					}
+				}
+				cachedModels.push(toCachedModelSpec(model));
+			}
+			db.run(
+				`INSERT OR REPLACE INTO model_cache (
+					provider_id, version, updated_at, authoritative, static_fingerprint,
+					header_omitted_model_ids, unrestorable_header_model_ids,
+					header_restore_version, models
+				) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+				[
+					providerId,
+					CACHE_SCHEMA_VERSION,
+					updatedAt,
+					authoritative ? 1 : 0,
+					staticFingerprint,
+					JSON.stringify(headerOmittedModelIds),
+					JSON.stringify(unrestorableHeaderModelIds),
+					HEADER_RESTORE_VERSION,
+					JSON.stringify(cachedModels),
+				],
+			);
+		});
+	} catch {
+		// Cache writes are best-effort; failures should not break model resolution.
+	}
+}