@xopcai/xopc 0.0.252 → 0.0.253

package/dist/src/agent/embedded/run-for-session.js

@@ -3,6 +3,7 @@ import { init_logger } from "../../utils/logger.js";
 import { parseTurnOutcome } from "../../../packages/gateway-contract/src/turn-outcome.js";
 import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { init_providers, resolveModel } from "../../providers/index.js";
+import { runWithEmbeddedExecutionSession } from "./execution-context.js";
 import { resolveAgentTurnTimeoutMs } from "../orchestration/run-agent-turn-with-timeout.js";
 import { resolvePromptCachePolicy } from "../../providers/prompt-cache-plan.js";
 import { evaluateContextBudget } from "../memory/context-budget.js";
@@ -27,7 +28,7 @@ async function runEmbeddedTurnForSession(params) {
 		parentSignal: params.abortSignal
 	});
 	const finish = async (result) => {
-		if (result.stopReason === "connection_required") return result;
+		if (result.stopReason === "connection_required" || result.stopReason === "clarification_required") return result;
 		try {
 			const rows = await sessionStore.loadTranscriptRows(sessionKey);
 			const hasTurn = rows.some((source) => {
@@ -180,7 +181,7 @@ async function runEmbeddedTurnForSession(params) {
 				total: resolvedCandidates.length
 			}, "Agent model fallback started");
 			try {
-				const turnResult = await runXopcEmbeddedTurn({
+				const turnResult = await runWithEmbeddedExecutionSession(sessionKey, () => runXopcEmbeddedTurn({
 					sessionKey,
 					runId,
 					userMessage: userMessageForTurn,
@@ -199,7 +200,7 @@ async function runEmbeddedTurnForSession(params) {
 					onEvent: params.onEvent,
 					onAgentEvent: (event) => agentManager.emitRuntimeEvent(sessionKey, event),
 					resumeLastUserMessage
-				});
+				}), runId);
 				if (turnResult.ok) {
 					if (isFallbackAttempt) log.info({
 						sessionKey,

package/dist/src/agent/embedded/run-turn.js

@@ -1,5 +1,6 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { getClarificationResumeInput, isClarificationSuspended } from "../../storage/sqlite/clarification-wait-repository.js";
 import { getConnectionResumeInput, isConnectionSuspended } from "../../storage/sqlite/connection-wait-repository.js";
 import { EmbeddedRunConflictError, abortEmbeddedRun, acquireEmbeddedRunLease, queueEmbeddedSteer } from "./runs.js";
 import { lastAssistantPlainText, subscribeEmbeddedSessionEvents } from "./subscribe-session.js";
@@ -235,6 +236,7 @@ async function runXopcEmbeddedTurn(params) {
 		});
 		let policyStopped = false;
 		let connectionStopped = false;
+		let clarificationStopped = false;
 		params.turnPolicy?.reset();
 		session.agent.beforeToolCall = async (context, signal) => {
 			if (connectionStopped) return {
@@ -242,6 +244,11 @@ async function runXopcEmbeddedTurn(params) {
 				reason: "Waiting for the user to connect an app.",
 				terminate: true
 			};
+			if (clarificationStopped) return {
+				block: true,
+				reason: "Waiting for the user to answer.",
+				terminate: true
+			};
 			const decision = await params.turnPolicy?.beforeToolCall(context, signal);
 			if (decision?.block) {
 				policyStopped ||= decision.terminate === true;
@@ -259,6 +266,7 @@ async function runXopcEmbeddedTurn(params) {
 		};
 		session.agent.afterToolCall = async (context) => {
 			connectionStopped ||= isConnectionSuspended(sessionKey, runId);
+			clarificationStopped ||= isClarificationSuspended(sessionKey, runId);
 			const scoped = context.toolCall.name === "read_file" ? await instructions.forTool(context.toolCall.name, context.args) : "";
 			const checked = await verification.afterTool(context);
 			if (scoped) checked.result.content.unshift({
@@ -273,7 +281,7 @@ async function runXopcEmbeddedTurn(params) {
 		};
 		session.agent.shouldStopAfterTurn = (context) => {
 			policyStopped ||= params.turnPolicy?.shouldStopAfterTurn(context) ?? false;
-			return policyStopped || connectionStopped;
+			return policyStopped || connectionStopped || clarificationStopped;
 		};
 		unsubscribe = subscribeEmbeddedSessionEvents(session, (event) => {
 			if (event.type === "message_end" && event.message.role === "assistant") recordPromptCacheTouch(sessionKey, resolvedModel, event.message.usage);
@@ -290,11 +298,17 @@ async function runXopcEmbeddedTurn(params) {
 		try {
 			await runAgentTurnWithTimeout(session.agent, async () => {
 				const connectionResume = getConnectionResumeInput(sessionKey, runId);
+				const clarificationResume = getClarificationResumeInput(sessionKey, runId);
 				if (connectionResume) await session.sendCustomMessage({
 					customType: "connection_resume",
 					content: connectionResume.content,
 					display: false
 				}, { triggerTurn: true });
+				else if (clarificationResume) await session.sendCustomMessage({
+					customType: "clarification_resume",
+					content: clarificationResume.content,
+					display: false
+				}, { triggerTurn: true });
 				else if (params.resumeLastUserMessage) await session.agent.continue();
 				else {
 					const text = userMessageToPromptText(userMessage);
@@ -302,7 +316,8 @@ async function runXopcEmbeddedTurn(params) {
 					await session.prompt(text, images.length > 0 ? { images } : void 0);
 				}
 				await session.agent.waitForIdle();
-				if (connectionStopped) return;
+				clarificationStopped ||= isClarificationSuspended(sessionKey, runId);
+				if (connectionStopped || clarificationStopped) return;
 				await maybeRetryTurnAfterTransientLlmFailure(session.agent, {
 					sessionKey,
 					log,
@@ -330,6 +345,10 @@ async function runXopcEmbeddedTurn(params) {
 				runId,
 				sessionKey
 			});
+			if (clarificationStopped) runner.piSm.appendCustomEntry("clarification_required", {
+				runId,
+				sessionKey
+			});
 			runner.piSm.appendCustomEntry("coding_verification", {
 				runId,
 				workspace: workspaceDir,
@@ -356,7 +375,7 @@ async function runXopcEmbeddedTurn(params) {
 			});
 			return {
 				ok: true,
-				...connectionStopped ? { stopReason: "connection_required" } : {},
+				...connectionStopped ? { stopReason: "connection_required" } : clarificationStopped ? { stopReason: "clarification_required" } : {},
 				lastAssistantText: lastAssistantPlainText(session)
 			};
 		} finally {

package/dist/src/agent/embedded/types.d.ts

@@ -89,7 +89,7 @@ export type RunXopcEmbeddedTurnParams = {
 };
 export type RunXopcEmbeddedTurnResult = {
     ok: boolean;
-    stopReason?: 'connection_required';
+    stopReason?: 'connection_required' | 'clarification_required';
     /** False for harness failures that must not trigger another model attempt. */
     retryable?: boolean;
     errorMessage?: string;

package/dist/src/agent/service/direct-turn-helpers.js

@@ -1,3 +1,4 @@
+import { getClarificationResumeInput } from "../../storage/sqlite/clarification-wait-repository.js";
 import { getConnectionResumeInput } from "../../storage/sqlite/connection-wait-repository.js";
 import { resolveImageHandlingStrategy } from "../image/vision-detection.js";
 import { hydrateUserTurnForLlm } from "../inbound/attachment-pipeline.js";
@@ -87,6 +88,8 @@ async function tryRunSlashCommand(deps, ctx, content, options) {
 async function runDirectAgentTurn(deps, input) {
 	const turnId = input.runId ?? crypto.randomUUID();
 	const isConnectionResume = Boolean(getConnectionResumeInput(input.sessionKey, turnId));
+	const isClarificationResume = Boolean(getClarificationResumeInput(input.sessionKey, turnId));
+	const isResume = isConnectionResume || isClarificationResume;
 	const userPlain = extractAgentUserPlainText(input.userMessage);
 	const userContext = await deps.agentManager.prepareUserTurnContext(input.userMessage, input.sessionKey, turnId);
 	const sourceContexts = input.sourceContexts ?? [];
@@ -111,11 +114,11 @@ async function runDirectAgentTurn(deps, input) {
 		getConfig: () => deps.config,
 		abortSignal: input.abortSignal,
 		deadlineAtMs: input.deadlineAtMs,
-		beforeTurn: isConnectionResume ? void 0 : () => deps.agentManager.beginBackgroundReviewUserTurn(input.sessionKey),
+		beforeTurn: isResume ? void 0 : () => deps.agentManager.beginBackgroundReviewUserTurn(input.sessionKey),
 		onEvent: input.onEvent
 	});
-	if (!isConnectionResume) await deps.agentManager.afterAgentTurn(input.sessionKey, userPlain, turnId);
-	if (!isConnectionResume && result.stopReason !== "connection_required") deps.agentManager.scheduleBackgroundReviewAfterUserTurn(input.sessionKey);
+	if (!isResume) await deps.agentManager.afterAgentTurn(input.sessionKey, userPlain, turnId);
+	if (!isResume && result.stopReason !== "connection_required" && result.stopReason !== "clarification_required") deps.agentManager.scheduleBackgroundReviewAfterUserTurn(input.sessionKey);
 	return result;
 }
 //#endregion

package/dist/src/agent/service/process-direct-streaming.js

@@ -1,3 +1,4 @@
+import { getClarificationResumeInput } from "../../storage/sqlite/clarification-wait-repository.js";
 import { getConnectionResumeInput } from "../../storage/sqlite/connection-wait-repository.js";
 import { readAgentMessageContent } from "../memory/agent-message-access.js";
 import { abortEmbeddedRun } from "../embedded/runs.js";
@@ -126,6 +127,8 @@ function pushAssistantReceipt(queue, text, runId, metadata) {
 async function* runProcessDirectStreaming(deps, input) {
 	const sessionKey = input.sessionKey ?? "agent:main:main";
 	const isConnectionResume = Boolean(input.runId && getConnectionResumeInput(sessionKey, input.runId));
+	const isClarificationResume = Boolean(input.runId && getClarificationResumeInput(sessionKey, input.runId));
+	const isInternalResume = isConnectionResume || isClarificationResume;
 	const { channel, chatId } = await deps.resolveSessionEndpoint(sessionKey);
 	const context = deps.initDirectStreamingSession(sessionKey, channel, chatId, input.origin);
 	const queue = new AsyncQueue({
@@ -276,7 +279,7 @@ async function* runProcessDirectStreaming(deps, input) {
 					if (sourceContext && !sourceContexts.some((context) => context.kind === sourceContext.kind && context.sourceId === sourceContext.sourceId)) sourceContexts.push(sourceContext);
 				}
 			}
-			if (channel === "webchat" && !isConnectionResume) {
+			if (channel === "webchat" && !isInternalResume) {
 				pushVisible({
 					type: "user_message",
 					timestamp: userMessage.timestamp ?? Date.now(),
@@ -287,7 +290,7 @@ async function* runProcessDirectStreaming(deps, input) {
 				if (textForAgent.trim()) deps.enqueueProvisionalSessionTitle?.(sessionKey, textForAgent);
 			}
 			const pendingUserMessage = sourceContexts.length > 0 ? injectSourceContextsIntoUserMessage(userMessage, sourceContexts) : userMessage;
-			if (!isConnectionResume) setPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
+			if (!isInternalResume) setPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
 			try {
 				const result = await deps.agentManager.withSkillCapabilities(sessionKey, skillTurn.activatedCapabilityNames, () => runDirectAgentTurn({
 					sessionStore: deps.sessionStore,
@@ -314,7 +317,7 @@ async function* runProcessDirectStreaming(deps, input) {
 					content: formatStreamError(result.errorMessage)
 				});
 			} finally {
-				if (!isConnectionResume) clearPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
+				if (!isInternalResume) clearPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
 			}
 		} catch (err) {
 			if (err instanceof AsyncQueueOverflowError) {

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

@@ -121,12 +121,14 @@ export declare class AgentService {
     refreshUserProfileContext(): void;
     getMemoryManager(): import("./memory/manager.js").MemoryManager;
     getModelForSession(sessionKey: string): string;
+    getThinkingLevelForSession(sessionKey: string): ThinkingLevel;
     /** Run a full tool-capable turn against a caller-owned, non-persistent transcript. */
     runEphemeralTurn(params: {
         executionSessionKey: string;
         parentSessionKey: string;
         runId: string;
         content: string;
+        attachments?: InboundAttachmentInput[];
         modelRef: string;
         thinkingLevel?: ThinkingLevel;
         transcriptRuntime: EmbeddedTranscriptRuntime;

package/dist/src/agent/service.js

@@ -19,6 +19,7 @@ import "../user-model/index.js";
 import { resolveAgentTurnTimeoutMs } from "./orchestration/run-agent-turn-with-timeout.js";
 import { onSessionTranscriptUpdate } from "../session/transcript-events.js";
 import { persistInboundAttachments } from "../channels/attachments/inbound-persist.js";
+import { buildTranscriptUserMessage, hydrateUserTurnForLlm } from "./inbound/attachment-pipeline.js";
 import { runXopcEmbeddedTurn } from "./embedded/run-turn.js";
 import { resolveResponseLanguageForSession } from "./prompt/response-language.js";
 import { normalizeSkillInstallTarget } from "./skills/install-target.js";
@@ -577,19 +578,31 @@ var AgentService = class {
 	getModelForSession(sessionKey) {
 		return this.modelManager.getModelForSession(sessionKey);
 	}
+	getThinkingLevelForSession(sessionKey) {
+		return this.agentManager.getOrCreateAgent(sessionKey).state.thinkingLevel ?? "medium";
+	}
 	/** Run a full tool-capable turn against a caller-owned, non-persistent transcript. */
 	async runEphemeralTurn(params) {
 		const agent = this.agentManager.getOrCreateAgent(params.parentSessionKey);
 		const workspaceDir = this.agentManager.getResolvedWorkspaceForSession(params.parentSessionKey);
 		const model = resolveModel(params.modelRef);
+		const prepared = await this.prepareInboundAttachments(params.executionSessionKey, params.attachments);
+		const userMessage = await buildTranscriptUserMessage({
+			text: params.content,
+			prepared,
+			sessionKey: params.parentSessionKey,
+			modelRef: params.modelRef,
+			config: this.effectiveAppConfig(),
+			agentManager: this.agentManager
+		});
+		const llmTurn = await hydrateUserTurnForLlm({
+			message: userMessage,
+			modelRef: params.modelRef
+		});
 		return runWithEmbeddedExecutionSession(params.executionSessionKey, () => runXopcEmbeddedTurn({
 			sessionKey: params.executionSessionKey,
 			runId: params.runId,
-			userMessage: {
-				role: "user",
-				content: params.content,
-				timestamp: Date.now()
-			},
+			userMessage,
 			model,
 			modelRef: params.modelRef,
 			tools: agent.state.tools,
@@ -600,8 +613,9 @@ var AgentService = class {
 			timeoutMs: resolveAgentTurnTimeoutMs(this.effectiveAppConfig(), params.parentSessionKey),
 			turnPolicy: this.agentManager.createAgentTurnPolicy(params.parentSessionKey),
 			abortSignal: params.abortSignal,
-			onEvent: params.onEvent
-		}));
+			onEvent: params.onEvent,
+			images: llmTurn.images
+		}), params.runId);
 	}
 	async switchModelForSession(sessionKey, modelId) {
 		if (!await this.modelManager.switchModelForSession(sessionKey, modelId)) return false;

package/dist/src/agent/tools/clarify-tool.d.ts

@@ -3,11 +3,25 @@ export type ClarifyRequestPayload = {
     kind?: 'approval';
     question: string;
     choices?: string[];
-    default?: string;
+    suggestedAnswer?: string;
+    /** Stable hash of the exact operation guarded by an approval. */
+    approvalKey?: string;
 };
-export type GatewayClarifyRequestFn = (sessionKey: string, request: ClarifyRequestPayload) => Promise<string>;
+export type ClarifyRequestResult = {
+    status: 'answered';
+    answer: string;
+} | {
+    status: 'waiting';
+    waitId: string;
+    expiresAt?: number;
+};
+export type GatewayClarifyRequestFn = (context: {
+    sessionKey: string;
+    runId: string;
+    toolCallId: string;
+}, request: ClarifyRequestPayload) => Promise<ClarifyRequestResult>;
 export interface ClarifyToolDeps {
     /** Resolve a per-turn callback; returns null when clarification is unavailable. */
-    resolveAskUser: () => ((request: ClarifyRequestPayload) => Promise<string>) | null;
+    resolveAskUser: (toolCallId: string) => ((request: ClarifyRequestPayload) => Promise<ClarifyRequestResult>) | null;
 }
 export declare function createClarifyTool(deps: ClarifyToolDeps): AgentTool;

package/dist/src/agent/tools/clarify-tool.js

@@ -7,7 +7,7 @@ const ClarifySchema = Type.Object({
 		minItems: 2,
 		maxItems: 10
 	})),
-	default: Type.Optional(Type.String({ description: "Default answer if the user does not respond within timeout." }))
+	suggestedAnswer: Type.Optional(Type.String({ description: "Optional recommendation shown to the user. It is never selected automatically." }))
 });
 function waitForAbort(signal) {
 	return new Promise((_, reject) => {
@@ -23,40 +23,42 @@ function createClarifyTool(deps) {
 	return {
 		name: "clarify",
 		label: "❓ Clarify",
-		description: "Ask the user a clarifying question and wait for their response.\n\nUse this when you need more information to proceed correctly, rather than guessing.\n\nWHEN TO USE:\n- Ambiguous instructions with multiple valid interpretations\n- Missing critical information (which file, which approach, etc.)\n- Confirming destructive or irreversible actions\n\nWHEN NOT TO USE:\n- When you can reasonably infer the answer from context\n- For trivial decisions that do not affect the task\n- When the user explicitly said \"just do it\" or \"your choice\"\n\nTIPS:\n- Provide choices when there are clear options (faster for the user)\n- Keep questions short and specific\n- Include a default when one option is clearly more likely",
+		description: "Ask the user a clarifying question and pause the objective until they respond.\n\nUse this when you need more information to proceed correctly, rather than guessing.\n\nWHEN TO USE:\n- Ambiguous instructions with multiple valid interpretations\n- Missing critical information (which file, which approach, etc.)\n- Confirming destructive or irreversible actions\n\nWHEN NOT TO USE:\n- When you can reasonably infer the answer from context\n- For trivial decisions that do not affect the task\n- When the user explicitly said \"just do it\" or \"your choice\"\n\nTIPS:\n- Provide choices when there are clear options (faster for the user)\n- Keep questions short and specific\n- Include a suggested answer when one option is clearly more likely",
 		parameters: ClarifySchema,
-		async execute(_toolCallId, params, signal) {
+		async execute(toolCallId, params, signal) {
 			const p = params;
-			const askUser = deps.resolveAskUser();
-			if (!askUser) {
-				if (p.default !== void 0 && p.default !== "") return {
-					content: [{
-						type: "text",
-						text: `Interactive clarification is not available in this environment. Using default: ${p.default}`
-					}],
-					details: { answer: p.default }
-				};
-				return {
-					content: [{
-						type: "text",
-						text: "Clarification is not available in this environment (no active webchat run). Provide a default or proceed with the best assumption."
-					}],
-					details: { answer: "" }
-				};
-			}
+			const askUser = deps.resolveAskUser(toolCallId);
+			if (!askUser) return {
+				content: [{
+					type: "text",
+					text: "Clarification is not available in this environment. Proceed with the best safe assumption or explain what is missing."
+				}],
+				details: { answer: "" }
+			};
 			const payload = {
 				question: p.question,
 				choices: p.choices,
-				default: p.default
+				suggestedAnswer: p.suggestedAnswer
 			};
 			try {
-				const answer = await Promise.race([askUser(payload), waitForAbort(signal)]);
+				const result = await Promise.race([askUser(payload), waitForAbort(signal)]);
+				if (result.status === "waiting") return {
+					content: [{
+						type: "text",
+						text: "Waiting for the user to answer this clarification. End the current run now."
+					}],
+					details: {
+						answer: "",
+						waitId: result.waitId,
+						status: result.status
+					}
+				};
 				return {
 					content: [{
 						type: "text",
-						text: `User answered: ${answer}`
+						text: `User answered: ${result.answer}`
 					}],
-					details: { answer }
+					details: { answer: result.answer }
 				};
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
@@ -65,14 +67,7 @@ function createClarifyTool(deps) {
 						type: "text",
 						text: "Clarification cancelled (run aborted)."
 					}],
-					details: { answer: p.default ?? "" }
-				};
-				if (p.default !== void 0 && p.default !== "" && message.toLowerCase().includes("timeout")) return {
-					content: [{
-						type: "text",
-						text: `User did not respond in time. Using default: ${p.default}`
-					}],
-					details: { answer: p.default }
+					details: { answer: "" }
 				};
 				return {
 					content: [{

package/dist/src/agent/tools/cli-clarify.js

@@ -5,7 +5,7 @@ import * as readline from "node:readline/promises";
 * stdin/stdout prompts for `clarify` when running the CLI agent (no gateway).
 */
 function createCliReadlineClarifyRequestFn() {
-	return async (_sessionKey, req) => {
+	return async (_context, req) => {
 		const rl = readline.createInterface({
 			input: stdin,
 			output: stdout
@@ -15,19 +15,34 @@ function createCliReadlineClarifyRequestFn() {
 			if (choices && choices.length >= 2) {
 				stdout.write(`\n${req.question}\n`);
 				choices.forEach((c, i) => stdout.write(`  ${i + 1}) ${c}\n`));
-				if (req.default) stdout.write(`  (default: ${req.default})\n`);
+				if (req.suggestedAnswer) stdout.write(`  (recommended: ${req.suggestedAnswer})\n`);
 				const raw = (await rl.question("Choice (number or exact text): ")).trim();
 				const n = parseInt(raw, 10);
-				if (!Number.isNaN(n) && n >= 1 && n <= choices.length) return choices[n - 1];
-				if (raw) return raw;
-				if (req.default) return req.default;
+				if (!Number.isNaN(n) && n >= 1 && n <= choices.length) return {
+					status: "answered",
+					answer: choices[n - 1]
+				};
+				if (raw) return {
+					status: "answered",
+					answer: raw
+				};
+				if (req.suggestedAnswer) return {
+					status: "answered",
+					answer: req.suggestedAnswer
+				};
 				throw new Error("No answer provided");
 			}
 			stdout.write(`\n${req.question}\n`);
-			if (req.default) stdout.write(`(Press Enter for default: ${req.default})\n`);
+			if (req.suggestedAnswer) stdout.write(`(Press Enter for recommendation: ${req.suggestedAnswer})\n`);
 			const raw = (await rl.question("> ")).trim();
-			if (raw) return raw;
-			if (req.default) return req.default;
+			if (raw) return {
+				status: "answered",
+				answer: raw
+			};
+			if (req.suggestedAnswer) return {
+				status: "answered",
+				answer: req.suggestedAnswer
+			};
 			throw new Error("No answer provided");
 		} finally {
 			rl.close();

package/dist/src/agent/tools/factory.js

@@ -7,7 +7,7 @@ import { getSessionTaskPlan, setSessionTaskPlan } from "../../storage/sqlite/ses
 import "../../storage/sqlite/index.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../agent-scope.js";
 import { resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
-import { getEmbeddedExecutionSession } from "../embedded/execution-context.js";
+import { getEmbeddedExecutionRunId, getEmbeddedExecutionSession } from "../embedded/execution-context.js";
 import { wrapToolsWithProtection } from "./executor.js";
 import { EXTERNAL_TOOL_NAMES } from "../external-tools/gateway-tools.js";
 import { buildRuntimeEnvironment } from "../../runtime-tools/environment.js";
@@ -215,15 +215,25 @@ var AgentToolsFactory = class AgentToolsFactory {
 			createSessionStatusTool(),
 			createMemoryMaintenanceTool({ getConfig: () => this.deps.getConfig?.() }),
 			createToolManualTool(),
-			createClarifyTool({ resolveAskUser: () => {
+			createClarifyTool({ resolveAskUser: (toolCallId) => {
 				const req = this.deps.gatewayClarify?.requestClarification;
 				if (!req) return null;
 				const executionSession = getEmbeddedExecutionSession();
-				if (executionSession) return (r) => req(executionSession, r);
+				const runId = getEmbeddedExecutionRunId();
+				if (executionSession && runId) return (request) => req({
+					sessionKey: executionSession,
+					runId,
+					toolCallId
+				}, request);
 				const ctx = this.deps.getCurrentContext();
 				if (!ctx?.sessionKey) return null;
 				if (!CLARIFY_SUPPORTED_CHANNELS.has(ctx.channel)) return null;
-				return (r) => req(ctx.sessionKey, r);
+				if (!runId) return null;
+				return (request) => req({
+					sessionKey: ctx.sessionKey,
+					runId,
+					toolCallId
+				}, request);
 			} }),
 			createTodoTool({
 				getSessionKey: () => this.deps.getCurrentContext()?.sessionKey,

package/dist/src/automations/domain/validation.d.ts

@@ -117,9 +117,9 @@ export declare const AutomationActionSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
         type: z.ZodLiteral<"add_wait">;
         wait: z.ZodObject<{
             kind: z.ZodEnum<{
+                approval: "approval";
                 dependency: "dependency";
                 user_input: "user_input";
-                approval: "approval";
                 external_event: "external_event";
                 scheduled_time: "scheduled_time";
                 retry_backoff: "retry_backoff";
@@ -294,9 +294,9 @@ export declare const AutomationSchema: z.ZodObject<{
             type: z.ZodLiteral<"add_wait">;
             wait: z.ZodObject<{
                 kind: z.ZodEnum<{
+                    approval: "approval";
                     dependency: "dependency";
                     user_input: "user_input";
-                    approval: "approval";
                     external_event: "external_event";
                     scheduled_time: "scheduled_time";
                     retry_backoff: "retry_backoff";
@@ -456,9 +456,9 @@ export declare const CreateAutomationSchema: z.ZodObject<{
             type: z.ZodLiteral<"add_wait">;
             wait: z.ZodObject<{
                 kind: z.ZodEnum<{
+                    approval: "approval";
                     dependency: "dependency";
                     user_input: "user_input";
-                    approval: "approval";
                     external_event: "external_event";
                     scheduled_time: "scheduled_time";
                     retry_backoff: "retry_backoff";
@@ -645,9 +645,9 @@ export declare const UpdateAutomationSchema: z.ZodObject<{
             type: z.ZodLiteral<"add_wait">;
             wait: z.ZodObject<{
                 kind: z.ZodEnum<{
+                    approval: "approval";
                     dependency: "dependency";
                     user_input: "user_input";
-                    approval: "approval";
                     external_event: "external_event";
                     scheduled_time: "scheduled_time";
                     retry_backoff: "retry_backoff";

package/dist/src/automations/draft/automation-draft-validator.d.ts

@@ -79,7 +79,7 @@ export declare function buildAutomationDraftResponse(draft: GeneratedAutomationD
             } | {
                 type: "add_wait";
                 wait: {
-                    kind: "dependency" | "user_input" | "approval" | "external_event" | "scheduled_time" | "retry_backoff" | "paused";
+                    kind: "approval" | "dependency" | "user_input" | "external_event" | "scheduled_time" | "retry_backoff" | "paused";
                     reason: string;
                     condition: Record<string, unknown>;
                     resumeAt?: number;

package/dist/src/cli/commands/doctor/checks/database-schema.js

@@ -52,7 +52,7 @@ async function checkDatabaseSchema(ctx) {
 		id: "database-schema",
 		label: "Database schema",
 		status: "pass",
-		message: `SQLite schema v${status.dbVersion} (current release v153).`,
+		message: `SQLite schema v${status.dbVersion} (current release v154).`,
 		hints: []
 	};
 }

package/dist/src/gateway/chat-stream/mapper.js

@@ -95,9 +95,13 @@ var ChatStreamMapper = class {
 			})];
 			case "clarify_request": return [this.make("clarify_request", {
 				requestId: String(event.requestId ?? ""),
+				kind: event.kind === "approval" ? "approval" : "input",
 				question: String(event.question ?? ""),
 				choices: Array.isArray(event.choices) ? event.choices.filter((x) => typeof x === "string") : void 0,
-				default: typeof event.default === "string" ? event.default : void 0,
+				suggestedAnswer: typeof event.suggestedAnswer === "string" ? event.suggestedAnswer : void 0,
+				version: typeof event.version === "number" ? event.version : 1,
+				createdAt: typeof event.createdAt === "number" ? event.createdAt : Date.now(),
+				expiresAt: typeof event.expiresAt === "number" ? event.expiresAt : void 0,
 				petFeedback: createPetFeedback("clarify")
 			})];
 			case "turn_outcome": {

package/dist/src/gateway/chat-stream/protocol.d.ts

@@ -200,9 +200,13 @@ export type TtsAudioEvent = ChatStreamEnvelope<'tts_audio', {
 }>;
 export type ClarifyRequestEvent = ChatStreamEnvelope<'clarify_request', {
     requestId: string;
+    kind: 'input' | 'approval';
     question: string;
     choices?: string[];
-    default?: string;
+    suggestedAnswer?: string;
+    version: number;
+    createdAt: number;
+    expiresAt?: number;
     petFeedback: PetFeedback;
 }>;
 export type RunEndEvent = ChatStreamEnvelope<'run_end', {

package/dist/src/gateway/clarify-runtime.d.ts

@@ -1,5 +1,7 @@
-import type { ClarifyBridge } from './clarify-bridge.js';
-export declare function registerClarifyBridge(bridge: ClarifyBridge | null): void;
-export declare function submitClarifyResponseFromChannel(requestId: string, answer: string): boolean;
-export declare function submitClarifyChoiceFromChannel(requestId: string, choiceIndex: number): boolean;
-export declare function tryConsumeTelegramClarifyFreeText(sessionKey: string, text: string): boolean;
+export type ClarificationChannelRuntime = {
+    answerChoice(requestId: string, choiceIndex: number, idempotencyKey: string): boolean;
+    answerText(sessionKey: string, text: string, idempotencyKey: string): boolean;
+};
+export declare function registerClarificationChannelRuntime(next: ClarificationChannelRuntime | null): void;
+export declare function answerClarificationChoiceFromChannel(requestId: string, choiceIndex: number, idempotencyKey: string): boolean;
+export declare function answerClarificationTextFromChannel(sessionKey: string, text: string, idempotencyKey: string): boolean;

package/dist/src/gateway/clarify-runtime.js

@@ -1,16 +1,13 @@
 //#region src/gateway/clarify-runtime.ts
-let bridgeRef = null;
-function registerClarifyBridge(bridge) {
-	bridgeRef = bridge;
+let runtime = null;
+function registerClarificationChannelRuntime(next) {
+	runtime = next;
 }
-function submitClarifyResponseFromChannel(requestId, answer) {
-	return bridgeRef?.handleResponse(requestId, answer) ?? false;
+function answerClarificationChoiceFromChannel(requestId, choiceIndex, idempotencyKey) {
+	return runtime?.answerChoice(requestId, choiceIndex, idempotencyKey) ?? false;
 }
-function submitClarifyChoiceFromChannel(requestId, choiceIndex) {
-	return bridgeRef?.handleChoiceCallback(requestId, choiceIndex) ?? false;
-}
-function tryConsumeTelegramClarifyFreeText(sessionKey, text) {
-	return bridgeRef?.tryConsumeFreeTextReply(sessionKey, text) ?? false;
+function answerClarificationTextFromChannel(sessionKey, text, idempotencyKey) {
+	return runtime?.answerText(sessionKey, text, idempotencyKey) ?? false;
 }
 //#endregion
-export { registerClarifyBridge, submitClarifyChoiceFromChannel, submitClarifyResponseFromChannel, tryConsumeTelegramClarifyFreeText };
+export { answerClarificationChoiceFromChannel, answerClarificationTextFromChannel, registerClarificationChannelRuntime };

package/dist/src/gateway/ephemeral-clarification-waiter.d.ts

@@ -0,0 +1,17 @@
+import type { ClarifyRequestPayload } from '../agent/tools/clarify-tool.js';
+export type ClarificationStreamEvent = {
+    type: string;
+} & Record<string, unknown>;
+/** In-memory waiter exclusively for caller-owned ephemeral runs such as side chat. */
+export declare class EphemeralClarificationWaiter {
+    private readonly pending;
+    start(input: {
+        runId: string;
+        publish: (event: ClarificationStreamEvent) => void;
+        request: ClarifyRequestPayload;
+        beforeResponse?: () => boolean;
+    }): Promise<string>;
+    answer(requestId: string, answer: string): boolean;
+    cancelForRun(runId: string): void;
+    dispose(): void;
+}