@xopcai/xopc 0.0.218 → 0.0.219

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

@@ -27,6 +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 type { AgentSourceContext, TurnContextRef } from '../../agent/source-context/types.js';
 import { SessionInputCoordinator, type ReplaceLatestTurnInput, type SubmitSessionInput } from './session-input-coordinator.js';
 export interface GatewayAgentRunnerOptions {
     bus: MessageBus;
@@ -39,6 +40,7 @@ export interface GatewayAgentRunnerOptions {
     emit: (type: string, payload: unknown) => void;
     publishRealtime: (topic: string, event: string, data: unknown) => void;
     completeRealtimeTopic: (topic: string) => void;
+    resolveTurnContext: (ref: TurnContextRef) => Promise<AgentSourceContext | null>;
 }
 export declare class GatewayAgentRunner {
     private readonly opts;
@@ -64,6 +66,7 @@ export declare class GatewayAgentRunner {
     runAgent(message: string, channel: string, chatId: string, origin: TurnOrigin, attachments?: UserTurnAttachment[], thinking?: string, runOptions?: {
         signal?: AbortSignal;
         runId?: string;
+        sourceContexts?: AgentSourceContext[];
     }): AsyncGenerator<{
         type: string;
         [key: string]: unknown;
@@ -77,7 +80,7 @@ export declare class GatewayAgentRunner {
         state: import("../../storage/sqlite/session-input-repository.js").SessionInputState;
     } | {
         ok: false;
-        code: "BAD_REQUEST" | "QUEUE_FULL";
+        code: "BAD_REQUEST" | "QUEUE_FULL" | "CONTEXT_UNAVAILABLE";
     }>;
     replaceLatestSessionTurn(input: ReplaceLatestTurnInput): Promise<{
         ok: true;
@@ -85,18 +88,20 @@ export declare class GatewayAgentRunner {
         state: import("../../storage/sqlite/session-input-repository.js").SessionInputState;
     } | {
         ok: false;
-        code: "BAD_REQUEST" | "TARGET_NOT_FOUND" | "NOT_LATEST" | "SESSION_BUSY";
+        code: "BAD_REQUEST" | "TARGET_NOT_FOUND" | "NOT_LATEST" | "SESSION_BUSY" | "CONTEXT_UNAVAILABLE";
     }>;
     getSessionInputState(sessionKey: string): import("../../storage/sqlite/session-input-repository.js").SessionInputState;
     updateSessionInput(sessionKey: string, id: string, body: {
         version: number;
         content?: string;
         attachments?: UserTurnAttachment[];
+        contextRefs?: TurnContextRef[];
         thinking?: string;
         position?: number;
     }): Promise<{
         ok: boolean;
         state: import("../../storage/sqlite/session-input-repository.js").SessionInputState;
+        contextUnavailable?: boolean;
     }>;
     removeSessionInput(sessionKey: string, id: string, version: number): {
         ok: boolean;

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

@@ -2,11 +2,13 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { ClarifyBridge } from "../clarify-bridge.js";
 import { runGatewayAgent } from "./run-gateway-agent.js";
+import { fitSourceContextsToBudget } from "../../agent/source-context/budget.js";
 import { SessionInputCoordinator } from "./session-input-coordinator.js";
 import crypto from "node:crypto";
 //#region src/gateway/service/agent-runner.ts
 init_logger();
 const log = createLogger("Gateway:AgentRunner");
+const MAX_TURN_CONTEXTS = 5;
 var GatewayAgentRunner = class {
 	opts;
 	/** Per-run abort for webchat (POST /api/agent/abort or client disconnect). */
@@ -23,7 +25,10 @@ var GatewayAgentRunner = class {
 		this.inputs = new SessionInputCoordinator({
 			sessionExists: async (sessionKey) => Boolean(await opts.sessionIndex.getSessionMetadata(sessionKey)),
 			execute: async (input) => {
-				const generator = this.runAgent(input.content, "webchat", input.sessionKey, input.origin, input.attachments, input.thinking, { runId: input.runId });
+				const generator = this.runAgent(input.content, "webchat", input.sessionKey, input.origin, input.attachments, input.thinking, {
+					runId: input.runId,
+					sourceContexts: input.sourceContexts
+				});
 				let result;
 				while (true) {
 					const step = await generator.next();
@@ -46,6 +51,21 @@ var GatewayAgentRunner = class {
 					size: ref.size
 				}));
 			},
+			prepareContexts: async (refs) => {
+				if (!refs?.length) return void 0;
+				const unique = /* @__PURE__ */ new Map();
+				for (const ref of refs) {
+					const sourceId = ref.sourceId.trim();
+					if (sourceId) unique.set(`${ref.kind}:${sourceId}`, {
+						...ref,
+						sourceId
+					});
+				}
+				if (unique.size > MAX_TURN_CONTEXTS) throw new Error(`A message can reference at most ${MAX_TURN_CONTEXTS} notes`);
+				const contexts = await Promise.all([...unique.values()].map((ref) => opts.resolveTurnContext(ref)));
+				if (contexts.some((context) => context === null)) throw new Error("A referenced note is no longer available");
+				return fitSourceContextsToBudget(contexts.filter((context) => context !== null));
+			},
 			steer: (sessionKey, content) => opts.getAgentService().turnDispatcher.steerWebchatSession(sessionKey, content),
 			emit: opts.emit
 		});

package/dist/src/gateway/service/config-coordinator.js

@@ -1,15 +1,15 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { getModelRegistry } from "../../providers/model-registry.js";
 import { loadConfig, saveConfig } from "../../config/loader.js";
+import { getModelRegistry } from "../../providers/model-registry.js";
 import { init_providers } from "../../providers/index.js";
 import { disposeAllSessionMcpRuntimes } from "../../agent/mcp/bundle-mcp-runtime.js";
 import { reloadImageGenerationProviders } from "../../agent/image/generation/provider-registry.js";
 import "../../agent/mcp/bundle-mcp-tools.js";
 import { ConfigHotReloader } from "../../config/reload.js";
 import "../../config/index.js";
-import { computeBundledExtensionExtensionsPatch } from "../../extensions/bundled-extension-activation.js";
 import { sanitizeTunnelConfig } from "../../tunnel/tunnel-config.js";
+import { computeBundledExtensionExtensionsPatch } from "../../extensions/bundled-extension-activation.js";
 //#region src/gateway/service/config-coordinator.ts
 init_providers();
 init_logger();

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

@@ -5,6 +5,7 @@ import type { MessageBus } from '../../infra/bus/index.js';
 import type { SessionIndex } from '../../session/index.js';
 import type { ChatStreamEvent } from '../chat-stream/protocol.js';
 import type { UserTurnAttachment } from '../user-turn-input.js';
+import type { AgentSourceContext } from '../../agent/source-context/types.js';
 export type RunGatewayAgentYield = ChatStreamEvent;
 export type RunGatewayAgentDeps = {
     config: Config;
@@ -23,6 +24,7 @@ export type RunGatewayAgentDeps = {
 export declare function runGatewayAgent(deps: RunGatewayAgentDeps, message: string, channel: string, chatId: string, origin: TurnOrigin, attachments?: UserTurnAttachment[], thinking?: string, runOptions?: {
     signal?: AbortSignal;
     runId?: string;
+    sourceContexts?: AgentSourceContext[];
 }): AsyncGenerator<RunGatewayAgentYield, {
     status: string;
     summary: string;

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

@@ -131,7 +131,8 @@ async function* runGatewayAgent(deps, message, channel, chatId, origin, attachme
 			try {
 				const eventStream = agentService.turnDispatcher.processDirectStreaming(stampedMessage, sessionKey, origin, prepared, thinking, {
 					signal: mergedSignal,
-					runId
+					runId,
+					sourceContexts: runOptions?.sourceContexts
 				});
 				const mappedEvents = (async function* () {
 					for await (const event of eventStream) yield* mapper.map(event);

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

@@ -1,5 +1,6 @@
 import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
 import type { UserTurnAttachment } from '../user-turn-input.js';
+import { type AgentSourceContext, type TurnContextRef } from '../../agent/source-context/types.js';
 import { type SessionInputDelivery, type SessionInputState } from '../../storage/sqlite/index.js';
 export type SubmitSessionInput = {
     sessionKey: string;
@@ -7,6 +8,7 @@ export type SubmitSessionInput = {
     delivery: SessionInputDelivery;
     content: string;
     attachments?: UserTurnAttachment[];
+    contextRefs?: TurnContextRef[];
     thinking?: string;
     origin: TurnOrigin;
 };
@@ -24,6 +26,7 @@ export declare class SessionInputCoordinator {
             sessionKey: string;
             content: string;
             attachments?: UserTurnAttachment[];
+            sourceContexts?: AgentSourceContext[];
             thinking?: string;
             origin: TurnOrigin;
         }) => Promise<{
@@ -31,6 +34,7 @@ export declare class SessionInputCoordinator {
             summary: string;
         }>;
         prepareAttachments: (sessionKey: string, attachments?: UserTurnAttachment[]) => Promise<UserTurnAttachment[] | undefined>;
+        prepareContexts: (contextRefs?: TurnContextRef[]) => Promise<AgentSourceContext[] | undefined>;
         steer: (sessionKey: string, content: string) => Promise<boolean>;
         emit: (type: string, payload: unknown) => void;
     });
@@ -43,7 +47,7 @@ export declare class SessionInputCoordinator {
         state: SessionInputState;
     } | {
         ok: false;
-        code: 'BAD_REQUEST' | 'QUEUE_FULL';
+        code: 'BAD_REQUEST' | 'QUEUE_FULL' | 'CONTEXT_UNAVAILABLE';
     }>;
     replaceLatestTurn(input: ReplaceLatestTurnInput, beforeReplace: () => Promise<void>): Promise<{
         ok: true;
@@ -51,7 +55,7 @@ export declare class SessionInputCoordinator {
         state: SessionInputState;
     } | {
         ok: false;
-        code: 'BAD_REQUEST' | 'TARGET_NOT_FOUND' | 'NOT_LATEST' | 'SESSION_BUSY';
+        code: 'BAD_REQUEST' | 'TARGET_NOT_FOUND' | 'NOT_LATEST' | 'SESSION_BUSY' | 'CONTEXT_UNAVAILABLE';
     }>;
     private submitLocked;
     drain(sessionKey: string): Promise<void>;
@@ -59,11 +63,13 @@ export declare class SessionInputCoordinator {
         version: number;
         content?: string;
         attachments?: UserTurnAttachment[];
+        contextRefs?: TurnContextRef[];
         thinking?: string;
         position?: number;
     }): Promise<{
         ok: boolean;
         state: SessionInputState;
+        contextUnavailable?: boolean;
     }>;
     remove(sessionKey: string, id: string, version: number): {
         ok: boolean;

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

@@ -1,14 +1,22 @@
 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 { cancelQueuedSessionInput, claimNextSessionInput, findSessionInput, finishSessionInputRun, getSessionInputById, 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 { summarizeSourceContext } from "../../agent/source-context/types.js";
 import { deleteMediaUrisNoLongerReferenced } from "../../media/session-references.js";
 import crypto from "node:crypto";
 //#region src/gateway/service/session-input-coordinator.ts
 init_logger();
 const log = createLogger("SessionInputCoordinator");
 const MAX_PENDING_INPUTS = 10;
+function contextRefsMatchFrozenSnapshot(requested, frozen) {
+	if (requested.length !== (frozen?.length ?? 0)) return false;
+	return requested.every((ref, index) => {
+		const snapshot = frozen?.[index];
+		return snapshot?.kind === ref.kind && snapshot.sourceId === ref.sourceId && ref.expectedVersion === snapshot.version;
+	});
+}
 var SessionInputCoordinator = class {
 	draining = /* @__PURE__ */ new Set();
 	submissionTails = /* @__PURE__ */ new Map();
@@ -69,12 +77,27 @@ var SessionInputCoordinator = class {
 			if (target.ok === false) return target;
 			await beforeReplace();
 			const attachments = await this.deps.prepareAttachments(sessionKey, input.attachments);
+			let sourceContexts;
+			try {
+				sourceContexts = await this.deps.prepareContexts(input.contextRefs);
+			} catch (err) {
+				log.warn({
+					err,
+					sessionKey
+				}, "Session input context preparation failed");
+				return {
+					ok: false,
+					code: "CONTEXT_UNAVAILABLE"
+				};
+			}
 			const result = replaceLatestSessionTurnAndQueueInput({
 				sessionKey,
 				targetTurnId,
 				clientMessageId,
 				content,
 				attachments,
+				contextRefs: sourceContexts?.map(summarizeSourceContext),
+				contextSnapshots: sourceContexts,
 				thinking: input.thinking,
 				origin: input.origin
 			});
@@ -121,8 +144,21 @@ var SessionInputCoordinator = class {
 			code: "QUEUE_FULL"
 		};
 		const attachments = await this.deps.prepareAttachments(sessionKey, input.attachments);
+		let sourceContexts;
+		try {
+			sourceContexts = await this.deps.prepareContexts(input.contextRefs);
+		} catch (err) {
+			log.warn({
+				err,
+				sessionKey
+			}, "Session input context preparation failed");
+			return {
+				ok: false,
+				code: "CONTEXT_UNAVAILABLE"
+			};
+		}
 		const runtime = this.snapshot(sessionKey);
-		const canSteer = input.origin.type !== "endpoint" && input.delivery === "steer" && runtime.activeRunId !== void 0 && !attachments?.length;
+		const canSteer = input.origin.type !== "endpoint" && input.delivery === "steer" && runtime.activeRunId !== void 0 && !attachments?.length && !sourceContexts?.length;
 		const effectiveDelivery = canSteer ? "steer" : "next";
 		const row = insertSessionInput({
 			id: crypto.randomUUID(),
@@ -133,6 +169,8 @@ var SessionInputCoordinator = class {
 			status: canSteer ? "injecting" : "queued",
 			content,
 			attachments,
+			contextRefs: sourceContexts?.map(summarizeSourceContext),
+			contextSnapshots: sourceContexts,
 			thinking: input.thinking,
 			origin: input.origin,
 			targetRunId: canSteer ? runtime.activeRunId : void 0
@@ -179,6 +217,7 @@ var SessionInputCoordinator = class {
 						sessionKey,
 						content: input.content,
 						attachments: input.attachments,
+						sourceContexts: input.contextSnapshots,
 						thinking: input.thinking,
 						origin: input.origin
 					});
@@ -204,11 +243,31 @@ var SessionInputCoordinator = class {
 	}
 	async update(sessionKey, id, body) {
 		const attachments = body.attachments === void 0 ? void 0 : await this.deps.prepareAttachments(sessionKey, body.attachments);
+		let sourceContexts;
+		if (body.contextRefs !== void 0) {
+			const existing = getSessionInputById(sessionKey, id);
+			if (!contextRefsMatchFrozenSnapshot(body.contextRefs, existing?.contextRefs)) try {
+				sourceContexts = await this.deps.prepareContexts(body.contextRefs) ?? [];
+			} catch (err) {
+				log.warn({
+					err,
+					sessionKey,
+					inputId: id
+				}, "Queued input context preparation failed");
+				return {
+					ok: false,
+					contextUnavailable: true,
+					state: this.snapshot(sessionKey)
+				};
+			}
+		}
 		const ok = mutateQueuedSessionInput({
 			sessionKey,
 			id,
 			...body,
-			attachments
+			attachments,
+			contextRefs: sourceContexts?.map(summarizeSourceContext),
+			contextSnapshots: sourceContexts
 		});
 		return {
 			ok,

package/dist/src/gateway/service/sessions-api.d.ts

@@ -93,6 +93,7 @@ export declare class GatewaySessionsApi {
         verboseLevel?: string;
         workingDirectory?: string;
         responseLanguage?: string | null;
+        userContextMode?: 'enabled' | 'off' | 'temporary';
     }): Promise<import("../../agent/session/session-config-service.js").PatchSessionAgentConfigResult>;
     listCompactionBoundaries(key: string): Promise<import("../../session/types.js").CompactionBoundarySummary[]>;
     restoreBeforeCompactionBoundary(key: string, compactionId: string): Promise<void>;

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

@@ -139,7 +139,7 @@ export declare class GatewayService {
         state: import("../storage/sqlite/session-input-repository.js").SessionInputState;
     } | {
         ok: false;
-        code: "BAD_REQUEST" | "QUEUE_FULL";
+        code: "BAD_REQUEST" | "QUEUE_FULL" | "CONTEXT_UNAVAILABLE";
     }>;
     replaceLatestSessionTurn(...args: Parameters<GatewayAgentRunner['replaceLatestSessionTurn']>): Promise<{
         ok: true;
@@ -147,12 +147,13 @@ export declare class GatewayService {
         state: import("../storage/sqlite/session-input-repository.js").SessionInputState;
     } | {
         ok: false;
-        code: "BAD_REQUEST" | "TARGET_NOT_FOUND" | "NOT_LATEST" | "SESSION_BUSY";
+        code: "BAD_REQUEST" | "TARGET_NOT_FOUND" | "NOT_LATEST" | "SESSION_BUSY" | "CONTEXT_UNAVAILABLE";
     }>;
     getSessionInputState(...args: Parameters<GatewayAgentRunner['getSessionInputState']>): import("../storage/sqlite/session-input-repository.js").SessionInputState;
     updateSessionInput(...args: Parameters<GatewayAgentRunner['updateSessionInput']>): Promise<{
         ok: boolean;
         state: import("../storage/sqlite/session-input-repository.js").SessionInputState;
+        contextUnavailable?: boolean;
     }>;
     removeSessionInput(...args: Parameters<GatewayAgentRunner['removeSessionInput']>): {
         ok: boolean;

package/dist/src/gateway/service.js

@@ -9,14 +9,14 @@ import { closeXopcDatabase, openXopcDatabase } from "../storage/sqlite/connectio
 import "../storage/sqlite/index.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { init_agent_scope, listAgentEntries, normalizeAgentId, resolveDefaultAgentId } from "../agent/agent-scope.js";
+import { buildSessionKey, init_session_key, sanitizeSegment } from "../routing/session-key.js";
+import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
 import { init_paths, resolveAgentDir, resolveConfigPath, resolveExtensionsDir } from "../config/paths.js";
-import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { areExtensionsGloballyDisabled } from "../extensions/discover-extensions.js";
 import { buildExtensionMetadataSnapshot } from "../extensions/extension-metadata-snapshot.js";
 import { buildChannelCatalogForConfig, buildChannelCatalogFromSnapshot, init_channel_catalog_service } from "../channels/catalog/channel-catalog-service.js";
 import { loadConfig, saveConfig } from "../config/loader.js";
-import { buildSessionKey, init_session_key, sanitizeSegment } from "../routing/session-key.js";
-import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
+import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { init_providers, providers_exports } from "../providers/index.js";
 import { TaskRepository } from "../tasks/task-repository.js";
 import { TaskConversationRepository } from "../tasks/task-conversation-repository.js";
@@ -50,18 +50,18 @@ import { registerClarifyBridge } from "./clarify-runtime.js";
 import { ChannelManager } from "../channels/manager.js";
 import { getWorkspacePath } from "../config/workspace-path-helpers.js";
 import "../config/index.js";
-import { DiscussionService } from "../discussions/service.js";
-import { DiscussionOrganizer } from "../discussions/organizer.js";
-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 { 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 { DiscussionService } from "../discussions/service.js";
+import { DiscussionOrganizer } from "../discussions/organizer.js";
+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 { assertGatewayAuthConfigured, extractToken, resolveGatewayAuth, validateToken } from "./auth.js";
@@ -369,6 +369,18 @@ var GatewayService = class {
 			getAgentService: () => this.ensureAgentService(),
 			getChannelManager: () => this.channelManager,
 			getConfig: () => this.config,
+			resolveTurnContext: async (ref) => {
+				if (ref.kind !== "note") return null;
+				const note = await this.notesService.getNote(ref.sourceId);
+				if (!note || note.status === "trashed") return null;
+				if (ref.expectedVersion && ref.expectedVersion !== String(note.updatedAt)) return null;
+				const { images: _images, ...snapshot } = await buildNoteAgentContext({
+					note,
+					notesService: this.notesService,
+					config: this.config
+				});
+				return snapshot;
+			},
 			emit: (type, payload) => this.emit(type, payload),
 			publishRealtime: (topic, event, data) => {
 				this.realtime.broker.publish(topic, event, data);
@@ -1161,8 +1173,9 @@ var GatewayService = class {
 	* PATCH saves update config in memory without re-running gateway startup, so this must run on save too.
 	*/
 	async reconcileBrowserExtensionServer() {
-		const { shouldRunExtensionBridgeServer } = await import("../browser/backend-from-config.js");
-		if (!shouldRunExtensionBridgeServer(this.config)) {
+		const { resolveExtensionBridgeServerConfig } = await import("../browser/backend-from-config.js");
+		const bridgeConfig = resolveExtensionBridgeServerConfig(this.config);
+		if (!bridgeConfig) {
 			if (this.browserExtensionRelease) {
 				await this.browserExtensionRelease();
 				this.browserExtensionRelease = null;
@@ -1172,10 +1185,7 @@ var GatewayService = class {
 			}
 			return;
 		}
-		const port = 19820;
-		const host = "127.0.0.1";
-		const connectionTimeout = void 0;
-		const commandTimeout = void 0;
+		const { port, host, connectionTimeout, commandTimeout } = bridgeConfig;
 		const bindKey = `${host}:${port}`;
 		if (this.browserExtensionRelease && this.browserExtensionBindKey === bindKey) return;
 		if (this.browserExtensionRelease) {

package/dist/src/gateway/user-turn-input.d.ts

@@ -1,4 +1,5 @@
 import type { MediaRef } from '../media/types.js';
+import type { TurnContextRef } from '../agent/source-context/types.js';
 export interface UserTurnAttachment {
     id?: string;
     type: string;
@@ -13,5 +14,6 @@ export interface UserTurnAttachment {
 export interface UserTurnInput {
     text: string;
     attachments?: UserTurnAttachment[];
+    contextRefs?: TurnContextRef[];
 }
 export declare function mediaRefsToUserTurnAttachments(media: MediaRef[] | undefined): UserTurnAttachment[] | undefined;

package/dist/src/gateway/xopc-cloud-capability-setup.d.ts

@@ -1,7 +1,8 @@
 import type { Config } from '../config/schema.js';
 import type { CatalogSource } from '../providers/model-catalog-store.js';
-type CloudCapability = 'vision' | 'image-generation' | 'stt' | 'tts';
+type CloudCapability = 'chat' | 'vision' | 'image-generation' | 'stt' | 'tts';
 export interface XopcCloudCapabilitySelection {
+    chat: string;
     vision: string;
     imageGeneration: string;
     stt: string;
@@ -29,7 +30,7 @@ export declare function selectXopcCloudCapabilities(source: CatalogSource): {
     selection?: XopcCloudCapabilitySelection;
     missing: CloudCapability[];
 };
-/** Build one atomic config update for every managed XOPC Cloud media capability. */
+/** Build one atomic config update for the managed XOPC Cloud chat and media capabilities. */
 export declare function prepareXopcCloudCapabilitySetup(config: Config, source: CatalogSource): PrepareXopcCloudCapabilitySetupResult;
 export declare function applyXopcCloudCapabilitySetup(service: {
     currentConfig: Config;

package/dist/src/gateway/xopc-cloud-capability-setup.js

@@ -5,29 +5,33 @@ import { ensureGlobalDefaultsConfig, prepareUpdateGlobalDefaults } from "./globa
 init_model_catalog_store();
 function supportsCapability(model, capability) {
 	if (model.availability !== "available") return false;
+	if (capability === "chat") return model.kind === "language" && (model.operations.includes("chat.completions") || model.operations.includes("responses"));
 	if (capability === "vision") return model.kind === "language" && model.input.includes("image");
 	if (capability === "image-generation") return model.kind === "image" && model.operations.includes("images.generate");
 	if (capability === "stt") return model.kind === "stt" && model.operations.includes("audio.transcription");
 	return model.kind === "tts" && model.operations.includes("audio.speech") && Boolean(model.tts?.defaultVoice);
 }
 function recommendedModel(source, capability) {
-	const recommendation = source.recommended?.[capability];
+	const recommendation = capability === "chat" ? source.recommendedModel ?? void 0 : source.recommended?.[capability];
 	return source.models.filter((model) => supportsCapability(model, capability)).sort((left, right) => compareCatalogModels(left, right, recommendation))[0];
 }
 function selectXopcCloudCapabilities(source) {
+	const chat = recommendedModel(source, "chat");
 	const vision = recommendedModel(source, "vision");
 	const imageGeneration = recommendedModel(source, "image-generation");
 	const stt = recommendedModel(source, "stt");
 	const tts = recommendedModel(source, "tts");
 	const missing = [];
+	if (!chat) missing.push("chat");
 	if (!vision) missing.push("vision");
 	if (!imageGeneration) missing.push("image-generation");
 	if (!stt) missing.push("stt");
 	if (!tts) missing.push("tts");
-	if (!vision || !imageGeneration || !stt || !tts || !tts.tts?.defaultVoice) return { missing };
+	if (!chat || !vision || !imageGeneration || !stt || !tts || !tts.tts?.defaultVoice) return { missing };
 	return {
 		missing,
 		selection: {
+			chat: chat.id,
 			vision: vision.id,
 			imageGeneration: imageGeneration.id,
 			stt: stt.id,
@@ -36,7 +40,7 @@ function selectXopcCloudCapabilities(source) {
 		}
 	};
 }
-/** Build one atomic config update for every managed XOPC Cloud media capability. */
+/** Build one atomic config update for the managed XOPC Cloud chat and media capabilities. */
 function prepareXopcCloudCapabilitySetup(config, source) {
 	const selected = selectXopcCloudCapabilities(source);
 	if (!selected.selection) return {
@@ -48,8 +52,17 @@ function prepareXopcCloudCapabilitySetup(config, source) {
 	const normalized = ensureGlobalDefaultsConfig(config);
 	const presetId = normalized.agents.defaultPreset;
 	const currentModels = normalized.agents.capabilityPresets[presetId]?.models;
+	const defaultRole = currentModels?.defaultRole ?? "deep";
 	const defaultsUpdate = prepareUpdateGlobalDefaults(normalized, { models: {
 		...currentModels,
+		defaultRole,
+		roles: {
+			...currentModels?.roles ?? {},
+			[defaultRole]: {
+				...currentModels?.roles?.[defaultRole],
+				model: `xopc-cloud/${selection.chat}`
+			}
+		},
 		imageModel: {
 			...currentModels?.imageModel,
 			primary: `xopc-cloud/${selection.vision}`

package/dist/src/infra/update-runner.js

@@ -1,4 +1,3 @@
-import { runPostUpdateExtensionSync } from "../extensions/update.js";
 import "./update-channels.js";
 import { compareSemver, resolveNpmChannelTag } from "./update-check.js";
 import { readPackageName, readPackageVersion } from "./package-json.js";
@@ -8,6 +7,7 @@ import { runGlobalPackageUpdateSteps } from "./package-update-steps.js";
 import { resolveStableNodePath } from "./stable-node-path.js";
 import { trimLogTail } from "./update-log.js";
 import { maybeRestartGatewayAfterUpdate } from "./update-restart.js";
+import { runPostUpdateExtensionSync } from "../extensions/update.js";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region src/infra/update-runner.ts

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(agentId: string): Promise<UnderstandingReviewResult>;
+    process(agentId: string, extractionRunId: string): Promise<UnderstandingReviewResult>;
 }

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

@@ -226,7 +226,7 @@ var ConnectedUnderstandingPipeline = class {
 	constructor(memoryManager) {
 		this.memoryManager = memoryManager;
 	}
-	async process(agentId) {
+	async process(agentId, extractionRunId) {
 		const observations = deriveConnectedClaimObservations(listKnowledgeSourceItems({
 			agentId,
 			includeDeleted: false,
@@ -253,12 +253,14 @@ var ConnectedUnderstandingPipeline = class {
 					provider: "connected-sources",
 					...sourceInstanceIds.length === 1 ? { sourceInstanceId: sourceInstanceIds[0] } : {}
 				},
-				reviewSource: "background"
+				reviewSource: "background",
+				extractionRunId
 			});
 			totals.created += result.created;
 			totals.deduplicated += result.deduplicated;
 			totals.rejected += result.rejected;
 			totals.createdRecords.push(...result.createdRecords);
+			totals.writeOutputs = [...totals.writeOutputs ?? [], ...result.writeOutputs ?? []];
 		}
 		return totals;
 	}

package/dist/src/providers/auth-runtime/resolve-auth.js

@@ -1,5 +1,5 @@
-import { getApiKeyFromEnv, init_env_keys } from "../env-keys.js";
 import { init_sync_provider_auth, resolveProviderApiKeyForAgentSync } from "../../auth/sync-provider-auth.js";
+import { getApiKeyFromEnv, init_env_keys } from "../env-keys.js";
 import { getDefaultAuthProfileStore } from "./auth-profile-store.js";
 //#region src/providers/auth-runtime/resolve-auth.ts
 init_env_keys();

package/dist/src/providers/index.js

@@ -1,11 +1,11 @@
 import { __esmMin, __exportAll } from "../../_virtual/_rolldown/runtime.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
+import { getOAuthProviderIds, init_registry } from "../auth/oauth/registry.js";
+import { hasProviderAuthOnDiskSync, init_sync_provider_auth } from "../auth/sync-provider-auth.js";
 import { PROVIDER_ENV_MAP, getApiKeyFromEnv, init_env_keys } from "./env-keys.js";
 import { init_model_ref, splitProviderModelRef } from "./model-ref.js";
 import { ModelRegistry, getModelRegistry, init_model_registry, prewarmModelRegistry, resetModelRegistry } from "./model-registry.js";
-import { getOAuthProviderIds, init_registry } from "../auth/oauth/registry.js";
 import { CredentialResolver, hasCredentials, init_credentials } from "../auth/credentials.js";
-import { hasProviderAuthOnDiskSync, init_sync_provider_auth } from "../auth/sync-provider-auth.js";
 import { EXTENSION_PROVIDER_BASE_URL, init_constants } from "./constants.js";
 import { applyOfficialModelMetadataCorrections, getSupplementalModels, init_model_supplements } from "./model-supplements.js";
 import { getProviderRegistry, init_plugin_registry } from "./plugin-registry.js";

package/dist/src/providers/model-registry.js

@@ -1,8 +1,8 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { init_resolve_config_value, resolveConfigValue, resolveHeaders } from "../config/resolve-config-value.js";
 import { resolveModelsJsonPath } from "../config/paths.js";
+import { init_resolve_config_value, resolveConfigValue, resolveHeaders } from "../config/resolve-config-value.js";
 import { getDefaultModelValues, init_models_json, validateModelsConfig } from "../config/models-json.js";
 import { getApiKeyFromEnv, init_env_keys } from "./env-keys.js";
 import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";

package/dist/src/providers/register-runtime-providers.js

@@ -1,6 +1,6 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
-import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
 import { getOAuthProviderDefinition, init_registry } from "../auth/oauth/registry.js";
+import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
 import { XOPC_CLOUD_PROVIDER_ID, init_xopc_cloud_config, resolveXopcModelRouterUrl } from "./xopc-cloud-config.js";
 //#region src/providers/register-runtime-providers.ts
 function registerRuntimeProvider(modelRuntime, source) {