@xopcai/xopc 0.0.252 → 0.0.254

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

@@ -1,15 +1,20 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { listActiveSessionInputRuns } from "../../storage/sqlite/session-input-repository.js";
+import { createClarificationWait, getClarification, getClarificationSnapshot, resolveClarification, supersedeActiveClarification } from "../../storage/sqlite/clarification-wait-repository.js";
 import { onConnectionWaitChanged } from "../../storage/sqlite/connection-wait-repository.js";
 import "../../storage/sqlite/index.js";
-import { ClarifyBridge } from "../clarify-bridge.js";
+import { EphemeralClarificationWaiter } from "../ephemeral-clarification-waiter.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();
+/**
+* Owns gateway agent runs, durable clarification coordination, and the
+* lifecycle-bound clarification waiter used by ephemeral side chats.
+*/
 const log = createLogger("Gateway:AgentRunner");
 const MAX_TURN_CONTEXTS = 5;
 var GatewayAgentRunner = class {
@@ -18,11 +23,10 @@ var GatewayAgentRunner = class {
 	runAbortControllers = /* @__PURE__ */ new Map();
 	runCompletions = /* @__PURE__ */ new Map();
 	resolveRunCompletions = /* @__PURE__ */ new Map();
-	clarifyBridge = new ClarifyBridge();
+	ephemeralClarifications = new EphemeralClarificationWaiter();
 	/** Maps webchat session key → active `runId` for `clarify` tool routing. */
 	activeWebchatRunBySession = /* @__PURE__ */ new Map();
 	externalStreamBySession = /* @__PURE__ */ new Map();
-	externalClarificationTimeouts = /* @__PURE__ */ new Map();
 	externalClarificationResponses = /* @__PURE__ */ new Map();
 	inputs;
 	unsubscribeConnectionWait;
@@ -104,30 +108,24 @@ var GatewayAgentRunner = class {
 			runId
 		}));
 	}
-	getClarifyBridge() {
-		return this.clarifyBridge;
-	}
-	/** Called from `GatewayService.stop()` so the bridge gets cleaned up. */
-	disposeClarifyBridge() {
-		this.clarifyBridge.dispose();
+	disposeClarifications() {
+		this.ephemeralClarifications.dispose();
 		this.unsubscribeConnectionWait();
 	}
 	registerExternalWebchatRun(sessionKey, runId, publish, options) {
 		this.activeWebchatRunBySession.set(sessionKey, runId);
 		this.externalStreamBySession.set(sessionKey, publish);
-		if (options?.clarificationTimeoutMs !== void 0) this.externalClarificationTimeouts.set(sessionKey, options.clarificationTimeoutMs);
 		if (options?.beforeClarificationResponse) this.externalClarificationResponses.set(sessionKey, options.beforeClarificationResponse);
 	}
 	unregisterExternalWebchatRun(sessionKey, runId) {
 		if (this.activeWebchatRunBySession.get(sessionKey) === runId) {
 			this.activeWebchatRunBySession.delete(sessionKey);
 			this.externalStreamBySession.delete(sessionKey);
-			this.externalClarificationTimeouts.delete(sessionKey);
 			this.externalClarificationResponses.delete(sessionKey);
 		}
 	}
 	cancelClarificationForRun(runId) {
-		this.clarifyBridge.cancelForRun(runId);
+		this.ephemeralClarifications.cancelForRun(runId);
 	}
 	async *runAgent(message, channel, chatId, origin, attachments, thinking, runOptions) {
 		const trackedRunId = runOptions?.runId;
@@ -185,7 +183,7 @@ var GatewayAgentRunner = class {
 	}
 	/** Abort an in-flight webchat agent run. */
 	async abortAgentRun(runId) {
-		this.clarifyBridge.cancelForRun(runId);
+		this.ephemeralClarifications.cancelForRun(runId);
 		const keysToMark = [];
 		for (const [sk, id] of this.activeWebchatRunBySession) if (id === runId) keysToMark.push(sk);
 		const c = this.runAbortControllers.get(runId);
@@ -194,10 +192,13 @@ var GatewayAgentRunner = class {
 			idle: true
 		};
 		const completion = this.runCompletions.get(runId);
-		for (const sk of keysToMark) this.opts.sessionIndex.appendTranscriptContextEntry(sk, {
-			text: "Webchat agent run aborted",
-			data: { runId }
-		}).catch(() => {});
+		for (const sk of keysToMark) {
+			if ((getClarificationSnapshot(sk)?.clarification)?.originRunId === runId) supersedeActiveClarification(sk);
+			this.opts.sessionIndex.appendTranscriptContextEntry(sk, {
+				text: "Webchat agent run aborted",
+				data: { runId }
+			}).catch(() => {});
+		}
 		c.abort();
 		const { abortEmbeddedRun } = await import("../../agent/embedded/runs.js");
 		await Promise.all(keysToMark.map((sessionKey) => abortEmbeddedRun(sessionKey).catch(() => false)));
@@ -207,9 +208,45 @@ var GatewayAgentRunner = class {
 			idle: true
 		};
 	}
-	/** Deliver a user's answer to a pending `clarify` tool call. */
-	submitClarifyResponse(requestId, answer) {
-		return this.clarifyBridge.handleResponse(requestId, answer);
+	answerEphemeralClarification(requestId, answer) {
+		return this.ephemeralClarifications.answer(requestId, answer);
+	}
+	getClarificationState(sessionKey) {
+		return getClarificationSnapshot(sessionKey);
+	}
+	resolveClarificationResponse(input) {
+		const result = resolveClarification(input);
+		if (result.ok) {
+			this.opts.emit("clarification.updated", result.clarification);
+			if (result.queued) this.inputs.drain(result.clarification.sessionKey);
+		}
+		return result;
+	}
+	getClarificationById(id) {
+		return getClarification(id);
+	}
+	answerClarificationChoice(requestId, choiceIndex, idempotencyKey) {
+		const wait = getClarification(requestId);
+		const answer = wait?.status === "open" ? wait.choices?.[choiceIndex] : void 0;
+		if (!answer) return false;
+		return this.resolveClarificationResponse({
+			id: wait.id,
+			expectedVersion: wait.version,
+			idempotencyKey,
+			action: "answer",
+			answer
+		}).ok;
+	}
+	answerClarificationText(sessionKey, answer, idempotencyKey) {
+		const wait = getClarificationSnapshot(sessionKey)?.clarification;
+		if (!wait || wait.status !== "open" || !answer.trim()) return false;
+		return this.resolveClarificationResponse({
+			id: wait.id,
+			expectedVersion: wait.version,
+			idempotencyKey,
+			action: "answer",
+			answer
+		}).ok;
 	}
 	/** Same execution path as scheduled continuation, but lets callers observe failures. */
 	async runScheduledWebchatTurn(sessionKey, userTurn) {
@@ -243,8 +280,8 @@ var GatewayAgentRunner = class {
 		}
 	}
 	/**
-	* Resolve clarify-bridge config for `sessionKey`: who delivers the question
-	* (webchat stream, Telegram message, or both), then start the bridge request.
+	* Persist normal clarification waits and use the lifecycle-bound waiter only
+	* for caller-owned ephemeral sessions.
 	* Rejects when neither path is available (e.g. CLI without webchat or TG).
 	*
 	* `publishStreamFor(runId)` is the bridge into AgentService's
@@ -253,33 +290,67 @@ var GatewayAgentRunner = class {
 	*/
 	async requestClarification(opts) {
 		const { sessionKey, request, publishStreamFor } = opts;
-		const runId = this.activeWebchatRunBySession.get(sessionKey);
+		const runId = this.activeWebchatRunBySession.get(sessionKey) ?? opts.runId;
 		const publishStream = this.externalStreamBySession.get(sessionKey) ?? (runId ? publishStreamFor(runId) : void 0);
 		const deliver = ((await this.opts.sessionIndex.getSessionMetadata(sessionKey).catch(() => null))?.routing)?.source === "telegram" ? async (ctx) => {
 			await this.deliverTelegramClarify(ctx);
 		} : void 0;
-		if (!runId && !deliver) return Promise.reject(/* @__PURE__ */ new Error("Clarify is not available for this session (use webchat, Telegram, or CLI)"));
-		return this.clarifyBridge.startRequest({
-			timeoutMs: this.externalClarificationTimeouts.get(sessionKey),
+		const persistedSession = getClarificationSnapshot(sessionKey);
+		if (!persistedSession && this.externalStreamBySession.has(sessionKey)) return this.ephemeralClarifications.start({
 			beforeResponse: this.externalClarificationResponses.get(sessionKey),
-			sessionKey,
 			runId,
-			publishStream,
-			request,
-			deliver
+			publish: publishStream,
+			request
+		}).then((answer) => ({
+			status: "answered",
+			answer
+		}));
+		if (!persistedSession) return Promise.reject(/* @__PURE__ */ new Error("Clarify requires a persisted session."));
+		const wait = createClarificationWait({
+			sessionKey,
+			runId: opts.runId,
+			toolCallId: opts.toolCallId,
+			kind: request.kind === "approval" ? "approval" : "input",
+			question: request.question,
+			choices: request.choices,
+			suggestedAnswer: request.suggestedAnswer,
+			approvalKey: request.approvalKey
+		});
+		const event = {
+			type: "clarify_request",
+			requestId: wait.id,
+			kind: wait.kind,
+			question: wait.question,
+			choices: wait.choices,
+			suggestedAnswer: wait.suggestedAnswer,
+			expiresAt: wait.expiresAt,
+			createdAt: wait.createdAt,
+			version: wait.version
+		};
+		if (this.activeWebchatRunBySession.has(sessionKey)) publishStream?.(event);
+		if (deliver) await deliver({
+			sessionKey,
+			requestId: wait.id,
+			request
 		});
+		return {
+			status: "waiting",
+			waitId: wait.id,
+			expiresAt: wait.expiresAt
+		};
 	}
 	async deliverTelegramClarify(ctx) {
 		const routing = (await this.opts.sessionIndex.getSessionMetadata(ctx.sessionKey).catch(() => null))?.routing;
 		if (!routing || routing.source !== "telegram") return;
 		let body = ctx.request.question;
-		if (ctx.request.default) body += `\n\nDefault if unsure: ${ctx.request.default}`;
+		if (ctx.request.suggestedAnswer) body += `\n\nSuggested answer (never selected automatically): ${ctx.request.suggestedAnswer}`;
+		body += ctx.request.kind === "approval" ? "\n\nFor safety, this approval expires after 10 minutes." : "\n\nThis question remains available until you answer or cancel the task.";
 		const choices = ctx.request.choices;
 		const buttonRows = choices && choices.length >= 2 ? choices.map((c, i) => [{
 			text: c.length > 64 ? `${c.slice(0, 61)}…` : c,
 			callback_data: `clarify:${ctx.requestId}:${i}`
 		}]) : void 0;
-		if (!buttonRows) body += "\n\nReply with your answer in this chat.";
+		body += buttonRows ? "\n\nReply with your answer, or tap an option below." : "\n\nReply with your answer.";
 		await this.opts.getChannelManager().send({
 			channel: "telegram",
 			chat_id: routing.peerId,

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

@@ -1,7 +1,7 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { loadConfig, saveConfig } from "../../config/loader.js";
 import { getModelRegistry } from "../../providers/model-registry.js";
+import { loadConfig, saveConfig } from "../../config/loader.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";

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

@@ -1,6 +1,7 @@
 import { inboundCorrelationMetadataFromAsyncLogContext, updateAsyncLogContext } from "../../utils/logger/context.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { isClarificationSuspended } from "../../storage/sqlite/clarification-wait-repository.js";
 import { updateInteractionStateFromMessage } from "../../storage/sqlite/interaction-state-repository.js";
 import { getConnectionResumeInput, isConnectionSuspended } from "../../storage/sqlite/connection-wait-repository.js";
 import "../../storage/sqlite/index.js";
@@ -144,9 +145,11 @@ async function* runGatewayAgent(deps, message, channel, chatId, origin, attachme
 					for await (const event of eventStream) yield* mapper.map(event);
 				})();
 				for await (const event of coalesceThinkingDeltas(mappedEvents)) yield* emitAndYield([event]);
-				const suspended = isConnectionSuspended(sessionKey, runId);
+				const connectionSuspended = isConnectionSuspended(sessionKey, runId);
+				const clarificationSuspended = isClarificationSuspended(sessionKey, runId);
+				const suspended = connectionSuspended || clarificationSuspended;
 				const endStatus = mergedSignal.aborted ? "cancelled" : suspended ? "suspended" : "success";
-				const endSummary = mergedSignal.aborted ? "Interrupted" : suspended ? "Waiting for connection" : "Message processed successfully";
+				const endSummary = mergedSignal.aborted ? "Interrupted" : connectionSuspended ? "Waiting for connection" : clarificationSuspended ? "Waiting for user input" : "Message processed successfully";
 				taskRunStatus = mergedSignal.aborted ? "cancelled" : "succeeded";
 				terminalStatus = endStatus;
 				taskRunSummary = endSummary;

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

@@ -1,6 +1,7 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { SessionInstanceChangedError, cancelQueuedSessionInput, claimNextSessionInput, findSessionInput, finishSessionInputRun, getSessionInputById, getSessionInputState, insertSessionInput, mutateQueuedSessionInput, recoverSessionInputState, setSessionInputStatus } from "../../storage/sqlite/session-input-repository.js";
+import { consumeClarificationResume, supersedeActiveClarification } from "../../storage/sqlite/clarification-wait-repository.js";
 import { replaceLatestSessionTurnAndQueueInput, validateLatestSessionTurnTarget } from "../../storage/sqlite/session-turn-replace-repository.js";
 import { cancelConnectionObjective, consumeConnectionResume, invalidateConnectionResumeIntent, publishConnectionWait } from "../../storage/sqlite/connection-wait-repository.js";
 import "../../storage/sqlite/index.js";
@@ -113,6 +114,7 @@ var SessionInputCoordinator = class {
 			if (result.ok === false) return result;
 			if (!result.idempotent) {
 				cancelConnectionObjective(sessionKey);
+				supersedeActiveClarification(sessionKey);
 				const replacement = {
 					role: "user",
 					content,
@@ -187,6 +189,7 @@ var SessionInputCoordinator = class {
 			targetRunId: canSteer ? runtime.activeRunId : void 0
 		});
 		invalidateConnectionResumeIntent(sessionKey);
+		supersedeActiveClarification(sessionKey);
 		if (canSteer) {
 			if (!await this.deps.steer(sessionKey, content)) {
 				setSessionInputStatus(row.id, "queued", {
@@ -221,7 +224,7 @@ var SessionInputCoordinator = class {
 				const runId = crypto.randomUUID();
 				const input = claimNextSessionInput(sessionKey, runId);
 				if (!input) return;
-				if (this.deps.beforeExecute && !await this.deps.beforeExecute(input) || !consumeConnectionResume(input)) {
+				if (this.deps.beforeExecute && !await this.deps.beforeExecute(input) || !consumeConnectionResume(input) || !consumeClarificationResume(input)) {
 					finishSessionInputRun(sessionKey, runId, "cancelled");
 					this.publish(sessionKey);
 					continue;

package/dist/src/gateway/service/sessions-api.js

@@ -4,8 +4,8 @@ import { retireSessionMcpRuntimeForSessionKey } from "../../agent/mcp/bundle-mcp
 import "../../agent/mcp/bundle-mcp-tools.js";
 import { buildSessionTimeline } from "../../session/transcript-outline.js";
 import { transcriptRowsToClientHistory } from "../../session/client-history.js";
-import { withModelConfigLock } from "../../session/model-config-lock.js";
 import { collectMediaUrisFromValues, deleteMediaUris } from "../../media/session-references.js";
+import { withModelConfigLock } from "../../session/model-config-lock.js";
 import { getDistinctSessionChatIds } from "./session-chat-ids.js";
 import { performSessionReset } from "../session-reset-service.js";
 import { randomUUID } from "node:crypto";

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

@@ -12,16 +12,16 @@ import { getSessionConfig } from "../storage/sqlite/config-repository.js";
 import "../storage/sqlite/index.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { init_agent_scope, listAgentEntries, normalizeAgentId, resolveAgentWorkspaceDir, 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 { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { init_paths, 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 { prewarmModelRegistry } from "../providers/model-registry.js";
+import { buildSessionKey, init_session_key, sanitizeSegment } from "../routing/session-key.js";
+import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
 import { init_providers, providers_exports } from "../providers/index.js";
+import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { TaskRepository } from "../tasks/task-repository.js";
 import { TaskConversationRepository } from "../tasks/task-conversation-repository.js";
 import { getEmbeddedExecutionSession } from "../agent/embedded/execution-context.js";
@@ -50,10 +50,16 @@ 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";
+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";
@@ -61,12 +67,6 @@ import { ConnectionRecoveryService } from "../connectors/connection-recovery-ser
 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";
@@ -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;