@hyav/pi-provider 0.1.0-oidc-bootstrap.0

package/core/retry-after.ts

@@ -0,0 +1,24 @@
+export const MAX_RETRY_AFTER_MS = 24 * 60 * 60 * 1_000;
+
+function cappedRetryAt(now: number, delayMs: number): number | undefined {
+	const retryAt = now + Math.min(delayMs, MAX_RETRY_AFTER_MS);
+	return Number.isFinite(retryAt) ? retryAt : undefined;
+}
+
+export function parseRetryAfter(value: string | null, now: number): number | undefined {
+	if (value === null || !Number.isFinite(now)) return undefined;
+	const trimmed = value.trim();
+	if (trimmed === "") return undefined;
+
+	if (/^\d+(?:\.\d+)?$/.test(trimmed)) {
+		const seconds = Number(trimmed);
+		if (!Number.isFinite(seconds)) return cappedRetryAt(now, MAX_RETRY_AFTER_MS);
+		return cappedRetryAt(now, seconds * 1_000);
+	}
+	if (/^[+-]?\d+(?:\.\d+)?$/.test(trimmed)) return undefined;
+
+	const timestamp = Date.parse(trimmed);
+	if (!Number.isFinite(timestamp)) return undefined;
+	const maxRetryAt = cappedRetryAt(now, MAX_RETRY_AFTER_MS);
+	return maxRetryAt === undefined ? undefined : Math.min(Math.max(now, timestamp), maxRetryAt);
+}

package/core/runtime-config.ts

@@ -0,0 +1,95 @@
+import { isValidTimeoutMs } from "./deadline.ts";
+import type { ProviderKitDefinition } from "./definition.ts";
+import { getDefaultOpenRouterMetadataCachePath, OPENROUTER_MODELS_URL } from "./official-pricing.ts";
+import { validatePricingPolicy } from "./pricing-adjustments.ts";
+import type { ProviderPricingPolicy } from "./types.ts";
+
+export interface ProviderKitDependencies {
+	fetch: typeof globalThis.fetch;
+	now: () => number;
+	modelDiscoveryTimeoutMs: number;
+	statusRequestTimeoutMs: number;
+	liveCheckRequestTimeoutMs: number;
+	officialPricingUrl: string;
+	officialPricingTimeoutMs: number;
+	officialPricingCacheTtlMs: number;
+	officialPricingMaxStaleMs: number;
+	/** Persistent cache for OpenRouter metadata used by the pricing fallback. */
+	openRouterMetadataCachePath: string;
+	enableOfficialPricingFallback: boolean;
+	/** Optional Provider Kit-level price policies keyed by Provider ID. */
+	pricingPolicies?: Record<string, ProviderPricingPolicy>;
+}
+
+export type ProviderKitLoader = (runtime: ProviderKitDependencies) => Promise<ProviderKitDefinition>;
+
+const defaultDependencies: ProviderKitDependencies = {
+	fetch: globalThis.fetch,
+	now: Date.now,
+	modelDiscoveryTimeoutMs: 3_000,
+	statusRequestTimeoutMs: 8_000,
+	liveCheckRequestTimeoutMs: 8_000,
+	officialPricingUrl: OPENROUTER_MODELS_URL,
+	officialPricingTimeoutMs: 3_000,
+	officialPricingCacheTtlMs: 60 * 60 * 1_000,
+	officialPricingMaxStaleMs: 24 * 60 * 60 * 1_000,
+	openRouterMetadataCachePath: getDefaultOpenRouterMetadataCachePath(),
+	enableOfficialPricingFallback: true,
+	pricingPolicies: {},
+};
+
+export function getDefaultProviderKitDependencies(): ProviderKitDependencies {
+	return { ...defaultDependencies };
+}
+
+export function validateProviderKitDependencies(runtime: ProviderKitDependencies): void {
+	if (typeof runtime.fetch !== "function") throw new Error("Provider Kit fetch must be a function");
+	if (typeof runtime.now !== "function") throw new Error("Provider Kit now must be a function");
+	for (const [name, value] of [
+		["modelDiscoveryTimeoutMs", runtime.modelDiscoveryTimeoutMs],
+		["statusRequestTimeoutMs", runtime.statusRequestTimeoutMs],
+		["liveCheckRequestTimeoutMs", runtime.liveCheckRequestTimeoutMs],
+		["officialPricingTimeoutMs", runtime.officialPricingTimeoutMs],
+	] as const) {
+		if (!isValidTimeoutMs(value)) throw new Error(`Provider Kit ${name} must be a valid timeout`);
+	}
+	for (const [name, value] of [
+		["officialPricingCacheTtlMs", runtime.officialPricingCacheTtlMs],
+		["officialPricingMaxStaleMs", runtime.officialPricingMaxStaleMs],
+	] as const) {
+		if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+			throw new Error(`Provider Kit ${name} must be a finite non-negative number`);
+		}
+	}
+	if (typeof runtime.officialPricingUrl !== "string" || runtime.officialPricingUrl.trim() === "") {
+		throw new Error("Provider Kit officialPricingUrl must be a non-empty string");
+	}
+	if (typeof runtime.openRouterMetadataCachePath !== "string" || runtime.openRouterMetadataCachePath.trim() === "") {
+		throw new Error("Provider Kit openRouterMetadataCachePath must be a non-empty path");
+	}
+	if (typeof runtime.enableOfficialPricingFallback !== "boolean") {
+		throw new Error("Provider Kit enableOfficialPricingFallback must be a boolean");
+	}
+	if (runtime.pricingPolicies !== undefined) {
+		if (
+			runtime.pricingPolicies === null ||
+			typeof runtime.pricingPolicies !== "object" ||
+			Array.isArray(runtime.pricingPolicies)
+		) {
+			throw new Error("Provider Kit pricingPolicies must be an object");
+		}
+		for (const [providerId, policy] of Object.entries(runtime.pricingPolicies)) {
+			if (providerId.trim() === "") throw new Error("Provider Kit pricingPolicies has an empty Provider ID");
+			validatePricingPolicy(policy, `Provider Kit pricingPolicies.${providerId}`);
+		}
+	}
+}
+
+export function resolveProviderKitDependencies(
+	dependencies: Partial<ProviderKitDependencies> = {},
+): ProviderKitDependencies {
+	const runtime = { ...defaultDependencies, ...dependencies };
+	if (runtime.pricingPolicies === undefined) runtime.pricingPolicies = {};
+	validateProviderKitDependencies(runtime);
+	return runtime;
+}

package/core/runtime.ts

@@ -0,0 +1,473 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { readStoredCredential } from "@earendil-works/pi-coding-agent";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import type { ProviderKitDefinition } from "./definition.ts";
+import { validateProviderKitDefinition } from "./definition.ts";
+import { LiveCheckManager, type LiveCheckResult } from "./live-check-manager.ts";
+import {
+	fetchOfficialPricing,
+	findOfficialMeta,
+	getPricingCacheAge,
+	type OfficialModelMeta,
+	OPENROUTER_MODELS_URL,
+} from "./official-pricing.ts";
+import type { PreflightContextLike } from "./preflight-manager.ts";
+import { PreflightManager } from "./preflight-manager.ts";
+import { refreshProviderRegistrations, registerProviderAdapter } from "./provider-registration.ts";
+import type { ProviderKitDependencies, ProviderKitLoader } from "./runtime-config.ts";
+import { resolveProviderKitDependencies } from "./runtime-config.ts";
+import type { StatusContextLike } from "./status-manager.ts";
+import { StatusManager } from "./status-manager.ts";
+import {
+	formatProviderStatus,
+	getStatusModeCompletions,
+	type NativeProviderRegistry,
+	nativeModelMatches,
+	parseStatusMode,
+	resolveNativeProvider,
+} from "./status-report.ts";
+import { applyTunerAdapters, sortTunerAdapters } from "./tuner-manager.ts";
+import type {
+	ModelMetadataStatus,
+	ProviderAdapter,
+	ProviderCost,
+	ProviderModelDraft,
+	ProviderModelMetadata,
+} from "./types.ts";
+
+type ActiveModel = NonNullable<ExtensionContext["model"]>;
+type StatusNotificationContext = Pick<ExtensionContext, "modelRegistry" | "ui"> & {
+	mode?: ExtensionContext["mode"];
+};
+const STATUS_WIDGET_KEY = "provider-kit-status";
+
+function readProviderCredentialMetadata(provider: string): unknown {
+	try {
+		const credential = readStoredCredential(provider);
+		if (credential?.type !== "oauth") return undefined;
+		return {
+			type: "oauth",
+			...(typeof credential.teamName === "string" ? { teamName: credential.teamName } : {}),
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function clearTransientStatus(ctx: Pick<ExtensionContext, "ui">): void {
+	if (typeof ctx.ui.setWidget !== "function") return;
+	ctx.ui.setWidget(STATUS_WIDGET_KEY, undefined);
+}
+
+function showTransientStatus(message: string, ctx: StatusNotificationContext): boolean {
+	if ((ctx.mode !== "tui" && ctx.mode !== "rpc") || typeof ctx.ui.setWidget !== "function") return false;
+	// RPC cannot render component factories, so keep its plain text protocol unchanged.
+	if (ctx.mode === "rpc") {
+		ctx.ui.setWidget(STATUS_WIDGET_KEY, [message], { placement: "aboveEditor" });
+		return true;
+	}
+	// Use the active Pi theme's dim status text instead of the terminal's foreground.
+	// Keep the report in one component so Pi's widget line cap does not truncate it.
+	const widgetMessage = `${message}\n`;
+	ctx.ui.setWidget(
+		STATUS_WIDGET_KEY,
+		(_tui, theme) => ({
+			render(width: number): string[] {
+				if (width <= 0) return [];
+				const padding = width > 2 ? " " : "";
+				const contentWidth = Math.max(1, width - padding.length * 2);
+				return widgetMessage.split("\n").flatMap((line) => {
+					if (line === "") return [""];
+					return wrapTextWithAnsi(theme.fg("dim", line), contentWidth).map(
+						(chunk) => `${padding}${chunk}${padding}`,
+					);
+				});
+			},
+			invalidate() {},
+		}),
+		{ placement: "aboveEditor" },
+	);
+	return true;
+}
+
+function compareAdapterIds(left: { id: string }, right: { id: string }): number {
+	return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+}
+
+export function scheduleModelCatalogRefresh(ctx: Pick<ExtensionContext, "modelRegistry">, reason: string): void {
+	if (reason !== "startup" && reason !== "reload") return;
+	const refresh = ctx.modelRegistry?.refresh;
+	if (typeof refresh !== "function") return;
+	void Promise.resolve()
+		.then(() => refresh.call(ctx.modelRegistry))
+		.catch(() => undefined);
+}
+
+export interface ProviderKitRuntimeController {
+	resetForSession(): void;
+	updateOfficialPricing?(snapshot: Record<string, OfficialModelMeta>): void;
+	shutdown(): void;
+	clearStatusPresentation(ctx: Pick<ExtensionContext, "ui">): void;
+	applyTunerPayload(payload: unknown, model: ActiveModel): unknown | undefined | Promise<unknown | undefined>;
+	handleModelSelect(model: ActiveModel, ctx: Pick<ExtensionContext, "modelRegistry" | "ui">): void;
+	handleStatusCommand(args: string, ctx: ExtensionContext): Promise<void>;
+}
+
+function createNativeProviderRegistry(modelRegistry: ExtensionContext["modelRegistry"]): NativeProviderRegistry {
+	return modelRegistry as unknown as NativeProviderRegistry;
+}
+
+function cloneProviderCost(cost: ProviderCost): ProviderCost {
+	return {
+		...cost,
+		...(cost.tiers ? { tiers: cost.tiers.map((tier) => ({ ...tier })) } : {}),
+	};
+}
+
+function getOfficialMetadataStatus(
+	snapshot: Record<string, OfficialModelMeta>,
+	runtime: ProviderKitDependencies,
+): ModelMetadataStatus | undefined {
+	const source = runtime.officialPricingUrl === OPENROUTER_MODELS_URL ? "AA/OpenRouter" : "Official metadata";
+	if (!runtime.enableOfficialPricingFallback && Object.keys(snapshot).length === 0) return undefined;
+	if (Object.keys(snapshot).length === 0) return { state: "unavailable", source };
+	const now = runtime.now();
+	const age = getPricingCacheAge(runtime.officialPricingUrl, now);
+	const updatedAt = age === undefined ? now : now - age;
+	return {
+		state: age !== undefined && age >= runtime.officialPricingCacheTtlMs ? "stale" : "fresh",
+		updatedAt,
+		source,
+	};
+}
+
+function hasKnownNativeCost(cost: ProviderCost | undefined): cost is ProviderCost {
+	if (!cost) return false;
+	return (
+		[cost.input, cost.output, cost.cacheRead, cost.cacheWrite].some((rate) => Number.isFinite(rate) && rate > 0) ||
+		(cost.tiers?.some((tier) =>
+			[tier.input, tier.output, tier.cacheRead, tier.cacheWrite].some((rate) => Number.isFinite(rate) && rate > 0),
+		) ??
+			false)
+	);
+}
+
+/** Build report-only metadata; never merge external fields into Pi's native model. */
+function getNativeModelMetadata(
+	model: ActiveModel,
+	officialPricing: Record<string, OfficialModelMeta>,
+): ProviderModelMetadata {
+	const officialMeta =
+		findOfficialMeta(`${model.provider}/${model.id}`, officialPricing) ?? findOfficialMeta(model.id, officialPricing);
+	const knownPrice = hasKnownNativeCost(model.cost);
+	return {
+		pricing: {
+			known: knownPrice,
+			source: "native",
+			...(knownPrice
+				? { baseCost: cloneProviderCost(model.cost), effectiveCost: cloneProviderCost(model.cost) }
+				: {}),
+		},
+		fieldSources: {
+			contextWindow: "native",
+			maxTokens: "native",
+			input: "native",
+			reasoning: "native",
+		},
+		...(officialMeta?.quality
+			? {
+					quality: officialMeta.quality.map((score) => ({
+						...score,
+						...(score.confidenceInterval ? { confidenceInterval: { ...score.confidenceInterval } } : {}),
+					})),
+				}
+			: {}),
+	};
+}
+
+export function installProviderKitRuntime(
+	pi: ExtensionAPI,
+	runtime: ProviderKitDependencies,
+	definition: ProviderKitDefinition,
+	officialPricing: Record<string, OfficialModelMeta> = {},
+	options: {
+		registerHandlers?: boolean;
+		providerDrafts?: ReadonlyMap<ProviderAdapter, ProviderModelDraft[]>;
+	} = {},
+): ProviderKitRuntimeController {
+	validateProviderKitDefinition(definition);
+	const registerHandlers = options.registerHandlers ?? true;
+	let currentOfficialPricing = officialPricing;
+	let currentOfficialMetadataStatus = getOfficialMetadataStatus(officialPricing, runtime);
+	const providers = [...definition.providers].sort(compareAdapterIds);
+	const statuses = [...(definition.statuses ?? [])].sort(compareAdapterIds);
+	const preflights = [...(definition.preflights ?? [])].sort(compareAdapterIds);
+	const tuners = sortTunerAdapters(definition.tuners ?? []);
+
+	for (const adapter of providers) {
+		registerProviderAdapter(pi, adapter, runtime, officialPricing, options.providerDrafts?.get(adapter));
+	}
+
+	const statusManager = new StatusManager(statuses, runtime.fetch, runtime.now);
+	const preflightManager = new PreflightManager(preflights, runtime.fetch, runtime.now);
+	const liveCheckManager = new LiveCheckManager(runtime.liveCheckRequestTimeoutMs, runtime.fetch, runtime.now);
+	let lifecycleGeneration = 0;
+	let statusPresentationGeneration = 0;
+	let statusPresentationVisible = false;
+	const clearStatusPresentation = (ctx: Pick<ExtensionContext, "ui">): void => {
+		statusPresentationGeneration++;
+		if (!statusPresentationVisible) return;
+		statusPresentationVisible = false;
+		clearTransientStatus(ctx);
+	};
+
+	const getStatusDetails = (model: ActiveModel, ctx: Pick<ExtensionContext, "modelRegistry">) => {
+		const provider = providers.find(({ id }) => id === model.provider);
+		const native = resolveNativeProvider(createNativeProviderRegistry(ctx.modelRegistry), model.provider);
+		return {
+			provider,
+			metadataStatus: currentOfficialMetadataStatus,
+			modelMetadata:
+				provider?.registration?.modelMetadata?.[model.id] ??
+				(provider === undefined ? getNativeModelMetadata(model, currentOfficialPricing) : undefined),
+			status: statuses.find(({ providerId }) => providerId === model.provider),
+			preflight: preflights.find(({ providerId }) => providerId === model.provider),
+			nativeProvider: native.provider,
+			nativeLookupAvailable: native.available,
+			nativePreflight:
+				provider === undefined && native.available
+					? {
+							providerAvailable: native.provider !== undefined,
+							modelMatched: nativeModelMatches(native.provider, model.id),
+						}
+					: undefined,
+			auth: ctx.modelRegistry.getProviderAuthStatus(model.provider),
+		};
+	};
+
+	const notifyProviderStatus = (
+		model: ActiveModel,
+		ctx: StatusNotificationContext,
+		generation: number,
+		options: {
+			presentationGeneration?: number;
+			liveCheckRequested?: boolean;
+			showLiveCheckScope?: boolean;
+		} = {},
+	): void => {
+		if (
+			generation !== lifecycleGeneration ||
+			(options.presentationGeneration !== undefined &&
+				options.presentationGeneration !== statusPresentationGeneration)
+		)
+			return;
+		const {
+			provider,
+			modelMetadata,
+			status,
+			preflight,
+			nativeProvider,
+			nativeLookupAvailable,
+			nativePreflight,
+			auth,
+			metadataStatus,
+		} = getStatusDetails(model, ctx);
+		const diagnostics = status ? statusManager.getDiagnostics(model.provider) : undefined;
+		const preflightDiagnostics = preflightManager.getDiagnostics(model.provider, model.id);
+		const liveCheckDiagnostics = liveCheckManager.getDiagnostics(model.provider, model.id);
+		const report = formatProviderStatus(
+			model,
+			provider,
+			status,
+			preflight,
+			nativePreflight,
+			auth,
+			diagnostics,
+			preflightDiagnostics,
+			liveCheckDiagnostics,
+			nativeProvider,
+			nativeLookupAvailable,
+			runtime.now(),
+			{
+				liveCheckRequested: options.liveCheckRequested,
+				showLiveCheckScope:
+					options.showLiveCheckScope ??
+					(liveCheckDiagnostics?.snapshot !== undefined ||
+						liveCheckDiagnostics?.pending === true ||
+						liveCheckDiagnostics?.lastError !== undefined),
+				modelMetadata,
+				metadataStatus,
+			},
+		);
+		const message = report.report;
+		if (report.warningLevel !== "hard") {
+			statusPresentationVisible = showTransientStatus(message, ctx);
+			if (!statusPresentationVisible) ctx.ui.notify(message, "info");
+			return;
+		}
+		statusPresentationVisible = false;
+		ctx.ui.notify(report.report, "warning");
+	};
+
+	const handleModelSelect = (_model: ActiveModel, ctx: Pick<ExtensionContext, "modelRegistry" | "ui">): void => {
+		lifecycleGeneration++;
+		clearStatusPresentation(ctx);
+	};
+
+	const handleStatusCommand = async (args: string, ctx: ExtensionContext): Promise<void> => {
+		clearStatusPresentation(ctx);
+		const generation = lifecycleGeneration;
+		const presentationGeneration = statusPresentationGeneration;
+		const model = ctx.model;
+		if (!model) {
+			ctx.ui.notify("No active model", "warning");
+			return;
+		}
+		const mode = parseStatusMode(args);
+		if (mode === undefined) {
+			ctx.ui.notify("Usage: /status [refresh|check]", "warning");
+			return;
+		}
+		const { status, preflight, auth } = getStatusDetails(model, ctx);
+		let liveCheckRequested = false;
+		if ((mode === "refresh" || mode === "check") && auth.configured) {
+			const statusContext: StatusContextLike = {
+				model,
+				modelRegistry: ctx.modelRegistry,
+				getCredentialKey: () => ctx.modelRegistry.getApiKeyForProvider(model.provider),
+				getCredentialMetadata: () => readProviderCredentialMetadata(model.provider),
+			};
+			const preflightContext: PreflightContextLike = { model, modelRegistry: ctx.modelRegistry };
+			const refreshChecks: Array<Promise<unknown>> = [];
+			if (status) refreshChecks.push(statusManager.update(statusContext, { force: true }));
+			if (preflight) refreshChecks.push(preflightManager.update(preflightContext, { force: true }));
+
+			let liveCheck: Promise<LiveCheckResult | undefined> = Promise.resolve(undefined);
+			if (mode === "check") {
+				liveCheckRequested = true;
+				liveCheck = liveCheckManager.check({
+					model,
+					modelRegistry: ctx.modelRegistry,
+					...(tuners.length > 0
+						? {
+								onPayload: (payload, liveCheckModel) =>
+									applyTunerAdapters(payload, { model: liveCheckModel }, tuners),
+							}
+						: {}),
+				});
+			}
+			// Account status, free preflight, and the live check are independent requests.
+			// Start all of them before awaiting any result so /status check waits only for the slowest one.
+			await Promise.all([Promise.all(refreshChecks), liveCheck]);
+			if (generation !== lifecycleGeneration) return;
+		}
+		if (generation !== lifecycleGeneration) return;
+		notifyProviderStatus(model, ctx, generation, {
+			presentationGeneration,
+			liveCheckRequested,
+			showLiveCheckScope: mode === "check",
+		});
+	};
+
+	const resetForSession = (): void => {
+		lifecycleGeneration++;
+		statusPresentationGeneration++;
+		statusPresentationVisible = false;
+	};
+
+	const shutdown = (): void => {
+		lifecycleGeneration++;
+		statusPresentationGeneration++;
+		statusPresentationVisible = false;
+		statusManager.cancelAll();
+		statusManager.clear();
+		preflightManager.cancelAll();
+		preflightManager.clear();
+		liveCheckManager.cancelAll();
+		liveCheckManager.clear();
+	};
+
+	const controller: ProviderKitRuntimeController = {
+		resetForSession,
+		updateOfficialPricing(snapshot) {
+			currentOfficialPricing = snapshot;
+			currentOfficialMetadataStatus = getOfficialMetadataStatus(snapshot, runtime);
+		},
+		shutdown,
+		clearStatusPresentation,
+		applyTunerPayload(payload, model) {
+			if (tuners.length === 0) return undefined;
+			return applyTunerAdapters(payload, { model }, tuners);
+		},
+		handleModelSelect,
+		handleStatusCommand,
+	};
+
+	if (registerHandlers) {
+		pi.on("before_provider_request", async (event, ctx) => {
+			if (!ctx.model) return;
+			return controller.applyTunerPayload(event.payload, ctx.model);
+		});
+		pi.on("input", (_event, ctx) => controller.clearStatusPresentation(ctx));
+		pi.on("session_start", (event, ctx) => {
+			resetForSession();
+			scheduleModelCatalogRefresh(ctx, event.reason);
+		});
+		pi.on("model_select", (event, ctx) => handleModelSelect(event.model, ctx));
+		pi.on("session_shutdown", () => shutdown());
+		pi.registerCommand("status", {
+			description: "Show status and diagnostics for the active provider",
+			getArgumentCompletions: getStatusModeCompletions,
+			handler: async (args, ctx) => handleStatusCommand(args, ctx),
+		});
+	}
+
+	return controller;
+}
+
+export function createProviderKitRuntime(
+	loadDefinition: ProviderKitLoader,
+	dependencies: Partial<ProviderKitDependencies> = {},
+): (pi: ExtensionAPI) => Promise<void> {
+	const runtime = resolveProviderKitDependencies(dependencies);
+	return async (pi) => {
+		let latestBackgroundPricing: Record<string, OfficialModelMeta> | undefined;
+		let installedDefinition: ProviderKitDefinition | undefined;
+		let installedController: ProviderKitRuntimeController | undefined;
+		let disposed = false;
+		const onBackgroundRefresh = (snapshot: Record<string, OfficialModelMeta>): void => {
+			latestBackgroundPricing = snapshot;
+			if (disposed) return;
+			installedController?.updateOfficialPricing?.(snapshot);
+			if (installedDefinition === undefined) return;
+			refreshProviderRegistrations(pi, installedDefinition.providers, runtime, snapshot);
+		};
+		const officialPricingPromise = runtime.enableOfficialPricingFallback
+			? fetchOfficialPricing(
+					runtime.fetch,
+					runtime.officialPricingUrl,
+					runtime.officialPricingTimeoutMs,
+					runtime.officialPricingCacheTtlMs,
+					runtime.officialPricingMaxStaleMs,
+					runtime.now,
+					{
+						cachePath:
+							runtime.officialPricingUrl === OPENROUTER_MODELS_URL
+								? runtime.openRouterMetadataCachePath
+								: undefined,
+						background: runtime.officialPricingUrl === OPENROUTER_MODELS_URL,
+						onBackgroundRefresh: onBackgroundRefresh,
+					},
+				)
+			: Promise.resolve({});
+		const definitionPromise = loadDefinition(runtime);
+		const [officialPricing, definition] = await Promise.all([officialPricingPromise, definitionPromise]);
+		validateProviderKitDefinition(definition);
+		installedController = installProviderKitRuntime(pi, runtime, definition, officialPricing);
+		installedDefinition = definition;
+		if (latestBackgroundPricing !== undefined) onBackgroundRefresh(latestBackgroundPricing);
+		pi.on("session_shutdown", () => {
+			disposed = true;
+		});
+	};
+}