@hyav/pi-provider 0.1.7 → 0.2.0

package/core/model-catalog.ts

@@ -0,0 +1,289 @@
+import type { ModelCatalogSource, ModelCatalogStatus, ProviderModelDraft, ProviderRefreshContext } from "./types.ts";
+
+export interface ModelCatalogDiagnostics {
+	rejectedCount?: number;
+	duplicateCount?: number;
+}
+
+export interface ModelCatalogDiscoveryResult {
+	models: ProviderModelDraft[];
+	diagnostics?: ModelCatalogDiagnostics;
+}
+
+export interface ModelCatalogLifecycleOptions {
+	initialModels?: ProviderModelDraft[];
+	initialSource?: ModelCatalogSource;
+	ttlMs: number;
+	failureBackoffMs?: number;
+	maxFailureBackoffMs?: number;
+	now?: () => number;
+	discover(
+		context: ProviderRefreshContext,
+	): Promise<ProviderModelDraft[] | ModelCatalogDiscoveryResult> | ProviderModelDraft[] | ModelCatalogDiscoveryResult;
+	restore(stored: ProviderRefreshContext["stored"]): ProviderModelDraft[] | undefined;
+	persist(models: ProviderModelDraft[], checkedAt: number): NonNullable<ProviderRefreshContext["stored"]>;
+	onUpdate(models: ProviderModelDraft[]): void;
+	errorCode(error: unknown): string;
+}
+
+export interface ModelCatalogLifecycle {
+	catalog: ModelCatalogStatus;
+	getModels(): ProviderModelDraft[];
+	refreshModels(context: ProviderRefreshContext): Promise<ProviderModelDraft[]>;
+	setModels(models: ProviderModelDraft[], source?: ModelCatalogSource, updatedAt?: number): void;
+}
+
+function isAbortError(error: unknown): boolean {
+	return error !== null && typeof error === "object" && "name" in error && error.name === "AbortError";
+}
+
+function isValidTimestamp(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+async function publish(
+	context: ProviderRefreshContext,
+	update: () => void,
+	persist?: NonNullable<ProviderRefreshContext["stored"]>,
+): Promise<boolean> {
+	try {
+		return await context.publish({ ...(persist ? { persist } : {}), update });
+	} catch {
+		if (!persist) return false;
+		// Persistence is an optimization. Retry the generation-checked update without it.
+		try {
+			return await context.publish({ update });
+		} catch {
+			return false;
+		}
+	}
+}
+
+function abortReason(signal: AbortSignal): unknown {
+	return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+
+function waitForCaller<T>(request: Promise<T>, signal: AbortSignal): Promise<T> {
+	if (signal.aborted) return Promise.reject(abortReason(signal));
+	return new Promise<T>((resolve, reject) => {
+		const onAbort = () => reject(abortReason(signal));
+		signal.addEventListener("abort", onAbort, { once: true });
+		void request.then(
+			(value) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(value);
+			},
+			(error) => {
+				signal.removeEventListener("abort", onAbort);
+				reject(error);
+			},
+		);
+	});
+}
+
+const DEFAULT_FAILURE_BACKOFF_MS = 30_000;
+const DEFAULT_MAX_FAILURE_BACKOFF_MS = 15 * 60_000;
+
+function finiteNonNegative(value: number | undefined, fallback: number, label: string): number {
+	const resolved = value ?? fallback;
+	if (!Number.isFinite(resolved) || resolved < 0)
+		throw new RangeError(`${label} must be a finite non-negative number`);
+	return resolved;
+}
+
+interface NormalizedCatalogDiscoveryResult {
+	models: ProviderModelDraft[];
+	diagnostics: Required<ModelCatalogDiagnostics>;
+}
+
+function diagnosticCount(value: number | undefined, label: string): number {
+	const count = value ?? 0;
+	if (!Number.isSafeInteger(count) || count < 0) {
+		throw new RangeError(`Model catalog ${label} must be a non-negative safe integer`);
+	}
+	return count;
+}
+
+function normalizeDiscoveryResult(
+	result: ProviderModelDraft[] | ModelCatalogDiscoveryResult,
+): NormalizedCatalogDiscoveryResult {
+	const models = Array.isArray(result) ? result : result.models;
+	const diagnostics = Array.isArray(result) ? undefined : result.diagnostics;
+	return {
+		models,
+		diagnostics: {
+			rejectedCount: diagnosticCount(diagnostics?.rejectedCount, "rejected count"),
+			duplicateCount: diagnosticCount(diagnostics?.duplicateCount, "duplicate count"),
+		},
+	};
+}
+
+interface ActiveCatalogRefresh {
+	request: Promise<NormalizedCatalogDiscoveryResult>;
+	publication: Promise<void>;
+	waiters: number;
+	settled: boolean;
+	applied: boolean;
+	failureRecorded: boolean;
+}
+
+export function createModelCatalogLifecycle(options: ModelCatalogLifecycleOptions): ModelCatalogLifecycle {
+	const now = options.now ?? Date.now;
+	const failureBackoffMs = finiteNonNegative(
+		options.failureBackoffMs,
+		DEFAULT_FAILURE_BACKOFF_MS,
+		"Model catalog failure backoff",
+	);
+	const maxFailureBackoffMs = finiteNonNegative(
+		options.maxFailureBackoffMs,
+		DEFAULT_MAX_FAILURE_BACKOFF_MS,
+		"Model catalog maximum failure backoff",
+	);
+	if (maxFailureBackoffMs < failureBackoffMs) {
+		throw new RangeError("Model catalog maximum failure backoff must not be less than its initial backoff");
+	}
+	let models = [...(options.initialModels ?? [])];
+	let lastCatalogUpdatedAt: number | undefined;
+	let inFlight: ActiveCatalogRefresh | undefined;
+	const catalog: ModelCatalogStatus = {
+		source: options.initialSource ?? (models.length > 0 ? "static" : "empty"),
+		modelCount: models.length,
+		consecutiveFailures: 0,
+	};
+
+	const applyModels = (
+		nextModels: ProviderModelDraft[],
+		source: ModelCatalogSource,
+		updatedAt?: number,
+		diagnostics: Required<ModelCatalogDiagnostics> = { rejectedCount: 0, duplicateCount: 0 },
+	) => {
+		models = [...nextModels];
+		options.onUpdate(models);
+		catalog.source = source;
+		catalog.modelCount = models.length;
+		catalog.rejectedCount = diagnostics.rejectedCount;
+		catalog.duplicateCount = diagnostics.duplicateCount;
+		catalog.lastError = undefined;
+		catalog.consecutiveFailures = 0;
+		catalog.nextRetryAt = undefined;
+		if (updatedAt !== undefined) {
+			catalog.updatedAt = updatedAt;
+			catalog.lastSuccessfulRefreshAt = updatedAt;
+			lastCatalogUpdatedAt = updatedAt;
+		}
+	};
+
+	const restoreStored = async (context: ProviderRefreshContext): Promise<void> => {
+		const restored = options.restore(context.stored);
+		if (!restored) return;
+		const checkedAt = isValidTimestamp(context.stored?.checkedAt) ? context.stored.checkedAt : undefined;
+		if (lastCatalogUpdatedAt !== undefined && (checkedAt === undefined || checkedAt <= lastCatalogUpdatedAt)) return;
+		await publish(context, () => {
+			applyModels(restored, "cached", checkedAt);
+		});
+	};
+
+	const clearSettledRefresh = (active: ActiveCatalogRefresh) => {
+		if (inFlight === active && active.settled && active.waiters === 0) inFlight = undefined;
+	};
+
+	const recordFailure = (active: ActiveCatalogRefresh, error: unknown) => {
+		if (active.failureRecorded || isAbortError(error)) return;
+		active.failureRecorded = true;
+		const failedAt = now();
+		const consecutiveFailures = (catalog.consecutiveFailures ?? 0) + 1;
+		const multiplier = 2 ** Math.min(30, consecutiveFailures - 1);
+		catalog.consecutiveFailures = consecutiveFailures;
+		catalog.nextRetryAt = failedAt + Math.min(maxFailureBackoffMs, failureBackoffMs * multiplier);
+		catalog.lastError = options.errorCode(error);
+	};
+
+	const startRefresh = (context: ProviderRefreshContext): ActiveCatalogRefresh => {
+		const active: ActiveCatalogRefresh = {
+			request: Promise.resolve({
+				models: [],
+				diagnostics: { rejectedCount: 0, duplicateCount: 0 },
+			}),
+			publication: Promise.resolve(),
+			waiters: 0,
+			settled: false,
+			applied: false,
+			failureRecorded: false,
+		};
+		const sharedContext = { ...context, signal: new AbortController().signal };
+		catalog.lastAttemptAt = now();
+		active.request = Promise.resolve()
+			.then(() => options.discover(sharedContext))
+			.then(normalizeDiscoveryResult)
+			.catch((error: unknown) => {
+				recordFailure(active, error);
+				throw error;
+			})
+			.finally(() => {
+				active.settled = true;
+				clearSettledRefresh(active);
+			});
+		inFlight = active;
+		return active;
+	};
+
+	const refreshModels = async (context: ProviderRefreshContext): Promise<ProviderModelDraft[]> => {
+		await restoreStored(context);
+		if (context.allowNetwork !== true || context.signal.aborted) return [...models];
+
+		const currentTime = now();
+		const isFresh =
+			catalog.lastSuccessfulRefreshAt !== undefined &&
+			Math.max(0, currentTime - catalog.lastSuccessfulRefreshAt) <= Math.max(0, options.ttlMs);
+		if (!context.force && catalog.lastError === undefined && isFresh) return [...models];
+		if (
+			!context.force &&
+			inFlight === undefined &&
+			catalog.nextRetryAt !== undefined &&
+			currentTime < catalog.nextRetryAt
+		) {
+			return [...models];
+		}
+
+		const active = inFlight ?? startRefresh(context);
+		active.waiters++;
+		try {
+			const discovered = await waitForCaller(active.request, context.signal);
+			const attempt = active.publication.then(async () => {
+				if (active.applied || context.signal.aborted) return;
+				const updatedAt = now();
+				await publish(
+					context,
+					() => {
+						applyModels(discovered.models, "live", updatedAt, discovered.diagnostics);
+						active.applied = true;
+					},
+					options.persist(discovered.models, updatedAt),
+				);
+			});
+			active.publication = attempt.catch(() => undefined);
+			await waitForCaller(attempt, context.signal);
+			return [...models];
+		} catch (error) {
+			if (!context.signal.aborted) recordFailure(active, error);
+			throw error;
+		} finally {
+			active.waiters = Math.max(0, active.waiters - 1);
+			clearSettledRefresh(active);
+		}
+	};
+
+	const setModels = (nextModels: ProviderModelDraft[], source?: ModelCatalogSource, updatedAt?: number): void => {
+		applyModels(nextModels, source ?? (nextModels.length > 0 ? "cached" : "empty"), updatedAt);
+	};
+
+	options.onUpdate(models);
+	const lifecycle: ModelCatalogLifecycle = {
+		catalog,
+		getModels: () => [...models],
+		refreshModels,
+		setModels,
+	};
+	(refreshModels as any).lifecycle = lifecycle;
+	return lifecycle;
+}

package/core/opencode-preflight.ts

@@ -1,3 +1,4 @@
+import { MAX_PROVIDER_MODEL_COUNT } from "../core/adapter-validation.ts";
 import { ProviderDataError } from "../core/errors.ts";
 import type { PreflightAdapter } from "../core/preflight-manager.ts";
 import { parseRetryAfter } from "../core/retry-after.ts";
@@ -25,6 +26,8 @@ export function createOpenCodeCatalogPreflightAdapter(
 		requestTimeoutMs,
 		async fetch(context) {
 			const apiKey = await context.getApiKey();
+			// OpenCode Zen catalogs are public. The check stays unauthenticated and
+			// intentionally omits the "auth" check when no credential is resolved.
 			const headers: Record<string, string> = {
 				Accept: "application/json",
 				"Accept-Encoding": "identity",
@@ -49,6 +52,9 @@ export function createOpenCodeCatalogPreflightAdapter(
 			if (!isRecord(payload) || !Array.isArray(payload.data)) {
 				throw new ProviderDataError(`${config.name} preflight returned invalid catalog data`, "badjson");
 			}
+			if (payload.data.length > MAX_PROVIDER_MODEL_COUNT) {
+				throw new ProviderDataError(`${config.name} preflight catalog exceeds the maximum model count`, "badjson");
+			}
 			const modelIds = new Set(
 				payload.data
 					.filter(isRecord)