@xopcai/xopc 0.0.252 → 0.0.253

package/dist/src/gateway/ephemeral-clarification-waiter.js

@@ -0,0 +1,46 @@
+//#region src/gateway/ephemeral-clarification-waiter.ts
+/** In-memory waiter exclusively for caller-owned ephemeral runs such as side chat. */
+var EphemeralClarificationWaiter = class {
+	pending = /* @__PURE__ */ new Map();
+	start(input) {
+		const requestId = crypto.randomUUID();
+		return new Promise((resolve, reject) => {
+			this.pending.set(requestId, {
+				runId: input.runId,
+				resolve,
+				reject,
+				beforeResponse: input.beforeResponse
+			});
+			input.publish({
+				type: "clarify_request",
+				requestId,
+				kind: input.request.kind ?? "input",
+				question: input.request.question,
+				choices: input.request.choices,
+				suggestedAnswer: input.request.suggestedAnswer,
+				version: 1,
+				createdAt: Date.now()
+			});
+		});
+	}
+	answer(requestId, answer) {
+		const pending = this.pending.get(requestId);
+		if (!pending || pending.beforeResponse?.() === false) return false;
+		this.pending.delete(requestId);
+		pending.resolve(answer.trim());
+		return true;
+	}
+	cancelForRun(runId) {
+		for (const [requestId, pending] of this.pending) {
+			if (pending.runId !== runId) continue;
+			this.pending.delete(requestId);
+			pending.reject(/* @__PURE__ */ new Error("Ephemeral clarification cancelled"));
+		}
+	}
+	dispose() {
+		for (const pending of this.pending.values()) pending.reject(/* @__PURE__ */ new Error("Gateway shutting down"));
+		this.pending.clear();
+	}
+};
+//#endregion
+export { EphemeralClarificationWaiter };

package/dist/src/gateway/hono/routes/agent-stream.js

@@ -122,38 +122,64 @@ function registerAgentStreamRoutes(authenticated, deps) {
 			payload: result.state
 		}, 409);
 	});
-	authenticated.post("/api/clarify/:requestId", chatRateLimitMiddleware, async (c) => {
-		const requestId = c.req.param("requestId")?.trim() ?? "";
-		if (!requestId) return c.json({
-			ok: false,
-			error: {
-				code: "BAD_REQUEST",
-				message: "Missing requestId"
-			}
-		}, 400);
-		const body = await c.req.json().catch(() => null);
-		const skip = body && typeof body === "object" && body.skip === true;
-		const rawAnswer = body && typeof body === "object" && typeof body.answer === "string" ? body.answer : "";
-		const answer = typeof rawAnswer === "string" ? rawAnswer.trim() : "";
-		if (!skip && !answer) return c.json({
+	authenticated.get("/api/sessions/:sessionKey/clarification", (c) => {
+		const sessionKey = (c.req.param("sessionKey") ?? "").trim();
+		if (!sessionKey) return c.json({
 			ok: false,
 			error: {
 				code: "BAD_REQUEST",
-				message: "Missing answer field"
+				message: "Missing sessionKey"
 			}
 		}, 400);
-		if (!service.submitClarifyResponse(requestId, skip ? "" : answer)) return c.json({
+		const snapshot = service.getClarificationState(sessionKey);
+		if (!snapshot) return c.json({
 			ok: false,
 			error: {
 				code: "NOT_FOUND",
-				message: "No pending clarification with this ID"
+				message: "Session not found"
 			}
 		}, 404);
 		return c.json({
 			ok: true,
-			payload: { received: true }
+			payload: snapshot
 		});
 	});
+	authenticated.post("/api/clarifications/:id/responses", chatRateLimitMiddleware, async (c) => {
+		const id = c.req.param("id")?.trim() ?? "";
+		const body = await c.req.json().catch(() => null);
+		const record = body && typeof body === "object" ? body : {};
+		const action = record.action;
+		const expectedVersion = record.expectedVersion;
+		const idempotencyKey = typeof record.idempotencyKey === "string" ? record.idempotencyKey.trim() : "";
+		if (!id || !idempotencyKey || typeof expectedVersion !== "number" || !Number.isInteger(expectedVersion) || action !== "answer" && action !== "agent_decide" && action !== "cancel") return c.json({
+			ok: false,
+			error: {
+				code: "BAD_REQUEST",
+				message: "Invalid clarification response"
+			}
+		}, 400);
+		const result = service.resolveClarificationResponse({
+			id,
+			expectedVersion,
+			idempotencyKey,
+			action,
+			answer: typeof record.answer === "string" ? record.answer : void 0
+		});
+		if (result.ok === true) return c.json({
+			ok: true,
+			payload: result
+		}, result.queued ? 202 : 200);
+		const status = result.code === "NOT_FOUND" ? 404 : result.code === "EXPIRED" ? 410 : result.code === "INVALID" ? 400 : 409;
+		const message = result.code === "NOT_FOUND" ? "This clarification is no longer active" : result.code === "EXPIRED" ? "This approval has expired" : result.code === "INVALID" ? "The clarification response is invalid" : "The clarification changed; reload and try again";
+		return c.json({
+			ok: false,
+			error: {
+				code: result.code,
+				message
+			},
+			payload: result.clarification
+		}, status);
+	});
 	authenticated.post("/api/send", chatRateLimitMiddleware, async (c) => {
 		const body = await c.req.json().catch(() => null);
 		const channel = typeof body?.channel === "string" ? body.channel : "";

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

@@ -45,11 +45,15 @@ export declare function submitSessionInput(c: Context, deps: AuthenticatedRouteD
                 status: import("../../../storage/sqlite/session-input-repository.js").SessionInputStatus;
                 content: string;
                 taskRunId?: string;
-                kind: "message" | "connection_resume";
+                kind: "message" | "connection_resume" | "clarification_resume";
                 payload?: {
                     waitId: string;
                     objectiveRevision: number;
                     resolution: "continued" | "skipped";
+                } | {
+                    waitId: string;
+                    objectiveRevision: number;
+                    resolution: "answered" | "agent_decide" | "cancelled";
                 };
                 attachments?: import("hono/dist/types/utils/types.js").JSONValue[];
                 contextRefs?: {
@@ -141,11 +145,15 @@ export declare function replaceLatestSessionTurn(c: Context, deps: Authenticated
                 status: import("../../../storage/sqlite/session-input-repository.js").SessionInputStatus;
                 content: string;
                 taskRunId?: string;
-                kind: "message" | "connection_resume";
+                kind: "message" | "connection_resume" | "clarification_resume";
                 payload?: {
                     waitId: string;
                     objectiveRevision: number;
                     resolution: "continued" | "skipped";
+                } | {
+                    waitId: string;
+                    objectiveRevision: number;
+                    resolution: "answered" | "agent_decide" | "cancelled";
                 };
                 attachments?: import("hono/dist/types/utils/types.js").JSONValue[];
                 contextRefs?: {

package/dist/src/gateway/hono/routes/side-chats.js

@@ -1,9 +1,13 @@
-import { validateWebchatContent } from "../../chat-limits.js";
+import { chooseModelThinking } from "../../../../packages/gateway-contract/src/model-selection.js";
+import { init_providers, resolveModel } from "../../../providers/index.js";
+import { getModelThinking } from "../../../providers/model-thinking.js";
+import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";
 import { validateSideChatSelections } from "../../side-chat/context-snapshot.js";
 import { SideChatError, parseThinkingLevel } from "../../side-chat/manager.js";
 import "../../side-chat/index.js";
 import { createGatewayRouteLogger, logRouteError } from "../lib/route-logger.js";
 //#region src/gateway/hono/routes/side-chats.ts
+init_providers();
 const CLIENT_HEADER = "x-xopc-client-instance-id";
 const log = createGatewayRouteLogger("SideChats");
 function registerSideChatRoutes(authenticated, deps) {
@@ -64,9 +68,18 @@ function registerSideChatRoutes(authenticated, deps) {
 			const body = await c.req.json().catch(() => ({}));
 			if (body.modelRef !== void 0 && typeof body.modelRef !== "string") throw new SideChatError("modelRef must be a string", "INVALID_REQUEST");
 			const modelRef = typeof body.modelRef === "string" ? body.modelRef : void 0;
+			const current = service.sideChats.get(c.req.param("sideChatId"), readClientInstanceId(c, body.clientInstanceId));
+			const nextModelRef = modelRef ?? current.config.modelRef;
+			let thinking;
+			try {
+				thinking = getModelThinking(resolveModel(nextModelRef));
+			} catch {
+				throw new SideChatError(`Model unavailable: ${nextModelRef}`, "INVALID_REQUEST");
+			}
+			const requestedThinking = parseThinkingLevel(body.thinkingLevel);
 			const sideChat = service.sideChats.updateConfig(c.req.param("sideChatId"), readClientInstanceId(c, body.clientInstanceId), {
-				modelRef,
-				thinkingLevel: parseThinkingLevel(body.thinkingLevel)
+				modelRef: nextModelRef,
+				thinkingLevel: chooseModelThinking(thinking, requestedThinking ?? current.config.thinkingLevel)
 			});
 			return c.json({
 				ok: true,
@@ -101,9 +114,16 @@ function registerSideChatRoutes(authenticated, deps) {
 		try {
 			const body = await c.req.json().catch(() => ({}));
 			const content = typeof body.content === "string" ? body.content : "";
+			const attachments = Array.isArray(body.attachments) ? body.attachments : void 0;
 			const contentError = validateWebchatContent(content);
 			if (contentError) throw new SideChatError(contentError, "INVALID_REQUEST");
-			const result = service.sideChatRuns.submit(c.req.param("sideChatId"), readClientInstanceId(c, body.clientInstanceId), content);
+			const attachmentError = validateWebchatAttachments(attachments);
+			if (attachmentError) throw new SideChatError(attachmentError, "INVALID_REQUEST");
+			if (!content.trim() && !attachments?.length) throw new SideChatError("content or attachments are required", "INVALID_REQUEST");
+			const result = service.sideChatRuns.submit(c.req.param("sideChatId"), readClientInstanceId(c, body.clientInstanceId), {
+				content,
+				attachments
+			});
 			return c.json({
 				ok: true,
 				payload: result

package/dist/src/gateway/security/gateway-scopes.js

@@ -57,7 +57,7 @@ function requiredGatewayScope(method, path) {
 	if (path.startsWith("/api/home") || path.startsWith("/api/inbox")) return methodScope(method, "tasks.read", "tasks.write");
 	if (path.startsWith("/api/automations") || path.startsWith("/api/automation-runs")) return methodScope(method, "automations.read", "automations.write");
 	if (path.startsWith("/api/workflows")) return methodScope(method, "automations.read", "automations.write");
-	if (path.startsWith("/api/voice") || path.startsWith("/api/media") || path.startsWith("/api/clarify")) return "sessions.write";
+	if (path.startsWith("/api/voice") || path.startsWith("/api/media") || path.startsWith("/api/clarifications")) return "sessions.write";
 	if (path.startsWith("/api/commands") || path.startsWith("/api/skills")) return methodScope(method, "agents.read", "gateway.admin");
 	if (path.startsWith("/api/workspace") || path.startsWith("/api/files") || path.startsWith("/api/projects") || path.startsWith("/api/notes") || path.startsWith("/api/shares")) return methodScope(method, "workspace.read", "workspace.write");
 	return "gateway.admin";

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

@@ -1,31 +1,12 @@
 import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
-/**
- * GatewayAgentRunner — webchat agent invocation and the surrounding control
- * surface (abort, steer, clarify-bridge plumbing, scheduled Task continuations).
- *
- * Was 200 lines of `GatewayService` covering seven concerns that all hung off
- * the same handful of fields (`activeWebchatRunBySession`, `runAbortControllers`,
- * `clarifyBridge`, `runRelay`):
- *
- *   - `runAgent(message, channel, chatId, ...)` — wraps {@link runGatewayAgent}
- *   - `abortAgentRun(runId)` — POST /api/agent/abort + cleanup
- *   - `submitClarifyResponse(requestId, answer)` — UI answers a `clarify` call
- *   - `runScheduledWebchatTurn(sk, userTurn)` — background webchat user turn
- *   - `drainScheduledWebchatContinuation(sk, msg)` — background Task continuation
- *   - `clarifyForSession({ sessionKey, request })` — clarify-bridge dispatch
- *     used by `gatewayClarify.requestClarification` in AgentService
- *
- * Owns the two state maps (`activeWebchatRunBySession`, `runAbortControllers`)
- * directly so peer coordinators (sessions-api, marketplace, config) cannot
- * accidentally mutate them.
- */
+import type { ClarificationResponseAction } from '@xopcai/gateway-contract';
 import type { Config } from '../../config/schema.js';
 import type { MessageBus } from '../../infra/bus/index.js';
 import type { AgentService } from '../../agent/service.js';
 import type { ChannelManager } from '../../channels/manager.js';
 import type { SessionIndex } from '../../session/index.js';
-import type { ClarifyStreamEvent } from '../clarify-bridge.js';
-import { ClarifyBridge, type ClarifyBridgeRequest } from '../clarify-bridge.js';
+import { type ClarificationStreamEvent } from '../ephemeral-clarification-waiter.js';
+import type { ClarifyRequestPayload, ClarifyRequestResult } from '../../agent/tools/clarify-tool.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';
@@ -49,11 +30,10 @@ export declare class GatewayAgentRunner {
     private readonly runAbortControllers;
     private readonly runCompletions;
     private readonly resolveRunCompletions;
-    private readonly clarifyBridge;
+    private readonly ephemeralClarifications;
     /** Maps webchat session key → active `runId` for `clarify` tool routing. */
     private readonly activeWebchatRunBySession;
     private readonly externalStreamBySession;
-    private readonly externalClarificationTimeouts;
     private readonly externalClarificationResponses;
     readonly inputs: SessionInputCoordinator;
     private readonly unsubscribeConnectionWait;
@@ -65,11 +45,8 @@ export declare class GatewayAgentRunner {
         sessionKey: string;
         runId: string;
     }>;
-    getClarifyBridge(): ClarifyBridge;
-    /** Called from `GatewayService.stop()` so the bridge gets cleaned up. */
-    disposeClarifyBridge(): void;
-    registerExternalWebchatRun(sessionKey: string, runId: string, publish: (event: ClarifyStreamEvent) => void, options?: {
-        clarificationTimeoutMs?: number | null;
+    disposeClarifications(): void;
+    registerExternalWebchatRun(sessionKey: string, runId: string, publish: (event: ClarificationStreamEvent) => void, options?: {
         beforeClarificationResponse?: () => boolean;
     }): void;
     unregisterExternalWebchatRun(sessionKey: string, runId: string): void;
@@ -126,16 +103,26 @@ export declare class GatewayAgentRunner {
         aborted: boolean;
         idle: boolean;
     }>;
-    /** Deliver a user's answer to a pending `clarify` tool call. */
-    submitClarifyResponse(requestId: string, answer: string): boolean;
+    answerEphemeralClarification(requestId: string, answer: string): boolean;
+    getClarificationState(sessionKey: string): import("@xopcai/gateway-contract").ClarificationWaitSnapshot;
+    resolveClarificationResponse(input: {
+        id: string;
+        expectedVersion: number;
+        idempotencyKey: string;
+        action: ClarificationResponseAction;
+        answer?: string;
+    }): import("../../storage/sqlite/clarification-wait-repository.js").ResolveClarificationResult;
+    getClarificationById(id: string): import("@xopcai/gateway-contract").ClarificationWait;
+    answerClarificationChoice(requestId: string, choiceIndex: number, idempotencyKey: string): boolean;
+    answerClarificationText(sessionKey: string, answer: string, idempotencyKey: string): boolean;
     /** Same execution path as scheduled continuation, but lets callers observe failures. */
     runScheduledWebchatTurn(sessionKey: string, userTurn: UserTurnInput): Promise<void>;
     runScheduledWebchatContinuation(sessionKey: string, message: string): Promise<void>;
     /** Background drain for extension-initiated webchat turns (`scheduleWebchatContinuation`). */
     drainScheduledWebchatContinuation(sessionKey: string, message: string): Promise<void>;
     /**
-     * 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
@@ -144,8 +131,10 @@ export declare class GatewayAgentRunner {
      */
     requestClarification(opts: {
         sessionKey: string;
-        request: ClarifyBridgeRequest;
-        publishStreamFor: (runId: string) => (event: ClarifyStreamEvent) => void;
-    }): Promise<string>;
+        runId: string;
+        toolCallId: string;
+        request: ClarifyRequestPayload;
+        publishStreamFor: (runId: string) => (event: ClarificationStreamEvent) => void;
+    }): Promise<ClarifyRequestResult>;
     private deliverTelegramClarify;
 }

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/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";