@xopcai/xopc 0.0.210 → 0.0.213

package/dist/src/providers/model-catalog-store.d.ts

@@ -1,68 +1,20 @@
-export interface CatalogModel {
-    id: string;
-    name: string;
-    availability: 'available' | 'unavailable';
-    kind: 'language' | 'image' | 'stt' | 'tts';
-    input: Array<'text' | 'image' | 'audio'>;
-    output: Array<'text' | 'image' | 'audio'>;
-    operations: Array<'chat.completions' | 'responses' | 'images.generate' | 'images.edit' | 'audio.transcription' | 'audio.speech'>;
-    reasoning: boolean;
-    contextWindow: number;
-    maxOutputTokens: number | null;
-    imageGeneration?: {
-        maxCount: number;
-        sizes: string[];
-        aspectRatios?: string[];
-        qualities: Array<'low' | 'medium' | 'high' | 'auto'>;
-        formats: Array<'png' | 'jpeg' | 'webp'>;
-        backgrounds: Array<'transparent' | 'opaque' | 'auto'>;
-        maxInputImages: number;
-    };
-    stt?: {
-        inputFormats: string[];
-        maxBytes: number;
-        maxDurationSeconds: number;
-        languages: string[];
-        languageHint: boolean;
-        prompt: boolean;
-        timestamps: Array<'segment' | 'word'>;
-        diarization: boolean;
-    };
-    tts?: {
-        maxCharacters: number;
-        languages: string[];
-        outputFormats: Array<'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'>;
-        streaming: boolean;
-        speed: boolean;
-        pitch: boolean;
-        instructions: boolean;
-        defaultVoice?: string;
-    };
-}
-export interface CatalogSource {
-    providerId: string;
-    baseUrl: string;
-    api: 'openai-completions' | 'openai-responses';
-    etag: string | null;
-    recommendedModel: string | null;
-    lastSuccessAt: number;
-    models: CatalogModel[];
-}
-export interface ModelCatalogSnapshot {
-    sources: Record<string, CatalogSource>;
-}
-export type AvailableCatalogModel = Omit<CatalogModel, 'availability'>;
+import type { AvailableCatalogModel, CatalogSource, CatalogSourceOrigin, ModelCatalogSnapshot } from './model-catalog-types.js';
+export type { AvailableCatalogModel, CatalogModel, CatalogSource, CatalogSourceOrigin, ModelCatalogSnapshot, } from './model-catalog-types.js';
 export declare class ModelCatalogStore {
     private sources;
+    private origins;
     load(): ModelCatalogSnapshot;
     getSource(sourceId: string): CatalogSource | undefined;
-    saveSource(sourceId: string, source: CatalogSource): void;
+    getSourceOrigin(sourceId: string): CatalogSourceOrigin | undefined;
+    saveSource(sourceId: string, source: CatalogSource, origin?: CatalogSourceOrigin): void;
     removeSource(sourceId: string): boolean;
-    replaceSourceModels(sourceId: string, source: Omit<CatalogSource, 'models'>, models: AvailableCatalogModel[]): {
+    replaceSourceModels(sourceId: string, source: Omit<CatalogSource, 'models'>, models: AvailableCatalogModel[], origin?: CatalogSourceOrigin): {
         addedCount: number;
         unavailableCount: number;
     };
     private cloneSource;
 }
 export declare function getModelCatalogStore(): ModelCatalogStore;
-export declare function resetModelCatalogStore(): void;
+export declare function resetModelCatalogStore(options?: {
+    rehydrate?: boolean;
+}): void;

package/dist/src/providers/model-catalog-store.js

@@ -1,16 +1,25 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+import { ModelCatalogPersistence, init_model_catalog_persistence } from "./model-catalog-persistence.js";
 //#region src/providers/model-catalog-store.ts
 function getModelCatalogStore() {
 	globalModelCatalogStore ??= new ModelCatalogStore();
+	if (!globalCatalogHydrated) {
+		globalCatalogHydrated = true;
+		const source = new ModelCatalogPersistence().loadSync();
+		if (source) globalModelCatalogStore.saveSource("xopc-cloud", source, "disk");
+	}
 	return globalModelCatalogStore;
 }
-function resetModelCatalogStore() {
+function resetModelCatalogStore(options = {}) {
 	globalModelCatalogStore = void 0;
+	if (options.rehydrate) globalCatalogHydrated = false;
 }
-var ModelCatalogStore, globalModelCatalogStore;
+var ModelCatalogStore, globalModelCatalogStore, globalCatalogHydrated;
 var init_model_catalog_store = __esmMin((() => {
+	init_model_catalog_persistence();
 	ModelCatalogStore = class {
 		sources = {};
+		origins = {};
 		load() {
 			return { sources: Object.fromEntries(Object.entries(this.sources).map(([id, source]) => [id, this.cloneSource(source)])) };
 		}
@@ -18,19 +27,28 @@ var init_model_catalog_store = __esmMin((() => {
 			const source = this.sources[sourceId];
 			return source ? this.cloneSource(source) : void 0;
 		}
-		saveSource(sourceId, source) {
+		getSourceOrigin(sourceId) {
+			return this.origins[sourceId];
+		}
+		saveSource(sourceId, source, origin = "memory") {
 			this.sources = {
 				...this.sources,
 				[sourceId]: this.cloneSource(source)
 			};
+			this.origins = {
+				...this.origins,
+				[sourceId]: origin
+			};
 		}
 		removeSource(sourceId) {
 			if (!this.sources[sourceId]) return false;
 			const { [sourceId]: _removed, ...sources } = this.sources;
+			const { [sourceId]: _removedOrigin, ...origins } = this.origins;
 			this.sources = sources;
+			this.origins = origins;
 			return true;
 		}
-		replaceSourceModels(sourceId, source, models) {
+		replaceSourceModels(sourceId, source, models, origin = "memory") {
 			const previous = this.getSource(sourceId);
 			const nextIds = new Set(models.map((model) => model.id));
 			const previousAvailableIds = new Set((previous?.models ?? []).filter((model) => model.availability === "available").map((model) => model.id));
@@ -44,7 +62,7 @@ var init_model_catalog_store = __esmMin((() => {
 					...model,
 					availability: "available"
 				})), ...unavailable]
-			});
+			}, origin);
 			return {
 				addedCount: models.filter((model) => !previousAvailableIds.has(model.id)).length,
 				unavailableCount: unavailable.length
@@ -81,6 +99,7 @@ var init_model_catalog_store = __esmMin((() => {
 			};
 		}
 	};
+	globalCatalogHydrated = false;
 }));
 //#endregion
 init_model_catalog_store();

package/dist/src/providers/model-catalog-sync-service.d.ts

@@ -2,7 +2,7 @@ import type { Config } from '../config/schema.js';
 import { type ModelsJsonConfig } from '../config/models-json.js';
 import { type ModelCatalogStore } from './model-catalog-store.js';
 import { discoverProviderModels } from './model-discovery.js';
-import { XopcCloudModelSource } from './xopc-cloud-model-source.js';
+import { type CatalogReadiness, type XopcCloudCatalogCoordinator } from './xopc-cloud-catalog-coordinator.js';
 export interface ModelCatalogSyncStatus {
     running: boolean;
     refreshing: boolean;
@@ -21,7 +21,7 @@ export declare class ModelCatalogSyncService {
     constructor(options?: {
         intervalMs?: number;
         onUpdated?: (modelCount: number) => void;
-        xopcCloud?: XopcCloudModelSource;
+        xopcCloud?: Pick<XopcCloudCatalogCoordinator, 'refresh'>;
         getConfig?: () => Config;
         catalogStore?: ModelCatalogStore;
         loadProviders?: () => ModelsJsonConfig['providers'];
@@ -32,7 +32,7 @@ export declare class ModelCatalogSyncService {
     start(): void;
     stop(): void;
     getStatus(): ModelCatalogSyncStatus;
-    refreshNow(): Promise<Awaited<ReturnType<XopcCloudModelSource['refresh']>>>;
+    refreshNow(): Promise<CatalogReadiness>;
     refreshAll(): Promise<{
         updatedSources: string[];
     }>;

package/dist/src/providers/model-catalog-sync-service.js

@@ -4,7 +4,7 @@ import { init_models_json, loadModelsJson } from "../config/models-json.js";
 import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
 import { getModelRegistry, init_model_registry } from "./model-registry.js";
 import { discoverProviderModels, isProviderApiDiscoverable } from "./model-discovery.js";
-import { XopcCloudModelSource } from "./xopc-cloud-model-source.js";
+import { getXopcCloudCatalogCoordinator } from "./xopc-cloud-catalog-coordinator.js";
 //#region src/providers/model-catalog-sync-service.ts
 init_logger();
 init_models_json();
@@ -23,7 +23,7 @@ var ModelCatalogSyncService = class {
 	};
 	constructor(options = {}) {
 		this.options = options;
-		this.xopcCloud = options.xopcCloud ?? new XopcCloudModelSource();
+		this.xopcCloud = options.xopcCloud ?? getXopcCloudCatalogCoordinator();
 	}
 	start() {
 		if (this.status.running) return;
@@ -47,12 +47,15 @@ var ModelCatalogSyncService = class {
 		if (this.refreshPromise) return this.refreshPromise;
 		this.status.refreshing = true;
 		this.status.lastAttemptAt = Date.now();
-		this.refreshPromise = this.xopcCloud.refresh().then((result) => {
-			if (result.status === "updated") {
+		this.refreshPromise = this.xopcCloud.refresh("manual").then((result) => {
+			if (result.state === "not-authorized") {
+				this.status.lastError = result.error?.message;
+				this.options.onUpdated?.(0);
+			} else if (result.source === "network" && !result.error) {
 				this.status.lastSuccessAt = Date.now();
 				this.status.lastError = void 0;
-				this.options.onUpdated?.(result.modelCount ?? 0);
-			}
+				this.options.onUpdated?.(result.modelCount);
+			} else if (result.error) this.status.lastError = result.error.message;
 			return result;
 		}).catch((err) => {
 			const errorMessage = err instanceof Error ? err.message : String(err);
@@ -81,7 +84,9 @@ var ModelCatalogSyncService = class {
 		const updatedSources = [];
 		const sourceErrors = {};
 		try {
-			if ((await this.refreshNow()).status === "updated") updatedSources.push("xopc-cloud");
+			const cloud = await this.refreshNow();
+			if (cloud.source === "network" && !cloud.error) updatedSources.push("xopc-cloud");
+			if (cloud.error) sourceErrors["xopc-cloud"] = cloud.error.message;
 		} catch (err) {
 			sourceErrors["xopc-cloud"] = err instanceof Error ? err.message : String(err);
 		}

package/dist/src/providers/model-catalog-types.d.ts

@@ -0,0 +1,60 @@
+export interface CatalogModel {
+    id: string;
+    name: string;
+    availability: 'available' | 'unavailable';
+    kind: 'language' | 'image' | 'stt' | 'tts';
+    input: Array<'text' | 'image' | 'audio'>;
+    output: Array<'text' | 'image' | 'audio'>;
+    operations: Array<'chat.completions' | 'responses' | 'images.generate' | 'images.edit' | 'audio.transcription' | 'audio.speech'>;
+    reasoning: boolean;
+    contextWindow: number;
+    maxOutputTokens: number | null;
+    stability?: 'stable' | 'preview' | 'deprecated';
+    priority?: number;
+    tier?: string;
+    bestEffort?: boolean;
+    imageGeneration?: {
+        maxCount: number;
+        sizes: string[];
+        aspectRatios?: string[];
+        qualities: Array<'low' | 'medium' | 'high' | 'auto'>;
+        formats: Array<'png' | 'jpeg' | 'webp'>;
+        backgrounds: Array<'transparent' | 'opaque' | 'auto'>;
+        maxInputImages: number;
+    };
+    stt?: {
+        inputFormats: string[];
+        maxBytes: number;
+        maxDurationSeconds: number;
+        languages: string[];
+        languageHint: boolean;
+        prompt: boolean;
+        timestamps: Array<'segment' | 'word'>;
+        diarization: boolean;
+    };
+    tts?: {
+        maxCharacters: number;
+        languages: string[];
+        outputFormats: Array<'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'>;
+        streaming: boolean;
+        speed: boolean;
+        pitch: boolean;
+        instructions: boolean;
+        defaultVoice?: string;
+    };
+}
+export interface CatalogSource {
+    providerId: string;
+    baseUrl: string;
+    api: 'openai-completions' | 'openai-responses';
+    etag: string | null;
+    recommendedModel: string | null;
+    recommended?: Partial<Record<'vision' | 'image-generation' | 'stt' | 'tts', string>>;
+    lastSuccessAt: number;
+    models: CatalogModel[];
+}
+export interface ModelCatalogSnapshot {
+    sources: Record<string, CatalogSource>;
+}
+export type CatalogSourceOrigin = 'memory' | 'disk' | 'network';
+export type AvailableCatalogModel = Omit<CatalogModel, 'availability'>;

package/dist/src/providers/model-catalog-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/providers/provider-auth-service.d.ts

@@ -15,6 +15,7 @@ export declare class ProviderAuthService {
     private runtime;
     constructor(options?: ProviderAuthServiceOptions);
     resolveApiKey(providerId: string, signal?: AbortSignal): Promise<string | null>;
+    invalidate(): void;
     private getRuntime;
 }
 export declare function getProviderAuthService(): ProviderAuthService;

package/dist/src/providers/provider-auth-service.js

@@ -55,6 +55,9 @@ var init_provider_auth_service = __esmMin((() => {
 			}
 			return await this.resolver.resolveApiKey(providerId);
 		}
+		invalidate() {
+			this.runtime = void 0;
+		}
 		getRuntime() {
 			this.runtime ??= this.runtimeFactory(this.credentials).catch((error) => {
 				this.runtime = void 0;

package/dist/src/providers/provider-disconnect-core.d.ts

@@ -0,0 +1,11 @@
+import { CredentialResolver } from '../auth/credentials.js';
+export interface ProviderDisconnectOptions {
+    resolver?: Pick<CredentialResolver, 'deleteProviderCredential'>;
+    invalidateAuth?: () => void;
+    clearCloudCatalog?: () => Promise<void>;
+    refreshModels?: () => void;
+    evictRunners?: () => void;
+    withLock?: <T>(providerId: string, operation: () => Promise<T>) => Promise<T>;
+}
+/** Low-level disconnect operation. Cloud callers must inject catalog cleanup. */
+export declare function disconnectProviderCore(providerId: string, options?: ProviderDisconnectOptions): Promise<void>;

package/dist/src/providers/provider-disconnect-core.js

@@ -0,0 +1,35 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { getModelRegistry, init_model_registry } from "./model-registry.js";
+import { init_oauth_provider_lock, withOAuthProviderLock } from "../auth/oauth-provider-lock.js";
+import { CredentialResolver, init_credentials } from "../auth/credentials.js";
+import { getProviderAuthService, init_provider_auth_service } from "./provider-auth-service.js";
+import { evictAllEmbeddedSessionRunners } from "../agent/embedded/session-runner.js";
+//#region src/providers/provider-disconnect-core.ts
+init_credentials();
+init_oauth_provider_lock();
+init_logger();
+init_model_registry();
+init_provider_auth_service();
+const log = createLogger("ProviderDisconnect");
+/** Low-level disconnect operation. Cloud callers must inject catalog cleanup. */
+async function disconnectProviderCore(providerId, options = {}) {
+	const provider = providerId.trim().toLowerCase();
+	if (!provider) throw new Error("Provider id is required");
+	const resolver = options.resolver ?? new CredentialResolver();
+	await (options.withLock ?? ((id, operation) => withOAuthProviderLock(id, operation)))(provider, async () => {
+		await resolver.deleteProviderCredential(provider);
+		(options.invalidateAuth ?? (() => getProviderAuthService().invalidate()))();
+		if (provider === "xopc-cloud") {
+			if (!options.clearCloudCatalog) throw new Error("XOPC Cloud disconnect requires a catalog cleanup hook");
+			await options.clearCloudCatalog();
+		} else (options.refreshModels ?? (() => getModelRegistry().refresh()))();
+		(options.evictRunners ?? (() => evictAllEmbeddedSessionRunners("provider_disconnected")))();
+	});
+	log.info({
+		provider,
+		phase: "provider_revoked"
+	}, `Disconnected provider: ${provider}`);
+}
+//#endregion
+export { disconnectProviderCore };

package/dist/src/providers/provider-disconnect.d.ts

@@ -0,0 +1,3 @@
+import { type ProviderDisconnectOptions } from './provider-disconnect-core.js';
+export type { ProviderDisconnectOptions } from './provider-disconnect-core.js';
+export declare function disconnectProvider(providerId: string, options?: ProviderDisconnectOptions): Promise<void>;

package/dist/src/providers/provider-disconnect.js

@@ -0,0 +1,11 @@
+import { disconnectProviderCore } from "./provider-disconnect-core.js";
+import { getXopcCloudCatalogCoordinator } from "./xopc-cloud-catalog-coordinator.js";
+//#region src/providers/provider-disconnect.ts
+async function disconnectProvider(providerId, options = {}) {
+	return disconnectProviderCore(providerId, {
+		...options,
+		clearCloudCatalog: options.clearCloudCatalog ?? (() => getXopcCloudCatalogCoordinator().clear("revoke"))
+	});
+}
+//#endregion
+export { disconnectProvider };

package/dist/src/providers/xopc-cloud-catalog-coordinator.d.ts

@@ -0,0 +1,56 @@
+import { ModelCatalogPersistence } from './model-catalog-persistence.js';
+import { type CatalogSourceOrigin, type ModelCatalogStore } from './model-catalog-store.js';
+import { XopcCloudModelSource } from './xopc-cloud-model-source.js';
+export type CatalogEnsureReason = 'startup' | 'oauth' | 'agent-run' | 'manual' | 'recovery';
+export interface EnsureCatalogOptions {
+    reason: CatalogEnsureReason;
+    network: 'never' | 'if-empty' | 'always';
+    timeoutMs?: number;
+}
+export interface CatalogReadiness {
+    state: 'not-authorized' | 'ready' | 'stale' | 'refreshing' | 'unavailable';
+    source: CatalogSourceOrigin | 'none';
+    fetchedAt?: number;
+    catalogVersion?: string | null;
+    modelCount: number;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+}
+interface CatalogCoordinatorOptions {
+    source?: Pick<XopcCloudModelSource, 'fetch'>;
+    store?: ModelCatalogStore;
+    persistence?: Pick<ModelCatalogPersistence, 'loadSync' | 'save' | 'clear'>;
+    staleAfterMs?: number;
+    refreshModels?: () => void;
+    reloadImageProviders?: () => void;
+    withLock?: <T>(operation: () => Promise<T>) => Promise<T>;
+    onPermanentAuthFailure?: () => Promise<void>;
+}
+export declare class XopcCloudCatalogCoordinator {
+    private readonly source;
+    private readonly store;
+    private readonly persistence;
+    private readonly staleAfterMs;
+    private readonly refreshModels;
+    private readonly reloadImageProviders;
+    private readonly withLock;
+    private readonly onPermanentAuthFailure;
+    private refreshPromise;
+    private generation;
+    private lastError;
+    private notAuthorized;
+    constructor(options?: CatalogCoordinatorOptions);
+    hydrate(): Promise<CatalogReadiness>;
+    ensure(options: EnsureCatalogOptions): Promise<CatalogReadiness>;
+    refresh(reason: CatalogEnsureReason, timeoutMs?: number): Promise<CatalogReadiness>;
+    clear(reason: 'revoke' | 'invalid-grant'): Promise<void>;
+    snapshot(): CatalogReadiness;
+    private buildSnapshot;
+    private runRefresh;
+}
+export declare function getXopcCloudCatalogCoordinator(): XopcCloudCatalogCoordinator;
+export declare function resetXopcCloudCatalogCoordinator(): void;
+export {};

package/dist/src/providers/xopc-cloud-catalog-coordinator.js

@@ -0,0 +1,182 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { ModelCatalogPersistence, init_model_catalog_persistence } from "./model-catalog-persistence.js";
+import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
+import { getModelRegistry, init_model_registry } from "./model-registry.js";
+import { init_oauth_provider_lock, withOAuthProviderLock } from "../auth/oauth-provider-lock.js";
+import { reloadImageGenerationProviders } from "../agent/image/generation/provider-registry.js";
+import { disconnectProviderCore } from "./provider-disconnect-core.js";
+import { XopcCloudModelSource } from "./xopc-cloud-model-source.js";
+//#region src/providers/xopc-cloud-catalog-coordinator.ts
+init_oauth_provider_lock();
+init_logger();
+init_model_catalog_persistence();
+init_model_catalog_store();
+init_model_registry();
+const log = createLogger("XopcCloudCatalog");
+const DEFAULT_STALE_AFTER_MS = 1440 * 6e4;
+var XopcCloudCatalogCoordinator = class {
+	source;
+	store;
+	persistence;
+	staleAfterMs;
+	refreshModels;
+	reloadImageProviders;
+	withLock;
+	onPermanentAuthFailure;
+	refreshPromise = null;
+	generation = 0;
+	lastError;
+	notAuthorized = false;
+	constructor(options = {}) {
+		this.source = options.source ?? new XopcCloudModelSource();
+		this.store = options.store ?? getModelCatalogStore();
+		this.persistence = options.persistence ?? new ModelCatalogPersistence();
+		this.staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+		this.refreshModels = options.refreshModels ?? (() => getModelRegistry().refresh());
+		this.reloadImageProviders = options.reloadImageProviders ?? reloadImageGenerationProviders;
+		this.withLock = options.withLock ?? ((operation) => withOAuthProviderLock("xopc-cloud", operation));
+		this.onPermanentAuthFailure = options.onPermanentAuthFailure ?? (async () => {
+			await disconnectProviderCore("xopc-cloud", { clearCloudCatalog: () => this.clear("invalid-grant") });
+		});
+	}
+	async hydrate() {
+		if (!this.store.getSource("xopc-cloud")) {
+			const source = this.persistence.loadSync();
+			if (source) this.store.saveSource("xopc-cloud", source, "disk");
+		}
+		return this.snapshot();
+	}
+	async ensure(options) {
+		await this.hydrate();
+		if (options.network === "never") return this.snapshot();
+		if (options.network === "if-empty" && this.store.getSource("xopc-cloud")) return this.snapshot();
+		return this.refresh(options.reason, options.timeoutMs);
+	}
+	refresh(reason, timeoutMs = 3e4) {
+		if (this.refreshPromise) return this.refreshPromise;
+		const generation = this.generation;
+		this.refreshPromise = this.runRefresh(reason, generation, timeoutMs).finally(() => {
+			this.refreshPromise = null;
+		});
+		return this.refreshPromise;
+	}
+	async clear(reason) {
+		this.generation += 1;
+		await this.withLock(async () => {
+			this.store.removeSource("xopc-cloud");
+			await this.persistence.clear();
+			this.lastError = void 0;
+			this.notAuthorized = reason === "revoke" || reason === "invalid-grant";
+			this.refreshModels();
+			this.reloadImageProviders();
+			log.info({
+				provider: "xopc-cloud",
+				reason,
+				phase: "catalog_commit"
+			}, "Cleared XOPC Cloud model catalog");
+		});
+	}
+	snapshot() {
+		return this.buildSnapshot(this.refreshPromise !== null);
+	}
+	buildSnapshot(refreshing) {
+		const source = this.store.getSource("xopc-cloud");
+		if (!source) return {
+			state: this.notAuthorized ? "not-authorized" : "unavailable",
+			source: "none",
+			modelCount: 0,
+			...this.lastError ? { error: this.lastError } : {}
+		};
+		const stale = Date.now() - source.lastSuccessAt > this.staleAfterMs;
+		return {
+			state: refreshing ? "refreshing" : stale ? "stale" : "ready",
+			source: this.store.getSourceOrigin("xopc-cloud") ?? "memory",
+			fetchedAt: source.lastSuccessAt,
+			catalogVersion: source.etag,
+			modelCount: source.models.filter((model) => model.availability === "available").length,
+			...this.lastError ? { error: this.lastError } : {}
+		};
+	}
+	async runRefresh(reason, generation, timeoutMs) {
+		const startedAt = Date.now();
+		try {
+			const readiness = await this.withLock(async () => {
+				const result = await this.source.fetch(AbortSignal.timeout(timeoutMs));
+				if (result.status === "skipped") {
+					await this.clear("revoke");
+					return this.buildSnapshot(false);
+				}
+				if (generation !== this.generation) return this.buildSnapshot(false);
+				const previous = this.store.getSource("xopc-cloud");
+				const previousOrigin = this.store.getSourceOrigin("xopc-cloud");
+				this.store.replaceSourceModels("xopc-cloud", result.source, result.models, "network");
+				const committed = this.store.getSource("xopc-cloud");
+				if (!committed) throw new Error("XOPC Cloud catalog commit failed");
+				try {
+					await this.persistence.save(committed);
+				} catch (error) {
+					if (previous) this.store.saveSource("xopc-cloud", previous, previousOrigin ?? "memory");
+					else this.store.removeSource("xopc-cloud");
+					throw error;
+				}
+				if (generation !== this.generation) {
+					this.store.removeSource("xopc-cloud");
+					await this.persistence.clear();
+					return this.buildSnapshot(false);
+				}
+				this.notAuthorized = false;
+				this.lastError = void 0;
+				this.refreshModels();
+				this.reloadImageProviders();
+				return this.buildSnapshot(false);
+			});
+			log.info({
+				provider: "xopc-cloud",
+				reason,
+				phase: "catalog_refresh",
+				durationMs: Date.now() - startedAt
+			}, `XOPC Cloud model catalog refresh completed with ${readiness.modelCount} models`);
+			return readiness;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			const modelError = asXopcCloudModelError(err);
+			if (modelError?.status === 401 && (modelError.code === "invalid_grant" || modelError.code === "invalid_token")) {
+				await this.onPermanentAuthFailure();
+				this.notAuthorized = true;
+			}
+			this.lastError = {
+				code: modelError ? modelError.code ?? `http_${modelError.status}` : "refresh_failed",
+				message,
+				retryable: !modelError || modelError.status === 429 || modelError.status >= 500
+			};
+			log.warn({
+				err,
+				provider: "xopc-cloud",
+				reason,
+				phase: "catalog_refresh",
+				durationMs: Date.now() - startedAt
+			}, `XOPC Cloud model catalog refresh failed: ${message}`);
+			return this.buildSnapshot(false);
+		}
+	}
+};
+function asXopcCloudModelError(error) {
+	if (!(error instanceof Error) || error.name !== "XopcCloudModelError") return void 0;
+	const candidate = error;
+	if (typeof candidate.status !== "number") return void 0;
+	return {
+		status: candidate.status,
+		...typeof candidate.code === "string" ? { code: candidate.code } : {}
+	};
+}
+let globalCoordinator;
+function getXopcCloudCatalogCoordinator() {
+	globalCoordinator ??= new XopcCloudCatalogCoordinator();
+	return globalCoordinator;
+}
+function resetXopcCloudCatalogCoordinator() {
+	globalCoordinator = void 0;
+}
+//#endregion
+export { XopcCloudCatalogCoordinator, getXopcCloudCatalogCoordinator, resetXopcCloudCatalogCoordinator };

package/dist/src/providers/xopc-cloud-model-source.d.ts

@@ -1,12 +1,12 @@
-import { type ModelCatalogStore } from './model-catalog-store.js';
+import type { AvailableCatalogModel, CatalogSource } from './model-catalog-store.js';
 import { type ProviderAuthService } from './provider-auth-service.js';
-export type XopcCloudModelRefreshResult = {
+export type XopcCloudCatalogFetchResult = {
     status: 'skipped';
     reason: 'not_configured';
 } | {
-    status: 'updated';
-    modelCount: number;
-    models: string[];
+    status: 'fetched';
+    source: Omit<CatalogSource, 'models'>;
+    models: AvailableCatalogModel[];
 };
 export declare class XopcCloudModelError extends Error {
     readonly status: number;
@@ -17,14 +17,10 @@ export declare class XopcCloudModelSource {
     private readonly fetchImpl;
     private readonly routerUrl;
     private readonly credentials;
-    private readonly catalogStore;
-    private readonly refreshModels;
     constructor(options?: {
         fetchImpl?: typeof fetch;
         routerUrl?: string;
         credentials?: Pick<ProviderAuthService, 'resolveApiKey'>;
-        catalogStore?: ModelCatalogStore;
-        refreshModels?: () => void;
     });
-    refresh(): Promise<XopcCloudModelRefreshResult>;
+    fetch(signal?: AbortSignal): Promise<XopcCloudCatalogFetchResult>;
 }