@xopcai/xopc 0.0.387 → 0.0.389

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

@@ -1,3 +1,4 @@
+import type { ClarificationPresentation } from '@xopcai/gateway-contract';
 import type { AgentStreamToolExecutionMetadata, ToolActivity, TurnOutcome } from '@xopcai/gateway-contract';
 import type { TaskUpdateTrigger } from '../../storage/sqlite/session-input-repository.js';
 export type ChatStreamStatus = 'success' | 'error' | 'cancelled' | 'suspended';
@@ -207,12 +208,10 @@ export type TtsAudioEvent = ChatStreamEnvelope<'tts_audio', {
     attachTo?: 'last_assistant';
     messageId?: string;
 }>;
-export type ClarifyRequestEvent = ChatStreamEnvelope<'clarify_request', {
+export type ClarifyRequestEvent = ChatStreamEnvelope<'clarify_request', ClarificationPresentation & {
     requestId: string;
     kind: 'input' | 'approval';
     question: string;
-    choices?: string[];
-    suggestedAnswer?: string;
     version: number;
     createdAt: number;
     expiresAt?: number;

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

@@ -1,7 +1,9 @@
 export type ClarificationChannelRuntime = {
     answerChoice(requestId: string, choiceIndex: number, idempotencyKey: string): boolean;
+    answerDecision(requestId: string, decision: 'approve' | 'deny', idempotencyKey: string): boolean;
     answerText(conversationId: 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(conversationId: string, text: string, idempotencyKey: string): boolean;
+export declare function answerClarificationDecisionFromChannel(requestId: string, decision: 'approve' | 'deny', idempotencyKey: string): boolean;

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

@@ -9,5 +9,8 @@ function answerClarificationChoiceFromChannel(requestId, choiceIndex, idempotenc
 function answerClarificationTextFromChannel(conversationId, text, idempotencyKey) {
 	return runtime?.answerText(conversationId, text, idempotencyKey) ?? false;
 }
+function answerClarificationDecisionFromChannel(requestId, decision, idempotencyKey) {
+	return runtime?.answerDecision(requestId, decision, idempotencyKey) ?? false;
+}
 //#endregion
-export { answerClarificationChoiceFromChannel, answerClarificationTextFromChannel, registerClarificationChannelRuntime };
+export { answerClarificationChoiceFromChannel, answerClarificationDecisionFromChannel, answerClarificationTextFromChannel, registerClarificationChannelRuntime };

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

@@ -1,3 +1,4 @@
+import { type ClarificationSubmission } from '@xopcai/gateway-contract';
 import type { ClarifyRequestPayload } from '../agent/tools/clarify-tool.js';
 export type ClarificationStreamEvent = {
     type: string;
@@ -11,7 +12,7 @@ export declare class EphemeralClarificationWaiter {
         request: ClarifyRequestPayload;
         beforeResponse?: () => boolean;
     }): Promise<string>;
-    answer(requestId: string, answer: string): boolean;
+    answer(requestId: string, answer: ClarificationSubmission): boolean;
     cancelForRun(runId: string): void;
     dispose(): void;
 }

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

@@ -1,12 +1,19 @@
+import { normalizeClarificationQuestion, normalizeClarificationSubmission, readClarificationPresentation } from "../../packages/gateway-contract/src/clarifications.js";
+import { init_src } from "../../packages/gateway-contract/src/index.js";
 //#region src/gateway/ephemeral-clarification-waiter.ts
+init_src();
 /** In-memory waiter exclusively for caller-owned ephemeral runs such as side chat. */
 var EphemeralClarificationWaiter = class {
 	pending = /* @__PURE__ */ new Map();
 	start(input) {
+		const request = normalizeClarificationQuestion(input.request);
 		const requestId = crypto.randomUUID();
+		const expiresAt = request.kind === "approval" ? Date.now() + 10 * 6e4 : void 0;
 		return new Promise((resolve, reject) => {
 			this.pending.set(requestId, {
 				runId: input.runId,
+				request,
+				expiresAt,
 				resolve,
 				reject,
 				beforeResponse: input.beforeResponse
@@ -14,10 +21,10 @@ var EphemeralClarificationWaiter = class {
 			input.publish({
 				type: "clarify_request",
 				requestId,
-				kind: input.request.kind ?? "input",
-				question: input.request.question,
-				choices: input.request.choices,
-				suggestedAnswer: input.request.suggestedAnswer,
+				...readClarificationPresentation(request),
+				kind: request.kind ?? "input",
+				question: request.question,
+				expiresAt,
 				version: 1,
 				createdAt: Date.now()
 			});
@@ -25,9 +32,15 @@ var EphemeralClarificationWaiter = class {
 	}
 	answer(requestId, answer) {
 		const pending = this.pending.get(requestId);
-		if (!pending || pending.beforeResponse?.() === false) return false;
+		if (!pending || pending.beforeResponse?.() === false || pending.expiresAt !== void 0 && pending.expiresAt <= Date.now()) return false;
+		let normalized;
+		try {
+			normalized = normalizeClarificationSubmission(pending.request, answer);
+		} catch {
+			return false;
+		}
 		this.pending.delete(requestId);
-		pending.resolve(answer.trim());
+		pending.resolve(normalized.answer);
 		return true;
 	}
 	cancelForRun(runId) {

package/dist/src/gateway/hono/lib/config-payload.d.ts

@@ -221,7 +221,7 @@ export declare function buildSafeWebConfigPayload(service: GatewayService, optio
         userModel: {
             enabled: boolean;
             writePolicy: "allow" | "deny";
-            sensitiveWritePolicy: "allow" | "confirm" | "deny";
+            sensitiveWritePolicy: "allow" | "deny" | "confirm";
             showMemoryReferences: boolean;
             processingPolicy: "local_only" | "remote_allowed";
             extraction: {

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

@@ -1,7 +1,7 @@
-import { ContextPlanningConfigSchema, KnowledgeMemoryConfigSchema, UserModelConfigSchema, init_config } from "../../../user-context/config.js";
 import { normalizeAgentId } from "../../../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../../../agent-catalog/repository.js";
 import { init_agent_scope, listAgentEntries, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
+import { ContextPlanningConfigSchema, KnowledgeMemoryConfigSchema, UserModelConfigSchema, init_config } from "../../../user-context/config.js";
 import { resolveModelsJsonPath } from "../../../config/paths.js";
 import { init_models_json, loadModelsJson } from "../../../config/models-json.js";
 import { CredentialResolver, init_credentials } from "../../../auth/credentials.js";

package/dist/src/gateway/hono/lib/config-write-lock.d.ts

@@ -0,0 +1,2 @@
+/** Keep HTTP read/merge/write sequences together, including the legacy configuration endpoint. */
+export declare function withGatewayConfigWriteLock<T>(service: object, operation: () => Promise<T>): Promise<T>;

package/dist/src/gateway/hono/lib/config-write-lock.js

@@ -0,0 +1,14 @@
+//#region src/gateway/hono/lib/config-write-lock.ts
+const writes = /* @__PURE__ */ new WeakMap();
+/** Keep HTTP read/merge/write sequences together, including the legacy configuration endpoint. */
+async function withGatewayConfigWriteLock(service, operation) {
+	const next = (writes.get(service) ?? Promise.resolve()).catch(() => {}).then(operation);
+	writes.set(service, next);
+	try {
+		return await next;
+	} finally {
+		if (writes.get(service) === next) writes.delete(service);
+	}
+}
+//#endregion
+export { withGatewayConfigWriteLock };

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

@@ -1,4 +1,5 @@
 import { parseUserTurnDocument, userTurnDocumentRefIds } from "../../../../packages/gateway-contract/src/user-turn-document.js";
+import { clarificationResponseCommandSchema } from "../../../../packages/gateway-contract/src/clarifications.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { parseTurnContextRefs } from "../../../agent/source-context/types.js";
 import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";
@@ -165,11 +166,8 @@ function registerAgentStreamRoutes(authenticated, deps) {
 	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({
+		const command = clarificationResponseCommandSchema.safeParse(body);
+		if (!id || !command.success) return c.json({
 			ok: false,
 			error: {
 				code: "BAD_REQUEST",
@@ -178,10 +176,7 @@ function registerAgentStreamRoutes(authenticated, deps) {
 		}, 400);
 		const result = service.resolveClarificationResponse({
 			id,
-			expectedVersion,
-			idempotencyKey,
-			action,
-			answer: typeof record.answer === "string" ? record.answer : void 0
+			...command.data
 		});
 		if (result.ok === true) return c.json({
 			ok: true,

package/dist/src/gateway/hono/routes/config-patch/misc.js

@@ -1,10 +1,10 @@
-import { ContextPlanningConfigSchema, HomeIntelligenceConfigSchema, KnowledgeMemoryConfigSchema, UserContextConfigSchema, UserModelConfigSchema, init_config } from "../../../../user-context/config.js";
 import { BindingsSchema, init_binding_schema } from "../../../../routing/binding-schema.js";
+import { AgentCatalogService } from "../../../../agent-catalog/service.js";
+import { ContextPlanningConfigSchema, HomeIntelligenceConfigSchema, KnowledgeMemoryConfigSchema, UserContextConfigSchema, UserModelConfigSchema, init_config } from "../../../../user-context/config.js";
 import { ComputerConfigSchema, init_config as init_config$1 } from "../../../../computer/config.js";
 import { BrowserConfigSchema, McpConfigSchema, VoiceConfigSchema, init_schema } from "../../../../config/schema.js";
 import { CredentialResolver, init_credentials } from "../../../../auth/credentials.js";
 import { canonicalizeConfiguredMcpServer } from "../../../../config/mcp-config-normalize.js";
-import { AgentCatalogService } from "../../../../agent-catalog/service.js";
 import { mergeGatewaySkillsMarketplacePatch, mergeSessionConfigPatch, mergeUpdateConfigPatch } from "../../../../config/web-patch.js";
 import { assertGatewayAuthConfigured, resolveGatewayAuth } from "../../../auth.js";
 import { isMaskedSecretPatchValue } from "../../lib/mask-secret-length.js";

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

@@ -1,6 +1,7 @@
 import { enumerateLanGatewayCandidates, init_host } from "../../host.js";
 import { getTunnelService } from "../../../tunnel/tunnel-service.js";
 import { buildSafeWebConfigPayload } from "../lib/config-payload.js";
+import { withGatewayConfigWriteLock } from "../lib/config-write-lock.js";
 import { applyChannelsPatch } from "./config-patch/channels.js";
 import { applyGatewayPatch } from "./config-patch/gateway.js";
 import { applyMiscPatch, validateGatewayAfterPatch } from "./config-patch/misc.js";
@@ -34,9 +35,10 @@ function registerConfigRoutes(authenticated, deps) {
 			payload: { candidates: enumerateLanGatewayCandidates(port) }
 		});
 	});
-	authenticated.patch("/api/config", strictRateLimitMiddleware, async (c) => {
+	authenticated.patch("/api/config", strictRateLimitMiddleware, async (c) => withGatewayConfigWriteLock(service, async () => {
 		const body = await c.req.json();
-		const config = service.currentConfig;
+		const expectedConfig = structuredClone(service.currentConfig);
+		const config = structuredClone(expectedConfig);
 		applyChannelsPatch(config, body);
 		const gatewayResult = applyGatewayPatch(config, body);
 		if (gatewayResult.ok === false) return c.json({
@@ -62,17 +64,17 @@ function registerConfigRoutes(authenticated, deps) {
 				error: `Failed to stop tunnel before clearing key: ${message}`
 			}, 500);
 		}
-		const result = await service.saveConfig(config);
+		const result = await service.saveConfig(config, expectedConfig);
 		if (!result.saved) return c.json({
 			ok: false,
 			error: result.error
-		}, 500);
+		}, result.conflict ? 409 : 500);
 		const safeConfig = await buildSafeWebConfigPayload(service, { locale: localeFromRequest(c) });
 		return c.json({
 			ok: true,
 			payload: { config: safeConfig }
 		});
-	});
+	}));
 	const revealGatewayAuthSecretHandler = async (c) => {
 		const field = await resolveRevealGatewayAuthField(c);
 		if (!field) return c.json({

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

@@ -6,9 +6,9 @@ import { getConnectorAccount, init_connector_account_repository, listConnectorAc
 import { decideConnectorApproval, getConnectorApproval, listConnectorApprovals, listConnectorConnections } from "../../../storage/sqlite/connector-repository.js";
 import { getConnectorSyncPolicy, upsertConnectorSyncPolicy } from "../../../storage/sqlite/connector-sync-policy-repository.js";
 import { init_sqlite } from "../../../storage/sqlite/index.js";
-import { listUnderstandingSourceGrants, revokeUnderstandingSourceGrant } from "../../../user-context/sources/repository.js";
 import { AgentCatalogRepository, init_repository } from "../../../agent-catalog/repository.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
+import { listUnderstandingSourceGrants, revokeUnderstandingSourceGrant } from "../../../user-context/sources/repository.js";
 import { activateComposioBackend, addComposioBackend, ensureComposioBackend, getComposioBackend, listComposioBackends, removeComposioBackend } from "../../../connectors/composio-backends.js";
 import { getAuthorizationAttempt } from "../../../connectors/authorization-attempts.js";
 import { ComposioSessionsAdapter, resolveComposioApiKey } from "../../../connectors/composio-sessions.js";

package/dist/src/gateway/hono/routes/context-sources.js

@@ -2,9 +2,9 @@ import { getSqliteDatabase, init_transaction } from "../../../storage/sqlite/tra
 import { getConnectorAccount } from "../../../storage/sqlite/connector-account-repository.js";
 import { countKnowledgeSourceItems, deleteKnowledgeSourceItems } from "../../../storage/sqlite/knowledge-repository.js";
 import { init_sqlite } from "../../../storage/sqlite/index.js";
+import { init_agent_scope, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
 import { getActiveUnderstandingConsent } from "../../../user-context/sources/consent-repository.js";
 import { getUnderstandingSourceGrant, listUnderstandingSourceGrants, listUnderstandingSourceRuns, revokeUnderstandingSourceGrant, updateUnderstandingSourceGrantPolicies } from "../../../user-context/sources/repository.js";
-import { init_agent_scope, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
 import { listUserModelObservations } from "../../../user-model/observation-repository.js";
 import "../../../user-model/index.js";
 import { listConnectedContentCandidates, readConnectedContent } from "../../../connectors/content-enrichment.js";

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

@@ -449,7 +449,7 @@ const AUTHENTICATED_LAZY_ROUTE_BUNDLES = [
 	},
 	{
 		id: "mcp",
-		match: (path) => path === "/api/mcp/servers" || /^\/api\/mcp\/servers\/[^/]+\/(tools|probe|auth)$/.test(path) || /^\/api\/mcp\/auth\/[^/]+(?:\/redirect)?$/.test(path),
+		match: (path) => path === "/api/mcp/servers" || /^\/api\/mcp\/servers\/[^/]+$/.test(path) || path === "/api/mcp/drafts" || /^\/api\/mcp\/drafts\/[^/]+(?:\/(?:probe|commit|tools|auth(?:\/redirect)?))?$/.test(path) || /^\/api\/mcp\/servers\/[^/]+\/(tools|probe|auth)$/.test(path) || /^\/api\/mcp\/auth\/[^/]+(?:\/redirect)?$/.test(path),
 		load: async () => {
 			const { registerMcpRoutes } = await import("./mcp.js");
 			return { register: registerMcpRoutes };

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

@@ -4,8 +4,67 @@ import { loadMergedMcpConfig } from "../../../agent/mcp/config.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
 import { discoverMcpTools } from "../../../agent/mcp/tool-catalog.js";
 import { cancelMcpAuthorization, getMcpAuthorization, probeMcpConnection, startMcpAuthorization, submitMcpRedirect } from "../../../agent/mcp/connection-setup.js";
+import { McpConnectionDrafts, McpDraftError, mcpConfigRevision } from "../../../agent/mcp/connection-drafts.js";
+import { withGatewayConfigWriteLock } from "../lib/config-write-lock.js";
 //#region src/gateway/hono/routes/mcp.ts
 function registerMcpRoutes(app, deps) {
+	const drafts = new McpConnectionDrafts({
+		readConfig: () => deps.service.currentConfig,
+		saveConfig: (config, expected) => deps.service.saveConfig(config, expected)
+	});
+	const owner = (c) => getGatewayPrincipal(c).principalId;
+	const draftRoute = (handler) => async (c) => {
+		try {
+			return c.json({
+				ok: true,
+				payload: await handler(c)
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: error instanceof McpDraftError ? error.message : "MCP draft operation failed."
+			}, error instanceof McpDraftError ? error.status : 500);
+		}
+	};
+	app.post("/api/mcp/drafts", deps.strictRateLimitMiddleware, draftRoute(async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (!body || typeof body.serverId !== "string" || body.sourceServerId !== void 0 && typeof body.sourceServerId !== "string") throw new McpDraftError(400, "Invalid MCP draft request.");
+		return drafts.create(owner(c), body);
+	}));
+	app.post("/api/mcp/drafts/:id/probe", deps.strictRateLimitMiddleware, draftRoute((c) => drafts.probe(owner(c), c.req.param("id"))));
+	app.post("/api/mcp/drafts/:id/auth", deps.strictRateLimitMiddleware, draftRoute((c) => drafts.authorize(owner(c), c.req.param("id"))));
+	app.get("/api/mcp/drafts/:id/auth", draftRoute((c) => drafts.authorization(owner(c), c.req.param("id"))));
+	app.delete("/api/mcp/drafts/:id/auth", draftRoute((c) => drafts.cancelAuthorization(owner(c), c.req.param("id"))));
+	app.post("/api/mcp/drafts/:id/auth/redirect", deps.strictRateLimitMiddleware, draftRoute(async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (typeof body?.url !== "string" || body.url.length >= 16384) throw new McpDraftError(400, "Invalid callback address.");
+		drafts.redirect(owner(c), c.req.param("id"), body.url);
+	}));
+	app.post("/api/mcp/drafts/:id/commit", deps.strictRateLimitMiddleware, draftRoute(async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (!body || body.enable !== void 0 && typeof body.enable !== "boolean") throw new McpDraftError(400, "Invalid commit request.");
+		return withGatewayConfigWriteLock(deps.service, () => drafts.commit(owner(c), c.req.param("id"), body.enable === true));
+	}));
+	app.get("/api/mcp/drafts/:id/tools", deps.strictRateLimitMiddleware, draftRoute(async (c) => ({ tools: await drafts.tools(owner(c), c.req.param("id")) })));
+	app.delete("/api/mcp/drafts/:id", draftRoute((c) => drafts.remove(owner(c), c.req.param("id"))));
+	app.delete("/api/mcp/servers/:id", deps.strictRateLimitMiddleware, draftRoute(async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (!body?.expectedServer || typeof body.expectedServer !== "object" || Array.isArray(body.expectedServer)) throw new McpDraftError(400, "The expected server configuration is required.");
+		return withGatewayConfigWriteLock(deps.service, async () => {
+			const current = deps.service.currentConfig, id = c.req.param("id");
+			const server = Object.hasOwn(current.mcp?.servers ?? {}, id) ? current.mcp?.servers?.[id] : void 0;
+			if (!server || isManagedConnectorServer(server) || mcpConfigRevision(server) !== mcpConfigRevision(body.expectedServer)) throw new McpDraftError(409, "The custom server changed. Reload before removing it.");
+			const next = structuredClone(current);
+			delete next.mcp.servers[id];
+			const result = await deps.service.saveConfig(next, structuredClone(current));
+			if (result.conflict) throw new McpDraftError(409, "Configuration changed before removing the server.");
+			if (!result.saved && !result.persisted) throw new McpDraftError(500, "Could not remove the server.");
+			return {
+				serverId: id,
+				...!result.saved ? { reloadRequired: true } : {}
+			};
+		});
+	}));
 	app.post("/api/mcp/servers/:id/probe", deps.strictRateLimitMiddleware, async (c) => {
 		const config = deps.service.currentConfig;
 		const id = c.req.param("id");
@@ -101,12 +160,20 @@ function registerMcpRoutes(app, deps) {
 		return c.json({
 			ok: true,
 			payload: {
-				servers: Object.entries(merged.config.mcpServers).map(([id, server]) => ({
-					id,
-					plugin: server.xopcPlugin,
-					managed: isManagedConnectorServer(server),
-					connectorId: isManagedConnectorServer(server) ? server.xopcConnector.connectorId : void 0
-				})).sort((a, b) => a.id.localeCompare(b.id)),
+				servers: Object.entries(merged.config.mcpServers).map(([id, server]) => {
+					const { xopcConnectionCheck, ...configuration } = server;
+					const check = xopcConnectionCheck;
+					return {
+						id,
+						plugin: server.xopcPlugin,
+						lastCheck: check?.revision === mcpConfigRevision(configuration) ? {
+							checkedAt: check.checkedAt,
+							toolCount: check.toolCount
+						} : void 0,
+						managed: isManagedConnectorServer(server),
+						connectorId: isManagedConnectorServer(server) ? server.xopcConnector.connectorId : void 0
+					};
+				}).sort((a, b) => a.id.localeCompare(b.id)),
 				mergedServerIds: Object.keys(merged.config.mcpServers).sort(),
 				configured: cfg.mcp?.servers ?? {}
 			}

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

@@ -1,9 +1,9 @@
 import { NoteDeleteOutputSchema, NoteGetOutputSchema, ProductReadContracts } from "../../../../packages/gateway-contract/src/capabilities.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
-import { init_session_key, resolveConversationId } from "../../../routing/session-key.js";
-import { agentExists, getDefaultAgentId, init_resolve_route } from "../../../routing/resolve-route.js";
 import { CapabilityError } from "../../../capabilities/runtime/errors.js";
 import "../../../capabilities/runtime/dispatcher.js";
+import { init_session_key, resolveConversationId } from "../../../routing/session-key.js";
+import { agentExists, getDefaultAgentId, init_resolve_route } from "../../../routing/resolve-route.js";
 import { resolveGatewayEffectiveHost } from "../../../config/gateway-bind.js";
 import { getShareStore } from "../../../share/share-store.js";
 import { resolveShareUrl } from "../../../share/share-url.js";

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

@@ -7,12 +7,12 @@ import { loadTranscriptRowsForSession } from "../../../storage/sqlite/transcript
 import { init_sqlite } from "../../../storage/sqlite/index.js";
 import { ActivityService } from "../../../activity/service.js";
 import "../../../activity/index.js";
+import { CapabilityError } from "../../../capabilities/runtime/errors.js";
+import "../../../capabilities/runtime/dispatcher.js";
 import { listKnowledgeItems, writeKnowledgeItem } from "../../../knowledge-memory/repository.js";
 import "../../../knowledge-memory/index.js";
 import { resolveEffectiveAgentProfile } from "../../../config/agent-profile.js";
 import { TaskReadModelProjector } from "../../../tasks/task-read-model-projector.js";
-import { CapabilityError } from "../../../capabilities/runtime/errors.js";
-import "../../../capabilities/runtime/dispatcher.js";
 import { ProjectWorkspaceConflictError, ProjectWorkspaceMissingError } from "../../../projects/workspace-project.js";
 import { inferProjectExecutionMode, inferProjectKind } from "../../../projects/project-kind.js";
 import { ProjectDeletionBlockedError, ProjectWorkspaceInUseError } from "../../../projects/project-service.js";

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

@@ -5,9 +5,9 @@ import { endpointContextSchema } from "../../../../packages/gateway-contract/src
 import { parseUserTurnDocument, userTurnDocumentRefIds } from "../../../../packages/gateway-contract/src/user-turn-document.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { endpointTurnClaimSchema, init_src as init_src$1 } from "../../../../packages/endpoint-tools-protocol/src/index.js";
-import { init_providers, resolveModel } from "../../../providers/index.js";
 import { CapabilityError } from "../../../capabilities/runtime/errors.js";
 import "../../../capabilities/runtime/dispatcher.js";
+import { init_providers, resolveModel } from "../../../providers/index.js";
 import { getModelThinking } from "../../../providers/model-thinking.js";
 import { parseTurnContextRefs } from "../../../agent/source-context/types.js";
 import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";

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

@@ -1,4 +1,5 @@
 import { chooseModelThinking } from "../../../../packages/gateway-contract/src/model-selection.js";
+import { clarificationSubmissionSchema } from "../../../../packages/gateway-contract/src/clarifications.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { init_providers, resolveModel } from "../../../providers/index.js";
 import { getModelThinking } from "../../../providers/model-thinking.js";
@@ -149,9 +150,9 @@ function registerSideChatRoutes(authenticated, deps) {
 	authenticated.post("/api/side-chats/:sideChatId/clarify/:requestId", deps.chatRateLimitMiddleware, async (c) => {
 		try {
 			const body = await c.req.json().catch(() => ({}));
-			const answer = body.skip === true ? "" : typeof body.answer === "string" ? body.answer.trim() : "";
-			if (body.skip !== true && !answer) throw new SideChatError("answer is required", "INVALID_REQUEST");
-			if (!service.sideChatRuns.submitClarification(c.req.param("sideChatId"), readClientInstanceId(c, body.clientInstanceId), c.req.param("requestId"), answer)) throw new SideChatError("Clarification request not found", "NOT_FOUND");
+			const submission = clarificationSubmissionSchema.safeParse(body);
+			if (!submission.success) throw new SideChatError("Invalid clarification response", "INVALID_REQUEST");
+			if (!service.sideChatRuns.submitClarification(c.req.param("sideChatId"), readClientInstanceId(c, body.clientInstanceId), c.req.param("requestId"), submission.data)) throw new SideChatError("Clarification request not found", "NOT_FOUND");
 			return c.json({ ok: true });
 		} catch (error) {
 			return respondSideChatError(c, error);

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

@@ -6,9 +6,9 @@ import { hasGatewayScope, init_gateway_scopes } from "../../security/gateway-sco
 import { enqueueTaskChangedEvent, init_task_change_events } from "../../../tasks/task-change-events.js";
 import { TaskRepository, init_task_repository } from "../../../tasks/task-repository.js";
 import { TaskRunRepository, init_task_run_repository } from "../../../tasks/task-run-repository.js";
-import { TaskConversationRepository } from "../../../tasks/task-conversation-repository.js";
 import { CapabilityError } from "../../../capabilities/runtime/errors.js";
 import "../../../capabilities/runtime/dispatcher.js";
+import { TaskConversationRepository } from "../../../tasks/task-conversation-repository.js";
 import { TaskCollaborationRepository } from "../../../tasks/task-collaboration-repository.js";
 import { TaskCriterionReviewRepository } from "../../../tasks/task-criterion-review-repository.js";
 import { TaskContextMutationOutputSchema } from "../../../tasks/capabilities/relations.js";

package/dist/src/gateway/image-generation-setup.js

@@ -1,11 +1,11 @@
 import { normalizeAgentId } from "../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_agent_scope } from "../agent/agent-scope.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
 import { resolveEffectiveAgentConfigForAgent } from "../config/agent-profile.js";
 import { ConfigSchema, init_schema } from "../config/schema.js";
 import { fetchWithTimeoutGuarded } from "../media-shared/http/provider-http.js";
 import "../media-shared/http/index.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
 import { getImageGenerationProvider, listImageGenerationProvidersSummary } from "../agent/image/generation/provider-registry.js";
 //#region src/gateway/image-generation-setup.ts
 init_repository();

package/dist/src/gateway/lock.js

@@ -1,8 +1,8 @@
 import path from "node:path";
 import fs from "node:fs";
 import { createHash } from "node:crypto";
-import net from "node:net";
 import fs$1 from "node:fs/promises";
+import net from "node:net";
 import { homedir } from "os";
 //#region src/gateway/lock.ts
 /**

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

@@ -1,3 +1,4 @@
+import { type ClarificationSubmission } from '@xopcai/gateway-contract';
 import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
 import type { ClarificationResponseAction } from '@xopcai/gateway-contract';
 import type { Config } from '../../config/schema.js';
@@ -112,18 +113,18 @@ export declare class GatewayAgentRunner {
         aborted: boolean;
         idle: boolean;
     }>;
-    answerEphemeralClarification(requestId: string, answer: string): boolean;
+    answerEphemeralClarification(requestId: string, answer: ClarificationSubmission): boolean;
     getClarificationState(conversationId: string): import("@xopcai/gateway-contract").ClarificationWaitSnapshot;
-    resolveClarificationResponse(input: {
+    resolveClarificationResponse(input: ClarificationSubmission & {
         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(conversationId: string, answer: string, idempotencyKey: string): boolean;
+    answerClarificationDecision(requestId: string, decision: 'approve' | 'deny', idempotencyKey: string): boolean;
+    answerClarificationText(conversationId: string, text: string, idempotencyKey: string): boolean;
     /** Same execution path as scheduled continuation, but lets callers observe failures. */
     runScheduledWebchatTurn(conversationId: string, userTurn: UserTurnInput): Promise<void>;
     runScheduledWebchatContinuation(conversationId: string, message: string): Promise<void>;

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

@@ -1,6 +1,8 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { init_transaction, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { readClarificationPresentation } from "../../../packages/gateway-contract/src/clarifications.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { listActiveSessionInputExecutions, listActiveSessionInputRuns } from "../../storage/sqlite/session-input-repository.js";
 import { TaskRepository, init_task_repository } from "../../tasks/task-repository.js";
 import { createClarificationWait, getClarification, getClarificationSnapshot, init_clarification_wait_repository, resolveClarification, supersedeActiveClarification } from "../../storage/sqlite/clarification-wait-repository.js";
@@ -20,6 +22,7 @@ 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_src();
 init_connection_wait_repository();
 init_clarification_wait_repository();
 init_logger();
@@ -299,25 +302,36 @@ var GatewayAgentRunner = class {
 	}
 	answerClarificationChoice(requestId, choiceIndex, idempotencyKey) {
 		const wait = getClarification(requestId);
-		const answer = wait?.status === "open" ? wait.choices?.[choiceIndex] : void 0;
-		if (!answer) return false;
+		const choice = wait?.status === "open" ? wait.choiceDetails?.[choiceIndex] : void 0;
+		if (!choice) return false;
 		return this.resolveClarificationResponse({
 			id: wait.id,
 			expectedVersion: wait.version,
 			idempotencyKey,
 			action: "answer",
-			answer
+			response: { choiceId: choice.id }
+		}).ok;
+	}
+	answerClarificationDecision(requestId, decision, idempotencyKey) {
+		const wait = getClarification(requestId);
+		if (!wait || wait.kind !== "approval" || wait.status !== "open") return false;
+		return this.resolveClarificationResponse({
+			id: wait.id,
+			expectedVersion: wait.version,
+			idempotencyKey,
+			action: "answer",
+			decision
 		}).ok;
 	}
-	answerClarificationText(conversationId, answer, idempotencyKey) {
+	answerClarificationText(conversationId, text, idempotencyKey) {
 		const wait = getClarificationSnapshot(conversationId)?.clarification;
-		if (!wait || wait.status !== "open" || !answer.trim()) return false;
+		if (!wait || wait.kind === "approval" || wait.status !== "open" || !text.trim()) return false;
 		return this.resolveClarificationResponse({
 			id: wait.id,
 			expectedVersion: wait.version,
 			idempotencyKey,
 			action: "answer",
-			answer
+			response: { text }
 		}).ok;
 	}
 	/** Same execution path as scheduled continuation, but lets callers observe failures. */
@@ -417,9 +431,8 @@ var GatewayAgentRunner = class {
 			runId: opts.runId,
 			toolCallId: opts.toolCallId,
 			kind: request.kind === "approval" ? "approval" : "input",
+			...readClarificationPresentation(request),
 			question: request.question,
-			choices: request.choices,
-			suggestedAnswer: request.suggestedAnswer,
 			approvalKey: request.approvalKey
 		});
 		this.opts.emit("clarification.created", wait);
@@ -427,9 +440,8 @@ var GatewayAgentRunner = class {
 			type: "clarify_request",
 			requestId: wait.id,
 			kind: wait.kind,
+			...readClarificationPresentation(wait),
 			question: wait.question,
-			choices: wait.choices,
-			suggestedAnswer: wait.suggestedAnswer,
 			expiresAt: wait.expiresAt,
 			createdAt: wait.createdAt,
 			version: wait.version
@@ -450,13 +462,17 @@ var GatewayAgentRunner = class {
 		const routing = (await this.opts.sessionIndex.getSessionMetadata(ctx.conversationId).catch(() => null))?.routing;
 		if (!routing || routing.source !== "telegram") return;
 		let body = ctx.request.question;
-		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;
+		const buttonRows = ctx.request.kind === "approval" ? [[{
+			text: "Approve once",
+			callback_data: `clarify:${ctx.requestId}:approve`
+		}, {
+			text: "Deny",
+			callback_data: `clarify:${ctx.requestId}:deny`
+		}]] : ctx.request.choiceDetails?.map((choice, index) => [{
+			text: choice.label.slice(0, 64),
+			callback_data: `clarify:${ctx.requestId}:${index}`
+		}]);
 		body += buttonRows ? "\n\nReply with your answer, or tap an option below." : "\n\nReply with your answer.";
 		await this.opts.getChannelManager().send({
 			channel: "telegram",