@xopcai/xopc 0.0.210 → 0.0.213

package/dist/src/gateway/service.js

@@ -28,11 +28,6 @@ import "../automations/index.js";
 import { ProjectService } from "../projects/project-service.js";
 import { resolveProjectAgentId } from "../projects/project-agent.js";
 import "../projects/index.js";
-import { sanitizeTunnelConfig } from "../tunnel/tunnel-config.js";
-import { wireTunnelEventsToGateway } from "../tunnel/gateway-lifecycle.js";
-import { buckets } from "./rate-limit/buckets.js";
-import { isGatewayStrictSecurityEnabled } from "./rate-limit/env-flags.js";
-import "./rate-limit/index.js";
 import { TaskApplicationService } from "../tasks/task-application-service.js";
 import { ProactiveScenarioService } from "../proactive/scenarios/service.js";
 import { TaskOutboxDispatcher } from "../tasks/task-outbox-dispatcher.js";
@@ -61,13 +56,14 @@ import { DiscussionLiveWorker } from "../discussions/live-worker.js";
 import { DiscussionOrganizerWorker } from "../discussions/organizer-worker.js";
 import { DiscussionSealer } from "../discussions/sealer.js";
 import "../discussions/index.js";
-import { EndpointToolRuntime } from "../endpoint-tools/runtime.js";
-import "../endpoint-tools/index.js";
+import { ManagedComposioEventPoller } from "../connectors/composio-managed-events.js";
 import { startConnectedKnowledgeCoordinator } from "../knowledge/coordinator.js";
 import "../knowledge/index.js";
 import { startConnectorLearningCoordinator } from "../connectors/learning-coordinator.js";
 import { ConnectedSourceChangePublisher } from "../connectors/source-change-publisher.js";
 import { startConnectorSupervisor } from "../connectors/supervisor.js";
+import { EndpointToolRuntime } from "../endpoint-tools/runtime.js";
+import "../endpoint-tools/index.js";
 import { assertGatewayAuthConfigured, extractToken, resolveGatewayAuth, validateToken } from "./auth.js";
 import { prepareAutomationAgentSession } from "./automation-agent-session.js";
 import { reconcileDreamingAutomations } from "./dreaming-automation-reconciler.js";
@@ -83,11 +79,17 @@ import "./heartbeat/index.js";
 import { EphemeralSideChatManager } from "./side-chat/manager.js";
 import { SideChatRunService } from "./side-chat/run-service.js";
 import "./side-chat/index.js";
+import { wireTunnelEventsToGateway } from "../tunnel/gateway-lifecycle.js";
 import { stopTailscaleExposure } from "./tailscale-lifecycle.js";
 import { getExposureManager } from "../remote-access/exposure-manager.js";
+import { sanitizeTunnelConfig } from "../tunnel/tunnel-config.js";
 import { assertGatewayAuthNotKnownWeak } from "./security/known-weak-secrets.js";
+import { buckets } from "./rate-limit/buckets.js";
+import { isGatewayStrictSecurityEnabled } from "./rate-limit/env-flags.js";
+import "./rate-limit/index.js";
 import { assertGatewayRuntimeConfig } from "./runtime-config.js";
 import { auditGatewayConfig } from "./security/audit.js";
+import { getXopcCloudCatalogCoordinator } from "../providers/xopc-cloud-catalog-coordinator.js";
 import { ModelCatalogSyncService } from "../providers/model-catalog-sync-service.js";
 import { runBootstrapMigrationsSync } from "../migrations/runner.js";
 import { MobileNotificationService } from "../mobile/notification-service.js";
@@ -182,6 +184,7 @@ var GatewayService = class {
 	workflowRunServiceInstance = null;
 	taskRunDispatcher = null;
 	taskRunDispatchTimer = null;
+	managedComposioEventPoller;
 	mobileNotifications = null;
 	connectorSupervisor = null;
 	connectorLearningCoordinator = null;
@@ -794,6 +797,20 @@ var GatewayService = class {
 		this.startupTrace = createGatewayStartupTrace();
 		this.readiness.markStarting(this.startTime);
 		const trace = this.startupTrace;
+		const catalogCoordinator = getXopcCloudCatalogCoordinator();
+		const catalog = await trace.measure("model-catalog.hydrate", () => catalogCoordinator.hydrate());
+		if (getAgentDefaultModelRef(this.config)?.startsWith("xopc-cloud/") && catalog.source === "none") {
+			const readiness = await trace.measure("model-catalog.initial-refresh", () => catalogCoordinator.ensure({
+				reason: "startup",
+				network: "if-empty",
+				timeoutMs: 1e4
+			}));
+			if (readiness.error) log.warn({
+				provider: "xopc-cloud",
+				phase: "catalog_refresh",
+				errorMessage: readiness.error.message
+			}, `Initial XOPC Cloud catalog refresh failed: ${readiness.error.message}`);
+		}
 		registerClarifyBridge(this.agentRunner.getClarifyBridge());
 		this.ensureAgentService();
 		this.agentRunner.recoverSessionInputs();
@@ -926,6 +943,17 @@ var GatewayService = class {
 			getMemoryManager: () => this.agentService.getMemoryManager(),
 			emit: (type, payload) => this.emit(type, payload)
 		});
+		this.managedComposioEventPoller = new ManagedComposioEventPoller({
+			getConfig: () => this.config,
+			triggerAutomation: (event) => this.automationService.triggerEvent(event),
+			requestLearning: (toolkit) => {
+				this.requestConnectorLearningForToolkit(toolkit);
+			},
+			setLearningPaused: (connectionId, paused) => {
+				this.setConnectorLearningPaused(connectionId, paused);
+			}
+		});
+		this.managedComposioEventPoller.start();
 		this.connectedSourceChangePublisher = new ConnectedSourceChangePublisher(this.proactive);
 		this.connectedSourceChangePublisher.start();
 		this.connectedKnowledgeCoordinator = startConnectedKnowledgeCoordinator({ resolvePipelineOptions: () => ({
@@ -1081,6 +1109,8 @@ var GatewayService = class {
 		this.connectorSupervisor = null;
 		this.connectorLearningCoordinator?.stop();
 		this.connectorLearningCoordinator = null;
+		this.managedComposioEventPoller?.stop();
+		this.managedComposioEventPoller = void 0;
 		this.connectedSourceChangePublisher?.stop();
 		this.connectedSourceChangePublisher = null;
 		this.connectedKnowledgeCoordinator?.stop();

package/dist/src/knowledge/connected-understanding-pipeline.d.ts

@@ -13,5 +13,5 @@ export declare function renderConnectedObservation(observation: ClaimObservation
 export declare class ConnectedUnderstandingPipeline {
     private readonly memoryManager;
     constructor(memoryManager: MemoryManager);
-    process(sourceInstanceId: string, connectorId: string, agentId: string): Promise<UnderstandingReviewResult>;
+    process(agentId: string): Promise<UnderstandingReviewResult>;
 }

package/dist/src/knowledge/connected-understanding-pipeline.js

@@ -1,5 +1,6 @@
 import { listKnowledgeSourceItems } from "../storage/sqlite/knowledge-repository.js";
 import "../storage/sqlite/index.js";
+import { clusterUnderstandingSignals } from "../user-context/sources/signal-clustering.js";
 //#region src/knowledge/connected-understanding-pipeline.ts
 function logicalEventKey(item) {
 	const value = item.metadata.logicalEventKey;
@@ -10,6 +11,59 @@ function eventTime(item) {
 	const value = Date.parse(item.occurredAt);
 	return Number.isFinite(value) ? value : void 0;
 }
+function normalizedRecord(item) {
+	if (!item.normalizedText) return {};
+	try {
+		const value = JSON.parse(item.normalizedText);
+		return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+	} catch {
+		return {};
+	}
+}
+function textField(record, ...fields) {
+	for (const field of fields) {
+		const value = record[field];
+		if (typeof value === "string" && value.trim()) return value.trim();
+		if (value && typeof value === "object" && !Array.isArray(value)) {
+			const nested = value;
+			for (const nestedField of [
+				"name",
+				"full_name",
+				"fullName",
+				"title"
+			]) {
+				const nestedValue = nested[nestedField];
+				if (typeof nestedValue === "string" && nestedValue.trim()) return nestedValue.trim();
+			}
+		}
+	}
+}
+function normalizeConversationTitle(value) {
+	return value.replace(/^(?:(?:re|fwd?|回复|转发)\s*[:：]\s*)+/i, "").trim();
+}
+function projectSignal(item) {
+	if (item.metadata.actorAttributed !== true) return void 0;
+	const observationKind = item.metadata.observationKind;
+	if (![
+		"activity",
+		"message",
+		"calendar_event",
+		"external_task",
+		"document_metadata"
+	].includes(String(observationKind))) return;
+	const title = textField(normalizedRecord(item), "subject", "title", "repository", "project", "fullName", "full_name", "name");
+	const subjectKey = typeof item.metadata.subjectKey === "string" && item.metadata.subjectKey.trim() ? item.metadata.subjectKey.trim() : void 0;
+	const displayTitle = title ? normalizeConversationTitle(title) : subjectKey;
+	if (!displayTitle) return void 0;
+	return {
+		evidenceRef: item.id,
+		sourceId: item.sourceInstanceId,
+		title: displayTitle,
+		group: typeof item.metadata.toolkit === "string" ? item.metadata.toolkit : void 0,
+		subjectKey,
+		occurredAt: eventTime(item)
+	};
+}
 function recent(items, days) {
 	const now = Date.now();
 	const cutoff = now - days * 864e5;
@@ -86,30 +140,24 @@ function routineObservations(items) {
 	});
 }
 function projectObservations(items) {
-	const grouped = /* @__PURE__ */ new Map();
-	for (const item of recent(items, 60)) {
-		if (item.metadata.observationKind !== "activity" || item.metadata.actorAttributed !== true) continue;
-		const subject = typeof item.metadata.subjectKey === "string" ? item.metadata.subjectKey.trim() : "";
-		if (!subject) continue;
-		const entry = grouped.get(subject.toLowerCase()) ?? {
-			label: subject,
-			events: /* @__PURE__ */ new Map()
-		};
-		const events = entry.events;
-		const eventKey = logicalEventKey(item);
-		if (!events.has(eventKey)) events.set(eventKey, item);
-		grouped.set(subject.toLowerCase(), entry);
-	}
-	return [...grouped.entries()].sort((left, right) => right[1].events.size - left[1].events.size).slice(0, 8).map(([, entry]) => {
-		const { label: subject, events } = entry;
-		return {
+	const recentItems = recent(items, 60);
+	const byId = new Map(recentItems.map((item) => [item.id, item]));
+	return clusterUnderstandingSignals(recentItems.map(projectSignal).filter((signal) => Boolean(signal))).flatMap((cluster) => {
+		const events = /* @__PURE__ */ new Map();
+		for (const signal of cluster.signals) {
+			const item = byId.get(signal.evidenceRef);
+			const eventKey = item && logicalEventKey(item);
+			if (item && eventKey && !events.has(eventKey)) events.set(eventKey, item);
+		}
+		if (![...events.values()].some((item) => item.itemType !== "calendar_event")) return [];
+		return [{
 			class: "project",
-			key: `project:${subject.toLocaleLowerCase()}`,
-			value: { label: subject },
+			key: `project:${cluster.key}`,
+			value: { label: cluster.title },
 			items: [...events.values()],
 			windowDays: 60
-		};
-	});
+		}];
+	}).sort((left, right) => right.items.length - left.items.length).slice(0, 8);
 }
 function deriveConnectedClaimObservations(items) {
 	const active = items.filter((item) => !item.deletedAt && item.synthesisPipeline === "connected_knowledge" && item.sensitivity !== "secret" && item.sensitivity !== "regulated" && item.metadata.observationKind !== "inventory");
@@ -178,9 +226,9 @@ var ConnectedUnderstandingPipeline = class {
 	constructor(memoryManager) {
 		this.memoryManager = memoryManager;
 	}
-	async process(sourceInstanceId, connectorId, agentId) {
+	async process(agentId) {
 		const observations = deriveConnectedClaimObservations(listKnowledgeSourceItems({
-			sourceInstanceId,
+			agentId,
 			includeDeleted: false,
 			limit: 500
 		}));
@@ -193,6 +241,7 @@ var ConnectedUnderstandingPipeline = class {
 		};
 		for (const observation of observations) {
 			if (!isDurableObservation(observation)) continue;
+			const sourceInstanceIds = [...new Set(observation.items.map((item) => item.sourceInstanceId))];
 			const result = await this.memoryManager.applyUnderstandingCandidates([renderConnectedObservation(observation)], {
 				sourceItemIds: observation.items.map((item) => item.id).slice(0, 20),
 				sourceText: JSON.stringify({
@@ -201,8 +250,8 @@ var ConnectedUnderstandingPipeline = class {
 					windowDays: observation.windowDays
 				}),
 				source: {
-					provider: connectorId,
-					sourceInstanceId
+					provider: "connected-sources",
+					...sourceInstanceIds.length === 1 ? { sourceInstanceId: sourceInstanceIds[0] } : {}
 				},
 				reviewSource: "background"
 			});

package/dist/src/knowledge/ingestion-service.js

@@ -4,6 +4,7 @@ import { finishKnowledgeSyncRun, getKnowledgeSourceCursor, listKnowledgeSourceIt
 //#region src/knowledge/ingestion-service.ts
 init_logger();
 const log = createLogger("KnowledgeIngestion");
+const MAX_PULL_PAGES = 20;
 function deletionInputs(instanceId, collectionScope, snapshotExternalIds) {
 	if (!snapshotExternalIds) return [];
 	const seen = new Set(snapshotExternalIds);
@@ -93,29 +94,46 @@ var KnowledgeIngestionService = class {
 		const controller = params.signal ? null : new AbortController();
 		const signal = params.signal ?? controller.signal;
 		try {
-			const pulled = await adapter.pull({
-				instanceId: params.instanceId,
-				collectionScope: params.collectionScope,
-				cursor: cursorBefore,
-				windowStart: params.windowStart,
-				signal
-			});
-			const tombstones = deletionInputs(params.instanceId, params.collectionScope, pulled.snapshotExternalIds);
-			const stored = upsertKnowledgeSourceItems([...pulled.items, ...tombstones]);
-			this.state.setCursor(params.instanceId, params.collectionScope, pulled.nextCursor);
+			const items = [];
+			const warnings = [];
+			const snapshotExternalIds = [];
+			let snapshotComplete = true;
+			let pullCursor = cursorBefore;
+			let cursorAfter = cursorBefore;
+			for (let page = 0; page < MAX_PULL_PAGES; page += 1) {
+				const pulled = await adapter.pull({
+					instanceId: params.instanceId,
+					collectionScope: params.collectionScope,
+					cursor: pullCursor,
+					windowStart: params.windowStart,
+					signal
+				});
+				items.push(...pulled.items);
+				warnings.push(...pulled.warnings);
+				if (pulled.snapshotExternalIds) snapshotExternalIds.push(...pulled.snapshotExternalIds);
+				else snapshotComplete = false;
+				cursorAfter = pulled.nextCursor;
+				if (!pulled.hasMore) break;
+				if (!pulled.nextCursor || pulled.nextCursor === pullCursor) throw new Error("Knowledge source returned an invalid pagination cursor.");
+				if (page === MAX_PULL_PAGES - 1) throw new Error(`Knowledge source exceeded the ${MAX_PULL_PAGES}-page safety limit.`);
+				pullCursor = pulled.nextCursor;
+			}
+			const tombstones = deletionInputs(params.instanceId, params.collectionScope, snapshotComplete ? snapshotExternalIds : void 0);
+			const stored = upsertKnowledgeSourceItems([...items, ...tombstones]);
+			this.state.setCursor(params.instanceId, params.collectionScope, cursorAfter);
 			const completed = finishKnowledgeSyncRun({
 				runId: run.id,
-				status: pulled.warnings.length > 0 ? "partial" : "succeeded",
-				cursorAfter: pulled.nextCursor,
-				itemsSeen: pulled.items.length,
+				status: warnings.length > 0 ? "partial" : "succeeded",
+				cursorAfter,
+				itemsSeen: items.length,
 				itemsCreated: stored.created,
 				itemsUpdated: stored.updated,
-				warnings: pulled.warnings
+				warnings
 			});
 			log.info({
 				runId: run.id,
 				sourceInstanceId: params.instanceId,
-				itemsSeen: pulled.items.length,
+				itemsSeen: items.length,
 				itemsCreated: stored.created,
 				itemsUpdated: stored.updated,
 				itemsDeleted: tombstones.length

package/dist/src/knowledge/types.d.ts

@@ -83,6 +83,8 @@ export interface KnowledgePullInput {
 export interface KnowledgePullResult {
     items: KnowledgeSourceItemInput[];
     nextCursor?: string;
+    /** True only when nextCursor is a required continuation page, not a committed checkpoint. */
+    hasMore?: boolean;
     warnings: string[];
     /** All active external ids observed during a complete source snapshot. Omit for partial/incremental-only pulls. */
     snapshotExternalIds?: string[];

package/dist/src/media-understanding/audio-transcription-runner.d.ts

@@ -41,6 +41,8 @@ export interface RunAudioTranscriptionResult {
         text: string;
         provider: string;
         model?: string;
+        language?: string;
+        durationSeconds?: number;
     }>;
     decision: MediaUnderstandingDecision;
 }

package/dist/src/media-understanding/audio-transcription-runner.js

@@ -25,7 +25,9 @@ async function runAudioTranscription(options) {
 		attachmentIndex: entry.attachmentIndex,
 		text: entry.text,
 		provider: entry.provider,
-		...entry.model ? { model: entry.model } : {}
+		...entry.model ? { model: entry.model } : {},
+		...entry.language ? { language: entry.language } : {},
+		...entry.durationSeconds !== void 0 ? { durationSeconds: entry.durationSeconds } : {}
 	}));
 	return {
 		transcript: outputs.length === 0 ? void 0 : outputs.slice().sort((a, b) => a.attachmentIndex - b.attachmentIndex).map((o) => o.text).join("\n").trim() || void 0,

package/dist/src/media-understanding/runner.js

@@ -116,7 +116,9 @@ async function runCapability(options) {
 					attachmentIndex: attachment.attachmentIndex,
 					text,
 					provider: provider.id,
-					model: callResult.model
+					model: callResult.model,
+					...callResult.language ? { language: callResult.language } : {},
+					...callResult.durationSeconds !== void 0 ? { durationSeconds: callResult.durationSeconds } : {}
 				});
 				break;
 			} catch (error) {

package/dist/src/media-understanding/types.d.ts

@@ -63,6 +63,8 @@ export interface MediaUnderstandingOutput {
     text: string;
     provider: string;
     model?: string;
+    language?: string;
+    durationSeconds?: number;
 }
 export interface MediaUnderstandingModelDecision {
     provider?: string;

package/dist/src/notes/note-attachment-sync.js

@@ -8,7 +8,7 @@ function partitionAttachmentsByReference(note) {
 	const attachments = note.attachments ?? [];
 	const kept = [];
 	const removed = [];
-	for (const attachment of attachments) if (referenced.has(attachment.id)) kept.push(attachment);
+	for (const attachment of attachments) if (attachment.retainWithoutReference || referenced.has(attachment.id)) kept.push(attachment);
 	else removed.push(attachment);
 	return {
 		kept,

package/dist/src/notes/service.d.ts

@@ -48,6 +48,7 @@ export declare class NotesService {
         buffer: Buffer;
         mimeType: string;
         duration?: number;
+        retainWithoutReference?: boolean;
     }): Promise<NoteAttachment | null>;
     removeAttachment(noteId: string, attachmentId: string): Promise<boolean>;
     getAttachmentPath(noteId: string, attachmentId: string): Promise<{

package/dist/src/notes/service.js

@@ -474,7 +474,8 @@ var NotesService = class {
 			fileName: file.name,
 			size,
 			relativePath,
-			duration: file.duration
+			duration: file.duration,
+			retainWithoutReference: file.retainWithoutReference
 		};
 		const attachments = [...note.attachments || [], attachment];
 		const kind = note.kind === "thought" && attachment.type === "audio" ? "voice" : note.kind === "thought" ? "media" : note.kind;

package/dist/src/notes/types.d.ts

@@ -45,6 +45,8 @@ export interface NoteAttachment {
     relativePath: string;
     transcript?: string;
     duration?: number;
+    /** Retained by a structured note feature even when absent from user-owned Markdown. */
+    retainWithoutReference?: boolean;
 }
 export interface NoteAiMeta {
     summary?: string;

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

@@ -0,0 +1,9 @@
+import type { CatalogSource } from './model-catalog-types.js';
+export declare class ModelCatalogPersistence {
+    private readonly path;
+    constructor(path?: string);
+    loadSync(): CatalogSource | undefined;
+    save(source: CatalogSource): Promise<void>;
+    clear(): Promise<void>;
+    clearSync(): void;
+}

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

@@ -0,0 +1,172 @@
+import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+import { init_paths_state, resolveXopcCloudCatalogCachePath } from "../config/paths-state.js";
+import { init_write_file_atomic, writeTextAtomic } from "../infra/write-file-atomic.js";
+import { readFileSync, rmSync } from "node:fs";
+import { z } from "zod";
+import { rm } from "node:fs/promises";
+//#region src/providers/model-catalog-persistence.ts
+var MAX_CATALOG_BYTES, imageGenerationSchema, sttSchema, ttsSchema, catalogModelSchema, persistedCatalogSchema, ModelCatalogPersistence;
+var init_model_catalog_persistence = __esmMin((() => {
+	init_paths_state();
+	init_write_file_atomic();
+	MAX_CATALOG_BYTES = 4 * 1024 * 1024;
+	imageGenerationSchema = z.object({
+		maxCount: z.number().int().positive(),
+		sizes: z.array(z.string()),
+		aspectRatios: z.array(z.string()).optional(),
+		qualities: z.array(z.enum([
+			"low",
+			"medium",
+			"high",
+			"auto"
+		])),
+		formats: z.array(z.enum([
+			"png",
+			"jpeg",
+			"webp"
+		])),
+		backgrounds: z.array(z.enum([
+			"transparent",
+			"opaque",
+			"auto"
+		])),
+		maxInputImages: z.number().int().nonnegative()
+	}).strict();
+	sttSchema = z.object({
+		inputFormats: z.array(z.string()),
+		maxBytes: z.number().int().nonnegative(),
+		maxDurationSeconds: z.number().int().nonnegative(),
+		languages: z.array(z.string()),
+		languageHint: z.boolean(),
+		prompt: z.boolean(),
+		timestamps: z.array(z.enum(["segment", "word"])),
+		diarization: z.boolean()
+	}).strict();
+	ttsSchema = z.object({
+		maxCharacters: z.number().int().nonnegative(),
+		languages: z.array(z.string()),
+		outputFormats: z.array(z.enum([
+			"mp3",
+			"opus",
+			"aac",
+			"flac",
+			"wav",
+			"pcm"
+		])),
+		streaming: z.boolean(),
+		speed: z.boolean(),
+		pitch: z.boolean(),
+		instructions: z.boolean(),
+		defaultVoice: z.string().optional()
+	}).strict();
+	catalogModelSchema = z.object({
+		id: z.string().min(1),
+		name: z.string().min(1),
+		availability: z.enum(["available", "unavailable"]),
+		kind: z.enum([
+			"language",
+			"image",
+			"stt",
+			"tts"
+		]),
+		input: z.array(z.enum([
+			"text",
+			"image",
+			"audio"
+		])),
+		output: z.array(z.enum([
+			"text",
+			"image",
+			"audio"
+		])),
+		operations: z.array(z.enum([
+			"chat.completions",
+			"responses",
+			"images.generate",
+			"images.edit",
+			"audio.transcription",
+			"audio.speech"
+		])),
+		reasoning: z.boolean(),
+		contextWindow: z.number().int().positive(),
+		maxOutputTokens: z.number().int().positive().nullable(),
+		stability: z.enum([
+			"stable",
+			"preview",
+			"deprecated"
+		]).optional(),
+		priority: z.number().optional(),
+		tier: z.string().optional(),
+		bestEffort: z.boolean().optional(),
+		imageGeneration: imageGenerationSchema.optional(),
+		stt: sttSchema.optional(),
+		tts: ttsSchema.optional()
+	}).strict();
+	persistedCatalogSchema = z.object({
+		schemaVersion: z.literal(1),
+		providerId: z.literal("xopc-cloud"),
+		catalogVersion: z.string().nullable(),
+		fetchedAt: z.number().int().nonnegative(),
+		baseUrl: z.string().url(),
+		api: z.enum(["openai-completions", "openai-responses"]),
+		recommendedModel: z.string().nullable(),
+		recommended: z.record(z.enum([
+			"vision",
+			"image-generation",
+			"stt",
+			"tts"
+		]), z.string()).optional(),
+		models: z.array(catalogModelSchema)
+	}).strict();
+	ModelCatalogPersistence = class {
+		constructor(path = resolveXopcCloudCatalogCachePath()) {
+			this.path = path;
+		}
+		loadSync() {
+			try {
+				const raw = readFileSync(this.path, "utf8");
+				if (Buffer.byteLength(raw) > MAX_CATALOG_BYTES) return void 0;
+				const parsed = persistedCatalogSchema.safeParse(JSON.parse(raw));
+				if (!parsed.success) return void 0;
+				return {
+					providerId: parsed.data.providerId,
+					baseUrl: parsed.data.baseUrl,
+					api: parsed.data.api,
+					etag: parsed.data.catalogVersion,
+					recommendedModel: parsed.data.recommendedModel,
+					recommended: parsed.data.recommended,
+					lastSuccessAt: parsed.data.fetchedAt,
+					models: parsed.data.models
+				};
+			} catch {
+				return;
+			}
+		}
+		async save(source) {
+			if (source.providerId !== "xopc-cloud") throw new Error(`Cannot persist catalog for provider ${source.providerId}`);
+			const payload = persistedCatalogSchema.parse({
+				schemaVersion: 1,
+				providerId: source.providerId,
+				catalogVersion: source.etag,
+				fetchedAt: source.lastSuccessAt,
+				baseUrl: source.baseUrl,
+				api: source.api,
+				recommendedModel: source.recommendedModel,
+				recommended: source.recommended,
+				models: source.models
+			});
+			const serialized = `${JSON.stringify(payload, null, 2)}\n`;
+			if (Buffer.byteLength(serialized) > MAX_CATALOG_BYTES) throw new Error("XOPC Cloud model catalog exceeds the 4 MiB cache limit");
+			await writeTextAtomic(this.path, serialized, { mode: 384 });
+		}
+		async clear() {
+			await rm(this.path, { force: true });
+		}
+		clearSync() {
+			rmSync(this.path, { force: true });
+		}
+	};
+}));
+//#endregion
+init_model_catalog_persistence();
+export { ModelCatalogPersistence, init_model_catalog_persistence };

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

@@ -0,0 +1,2 @@
+import type { CatalogModel } from './model-catalog-store.js';
+export declare function compareCatalogModels(left: CatalogModel, right: CatalogModel, recommendedModel?: string): number;

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

@@ -0,0 +1,17 @@
+//#region src/providers/model-catalog-ranking.ts
+const STABILITY_ORDER = {
+	stable: 0,
+	preview: 1,
+	deprecated: 2
+};
+function compareCatalogModels(left, right, recommendedModel) {
+	if (left.id === recommendedModel) return -1;
+	if (right.id === recommendedModel) return 1;
+	const stability = STABILITY_ORDER[left.stability ?? "stable"] - STABILITY_ORDER[right.stability ?? "stable"];
+	if (stability !== 0) return stability;
+	if (left.bestEffort !== right.bestEffort) return left.bestEffort ? 1 : -1;
+	if ((left.priority ?? 0) !== (right.priority ?? 0)) return (right.priority ?? 0) - (left.priority ?? 0);
+	return left.id.localeCompare(right.id);
+}
+//#endregion
+export { compareCatalogModels };