@xopcai/xopc 0.0.252 → 0.0.254

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/file-path-classifier.js

@@ -1,7 +1,7 @@
 import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
 import { init_agent_scope, resolveAgentProfileDir } from "../agent/agent-scope.js";
-import { extractProfileAgentId } from "../config/agent-profile.js";
 import { init_paths, resolveConfigPath, resolveSkillsDir } from "../config/paths.js";
+import { extractProfileAgentId } from "../config/agent-profile.js";
 import { isBareProfileMarkdownFileName, resolveProfileMarkdownPathIfBareName } from "../agent/tools/tool-paths.js";
 import { isPathUnderWorkspace, resolveWorkspaceSafePath } from "./workspace-editor-path.js";
 import { basename, isAbsolute, resolve } from "node:path";

package/dist/src/gateway/heartbeat/service.js

@@ -1,9 +1,9 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { shouldSilence, stripHeartbeatToken } from "../../heartbeat/tokens.js";
-import { appendCronEventLines } from "../../heartbeat/event-prompt.js";
 import { isWithinActiveHours } from "../../heartbeat/active-hours.js";
 import { isHeartbeatContentEmpty } from "../../heartbeat/content-check.js";
+import { appendCronEventLines } from "../../heartbeat/event-prompt.js";
 import { createHeartbeatWake } from "../../heartbeat/wake.js";
 import { resolveHeartbeatMdPath } from "../workspace-heartbeat-path.js";
 import { readFile } from "fs/promises";

package/dist/src/gateway/hono/lib/config-payload.js

@@ -1,9 +1,9 @@
 import { ContextPlanningConfigSchema, KnowledgeMemoryConfigSchema, UserModelConfigSchema, init_config } from "../../../user-context/config.js";
 import { init_agent_scope, listAgentEntries, normalizeAgentId, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
 import { resolveModelsJsonPath } from "../../../config/paths.js";
-import { buildChannelCatalogForConfig, buildChannelCatalogFromSnapshot, getChannelSetupStatus, init_channel_catalog_service } from "../../../channels/catalog/channel-catalog-service.js";
 import { init_models_json, loadModelsJson } from "../../../config/models-json.js";
 import { CredentialResolver, init_credentials } from "../../../auth/credentials.js";
+import { buildChannelCatalogForConfig, buildChannelCatalogFromSnapshot, getChannelSetupStatus, init_channel_catalog_service } from "../../../channels/catalog/channel-catalog-service.js";
 import { getProviderRegistry, init_plugin_registry } from "../../../providers/plugin-registry.js";
 import { getAllProviders, init_providers, isProviderConfigured } from "../../../providers/index.js";
 import { normalizeConfiguredMcpServers } from "../../../config/mcp-config-normalize.js";

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/browser.js

@@ -1,9 +1,52 @@
 import { decideBrowserApproval, listBrowserApprovals } from "../../../browser/policy/approval-store.js";
+import { createBrowserDriver } from "../../../browser/drivers/create-driver.js";
+import { checkBrowserReadiness } from "../../../browser/readiness.js";
 import { isLoopbackClientIp } from "../../security/loopback.js";
 import { getConnInfo } from "@hono/node-server/conninfo";
 //#region src/gateway/hono/routes/browser.ts
 /** Browser Control status, approvals, and driver diagnostics. */
 const EXTENSION_ENDPOINT = "http://127.0.0.1:19820/";
+async function extensionStatus() {
+	const { getExtensionBrowserServerSnapshot } = await import("../../../browser/providers/extension-ws-acquire.js");
+	const snapshot = getExtensionBrowserServerSnapshot();
+	let running = snapshot.active;
+	let socketConnected = false;
+	let connected = false;
+	let protocolVersion = null;
+	let expectedProtocolVersion = null;
+	let extensionVersion = null;
+	try {
+		const payload = await (await fetch(EXTENSION_ENDPOINT, { signal: AbortSignal.timeout(2e3) })).json();
+		running ||= payload.ok === true;
+		socketConnected = payload.socketConnected ?? payload.connected === true;
+		connected = payload.connected === true;
+		protocolVersion = typeof payload.protocolVersion === "number" ? payload.protocolVersion : null;
+		expectedProtocolVersion = typeof payload.expectedProtocolVersion === "number" ? payload.expectedProtocolVersion : null;
+		extensionVersion = typeof payload.extensionVersion === "string" ? payload.extensionVersion : null;
+	} catch {}
+	const { browserExtDoctor } = await import("../../../browser/providers/browser-ext-install.js");
+	const doctor = await browserExtDoctor({ runtimeExtensionVersion: extensionVersion ?? void 0 });
+	return {
+		running,
+		socketConnected,
+		connected,
+		driverKind: "extension",
+		protocolVersion,
+		expectedProtocolVersion,
+		extensionVersion,
+		artifacts: {
+			installed: doctor.installed,
+			bundledAvailable: doctor.bundledAvailable,
+			extensionDir: doctor.extensionDir,
+			xopcVersion: doctor.xopcVersion,
+			installedVersion: doctor.installedVersion,
+			needsRefresh: doctor.needsRefresh,
+			needsChromeReload: doctor.needsChromeReload || socketConnected && !connected
+		},
+		bridgeHeld: snapshot.active,
+		refCount: snapshot.refCount
+	};
+}
 function isLocalOwnerRequest(c, service) {
 	if (service.currentConfig.gateway?.bind === "loopback") return true;
 	try {
@@ -15,37 +58,116 @@ function isLocalOwnerRequest(c, service) {
 function registerBrowserRoutes(authenticated, deps) {
 	const { service, strictRateLimitMiddleware } = deps;
 	authenticated.get("/api/browser/extension-status", async (c) => {
-		const { getExtensionBrowserServerSnapshot } = await import("../../../browser/providers/extension-ws-acquire.js");
-		const snapshot = getExtensionBrowserServerSnapshot();
-		let running = snapshot.active;
-		let connected = false;
 		try {
-			const payload = await (await fetch(EXTENSION_ENDPOINT, { signal: AbortSignal.timeout(2e3) })).json();
-			running ||= payload.ok === true;
-			connected = payload.connected === true;
-		} catch {}
-		let artifacts;
-		try {
-			const { browserExtDoctor } = await import("../../../browser/providers/browser-ext-install.js");
-			const doctor = await browserExtDoctor();
-			artifacts = {
-				installed: doctor.installed,
-				extensionDir: doctor.extensionDir,
-				xopcVersion: doctor.xopcVersion,
-				installedVersion: doctor.installedVersion,
-				needsRefresh: doctor.needsRefresh,
-				needsChromeReload: doctor.needsChromeReload
-			};
-		} catch {}
+			return c.json(await extensionStatus());
+		} catch (error) {
+			return c.json({
+				running: false,
+				connected: false,
+				driverKind: "extension",
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+	});
+	authenticated.get("/api/browser/status", async (c) => {
+		const config = service.currentConfig.browser;
+		if (!config.enabled) return c.json({
+			ok: true,
+			payload: {
+				enabled: false,
+				driverKind: config.driver.kind,
+				state: "disabled"
+			}
+		});
+		const readiness = await checkBrowserReadiness(service.currentConfig);
+		const driverStatus = config.driver.kind === "extension" ? await extensionStatus().catch((error) => ({ error: error instanceof Error ? error.message : String(error) })) : config.driver.kind === "playwright" ? await import("../../../browser/providers/playwright-doctor.js").then(({ playwrightChromiumDoctor }) => playwrightChromiumDoctor()) : void 0;
+		const extensionConnected = config.driver.kind === "extension" ? driverStatus.connected === true : true;
+		const extensionProtocolDetail = config.driver.kind === "extension" && "socketConnected" in driverStatus && driverStatus.socketConnected && !driverStatus.connected ? `Chrome extension protocol ${driverStatus.protocolVersion ?? "unknown"} does not match ${driverStatus.expectedProtocolVersion ?? "the gateway"}. Reload the extension in Chrome.` : void 0;
 		return c.json({
-			running,
-			connected,
-			driverKind: "extension",
-			artifacts,
-			bridgeHeld: snapshot.active,
-			refCount: snapshot.refCount
+			ok: true,
+			payload: {
+				enabled: true,
+				driverKind: config.driver.kind,
+				state: !readiness && extensionConnected ? "ready" : "needs_attention",
+				reason: readiness?.hint.reason ?? (extensionConnected ? void 0 : "extension_not_connected"),
+				detail: readiness?.hint.detail ?? extensionProtocolDetail,
+				driverStatus
+			}
 		});
 	});
+	authenticated.post("/api/browser/test", strictRateLimitMiddleware, async (c) => {
+		if (!isLocalOwnerRequest(c, service)) return c.json({
+			ok: false,
+			error: "Local owner access required."
+		}, 403);
+		if (!service.currentConfig.browser.enabled) return c.json({
+			ok: false,
+			error: "Browser Control is disabled."
+		}, 400);
+		const startedAt = Date.now();
+		let driver;
+		try {
+			driver = await createBrowserDriver(service.currentConfig.browser);
+			await driver.connect();
+			return c.json({
+				ok: true,
+				payload: {
+					driverKind: service.currentConfig.browser.driver.kind,
+					durationMs: Date.now() - startedAt
+				}
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: error instanceof Error ? error.message : String(error)
+			}, 400);
+		} finally {
+			await driver?.disconnect().catch(() => {});
+		}
+	});
+	authenticated.post("/api/browser/extension/install", strictRateLimitMiddleware, async (c) => {
+		if (!isLocalOwnerRequest(c, service)) return c.json({
+			ok: false,
+			error: "Local owner access required."
+		}, 403);
+		const body = await c.req.json().catch(() => ({}));
+		try {
+			const { browserExtDoctor, ensureBrowserExtensionArtifacts } = await import("../../../browser/providers/browser-ext-install.js");
+			const result = await ensureBrowserExtensionArtifacts({ force: body.force === true });
+			return c.json({
+				ok: true,
+				payload: {
+					...result,
+					doctor: await browserExtDoctor()
+				}
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: error instanceof Error ? error.message : String(error)
+			}, 500);
+		}
+	});
+	authenticated.post("/api/browser/extension/open", strictRateLimitMiddleware, async (c) => {
+		if (!isLocalOwnerRequest(c, service)) return c.json({
+			ok: false,
+			error: "Local owner access required."
+		}, 403);
+		const body = await c.req.json().catch(() => ({}));
+		const action = body.action === "chrome" || body.action === "folder" || body.action === "both" ? body.action : "both";
+		try {
+			const { openBrowserExtensionInstallUi } = await import("../../../browser/providers/browser-ext-install.js");
+			return c.json({
+				ok: true,
+				payload: await openBrowserExtensionInstallUi({ action })
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: error instanceof Error ? error.message : String(error)
+			}, 400);
+		}
+	});
 	authenticated.get("/api/browser/approvals", (c) => {
 		if (!isLocalOwnerRequest(c, service)) return c.json({
 			ok: false,

package/dist/src/gateway/hono/routes/lazy-bundles.js

@@ -53,7 +53,7 @@ const AUTHENTICATED_LAZY_ROUTE_BUNDLES = [
 	},
 	{
 		id: "browser-install",
-		match: (path) => path === "/api/browser/playwright/install/stream",
+		match: (path) => path === "/api/browser/playwright/install/stream" || path === "/api/browser/playwright/install/cancel",
 		load: async () => {
 			const { registerBrowserInstallRoutes } = await import("./browser-install.js");
 			return { register: registerBrowserInstallRoutes };

package/dist/src/gateway/hono/routes/models.js

@@ -1,5 +1,5 @@
-import { resolveModelsJsonPath } from "../../../config/paths.js";
 import { init_resolve_config_value, testApiKeyResolution } from "../../../config/resolve-config-value.js";
+import { resolveModelsJsonPath } from "../../../config/paths.js";
 import { init_models_json, loadModelsJson, saveModelsJson, validateModelsConfig } from "../../../config/models-json.js";
 import { getModelCatalogStore, init_model_catalog_store } from "../../../providers/model-catalog-store.js";
 import { getModelRegistry } from "../../../providers/model-registry.js";

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;
 }