pi-model-manager 0.1.0

package/state-metadata-store.ts

@@ -0,0 +1,455 @@
+// state-metadata-store.ts
+//
+// state.json 持久层：负责插件私有元数据的原子读写和 schema 边界校验。
+// 模型定义的唯一权威源是 Pi 原生 models.json；这里仅保存请求头 profile、
+// profile 库、抓包缓存和 OpenAI Responses service_tier 等原生字段无法表达的元数据。
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWriteText } from "./atomic-write.ts";
+import { cloneJson, isObjectRecord, stringifyJson, stripJsonNoise } from "./common.ts";
+import type {
+	ApiKind,
+	BuiltInClientHeaderProfileId,
+	ClientHeaderProfileId,
+	CompatSettings,
+	ModelInputKind,
+	OpenAIServiceTier,
+	StateDocument,
+	StoredClientHeaderCapture,
+	StoredModel,
+	StoredProvider,
+	StoredRequestHeaderProfile,
+	ThinkingLevelMap,
+	TokenCost,
+} from "./types.ts";
+
+const STATE_DIR = join(getAgentDir(), "extensions", "pi-model-manager");
+export const STATE_PATH = join(STATE_DIR, "state.json");
+
+const API_KINDS = new Set<ApiKind>(["openai-completions", "openai-responses", "anthropic-messages", "google-generative-ai"]);
+const CLIENT_HEADER_PROFILE_IDS = new Set<ClientHeaderProfileId>(["recommended", "disabled", "claude-code", "codex-cli", "custom"]);
+const BUILT_IN_CLIENT_HEADER_PROFILE_IDS = new Set<BuiltInClientHeaderProfileId>(["claude-code", "codex-cli"]);
+const RESERVED_REQUEST_HEADER_PROFILE_IDS = new Set(["claude-code", "codex-cli", "claude-code-live", "codex-cli-live"]);
+const INPUT_KINDS = new Set<ModelInputKind>(["text", "image"]);
+const THINKING_LEVELS = new Set(Object.freeze(["off", "minimal", "low", "medium", "high", "xhigh", "max"]));
+const OPENAI_SERVICE_TIERS = new Set<OpenAIServiceTier>(["priority"]);
+
+export interface ProviderMetadata {
+	clientHeaderProfile?: ClientHeaderProfileId;
+	requestHeaderProfileId?: string;
+	customClientHeaders?: Record<string, string>;
+	httpProxyEnabled?: boolean;
+	httpProxyUrl?: string;
+}
+
+export interface ModelMetadata {
+	openAIServiceTier?: OpenAIServiceTier;
+}
+
+export interface MetadataDocument {
+	version: 2;
+	providers: Record<string, ProviderMetadata>;
+	models: Record<string, ModelMetadata>;
+	requestHeaderProfiles: Record<string, StoredRequestHeaderProfile>;
+	clientHeaderCaptures: Partial<Record<BuiltInClientHeaderProfileId, StoredClientHeaderCapture>>;
+}
+
+export interface ParsedMetadataStateFile {
+	metadata: MetadataDocument;
+	legacyProviders: StateDocument["providers"];
+}
+
+export function createEmptyMetadata(): MetadataDocument {
+	return { version: 2, providers: {}, models: {}, requestHeaderProfiles: {}, clientHeaderCaptures: {} };
+}
+
+function isNotFound(error: unknown): boolean {
+	return error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function fail(path: string, message: string): never {
+	throw new Error(`state.json ${path}: ${message}`);
+}
+
+function readRequiredString(record: Record<string, unknown>, key: string, path: string): string {
+	const value = record[key];
+	if (typeof value !== "string" || !value.trim()) fail(`${path}.${key}`, "必须是非空字符串");
+	return value;
+}
+
+function readOptionalString(record: Record<string, unknown>, key: string, path: string): string | undefined {
+	const value = record[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") fail(`${path}.${key}`, "必须是字符串");
+	return value;
+}
+
+function readOptionalBoolean(record: Record<string, unknown>, key: string, path: string): boolean | undefined {
+	const value = record[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "boolean") fail(`${path}.${key}`, "必须是 boolean");
+	return value;
+}
+
+function readPositiveInteger(record: Record<string, unknown>, key: string, path: string): number {
+	const value = record[key];
+	if (!Number.isInteger(value) || (value as number) <= 0) fail(`${path}.${key}`, "必须是正整数");
+	return value as number;
+}
+
+function readStringRecord(value: unknown, path: string): Record<string, string> {
+	if (!isObjectRecord(value)) fail(path, "必须是对象");
+	const record: Record<string, string> = {};
+	for (const [key, entry] of Object.entries(value)) {
+		if (typeof entry !== "string") fail(`${path}.${key}`, "值必须是字符串");
+		record[key] = entry;
+	}
+	return record;
+}
+
+function readOptionalStringRecord(record: Record<string, unknown>, key: string, path: string): Record<string, string> | undefined {
+	const value = record[key];
+	if (value === undefined) return undefined;
+	return readStringRecord(value, `${path}.${key}`);
+}
+
+function readObjectRecord(record: Record<string, unknown>, key: string, path: string): Record<string, unknown> | undefined {
+	const value = record[key];
+	if (value === undefined) return undefined;
+	if (!isObjectRecord(value)) fail(`${path}.${key}`, "必须是对象");
+	return cloneJson(value);
+}
+
+function readApiKind(record: Record<string, unknown>, key: string, path: string): ApiKind {
+	const value = readRequiredString(record, key, path);
+	if (!API_KINDS.has(value as ApiKind)) fail(`${path}.${key}`, `未知 API 协议：${value}`);
+	return value as ApiKind;
+}
+
+function readOptionalClientHeaderProfile(record: Record<string, unknown>, key: string, path: string): ClientHeaderProfileId | undefined {
+	const value = readOptionalString(record, key, path);
+	if (value === undefined) return undefined;
+	if (!CLIENT_HEADER_PROFILE_IDS.has(value as ClientHeaderProfileId)) fail(`${path}.${key}`, `未知请求头：${value}`);
+	return value as ClientHeaderProfileId;
+}
+
+function readOptionalOpenAIServiceTier(record: Record<string, unknown>, key: string, path: string): OpenAIServiceTier | undefined {
+	const value = readOptionalString(record, key, path);
+	if (value === undefined) return undefined;
+	if (!OPENAI_SERVICE_TIERS.has(value as OpenAIServiceTier)) fail(`${path}.${key}`, `未知 OpenAI service tier：${value}`);
+	return value as OpenAIServiceTier;
+}
+
+function readInputKinds(record: Record<string, unknown>, key: string, path: string): ModelInputKind[] {
+	const value = record[key];
+	if (!Array.isArray(value) || value.length === 0) fail(`${path}.${key}`, "必须是非空数组");
+	const kinds = value.map((item, index) => {
+		if (typeof item !== "string" || !INPUT_KINDS.has(item as ModelInputKind)) fail(`${path}.${key}[${index}]`, "必须是 text 或 image");
+		return item as ModelInputKind;
+	});
+	return [...new Set(kinds)];
+}
+
+function readCost(record: Record<string, unknown>, key: string, path: string): TokenCost {
+	const value = record[key];
+	if (!isObjectRecord(value)) fail(`${path}.${key}`, "必须是对象");
+	const cost: Partial<TokenCost> = {};
+	for (const field of ["input", "output", "cacheRead", "cacheWrite"] as const) {
+		const amount = value[field];
+		if (typeof amount !== "number" || !Number.isFinite(amount) || amount < 0) fail(`${path}.${key}.${field}`, "必须是非负数字");
+		cost[field] = amount;
+	}
+	return cost as TokenCost;
+}
+
+function readThinkingLevelMap(record: Record<string, unknown>, key: string, path: string): ThinkingLevelMap | undefined {
+	const value = record[key];
+	if (value === undefined) return undefined;
+	if (!isObjectRecord(value)) fail(`${path}.${key}`, "必须是对象");
+	const map: ThinkingLevelMap = {};
+	for (const [level, mapped] of Object.entries(value)) {
+		if (!THINKING_LEVELS.has(level)) fail(`${path}.${key}.${level}`, "未知 thinking level");
+		if (typeof mapped !== "string" && mapped !== null) fail(`${path}.${key}.${level}`, "必须是字符串或 null");
+		map[level as keyof ThinkingLevelMap] = mapped;
+	}
+	return map;
+}
+
+function readStoredModel(raw: unknown, path: string): StoredModel {
+	if (!isObjectRecord(raw)) fail(path, "必须是对象");
+	const reasoning = raw.reasoning;
+	if (typeof reasoning !== "boolean") fail(`${path}.reasoning`, "必须是 boolean");
+
+	const model: StoredModel = {
+		id: readRequiredString(raw, "id", path),
+		reasoning,
+		input: readInputKinds(raw, "input", path),
+		contextWindow: readPositiveInteger(raw, "contextWindow", path),
+		maxTokens: readPositiveInteger(raw, "maxTokens", path),
+		cost: readCost(raw, "cost", path),
+	};
+
+	const name = readOptionalString(raw, "name", path);
+	if (name !== undefined) model.name = name;
+	const thinkingLevelMap = readThinkingLevelMap(raw, "thinkingLevelMap", path);
+	if (thinkingLevelMap) model.thinkingLevelMap = thinkingLevelMap;
+	const clientHeaderProfile = readOptionalClientHeaderProfile(raw, "clientHeaderProfile", path);
+	if (clientHeaderProfile) model.clientHeaderProfile = clientHeaderProfile;
+	const requestHeaderProfileId = readOptionalString(raw, "requestHeaderProfileId", path);
+	if (requestHeaderProfileId !== undefined) model.requestHeaderProfileId = requestHeaderProfileId;
+	const customClientHeaders = readOptionalStringRecord(raw, "customClientHeaders", path);
+	if (customClientHeaders) model.customClientHeaders = customClientHeaders;
+	const openAIServiceTier = readOptionalOpenAIServiceTier(raw, "openAIServiceTier", path);
+	if (openAIServiceTier) model.openAIServiceTier = openAIServiceTier;
+	const compat = readObjectRecord(raw, "compat", path) as CompatSettings | undefined;
+	if (compat) model.compat = compat;
+	return model;
+}
+
+function readProviderMetadata(raw: unknown, path: string): ProviderMetadata {
+	if (!isObjectRecord(raw)) fail(path, "必须是对象");
+	const metadata: ProviderMetadata = {};
+	const clientHeaderProfile = readOptionalClientHeaderProfile(raw, "clientHeaderProfile", path);
+	if (clientHeaderProfile) metadata.clientHeaderProfile = clientHeaderProfile;
+	const requestHeaderProfileId = readOptionalString(raw, "requestHeaderProfileId", path);
+	if (requestHeaderProfileId !== undefined) metadata.requestHeaderProfileId = requestHeaderProfileId;
+	const customClientHeaders = readOptionalStringRecord(raw, "customClientHeaders", path);
+	if (customClientHeaders) metadata.customClientHeaders = customClientHeaders;
+	const httpProxyEnabled = readOptionalBoolean(raw, "httpProxyEnabled", path);
+	if (httpProxyEnabled !== undefined) metadata.httpProxyEnabled = httpProxyEnabled;
+	const httpProxyUrl = readOptionalString(raw, "httpProxyUrl", path);
+	if (httpProxyUrl !== undefined) metadata.httpProxyUrl = httpProxyUrl;
+	return metadata;
+}
+
+function readModelMetadata(raw: unknown, path: string): ModelMetadata {
+	if (!isObjectRecord(raw)) fail(path, "必须是对象");
+	const metadata: ModelMetadata = {};
+	const openAIServiceTier = readOptionalOpenAIServiceTier(raw, "openAIServiceTier", path);
+	if (openAIServiceTier) metadata.openAIServiceTier = openAIServiceTier;
+	return metadata;
+}
+
+interface HeaderProfileSelection {
+	clientHeaderProfile: ClientHeaderProfileId;
+	requestHeaderProfileId?: string;
+	customClientHeaders?: Record<string, string>;
+}
+
+function inferProviderHeaderProfile(models: StoredModel[]): HeaderProfileSelection {
+	const selections = models
+		.map((model): HeaderProfileSelection | undefined => {
+			const legacy = model as StoredModel & ProviderMetadata;
+			if (!legacy.clientHeaderProfile) return undefined;
+			return {
+				clientHeaderProfile: legacy.clientHeaderProfile,
+				requestHeaderProfileId: legacy.requestHeaderProfileId,
+				customClientHeaders: legacy.customClientHeaders ? cloneJson(legacy.customClientHeaders) : undefined,
+			};
+		})
+		.filter((selection): selection is HeaderProfileSelection => Boolean(selection));
+	return selections.find((selection) =>
+		selection.clientHeaderProfile !== "recommended"
+		|| Boolean(selection.requestHeaderProfileId)
+		|| Boolean(selection.customClientHeaders && Object.keys(selection.customClientHeaders).length > 0)
+	) ?? selections[0] ?? { clientHeaderProfile: "recommended" };
+}
+
+function readStoredProvider(raw: unknown, path: string): StoredProvider {
+	if (!isObjectRecord(raw)) fail(path, "必须是对象");
+	const models = raw.models;
+	if (!Array.isArray(models)) fail(`${path}.models`, "必须是数组");
+	const storedModels = models.map((model, index) => readStoredModel(model, `${path}.models[${index}]`));
+	const inferredProfile = inferProviderHeaderProfile(storedModels);
+	const clientHeaderProfile = readOptionalClientHeaderProfile(raw, "clientHeaderProfile", path) ?? inferredProfile.clientHeaderProfile;
+
+	const provider: StoredProvider = {
+		name: readRequiredString(raw, "name", path),
+		api: readApiKind(raw, "api", path),
+		baseUrl: readRequiredString(raw, "baseUrl", path),
+		clientHeaderProfile,
+		models: storedModels,
+	};
+	const apiKey = readOptionalString(raw, "apiKey", path);
+	if (apiKey) provider.apiKey = apiKey;
+
+	const authHeader = readOptionalBoolean(raw, "authHeader", path);
+	if (authHeader !== undefined) provider.authHeader = authHeader;
+	const requestHeaderProfileId = readOptionalString(raw, "requestHeaderProfileId", path) ?? inferredProfile.requestHeaderProfileId;
+	if (clientHeaderProfile === "custom" && requestHeaderProfileId !== undefined) provider.requestHeaderProfileId = requestHeaderProfileId;
+	const customClientHeaders = readOptionalStringRecord(raw, "customClientHeaders", path) ?? inferredProfile.customClientHeaders;
+	if (clientHeaderProfile === "custom" && customClientHeaders) provider.customClientHeaders = customClientHeaders;
+	const httpProxyEnabled = readOptionalBoolean(raw, "httpProxyEnabled", path);
+	if (httpProxyEnabled !== undefined) provider.httpProxyEnabled = httpProxyEnabled;
+	const httpProxyUrl = readOptionalString(raw, "httpProxyUrl", path);
+	if (httpProxyUrl !== undefined) provider.httpProxyUrl = httpProxyUrl;
+	return provider;
+}
+
+function readRequestHeaderProfile(raw: unknown, path: string): StoredRequestHeaderProfile {
+	if (!isObjectRecord(raw)) fail(path, "必须是对象");
+	return {
+		name: readRequiredString(raw, "name", path),
+		headers: readStringRecord(raw.headers, `${path}.headers`),
+	};
+}
+
+function readClientHeaderCapture(raw: unknown, path: string): StoredClientHeaderCapture {
+	if (!isObjectRecord(raw)) fail(path, "必须是对象");
+	return {
+		capturedAt: readRequiredString(raw, "capturedAt", path),
+		headers: readStringRecord(raw.headers, `${path}.headers`),
+	};
+}
+
+function readCommonMetadataFields(parsed: Record<string, unknown>, base: MetadataDocument): MetadataDocument {
+	const requestHeaderProfiles: MetadataDocument["requestHeaderProfiles"] = {};
+	const rawProfiles = parsed.requestHeaderProfiles;
+	if (rawProfiles !== undefined) {
+		if (!isObjectRecord(rawProfiles)) fail(".requestHeaderProfiles", "必须是对象");
+		for (const [profileId, profile] of Object.entries(rawProfiles)) {
+			if (RESERVED_REQUEST_HEADER_PROFILE_IDS.has(profileId)) {
+				fail(`.requestHeaderProfiles.${profileId}`, "不能使用插件内置请求头保留名");
+			}
+			requestHeaderProfiles[profileId] = readRequestHeaderProfile(profile, `.requestHeaderProfiles.${profileId}`);
+		}
+	}
+
+	const clientHeaderCaptures: MetadataDocument["clientHeaderCaptures"] = {};
+	const rawCaptures = parsed.clientHeaderCaptures;
+	if (rawCaptures !== undefined) {
+		if (!isObjectRecord(rawCaptures)) fail(".clientHeaderCaptures", "必须是对象");
+		for (const [profileId, capture] of Object.entries(rawCaptures)) {
+			if (!BUILT_IN_CLIENT_HEADER_PROFILE_IDS.has(profileId as BuiltInClientHeaderProfileId)) {
+				fail(`.clientHeaderCaptures.${profileId}`, "只能保存 ClaudeCode/Codex 内置 profile 的抓包数据");
+			}
+			clientHeaderCaptures[profileId as BuiltInClientHeaderProfileId] = readClientHeaderCapture(
+				capture,
+				`.clientHeaderCaptures.${profileId}`,
+			);
+		}
+	}
+
+	return {
+		...base,
+		requestHeaderProfiles,
+		clientHeaderCaptures,
+	};
+}
+
+function getFullModelId(providerId: string, modelId: string): string {
+	return `${providerId}/${modelId}`;
+}
+
+function extractProviderMetadata(provider: StoredProvider): ProviderMetadata {
+	const metadata: ProviderMetadata = {};
+	if (provider.clientHeaderProfile !== "recommended") metadata.clientHeaderProfile = provider.clientHeaderProfile;
+	if (provider.clientHeaderProfile === "custom" && provider.requestHeaderProfileId) {
+		metadata.clientHeaderProfile = "custom";
+		metadata.requestHeaderProfileId = provider.requestHeaderProfileId;
+	}
+	if (provider.clientHeaderProfile === "custom" && provider.customClientHeaders && Object.keys(provider.customClientHeaders).length > 0) {
+		metadata.clientHeaderProfile = "custom";
+		metadata.customClientHeaders = cloneJson(provider.customClientHeaders);
+	}
+	if (provider.httpProxyEnabled) metadata.httpProxyEnabled = true;
+	const httpProxyUrl = provider.httpProxyUrl?.trim();
+	if (httpProxyUrl) metadata.httpProxyUrl = httpProxyUrl;
+	return metadata;
+}
+
+function extractModelMetadata(model: StoredModel): ModelMetadata {
+	const metadata: ModelMetadata = {};
+	if (model.openAIServiceTier) metadata.openAIServiceTier = model.openAIServiceTier;
+	return metadata;
+}
+
+function extractMetadataFromLegacyState(legacy: StateDocument): MetadataDocument {
+	const metadata = createEmptyMetadata();
+	metadata.requestHeaderProfiles = cloneJson(legacy.requestHeaderProfiles);
+	metadata.clientHeaderCaptures = cloneJson(legacy.clientHeaderCaptures);
+	for (const [providerId, provider] of Object.entries(legacy.providers)) {
+		metadata.providers[providerId] = extractProviderMetadata(provider);
+		for (const model of provider.models) {
+			const modelMetadata = extractModelMetadata(model);
+			if (Object.keys(modelMetadata).length > 0) metadata.models[getFullModelId(providerId, model.id)] = modelMetadata;
+		}
+	}
+	return metadata;
+}
+
+function parseLegacyState(parsed: Record<string, unknown>): ParsedMetadataStateFile {
+	const providers: StateDocument["providers"] = {};
+	const rawProviders = parsed.providers;
+	if (rawProviders !== undefined) {
+		if (!isObjectRecord(rawProviders)) fail(".providers", "必须是对象");
+		for (const [providerId, provider] of Object.entries(rawProviders)) {
+			providers[providerId] = readStoredProvider(provider, `.providers.${providerId}`);
+		}
+	}
+	const common = readCommonMetadataFields(parsed, createEmptyMetadata());
+	const legacy = { version: 1, providers, requestHeaderProfiles: common.requestHeaderProfiles, clientHeaderCaptures: common.clientHeaderCaptures } satisfies StateDocument;
+	return { metadata: extractMetadataFromLegacyState(legacy), legacyProviders: providers };
+}
+
+function parseMetadataState(parsed: Record<string, unknown>): ParsedMetadataStateFile {
+	const metadata = readCommonMetadataFields(parsed, createEmptyMetadata());
+	const rawProviders = parsed.providers;
+	if (rawProviders !== undefined) {
+		if (!isObjectRecord(rawProviders)) fail(".providers", "必须是对象");
+		for (const [providerId, provider] of Object.entries(rawProviders)) {
+			metadata.providers[providerId] = readProviderMetadata(provider, `.providers.${providerId}`);
+		}
+	}
+	const rawModels = parsed.models;
+	if (rawModels !== undefined) {
+		if (!isObjectRecord(rawModels)) fail(".models", "必须是对象");
+		for (const [fullModelId, model] of Object.entries(rawModels)) {
+			metadata.models[fullModelId] = readModelMetadata(model, `.models.${fullModelId}`);
+		}
+	}
+	return { metadata, legacyProviders: {} };
+}
+
+function parseStateFile(source: string): ParsedMetadataStateFile {
+	const parsed = JSON.parse(stripJsonNoise(source));
+	if (!isObjectRecord(parsed)) fail("", "根节点必须是对象");
+	if (parsed.version === 2) return parseMetadataState(parsed);
+	if (parsed.version === undefined || parsed.version === 1) return parseLegacyState(parsed);
+	fail(".version", `不支持的版本：${String(parsed.version)}`);
+}
+
+export async function readMetadataStateFile(): Promise<ParsedMetadataStateFile> {
+	try {
+		const source = await readFile(STATE_PATH, "utf8");
+		return parseStateFile(source);
+	} catch (error) {
+		if (isNotFound(error)) return { metadata: createEmptyMetadata(), legacyProviders: {} };
+		throw error;
+	}
+}
+
+function extractMetadata(state: StateDocument): MetadataDocument {
+	const metadata = createEmptyMetadata();
+	metadata.requestHeaderProfiles = cloneJson(state.requestHeaderProfiles);
+	metadata.clientHeaderCaptures = cloneJson(state.clientHeaderCaptures);
+	for (const [providerId, provider] of Object.entries(state.providers)) {
+		const providerMetadata = extractProviderMetadata(provider);
+		if (Object.keys(providerMetadata).length > 0) metadata.providers[providerId] = providerMetadata;
+		for (const model of provider.models) {
+			const modelMetadata = extractModelMetadata(model);
+			if (Object.keys(modelMetadata).length > 0) metadata.models[getFullModelId(providerId, model.id)] = modelMetadata;
+		}
+	}
+	return metadata;
+}
+
+export async function writeMetadataState(state: StateDocument): Promise<void> {
+	await atomicWriteText(STATE_PATH, stringifyJson(extractMetadata(state)));
+}
+
+export function getStatePath(): string {
+	return STATE_PATH;
+}

package/state-store.ts

@@ -0,0 +1,238 @@
+// state-store.ts
+//
+// StateDocument 合成层：从 Pi 原生 models.json 读取模型定义，再叠加
+// state.json 中的插件私有元数据，提供 TUI 与运行时注册使用的统一视图。
+
+import { getBuiltinProviderDefaults } from "./builtin-model-catalog.ts";
+import { mergeCompatSettings } from "./compat-settings.ts";
+import { cloneJson, hasStringRecordEntries, isObjectRecord } from "./common.ts";
+import { readModelsJson, type ModelsJsonDocument, type ModelsJsonModelEntry, type ModelsJsonProviderEntry } from "./models-json-manager.ts";
+import {
+	getClientHeadersForProfile,
+	stripManagedClientHeaders,
+} from "./presets/client-headers.ts";
+import { normalizeThinkingLevelMap } from "./presets/thinking.ts";
+import {
+	getStatePath as getMetadataStatePath,
+	readMetadataStateFile,
+	writeMetadataState,
+	type MetadataDocument,
+} from "./state-metadata-store.ts";
+import type {
+	ApiKind,
+	CompatSettings,
+	ModelInputKind,
+	StateDocument,
+	StoredModel,
+	StoredProvider,
+	ThinkingLevelMap,
+	TokenCost,
+	TokenCostTier,
+} from "./types.ts";
+import { ZERO_COST } from "./types.ts";
+
+export { STATE_PATH } from "./state-metadata-store.ts";
+
+const API_KINDS = new Set<ApiKind>(["openai-completions", "openai-responses", "anthropic-messages", "google-generative-ai"]);
+const INPUT_KINDS = new Set<ModelInputKind>(["text", "image"]);
+
+function createEmptyStateDocument(): StateDocument {
+	return { version: 1, providers: {}, requestHeaderProfiles: {}, clientHeaderCaptures: {} };
+}
+
+function asApiKind(value: unknown): ApiKind | undefined {
+	return typeof value === "string" && API_KINDS.has(value as ApiKind) ? value as ApiKind : undefined;
+}
+
+function getFullModelId(providerId: string, modelId: string): string {
+	return `${providerId}/${modelId}`;
+}
+
+function readNonNegativeNumber(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+function readCostTier(value: unknown): TokenCostTier | undefined {
+	if (!isObjectRecord(value)) return undefined;
+	const inputTokensAbove = value.inputTokensAbove;
+	if (typeof inputTokensAbove !== "number" || !Number.isFinite(inputTokensAbove) || inputTokensAbove < 0) return undefined;
+	return {
+		inputTokensAbove,
+		input: readNonNegativeNumber(value.input),
+		output: readNonNegativeNumber(value.output),
+		cacheRead: readNonNegativeNumber(value.cacheRead),
+		cacheWrite: readNonNegativeNumber(value.cacheWrite),
+	};
+}
+
+function readModelCost(model: ModelsJsonModelEntry): TokenCost {
+	const cost = model.cost;
+	if (!cost) return { ...ZERO_COST };
+	const stored: TokenCost = {
+		input: readNonNegativeNumber(cost.input),
+		output: readNonNegativeNumber(cost.output),
+		cacheRead: readNonNegativeNumber(cost.cacheRead),
+		cacheWrite: readNonNegativeNumber(cost.cacheWrite),
+	};
+	const tiers = cost.tiers?.map(readCostTier).filter((tier): tier is TokenCostTier => Boolean(tier));
+	if (tiers && tiers.length > 0) stored.tiers = tiers;
+	return stored;
+}
+
+function readModelInput(model: ModelsJsonModelEntry): ModelInputKind[] {
+	const input = model.input?.filter((item): item is ModelInputKind => INPUT_KINDS.has(item as ModelInputKind));
+	return input && input.length > 0 ? [...new Set(input)] : ["text"];
+}
+
+function resolveProviderCustomHeaders(
+	providerMetadata: MetadataDocument["providers"][string] | undefined,
+	metadata: MetadataDocument,
+): Record<string, string> {
+	const profileId = providerMetadata?.requestHeaderProfileId;
+	if (profileId && metadata.requestHeaderProfiles[profileId]) return metadata.requestHeaderProfiles[profileId].headers;
+	return providerMetadata?.customClientHeaders ?? {};
+}
+
+function buildStoredModelFromModelsJson(
+	providerId: string,
+	providerApi: ApiKind,
+	providerBaseUrl: string,
+	providerCompat: CompatSettings | undefined,
+	clientHeaderProfile: StoredProvider["clientHeaderProfile"],
+	customClientHeaders: Record<string, string>,
+	model: ModelsJsonModelEntry,
+	metadata: MetadataDocument,
+): StoredModel | undefined {
+	if (!model.id || typeof model.id !== "string") return undefined;
+	const explicitApi = typeof model.api === "string" && model.api ? model.api : undefined;
+	const effectiveApi = asApiKind(explicitApi) ?? providerApi;
+	const modelCompat = model.compat ? cloneJson(model.compat) : undefined;
+	const effectiveCompat = mergeCompatSettings(providerCompat, modelCompat);
+	const profileHeaders = getClientHeadersForProfile(
+		clientHeaderProfile,
+		effectiveApi,
+		customClientHeaders,
+		metadata.clientHeaderCaptures,
+		effectiveCompat,
+	);
+	const nativeHeaders = stripManagedClientHeaders(model.headers, profileHeaders);
+	const stored: StoredModel = {
+		id: model.id,
+		reasoning: model.reasoning ?? false,
+		input: readModelInput(model),
+		contextWindow: model.contextWindow && model.contextWindow > 0 ? model.contextWindow : 128000,
+		maxTokens: model.maxTokens && model.maxTokens > 0 ? model.maxTokens : 16384,
+		cost: readModelCost(model),
+	};
+	if (explicitApi && explicitApi !== providerApi) stored.api = explicitApi;
+	if (model.baseUrl && model.baseUrl !== providerBaseUrl) stored.baseUrl = model.baseUrl;
+	if (nativeHeaders) stored.headers = nativeHeaders;
+	if (model.name) stored.name = model.name;
+	const storedThinkingLevelMap = model.thinkingLevelMap ? cloneJson(model.thinkingLevelMap) as ThinkingLevelMap : undefined;
+	const thinkingLevelMap = normalizeThinkingLevelMap(effectiveApi, stored.reasoning, storedThinkingLevelMap);
+	if (thinkingLevelMap) stored.thinkingLevelMap = thinkingLevelMap;
+	if (modelCompat) stored.compat = modelCompat;
+	const modelMetadata = metadata.models[getFullModelId(providerId, model.id)];
+	if (effectiveApi === "openai-responses" && modelMetadata?.openAIServiceTier) {
+		stored.openAIServiceTier = modelMetadata.openAIServiceTier;
+	}
+	return stored;
+}
+
+async function buildStoredProviderFromModelsJson(
+	providerId: string,
+	entry: ModelsJsonProviderEntry,
+	metadata: MetadataDocument,
+): Promise<StoredProvider | undefined> {
+	const rawModels = entry.models ?? [];
+	if (rawModels.length === 0) return undefined;
+
+	const firstModel = rawModels[0];
+	const builtInDefaults = await getBuiltinProviderDefaults(providerId);
+	const api = asApiKind(entry.api) ?? asApiKind(firstModel?.api) ?? asApiKind(builtInDefaults?.api);
+	const baseUrl = entry.baseUrl ?? firstModel?.baseUrl ?? builtInDefaults?.baseUrl;
+	if (!api || !baseUrl) return undefined;
+
+	const providerMetadata = metadata.providers[providerId];
+	const clientHeaderProfile = providerMetadata?.clientHeaderProfile ?? "recommended";
+	const customClientHeaders = clientHeaderProfile === "custom"
+		? resolveProviderCustomHeaders(providerMetadata, metadata)
+		: {};
+	const providerCompat = entry.compat ? cloneJson(entry.compat) : undefined;
+	const models = rawModels
+		.map((model) => buildStoredModelFromModelsJson(
+			providerId,
+			api,
+			baseUrl,
+			providerCompat,
+			clientHeaderProfile,
+			customClientHeaders,
+			model,
+			metadata,
+		))
+		.filter((model): model is StoredModel => Boolean(model));
+	if (models.length === 0) return undefined;
+
+	const provider: StoredProvider = {
+		name: entry.name || providerId,
+		api,
+		baseUrl,
+		clientHeaderProfile,
+		models,
+	};
+	if (entry.apiKey) provider.apiKey = entry.apiKey;
+	if (entry.authHeader !== undefined) provider.authHeader = entry.authHeader;
+	if (entry.headers !== undefined) provider.headers = cloneJson(entry.headers);
+	if (providerCompat) provider.compat = providerCompat;
+	if (entry.modelOverrides !== undefined) provider.modelOverrides = cloneJson(entry.modelOverrides);
+	if (provider.clientHeaderProfile === "custom" && providerMetadata?.requestHeaderProfileId) {
+		provider.requestHeaderProfileId = providerMetadata.requestHeaderProfileId;
+	}
+	if (provider.clientHeaderProfile === "custom" && hasStringRecordEntries(providerMetadata?.customClientHeaders)) {
+		provider.customClientHeaders = cloneJson(providerMetadata!.customClientHeaders!);
+	}
+	if (providerMetadata?.httpProxyEnabled !== undefined) provider.httpProxyEnabled = providerMetadata.httpProxyEnabled;
+	if (providerMetadata?.httpProxyUrl !== undefined) provider.httpProxyUrl = providerMetadata.httpProxyUrl;
+	return provider;
+}
+
+export async function buildStateDocumentFromModelsJson(
+	document: ModelsJsonDocument,
+	metadata: MetadataDocument,
+): Promise<StateDocument> {
+	const providers: StateDocument["providers"] = {};
+	for (const [providerId, entry] of Object.entries(document.providers)) {
+		const provider = await buildStoredProviderFromModelsJson(providerId, entry, metadata);
+		if (provider) providers[providerId] = provider;
+	}
+	return {
+		version: 1,
+		providers,
+		requestHeaderProfiles: metadata.requestHeaderProfiles,
+		clientHeaderCaptures: metadata.clientHeaderCaptures,
+	};
+}
+
+export async function readState(): Promise<StateDocument> {
+	const { metadata, legacyProviders } = await readMetadataStateFile();
+	const state = await buildStateDocumentFromModelsJson(
+		await readModelsJson(),
+		metadata,
+	);
+	for (const [providerId, provider] of Object.entries(legacyProviders)) {
+		if (!state.providers[providerId]) state.providers[providerId] = provider;
+	}
+	return state;
+}
+
+export async function writeState(state: StateDocument): Promise<void> {
+	await writeMetadataState(state);
+}
+
+export function getStatePath(): string {
+	return getMetadataStatePath();
+}
+
+export function createEmptyState(): StateDocument {
+	return createEmptyStateDocument();
+}