@xopcai/xopc 0.0.210 → 0.0.211

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/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.d.ts

@@ -0,0 +1,11 @@
+import { CredentialResolver } from '../auth/credentials.js';
+interface ProviderDisconnectOptions {
+    resolver?: Pick<CredentialResolver, 'deleteProviderCredential'>;
+    invalidateAuth?: () => void;
+    clearCloudCatalog?: () => Promise<void>;
+    refreshModels?: () => void;
+    evictRunners?: () => void;
+    withLock?: <T>(providerId: string, operation: () => Promise<T>) => Promise<T>;
+}
+export declare function disconnectProvider(providerId: string, options?: ProviderDisconnectOptions): Promise<void>;
+export {};

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

@@ -0,0 +1,33 @@
+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";
+import { getXopcCloudCatalogCoordinator } from "./xopc-cloud-catalog-coordinator.js";
+//#region src/providers/provider-disconnect.ts
+init_credentials();
+init_oauth_provider_lock();
+init_logger();
+init_model_registry();
+init_provider_auth_service();
+const log = createLogger("ProviderDisconnect");
+async function disconnectProvider(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") await (options.clearCloudCatalog ?? (() => getXopcCloudCatalogCoordinator().clear("revoke")))();
+		else (options.refreshModels ?? (() => getModelRegistry().refresh()))();
+		(options.evictRunners ?? (() => evictAllEmbeddedSessionRunners("provider_disconnected")))();
+	});
+	log.info({
+		provider,
+		phase: "provider_revoked"
+	}, `Disconnected provider: ${provider}`);
+}
+//#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 { 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 () => {
+			const { disconnectProvider } = await import("./provider-disconnect.js");
+			await disconnectProvider("xopc-cloud");
+		});
+	}
+	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>;
 }

package/dist/src/providers/xopc-cloud-model-source.js

@@ -1,11 +1,6 @@
-import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
-import { getModelRegistry, init_model_registry } from "./model-registry.js";
 import { init_xopc_cloud_config, resolveXopcModelRouterUrl } from "./xopc-cloud-config.js";
 import { getProviderAuthService, init_provider_auth_service } from "./provider-auth-service.js";
-import { reloadImageGenerationProviders } from "../agent/image/generation/provider-registry.js";
 //#region src/providers/xopc-cloud-model-source.ts
-init_model_catalog_store();
-init_model_registry();
 init_provider_auth_service();
 init_xopc_cloud_config();
 var XopcCloudModelError = class extends Error {
@@ -20,17 +15,14 @@ var XopcCloudModelSource = class {
 	fetchImpl;
 	routerUrl;
 	credentials;
-	catalogStore;
-	refreshModels;
 	constructor(options = {}) {
 		this.fetchImpl = options.fetchImpl ?? fetch;
 		this.routerUrl = resolveXopcModelRouterUrl(options.routerUrl);
 		this.credentials = options.credentials ?? getProviderAuthService();
-		this.catalogStore = options.catalogStore ?? getModelCatalogStore();
-		this.refreshModels = options.refreshModels ?? (() => getModelRegistry().refresh());
 	}
-	async refresh() {
-		const accessToken = await this.credentials.resolveApiKey("xopc-cloud");
+	async fetch(signal) {
+		const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(3e4)]) : AbortSignal.timeout(3e4);
+		const accessToken = await this.credentials.resolveApiKey("xopc-cloud", requestSignal);
 		if (!accessToken) return {
 			status: "skipped",
 			reason: "not_configured"
@@ -40,7 +32,7 @@ var XopcCloudModelSource = class {
 				authorization: `Bearer ${accessToken}`,
 				accept: "application/json"
 			},
-			signal: AbortSignal.timeout(3e4)
+			signal: requestSignal
 		});
 		const body = await response.json().catch(() => null);
 		if (!response.ok) throw new XopcCloudModelError(typeof body?.error?.message === "string" ? body.error.message : `XOPC model discovery failed (${response.status})`, response.status, typeof body?.error?.code === "string" ? body.error.code : void 0);
@@ -58,7 +50,7 @@ var XopcCloudModelSource = class {
 			const generation = parseImageGenerationCapabilities(model.xopc?.capabilities?.imageGeneration);
 			const stt = kind === "stt" ? parseSttCapabilities(model.xopc?.capabilities) : void 0;
 			const tts = kind === "tts" ? parseTtsCapabilities(model.xopc?.capabilities, model.xopc?.defaultVoice) : void 0;
-			return [model.id, {
+			const catalogModel = {
 				id: model.id,
 				name: model.id,
 				kind,
@@ -68,28 +60,58 @@ var XopcCloudModelSource = class {
 				reasoning: model.xopc?.capabilities?.reasoning === true,
 				contextWindow: 128e3,
 				maxOutputTokens: typeof maxOutputTokens === "number" && Number.isSafeInteger(maxOutputTokens) ? maxOutputTokens : null,
+				...model.xopc?.stability === "stable" || model.xopc?.stability === "preview" || model.xopc?.stability === "deprecated" ? { stability: model.xopc.stability } : {},
+				...typeof model.xopc?.priority === "number" && Number.isFinite(model.xopc.priority) ? { priority: model.xopc.priority } : {},
+				...typeof model.xopc?.tier === "string" && model.xopc.tier ? { tier: model.xopc.tier } : {},
+				...typeof model.xopc?.bestEffort === "boolean" ? { bestEffort: model.xopc.bestEffort } : {},
 				...generation ? { imageGeneration: generation } : {},
 				...stt ? { stt } : {},
 				...tts ? { tts } : {}
-			}];
+			};
+			return [model.id, catalogModel];
 		})).values()];
-		this.catalogStore.replaceSourceModels("xopc-cloud", {
-			providerId: "xopc-cloud",
-			baseUrl: this.routerUrl,
-			api: "openai-completions",
-			etag: response.headers.get("x-xopc-model-catalog-version"),
-			recommendedModel: models[0]?.id ?? null,
-			lastSuccessAt: Date.now()
-		}, models);
-		this.refreshModels();
-		reloadImageGenerationProviders();
+		const recommended = parseRecommendations(body.xopc?.defaults, models);
 		return {
-			status: "updated",
-			modelCount: models.length,
-			models: models.map((model) => model.id)
+			status: "fetched",
+			source: {
+				providerId: "xopc-cloud",
+				baseUrl: this.routerUrl,
+				api: "openai-completions",
+				etag: response.headers.get("x-xopc-model-catalog-version"),
+				recommendedModel: models[0]?.id ?? null,
+				...Object.keys(recommended).length > 0 ? { recommended } : {},
+				lastSuccessAt: Date.now()
+			},
+			models
 		};
 	}
 };
+function parseRecommendations(value, models) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+	const raw = value;
+	const capabilities = [
+		"vision",
+		"image-generation",
+		"stt",
+		"tts"
+	];
+	const recommended = {};
+	for (const capability of capabilities) {
+		const modelId = raw[capability];
+		if (typeof modelId !== "string") continue;
+		const model = models.find((entry) => entry.id === modelId);
+		if (model && modelMatchesRecommendation(model, capability)) recommended[capability] = modelId;
+	}
+	return recommended;
+}
+function modelMatchesRecommendation(model, capability) {
+	switch (capability) {
+		case "vision": return model.kind === "language" && model.input.includes("image");
+		case "image-generation": return model.kind === "image" && model.operations.includes("images.generate");
+		case "stt": return model.kind === "stt" && model.operations.includes("audio.transcription");
+		case "tts": return model.kind === "tts" && model.operations.includes("audio.speech");
+	}
+}
 function parseSttCapabilities(value) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
 	const raw = value;

package/dist/src/storage/sqlite/knowledge-repository.d.ts

@@ -40,6 +40,7 @@ export declare function getKnowledgeConsumerWatermark(consumerId: string, source
 export declare function setKnowledgeConsumerWatermark(consumerId: string, sourceInstanceId: string, sequence: number, nowMs?: number): void;
 export declare function listKnowledgeSourceItems(options?: {
     sourceInstanceId?: string;
+    agentId?: string;
     collectionScope?: string;
     itemType?: string;
     synthesisStatus?: KnowledgeSynthesisStatus;

package/dist/src/storage/sqlite/knowledge-repository.js

@@ -240,6 +240,10 @@ function listKnowledgeSourceItems(options = {}) {
 		where.push("source_instance_id = ?");
 		params.push(options.sourceInstanceId);
 	}
+	if (options.agentId) {
+		where.push("json_extract(metadata_json, '$.agentId') = ?");
+		params.push(options.agentId);
+	}
 	if (options.collectionScope) {
 		where.push("collection_scope = ?");
 		params.push(options.collectionScope);

package/dist/src/storage/sqlite/user-context-quality-repository.d.ts

@@ -26,6 +26,14 @@ export type UserUnderstandingQualityMetrics = {
         irrelevant: number;
         helpfulRate: number | null;
     };
+    quickUnderstanding: {
+        sourcesAuthorized: number;
+        sourcesCollected: number;
+        sourceCoverage: number | null;
+        bootstrapJobs: number;
+        successfulBootstrapRate: number | null;
+        medianBootstrapDurationMs: number | null;
+    };
 };
 export type UnderstandingFeedbackSummary = {
     understandingId: string;

package/dist/src/storage/sqlite/user-context-quality-repository.js

@@ -28,6 +28,12 @@ function summarizeUnderstandingFeedback(understandingIds) {
 function rate(numerator, denominator) {
 	return denominator > 0 ? Math.round(numerator / denominator * 1e4) / 1e4 : null;
 }
+function median(values) {
+	if (!values.length) return null;
+	const sorted = values.toSorted((left, right) => left - right);
+	const middle = Math.floor(sorted.length / 2);
+	return sorted.length % 2 ? sorted[middle] : Math.round((sorted[middle - 1] + sorted[middle]) / 2);
+}
 function summarizeUserUnderstandingQuality(options = {}) {
 	const nowMs = options.nowMs ?? Date.now();
 	const windowDays = Math.max(1, Math.min(365, Math.floor(options.windowDays ?? 30)));
@@ -83,6 +89,12 @@ function summarizeUserUnderstandingQuality(options = {}) {
 		helpfulRate: null
 	};
 	recall.helpfulRate = rate(recall.helpful, recall.total);
+	const sourceRows = db.prepare(`SELECT last_collected_at
+    FROM understanding_source_grants WHERE status = 'active'`).all();
+	const bootstrapRows = db.prepare(`SELECT status, started_at, finished_at
+    FROM connector_learning_jobs WHERE mode = 'bootstrap' AND created_at >= ?`).all(sinceMs);
+	const completedBootstraps = bootstrapRows.filter((row) => row.status === "completed");
+	const bootstrapDurations = completedBootstraps.flatMap((row) => row.started_at !== null && row.finished_at !== null && row.finished_at >= row.started_at ? [row.finished_at - row.started_at] : []);
 	return {
 		windowDays,
 		since: new Date(sinceMs).toISOString(),
@@ -91,7 +103,15 @@ function summarizeUserUnderstandingQuality(options = {}) {
 			total: recentDecisions.length,
 			acceptanceRate: rate(accepted, recentDecisions.length)
 		},
-		recall
+		recall,
+		quickUnderstanding: {
+			sourcesAuthorized: sourceRows.length,
+			sourcesCollected: sourceRows.filter((row) => row.last_collected_at !== null).length,
+			sourceCoverage: rate(sourceRows.filter((row) => row.last_collected_at !== null).length, sourceRows.length),
+			bootstrapJobs: bootstrapRows.length,
+			successfulBootstrapRate: rate(completedBootstraps.length, bootstrapRows.length),
+			medianBootstrapDurationMs: median(bootstrapDurations)
+		}
 	};
 }
 //#endregion

package/dist/src/tui/backends/embedded-backend.js

@@ -30,6 +30,7 @@ import { buildWorkflowChildTools } from "../../agent/workflow/workflow-child-too
 import { WorkflowRunService } from "../../workflows/service/workflow-run-service.js";
 import { WorkflowSessionBridge } from "../../workflows/service/workflow-session-bridge.js";
 import { ChatStreamMapper } from "../../gateway/chat-stream/mapper.js";
+import { getXopcCloudCatalogCoordinator } from "../../providers/xopc-cloud-catalog-coordinator.js";
 import { fuzzySearchWorkspaceFiles } from "../../gateway/workspace-file-search.js";
 import { sessionMetadataToTuiItem } from "../tui-session-format.js";
 import { buildTuiTranscriptTree, transcriptTreeEntryIdToRowNumber } from "../tui-transcript-tree.js";
@@ -148,9 +149,16 @@ var EmbeddedBackend = class {
 	}
 	async refreshXopcCloudModels() {
 		try {
-			const { XopcCloudModelSource } = await import("../../providers/xopc-cloud-model-source.js");
-			const result = await new XopcCloudModelSource().refresh();
-			if (result.status === "updated") log.info({ modelCount: result.modelCount }, `XOPC Cloud model catalog refreshed: ${result.modelCount} models`);
+			const readiness = await getXopcCloudCatalogCoordinator().ensure({
+				reason: "agent-run",
+				network: "if-empty",
+				timeoutMs: 1e4
+			});
+			if (!readiness.error) return;
+			log.warn({
+				errorMessage: readiness.error.message,
+				phase: "model_catalog_refresh"
+			}, `XOPC Cloud model catalog refresh failed: ${readiness.error.message}`);
 		} catch (err) {
 			const errorMessage = err instanceof Error ? err.message : String(err);
 			log.warn({