@xopcai/xopc 0.0.208 → 0.0.211

package/dist/src/gateway/hono/routes/session-input-handler.d.ts

@@ -60,3 +60,63 @@ export declare function submitSessionInput(c: Context, deps: AuthenticatedRouteD
         };
     };
 }, 202, "json">)>;
+export declare function replaceLatestSessionTurn(c: Context, deps: AuthenticatedRouteDeps, sessionKey: string, targetTurnId: string): Promise<(Response & import("hono").TypedResponse<{
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}, 401, "json">) | (Response & import("hono").TypedResponse<{
+    ok: false;
+    error: {
+        code: "TARGET_NOT_FOUND" | "NOT_LATEST" | "SESSION_BUSY" | "BAD_REQUEST";
+        message: string;
+    };
+}, 400 | 404 | 409, "json">) | (Response & import("hono").TypedResponse<{
+    ok: true;
+    payload: {
+        sessionKey: string;
+        ok: true;
+        effectiveDelivery: "next";
+        state: {
+            sessionKey: string;
+            revision: number;
+            activeRunId?: string;
+            activeInputId?: string;
+            inputs: {
+                id: string;
+                sessionKey: string;
+                clientMessageId: string;
+                requestedDelivery: import("../../../storage/sqlite/session-input-repository.js").SessionInputDelivery;
+                effectiveDelivery: import("../../../storage/sqlite/session-input-repository.js").SessionInputDelivery;
+                status: import("../../../storage/sqlite/session-input-repository.js").SessionInputStatus;
+                content: string;
+                attachments?: import("hono/dist/types/utils/types.js").JSONValue[];
+                thinking?: string;
+                origin: {
+                    type: "endpoint";
+                    endpointId: string;
+                } | {
+                    type: "channel";
+                    channel: string;
+                } | {
+                    type: "system";
+                    source: "cli" | "workflow" | "automation" | "heartbeat" | "internal";
+                };
+                position: number;
+                targetRunId?: string;
+                runId?: string;
+                version: number;
+                error?: string;
+                createdAtMs: number;
+                updatedAtMs: number;
+            }[];
+        };
+    };
+}, 202, "json">)>;

package/dist/src/gateway/hono/routes/session-input-handler.js

@@ -78,5 +78,79 @@ async function submitSessionInput(c, deps, sessionKey) {
 		}
 	}, 202);
 }
+async function replaceLatestSessionTurn(c, deps, sessionKey, targetTurnId) {
+	const body = await c.req.json().catch(() => null);
+	if (!body || !sessionKey || !targetTurnId) return c.json({
+		ok: false,
+		error: {
+			code: "BAD_REQUEST",
+			message: "Invalid request"
+		}
+	}, 400);
+	const attachments = Array.isArray(body.attachments) ? body.attachments : void 0;
+	const content = typeof body.content === "string" ? body.content : "";
+	const contentError = validateWebchatContent(content);
+	if (contentError) return c.json({
+		ok: false,
+		error: {
+			code: "BAD_REQUEST",
+			message: contentError
+		}
+	}, 400);
+	const attachmentError = validateWebchatAttachments(attachments);
+	if (attachmentError) return c.json({
+		ok: false,
+		error: {
+			code: "BAD_REQUEST",
+			message: attachmentError
+		}
+	}, 400);
+	const origin = endpointTurnClaimSchema.safeParse(body.origin);
+	if (!origin.success) return c.json({
+		ok: false,
+		error: {
+			code: "BAD_REQUEST",
+			message: "Invalid endpoint origin"
+		}
+	}, 400);
+	if (!deps.service.endpointTools.registry.verifyTurnClaim(origin.data.endpointId, origin.data.token)) return c.json({
+		ok: false,
+		error: {
+			code: "INVALID_ENDPOINT",
+			message: "Endpoint connection is not active"
+		}
+	}, 401);
+	const result = await deps.service.replaceLatestSessionTurn({
+		sessionKey,
+		targetTurnId,
+		clientMessageId: typeof body.clientMessageId === "string" ? body.clientMessageId : "",
+		delivery: "next",
+		content,
+		attachments,
+		thinking: typeof body.thinking === "string" ? body.thinking : void 0,
+		origin: {
+			type: "endpoint",
+			endpointId: origin.data.endpointId
+		}
+	});
+	if (result.ok === false) {
+		const status = result.code === "TARGET_NOT_FOUND" ? 404 : result.code === "BAD_REQUEST" ? 400 : 409;
+		const message = result.code === "NOT_LATEST" ? "Only the latest user turn can be replaced" : result.code === "SESSION_BUSY" ? "Session has pending input" : result.code === "TARGET_NOT_FOUND" ? "User turn was not found" : "Replacement input was not accepted";
+		return c.json({
+			ok: false,
+			error: {
+				code: result.code,
+				message
+			}
+		}, status);
+	}
+	return c.json({
+		ok: true,
+		payload: {
+			...result,
+			sessionKey
+		}
+	}, 202);
+}
 //#endregion
-export { submitSessionInput };
+export { replaceLatestSessionTurn, submitSessionInput };

package/dist/src/gateway/hono/routes/understanding-sources.js

@@ -1,10 +1,13 @@
 import { deleteUnderstanding, listUnderstandingEvidence, listUnderstandings } from "../../../storage/sqlite/user-context-repository.js";
 import { getConnectorAccount } from "../../../storage/sqlite/connector-account-repository.js";
 import "../../../storage/sqlite/index.js";
+import { init_agent_scope, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
 import { deleteUserFocus, getUnderstandingSourceGrant, listUnderstandingSourceGrants, listUserFocuses, revokeUnderstandingSourceGrant, setUserFocusStatus } from "../../../user-context/sources/repository.js";
+import { listConnectedContentCandidates, readConnectedContent } from "../../../connectors/content-enrichment.js";
 import { getWorkDiscoveryService } from "./work-discovery.js";
 import { listUnderstandingSourceDefinitions } from "../../../user-context/sources/catalog.js";
 //#region src/gateway/hono/routes/understanding-sources.ts
+init_agent_scope();
 function stringField(body, field) {
 	if (!body || typeof body !== "object") return "";
 	const value = body[field];
@@ -39,6 +42,32 @@ function registerUnderstandingSourceRoutes(authenticated, deps) {
 		ok: true,
 		grants: listUnderstandingSourceGrants({ includeRevoked: c.req.query("includeRevoked") === "true" })
 	}));
+	authenticated.get("/api/understanding/sources/content-candidates", (c) => {
+		const agentId = resolveDefaultAgentId(deps.service.currentConfig);
+		return c.json({
+			ok: true,
+			candidates: listConnectedContentCandidates({ agentId })
+		});
+	});
+	authenticated.post("/api/understanding/sources/content-reads", limited, async (c) => {
+		const body = await c.req.json().catch(() => null);
+		const sourceItemIds = body && typeof body === "object" && Array.isArray(body.sourceItemIds) ? body.sourceItemIds.filter((value) => typeof value === "string") : [];
+		try {
+			const agentId = resolveDefaultAgentId(deps.service.currentConfig);
+			return c.json({
+				ok: true,
+				result: await readConnectedContent({
+					sourceItemIds,
+					agentId
+				})
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: error instanceof Error ? error.message : String(error)
+			}, 400);
+		}
+	});
 	authenticated.delete("/api/understanding/sources/grants/:grantId", limited, (c) => {
 		const current = getUnderstandingSourceGrant(c.req.param("grantId"));
 		const accountId = typeof current?.config.accountId === "string" ? current.config.accountId : void 0;

package/dist/src/gateway/hono/routes/voice.d.ts

@@ -1,6 +1,5 @@
 /**
- * Voice routes — POST /api/voice/transcriptions (multipart) and legacy
- * POST /api/voice/transcribe (JSON/base64).
+ * Voice routes — POST /api/voice/transcriptions (multipart).
  *
  * The endpoints share one execution path that:
  *   1. Runs the configured STT provider and fallback chain

package/dist/src/gateway/hono/routes/voice.js

@@ -6,7 +6,7 @@ import { speak } from "../../../voice/tts/speak-core.js";
 import { mergeTtsConfigFromAppConfig } from "../../../voice/tts/merge-config.js";
 import { getLocalVoiceRuntimeClient } from "../../../voice/local/runtime-client.js";
 import { resolveSttProviderConfigSlice } from "../../../voice/stt/config-slice.js";
-import { transcribe } from "../../../voice/stt/transcribe-core.js";
+import { STTTranscriptionError, transcribe } from "../../../voice/stt/transcribe-core.js";
 import { isSTTAvailable } from "../../../voice/stt/availability.js";
 import { mergeSttConfigFromAppConfig } from "../../../voice/stt/config.js";
 import "../../../voice/stt/index.js";
@@ -497,6 +497,7 @@ function registerVoiceRoutes(authenticated, deps) {
 					...detectedLanguage ? { language: detectedLanguage } : {},
 					provider: result.provider,
 					attempts: result.attempts,
+					...result.duration !== void 0 ? { durationSeconds: result.duration } : {},
 					latencyMs: Date.now() - startedAt
 				}
 			});
@@ -507,9 +508,22 @@ function registerVoiceRoutes(authenticated, deps) {
 				mimeType: input.mimeType,
 				fileName: input.fileName
 			}, `Voice transcription failed: ${msg}`);
+			if (error instanceof STTTranscriptionError) {
+				const status = error.reasonCode === "unsupported_format" ? 415 : error.reasonCode === "timeout" ? 504 : 502;
+				return c.json({
+					ok: false,
+					error: {
+						code: error.reasonCode,
+						message: `Transcription failed: ${msg}`
+					}
+				}, status);
+			}
 			return c.json({
 				ok: false,
-				error: { message: `Transcription failed: ${msg}` }
+				error: {
+					code: "provider_error",
+					message: `Transcription failed: ${msg}`
+				}
 			}, 502);
 		}
 	};
@@ -544,39 +558,6 @@ function registerVoiceRoutes(authenticated, deps) {
 			...language ? { language } : {}
 		});
 	});
-	/** Legacy JSON/base64 endpoint retained for mobile and external clients. */
-	authenticated.post("/api/voice/transcribe", strictRateLimitMiddleware, async (c) => {
-		let body = {};
-		try {
-			body = await c.req.json();
-		} catch {
-			return c.json({
-				ok: false,
-				error: { message: "Invalid JSON body" }
-			}, 400);
-		}
-		if (typeof body.audio !== "string" || !body.audio.trim()) return c.json({
-			ok: false,
-			error: { message: "Missing required field: audio (base64)" }
-		}, 400);
-		if (typeof body.mimeType !== "string" || !body.mimeType.trim()) return c.json({
-			ok: false,
-			error: { message: "Missing required field: mimeType" }
-		}, 400);
-		const encoded = body.audio.replace(/\s/g, "");
-		if (encoded.length % 4 === 1 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) return c.json({
-			ok: false,
-			error: { message: "Invalid base64 audio data" }
-		}, 400);
-		const language = typeof body.language === "string" && body.language.trim() ? body.language.trim() : void 0;
-		const fileName = typeof body.fileName === "string" && body.fileName.trim() ? body.fileName.trim() : `audio-${Date.now()}`;
-		return runTranscription(c, {
-			audioBuffer: Buffer.from(encoded, "base64"),
-			mimeType: body.mimeType.trim(),
-			fileName,
-			...language ? { language } : {}
-		});
-	});
 }
 //#endregion
 export { registerVoiceRoutes };

package/dist/src/gateway/rate-limit/buckets.d.ts

@@ -36,6 +36,7 @@ declare class BucketRegistry {
     private authFailureSignature?;
     private strictApiLimiter?;
     private chatApiLimiter?;
+    private mediaApiLimiter?;
     private taskApiLimiter?;
     private xopcCloudPollLimiter?;
     private channelApiLimiter?;
@@ -53,6 +54,8 @@ declare class BucketRegistry {
     strictApi(): RateLimiter;
     /** Interactive chat actions — 180 req / 60 s per client IP. */
     chatApi(): RateLimiter;
+    /** Durable media chunk uploads — 300 req / 60 s per client IP. */
+    mediaApi(): RateLimiter;
     /** Interactive task and board mutations — 300 req / 60 s per client IP. */
     taskApi(): RateLimiter;
     /** XOPC Cloud authorization polling — 60 req / 60 s per client IP. */

package/dist/src/gateway/rate-limit/buckets.js

@@ -48,6 +48,7 @@ var BucketRegistry = class {
 	authFailureSignature;
 	strictApiLimiter;
 	chatApiLimiter;
+	mediaApiLimiter;
 	taskApiLimiter;
 	xopcCloudPollLimiter;
 	channelApiLimiter;
@@ -90,6 +91,14 @@ var BucketRegistry = class {
 		});
 		return this.chatApiLimiter;
 	}
+	/** Durable media chunk uploads — 300 req / 60 s per client IP. */
+	mediaApi() {
+		if (!this.mediaApiLimiter) this.mediaApiLimiter = new RateLimiter({
+			maxRequests: 300,
+			windowMs: 6e4
+		});
+		return this.mediaApiLimiter;
+	}
 	/** Interactive task and board mutations — 300 req / 60 s per client IP. */
 	taskApi() {
 		if (!this.taskApiLimiter) this.taskApiLimiter = new RateLimiter({
@@ -151,6 +160,7 @@ var BucketRegistry = class {
 		this.authFailureLimiter?.destroy();
 		this.strictApiLimiter?.destroy();
 		this.chatApiLimiter?.destroy();
+		this.mediaApiLimiter?.destroy();
 		this.taskApiLimiter?.destroy();
 		this.xopcCloudPollLimiter?.destroy();
 		this.channelApiLimiter?.destroy();
@@ -161,6 +171,7 @@ var BucketRegistry = class {
 		this.authFailureLimiter = void 0;
 		this.strictApiLimiter = void 0;
 		this.chatApiLimiter = void 0;
+		this.mediaApiLimiter = void 0;
 		this.taskApiLimiter = void 0;
 		this.xopcCloudPollLimiter = void 0;
 		this.channelApiLimiter = void 0;
@@ -175,6 +186,7 @@ var BucketRegistry = class {
 		this.authFailureLimiter?.resetForTests();
 		this.strictApiLimiter?.resetForTests();
 		this.chatApiLimiter?.resetForTests();
+		this.mediaApiLimiter?.resetForTests();
 		this.taskApiLimiter?.resetForTests();
 		this.xopcCloudPollLimiter?.resetForTests();
 		this.channelApiLimiter?.resetForTests();

package/dist/src/gateway/service/agent-runner.d.ts

@@ -27,7 +27,7 @@ import type { SessionIndex } from '../../session/index.js';
 import type { ClarifyStreamEvent } from '../clarify-bridge.js';
 import { ClarifyBridge, type ClarifyBridgeRequest } from '../clarify-bridge.js';
 import type { UserTurnAttachment, UserTurnInput } from '../user-turn-input.js';
-import { SessionInputCoordinator, type SubmitSessionInput } from './session-input-coordinator.js';
+import { SessionInputCoordinator, type ReplaceLatestTurnInput, type SubmitSessionInput } from './session-input-coordinator.js';
 export interface GatewayAgentRunnerOptions {
     bus: MessageBus;
     sessionIndex: SessionIndex;
@@ -79,6 +79,14 @@ export declare class GatewayAgentRunner {
         ok: false;
         code: "BAD_REQUEST" | "QUEUE_FULL";
     }>;
+    replaceLatestSessionTurn(input: ReplaceLatestTurnInput): Promise<{
+        ok: true;
+        effectiveDelivery: "next";
+        state: import("../../storage/sqlite/session-input-repository.js").SessionInputState;
+    } | {
+        ok: false;
+        code: "BAD_REQUEST" | "TARGET_NOT_FOUND" | "NOT_LATEST" | "SESSION_BUSY";
+    }>;
     getSessionInputState(sessionKey: string): import("../../storage/sqlite/session-input-repository.js").SessionInputState;
     updateSessionInput(sessionKey: string, id: string, body: {
         version: number;

package/dist/src/gateway/service/agent-runner.js

@@ -115,6 +115,15 @@ var GatewayAgentRunner = class {
 	submitSessionInput(input) {
 		return this.inputs.submit(input);
 	}
+	replaceLatestSessionTurn(input) {
+		return this.inputs.replaceLatestTurn(input, async () => {
+			const activeRunId = this.activeWebchatRunBySession.get(input.sessionKey) ?? this.inputs.snapshot(input.sessionKey).activeRunId;
+			if (activeRunId) await this.abortAgentRun(activeRunId);
+			const { evictEmbeddedSessionRunner } = await import("../../agent/embedded/session-runner.js");
+			evictEmbeddedSessionRunner(input.sessionKey, "gateway_user_turn_replaced");
+			this.opts.getAgentService().evictSessionAgent(input.sessionKey);
+		});
+	}
 	getSessionInputState(sessionKey) {
 		return this.inputs.snapshot(sessionKey);
 	}

package/dist/src/gateway/service/session-input-coordinator.d.ts

@@ -10,6 +10,9 @@ export type SubmitSessionInput = {
     thinking?: string;
     origin: TurnOrigin;
 };
+export type ReplaceLatestTurnInput = SubmitSessionInput & {
+    targetTurnId: string;
+};
 export declare class SessionInputCoordinator {
     private readonly deps;
     private readonly draining;
@@ -33,6 +36,7 @@ export declare class SessionInputCoordinator {
     });
     snapshot(sessionKey: string): SessionInputState;
     private publish;
+    private runSubmissionExclusive;
     submit(input: SubmitSessionInput): Promise<{
         ok: true;
         effectiveDelivery: SessionInputDelivery;
@@ -41,6 +45,14 @@ export declare class SessionInputCoordinator {
         ok: false;
         code: 'BAD_REQUEST' | 'QUEUE_FULL';
     }>;
+    replaceLatestTurn(input: ReplaceLatestTurnInput, beforeReplace: () => Promise<void>): Promise<{
+        ok: true;
+        effectiveDelivery: 'next';
+        state: SessionInputState;
+    } | {
+        ok: false;
+        code: 'BAD_REQUEST' | 'TARGET_NOT_FOUND' | 'NOT_LATEST' | 'SESSION_BUSY';
+    }>;
     private submitLocked;
     drain(sessionKey: string): Promise<void>;
     update(sessionKey: string, id: string, body: {

package/dist/src/gateway/service/session-input-coordinator.js

@@ -1,7 +1,9 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { cancelQueuedSessionInput, claimNextSessionInput, findSessionInput, finishSessionInputRun, getSessionInputState, insertSessionInput, mutateQueuedSessionInput, recoverSessionInputState, setSessionInputStatus } from "../../storage/sqlite/session-input-repository.js";
+import { replaceLatestSessionTurnAndQueueInput, validateLatestSessionTurnTarget } from "../../storage/sqlite/session-turn-replace-repository.js";
 import "../../storage/sqlite/index.js";
+import { deleteMediaUrisNoLongerReferenced } from "../../media/session-references.js";
 import crypto from "node:crypto";
 //#region src/gateway/service/session-input-coordinator.ts
 init_logger();
@@ -21,8 +23,7 @@ var SessionInputCoordinator = class {
 		this.deps.emit("session.input-state", state);
 		return state;
 	}
-	async submit(input) {
-		const sessionKey = input.sessionKey.trim();
+	async runSubmissionExclusive(sessionKey, operation) {
 		const previous = this.submissionTails.get(sessionKey) ?? Promise.resolve();
 		let release = () => {};
 		const current = new Promise((resolve) => {
@@ -32,15 +33,71 @@ var SessionInputCoordinator = class {
 		this.submissionTails.set(sessionKey, tail);
 		await previous;
 		try {
-			return await this.submitLocked({
-				...input,
-				sessionKey
-			});
+			return await operation();
 		} finally {
 			release();
 			if (this.submissionTails.get(sessionKey) === tail) this.submissionTails.delete(sessionKey);
 		}
 	}
+	async submit(input) {
+		const sessionKey = input.sessionKey.trim();
+		return this.runSubmissionExclusive(sessionKey, () => this.submitLocked({
+			...input,
+			sessionKey
+		}));
+	}
+	async replaceLatestTurn(input, beforeReplace) {
+		const sessionKey = input.sessionKey.trim();
+		return this.runSubmissionExclusive(sessionKey, async () => {
+			const clientMessageId = input.clientMessageId.trim();
+			const content = input.content.trim();
+			const targetTurnId = input.targetTurnId.trim();
+			if (!sessionKey || !clientMessageId || !targetTurnId || !content && !input.attachments?.length) return {
+				ok: false,
+				code: "BAD_REQUEST"
+			};
+			if (!await this.deps.sessionExists(sessionKey)) return {
+				ok: false,
+				code: "BAD_REQUEST"
+			};
+			if (findSessionInput(sessionKey, clientMessageId)) return {
+				ok: true,
+				effectiveDelivery: "next",
+				state: this.snapshot(sessionKey)
+			};
+			const target = validateLatestSessionTurnTarget(sessionKey, targetTurnId);
+			if (target.ok === false) return target;
+			await beforeReplace();
+			const attachments = await this.deps.prepareAttachments(sessionKey, input.attachments);
+			const result = replaceLatestSessionTurnAndQueueInput({
+				sessionKey,
+				targetTurnId,
+				clientMessageId,
+				content,
+				attachments,
+				thinking: input.thinking,
+				origin: input.origin
+			});
+			if (result.ok === false) return result;
+			if (!result.idempotent) {
+				const replacement = {
+					role: "user",
+					content,
+					media: attachments
+				};
+				await deleteMediaUrisNoLongerReferenced({
+					removed: result.removedMessages,
+					remaining: [...result.remainingMessages, replacement]
+				});
+			}
+			this.drain(sessionKey);
+			return {
+				ok: true,
+				effectiveDelivery: "next",
+				state: this.publish(sessionKey)
+			};
+		});
+	}
 	async submitLocked(input) {
 		const sessionKey = input.sessionKey;
 		const clientMessageId = input.clientMessageId.trim();

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

@@ -140,6 +140,14 @@ export declare class GatewayService {
         ok: false;
         code: "BAD_REQUEST" | "QUEUE_FULL";
     }>;
+    replaceLatestSessionTurn(...args: Parameters<GatewayAgentRunner['replaceLatestSessionTurn']>): Promise<{
+        ok: true;
+        effectiveDelivery: "next";
+        state: import("../storage/sqlite/session-input-repository.js").SessionInputState;
+    } | {
+        ok: false;
+        code: "BAD_REQUEST" | "TARGET_NOT_FOUND" | "NOT_LATEST" | "SESSION_BUSY";
+    }>;
     getSessionInputState(...args: Parameters<GatewayAgentRunner['getSessionInputState']>): import("../storage/sqlite/session-input-repository.js").SessionInputState;
     updateSessionInput(...args: Parameters<GatewayAgentRunner['updateSessionInput']>): Promise<{
         ok: boolean;

package/dist/src/gateway/service.js

@@ -88,6 +88,7 @@ import { getExposureManager } from "../remote-access/exposure-manager.js";
 import { assertGatewayAuthNotKnownWeak } from "./security/known-weak-secrets.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";
@@ -641,6 +642,9 @@ var GatewayService = class {
 	submitSessionInput(...args) {
 		return this.agentRunner.submitSessionInput(...args);
 	}
+	replaceLatestSessionTurn(...args) {
+		return this.agentRunner.replaceLatestSessionTurn(...args);
+	}
 	getSessionInputState(...args) {
 		return this.agentRunner.getSessionInputState(...args);
 	}
@@ -791,6 +795,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();

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>;
 }