@xopcai/xopc 0.0.252 → 0.0.253

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

@@ -81,7 +81,7 @@ export declare class GatewayService {
     private stopRealtimeLogBridge;
     /**
      * Webchat agent invocation surface (`runAgent`, `abortAgentRun`, `steer*`,
-     * `submitClarifyResponse`, clarify-bridge dispatch). Owns the
+     * clarification dispatch). Owns the
      * `activeWebchatRunBySession` + `runAbortControllers` maps.
      */
     readonly agentRunner: GatewayAgentRunner;
@@ -168,7 +168,9 @@ export declare class GatewayService {
         idle: boolean;
     }>;
     getActiveWebchatRunId(sessionKey: string): string | undefined;
-    submitClarifyResponse(requestId: string, answer: string): boolean;
+    answerEphemeralClarification(requestId: string, answer: string): boolean;
+    getClarificationState(sessionKey: string): import("@xopcai/gateway-contract/src/clarifications.js").ClarificationWaitSnapshot;
+    resolveClarificationResponse(input: Parameters<GatewayAgentRunner['resolveClarificationResponse']>[0]): import("../storage/sqlite/clarification-wait-repository.js").ResolveClarificationResult;
     private initializeExtensionLoader;
     private registerExtensionChannelPlugins;
     /**

package/dist/src/gateway/service.js

@@ -50,7 +50,7 @@ import "../infra/bus/index.js";
 import { AgentService } from "../agent/service.js";
 import { ensureStarterAgentsInitialized } from "../agent/starter-agents.js";
 import { setPairingBroadcastSink } from "../channels/pairing/pairing-events.js";
-import { registerClarifyBridge } from "./clarify-runtime.js";
+import { registerClarificationChannelRuntime } from "./clarify-runtime.js";
 import { ChannelManager } from "../channels/manager.js";
 import { getWorkspacePath } from "../config/workspace-path-helpers.js";
 import "../config/index.js";
@@ -97,6 +97,7 @@ 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 { collectMediaUrisFromMessages, deleteMediaUris } from "../media/session-references.js";
 import { runBootstrapMigrationsSync } from "../migrations/runner.js";
 import { NotificationService } from "../notifications/service.js";
 import { LocalAppService } from "../local-apps/service.js";
@@ -268,7 +269,7 @@ var GatewayService = class {
 	stopRealtimeLogBridge = null;
 	/**
 	* Webchat agent invocation surface (`runAgent`, `abortAgentRun`, `steer*`,
-	* `submitClarifyResponse`, clarify-bridge dispatch). Owns the
+	* clarification dispatch). Owns the
 	* `activeWebchatRunBySession` + `runAbortControllers` maps.
 	*/
 	agentRunner;
@@ -465,8 +466,12 @@ var GatewayService = class {
 			getParentMetadata: (sessionKey) => this.sessionIndex.getSessionMetadata(sessionKey),
 			loadParentMessages: (sessionKey) => this.sessionIndex.getStore().load(sessionKey),
 			getDefaultModelRef: (sessionKey) => this.ensureAgentService().getModelForSession(sessionKey),
+			getDefaultThinkingLevel: (sessionKey) => this.ensureAgentService().getThinkingLevelForSession(sessionKey),
 			getWorkspacePath: (metadata) => metadata.cwd || this.currentWorkspacePath,
-			onBeforeDispose: (sideChatId, clientInstanceId) => sideChatRuns?.cancelRun(sideChatId, clientInstanceId).then(() => void 0),
+			onBeforeDispose: async (sideChatId, clientInstanceId, messages) => {
+				await sideChatRuns?.cancelRun(sideChatId, clientInstanceId);
+				await deleteMediaUris(collectMediaUrisFromMessages(messages));
+			},
 			onExpired: (sideChatId, clientInstanceId, reason) => {
 				const topic = `side-chat:${clientInstanceId}:${sideChatId}`;
 				this.realtime.broker.publish(topic, "expired", { reason });
@@ -572,10 +577,12 @@ var GatewayService = class {
 				}
 				return null;
 			},
-			gatewayClarify: { requestClarification: (sessionKey, request) => {
-				const executionSessionKey = getEmbeddedExecutionSession() ?? sessionKey;
+			gatewayClarify: { requestClarification: (context, request) => {
+				const executionSessionKey = getEmbeddedExecutionSession() ?? context.sessionKey;
 				return this.agentRunner.requestClarification({
 					sessionKey: executionSessionKey,
+					runId: context.runId,
+					toolCallId: context.toolCallId,
 					request,
 					publishStreamFor: (_runId) => (event) => {
 						this._agentService.turnDispatcher.enqueueWebchatStreamEvent(executionSessionKey, event);
@@ -776,8 +783,14 @@ var GatewayService = class {
 	getActiveWebchatRunId(sessionKey) {
 		return this.agentRunner.getActiveRunId(sessionKey);
 	}
-	submitClarifyResponse(requestId, answer) {
-		return this.agentRunner.submitClarifyResponse(requestId, answer);
+	answerEphemeralClarification(requestId, answer) {
+		return this.agentRunner.answerEphemeralClarification(requestId, answer);
+	}
+	getClarificationState(sessionKey) {
+		return this.agentRunner.getClarificationState(sessionKey);
+	}
+	resolveClarificationResponse(input) {
+		return this.agentRunner.resolveClarificationResponse(input);
 	}
 	initializeExtensionLoader() {
 		try {
@@ -925,7 +938,10 @@ var GatewayService = class {
 				errorMessage: readiness.error.message
 			}, `Initial XOPC Cloud catalog refresh failed: ${readiness.error.message}`);
 		}
-		registerClarifyBridge(this.agentRunner.getClarifyBridge());
+		registerClarificationChannelRuntime({
+			answerChoice: (requestId, choiceIndex, idempotencyKey) => this.agentRunner.answerClarificationChoice(requestId, choiceIndex, idempotencyKey),
+			answerText: (sessionKey, text, idempotencyKey) => this.agentRunner.answerClarificationText(sessionKey, text, idempotencyKey)
+		});
 		this.ensureAgentService();
 		this.agentRunner.recoverSessionInputs();
 		this.connectionRecovery.start();
@@ -1242,9 +1258,9 @@ var GatewayService = class {
 		}
 		this.browserExtensionProvider = null;
 		this.browserExtensionBindKey = null;
-		registerClarifyBridge(null);
+		registerClarificationChannelRuntime(null);
 		this.connectionRecovery.stop();
-		this.agentRunner.disposeClarifyBridge();
+		this.agentRunner.disposeClarifications();
 		await disposeAllSessionMcpRuntimes().catch((err) => {
 			log.warn({ err }, "MCP runtime shutdown failed");
 		});

package/dist/src/gateway/side-chat/manager.d.ts

@@ -11,13 +11,14 @@ export interface EphemeralSideChatManagerOptions {
     getParentMetadata: (sessionKey: string) => Promise<SessionMetadata | null>;
     loadParentMessages: (sessionKey: string) => Promise<AgentMessage[]>;
     getDefaultModelRef: (sessionKey: string) => string;
+    getDefaultThinkingLevel?: (sessionKey: string) => ThinkingLevel;
     getWorkspacePath: (metadata: SessionMetadata) => string;
     idleTtlMs?: number;
     maxPerClient?: number;
     maxTotal?: number;
     now?: () => number;
     startSweepTimer?: boolean;
-    onBeforeDispose?: (sideChatId: string, clientInstanceId: string) => void | Promise<void>;
+    onBeforeDispose?: (sideChatId: string, clientInstanceId: string, messages: AgentMessage[]) => void | Promise<void>;
     onExpired?: (sideChatId: string, clientInstanceId: string, reason: 'idle' | 'waiting') => void;
 }
 export declare class EphemeralSideChatManager {

package/dist/src/gateway/side-chat/manager.js

@@ -90,7 +90,7 @@ var EphemeralSideChatManager = class {
 		runtime.captureBaseline();
 		const config = {
 			modelRef: normalizeOptionalString(input.config?.modelRef) || this.options.getDefaultModelRef(parentSessionKey),
-			thinkingLevel: input.config?.thinkingLevel
+			thinkingLevel: input.config?.thinkingLevel ?? this.options.getDefaultThinkingLevel?.(parentSessionKey) ?? "medium"
 		};
 		const entry = {
 			id,
@@ -169,10 +169,11 @@ var EphemeralSideChatManager = class {
 		}
 		if (entry.clientInstanceId !== clientInstanceId) return false;
 		entry.status = "closing";
+		const messages = entry.runtime.loadConversationMessages();
 		this.entries.delete(id);
 		const cleanup = (async () => {
 			try {
-				await this.runBeforeDispose(id, clientInstanceId);
+				await this.runBeforeDispose(id, clientInstanceId, messages);
 				await evictEmbeddedSessionRunner(entry.runtime.runtimeId, "side_chat_dispose");
 				return true;
 			} finally {
@@ -255,9 +256,9 @@ var EphemeralSideChatManager = class {
 		entry.lastActiveAt = new Date(now).toISOString();
 		entry.expiresAt = entry.status === "running" ? null : new Date(now + this.idleTtlMs).toISOString();
 	}
-	async runBeforeDispose(id, clientInstanceId) {
+	async runBeforeDispose(id, clientInstanceId, messages) {
 		try {
-			await this.options.onBeforeDispose?.(id, clientInstanceId);
+			await this.options.onBeforeDispose?.(id, clientInstanceId, messages);
 		} catch (err) {
 			log.warn({
 				err,

package/dist/src/gateway/side-chat/run-service.d.ts

@@ -1,6 +1,7 @@
 import type { AgentService } from '../../agent/service.js';
 import type { GatewayAgentRunner } from '../service/agent-runner.js';
 import { type EphemeralSideChatManager } from './manager.js';
+import type { UserTurnAttachment } from '../user-turn-input.js';
 export interface SideChatRunServiceOptions {
     manager: EphemeralSideChatManager;
     getAgentService: () => AgentService;
@@ -12,7 +13,10 @@ export declare class SideChatRunService {
     private readonly options;
     private readonly activeBySideChat;
     constructor(options: SideChatRunServiceOptions);
-    submit(sideChatId: string, clientInstanceId: string, content: string): {
+    submit(sideChatId: string, clientInstanceId: string, input: {
+        content: string;
+        attachments?: UserTurnAttachment[];
+    }): {
         runId: string;
     };
     abort(sideChatId: string, clientInstanceId: string, runId?: string): Promise<boolean>;

package/dist/src/gateway/side-chat/run-service.js

@@ -12,9 +12,9 @@ var SideChatRunService = class {
 	constructor(options) {
 		this.options = options;
 	}
-	submit(sideChatId, clientInstanceId, content) {
-		const text = content.trim();
-		if (!text) throw new SideChatError("content is required", "INVALID_REQUEST");
+	submit(sideChatId, clientInstanceId, input) {
+		const text = input.content.trim();
+		if (!text && !input.attachments?.length) throw new SideChatError("content or attachments are required", "INVALID_REQUEST");
 		const sideChat = this.options.manager.get(sideChatId, clientInstanceId);
 		if (this.activeBySideChat.has(sideChatId)) throw new SideChatError("A side chat run is already active", "CONFLICT");
 		const run = {
@@ -26,7 +26,10 @@ var SideChatRunService = class {
 		};
 		this.activeBySideChat.set(sideChatId, run);
 		this.options.manager.setStatus(sideChatId, clientInstanceId, "running", run.runId);
-		this.execute(run, text, sideChat.config).catch((err) => {
+		this.execute(run, {
+			content: text,
+			attachments: input.attachments
+		}, sideChat.config).catch((err) => {
 			log.error({
 				err,
 				sideChatId,
@@ -55,11 +58,11 @@ var SideChatRunService = class {
 	}
 	submitClarification(sideChatId, clientInstanceId, requestId, answer) {
 		if (this.options.manager.get(sideChatId, clientInstanceId).clarification?.requestId !== requestId) return false;
-		const handled = this.options.agentRunner.submitClarifyResponse(requestId, answer);
+		const handled = this.options.agentRunner.answerEphemeralClarification(requestId, answer);
 		if (handled) this.options.manager.setStatus(sideChatId, clientInstanceId, "running");
 		return handled;
 	}
-	async execute(run, content, config) {
+	async execute(run, input, config) {
 		const topic = `run:${run.runId}`;
 		const mapper = new ChatStreamMapper({
 			runId: run.runId,
@@ -73,8 +76,10 @@ var SideChatRunService = class {
 			if (run.abortController.signal.aborted) return;
 			if (event.type === "clarify_request") this.options.manager.waitForInput(run.sideChatId, run.clientInstanceId, {
 				requestId: String(event.requestId),
+				kind: event.kind === "approval" ? "approval" : "input",
 				question: String(event.question),
-				choices: Array.isArray(event.choices) ? event.choices.filter((choice) => typeof choice === "string") : void 0
+				choices: Array.isArray(event.choices) ? event.choices.filter((choice) => typeof choice === "string") : void 0,
+				suggestedAnswer: typeof event.suggestedAnswer === "string" ? event.suggestedAnswer : void 0
 			}, event.kind === "approval" ? "waiting-approval" : "waiting-input");
 			for (const mapped of mapper.map(event)) publish(mapped);
 		};
@@ -82,28 +87,24 @@ var SideChatRunService = class {
 			for (const event of mapper.start()) publish(event);
 			publishMapped({
 				type: "user_message",
-				message: {
-					role: "user",
-					content,
-					timestamp: Date.now()
-				}
+				content: input.content,
+				media: input.attachments?.map(({ data: _data, ...attachment }) => attachment),
+				timestamp: Date.now()
 			});
-			this.options.agentRunner.registerExternalWebchatRun(run.executionSessionKey, run.runId, (event) => publishMapped(event), {
-				clarificationTimeoutMs: null,
-				beforeClarificationResponse: () => {
-					try {
-						this.options.manager.setStatus(run.sideChatId, run.clientInstanceId, "running");
-						return true;
-					} catch {
-						return false;
-					}
+			this.options.agentRunner.registerExternalWebchatRun(run.executionSessionKey, run.runId, (event) => publishMapped(event), { beforeClarificationResponse: () => {
+				try {
+					this.options.manager.setStatus(run.sideChatId, run.clientInstanceId, "running");
+					return true;
+				} catch {
+					return false;
 				}
-			});
+			} });
 			const result = await this.options.getAgentService().runEphemeralTurn({
 				executionSessionKey: run.executionSessionKey,
 				parentSessionKey: this.options.manager.get(run.sideChatId, run.clientInstanceId).parentSessionKey,
 				runId: run.runId,
-				content,
+				content: input.content,
+				attachments: input.attachments,
 				modelRef: config.modelRef,
 				thinkingLevel: config.thinkingLevel,
 				transcriptRuntime: this.options.manager.getRuntime(run.sideChatId, run.clientInstanceId),

package/dist/src/gateway/side-chat/types.d.ts

@@ -39,7 +39,7 @@ export interface SideChatContextSnapshot {
 }
 export interface SideChatConfig {
     modelRef: string;
-    thinkingLevel?: ThinkingLevel;
+    thinkingLevel: ThinkingLevel;
 }
 export interface SideChatView {
     id: string;
@@ -54,8 +54,10 @@ export interface SideChatView {
     runId?: string;
     clarification?: {
         requestId: string;
+        kind: 'input' | 'approval';
         question: string;
         choices?: string[];
+        suggestedAnswer?: string;
     };
     messageCount: number;
     context: SideChatContextSnapshot;

package/dist/src/storage/sqlite/clarification-wait-repository.d.ts

@@ -0,0 +1,41 @@
+import type { ClarificationKind, ClarificationResponseAction, ClarificationWait, ClarificationWaitSnapshot } from '@xopcai/gateway-contract';
+import { type SessionInput } from './session-input-repository.js';
+export type CreateClarificationInput = {
+    sessionKey: string;
+    runId: string;
+    toolCallId: string;
+    kind: ClarificationKind;
+    question: string;
+    choices?: string[];
+    suggestedAnswer?: string;
+    approvalKey?: string;
+    now?: number;
+};
+export type ResolveClarificationInput = {
+    id: string;
+    expectedVersion: number;
+    idempotencyKey: string;
+    action: ClarificationResponseAction;
+    answer?: string;
+    now?: number;
+};
+export type ResolveClarificationResult = {
+    ok: true;
+    clarification: ClarificationWait;
+    idempotent: boolean;
+    queued: boolean;
+} | {
+    ok: false;
+    code: 'NOT_FOUND' | 'CONFLICT' | 'EXPIRED' | 'INVALID';
+    clarification?: ClarificationWait;
+};
+export declare function getClarification(id: string): ClarificationWait | undefined;
+export declare function getActiveClarification(sessionKey: string): ClarificationWait | undefined;
+export declare function getClarificationSnapshot(sessionKey: string): ClarificationWaitSnapshot | undefined;
+export declare function createClarificationWait(input: CreateClarificationInput): ClarificationWait;
+export declare function isClarificationSuspended(sessionKey: string, runId: string): boolean;
+export declare function resolveClarification(input: ResolveClarificationInput): ResolveClarificationResult;
+export declare function getClarificationResumeInput(sessionKey: string, runId: string): SessionInput | undefined;
+export declare function consumeClarificationResume(input: SessionInput): boolean;
+export declare function consumeClarificationApproval(sessionKey: string, approvalKey: string): 'approved' | 'denied' | undefined;
+export declare function supersedeActiveClarification(sessionKey: string, now?: number): ClarificationWait | undefined;