@xopcai/xopc 0.0.387 → 0.0.389

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

@@ -10,6 +10,7 @@ import { ConfigHotReloader } from "../../config/reload.js";
 import "../../config/index.js";
 import { computeExtensionActivationPatch } from "../../extensions/bundled-extension-activation.js";
 import { sanitizeTunnelConfig } from "../../tunnel/tunnel-config.js";
+import { isDeepStrictEqual } from "node:util";
 //#region src/gateway/service/config-coordinator.ts
 /**
 * GatewayConfigCoordinator — owns config persistence, hot-reload, and the
@@ -44,6 +45,7 @@ var GatewayConfigCoordinator = class {
 	configReloader = null;
 	channelReloadFlushPromise = null;
 	channelReloadPending = false;
+	configWrite = Promise.resolve();
 	constructor(opts) {
 		this.opts = opts;
 	}
@@ -97,9 +99,28 @@ var GatewayConfigCoordinator = class {
 			error: result.error
 		};
 	}
-	async saveConfig(config) {
+	async saveConfig(config, expectedConfig = this.opts.getConfig()) {
+		const candidate = structuredClone(config), expected = structuredClone(expectedConfig);
+		return this.queueConfigWrite(async () => {
+			if (!isDeepStrictEqual(this.opts.getConfig(), expected)) return {
+				saved: false,
+				conflict: true,
+				error: "Configuration changed before saving. Please retry."
+			};
+			return this.persistConfig(candidate);
+		});
+	}
+	async queueConfigWrite(operation) {
+		const next = this.configWrite.catch(() => {}).then(operation);
+		this.configWrite = next;
+		return next;
+	}
+	async persistConfig(config) {
+		let persisted = false;
 		try {
-			await this.writeConfigAndReloadFromDisk(config);
+			await this.writeConfigAndReloadFromDisk(config, () => {
+				persisted = true;
+			});
 			this.scheduleChannelPluginsAfterPersist();
 			return { saved: true };
 		} catch (err) {
@@ -111,35 +132,24 @@ var GatewayConfigCoordinator = class {
 			}, `Failed to save config: ${em}`);
 			return {
 				saved: false,
-				error: em
+				error: em,
+				persisted
 			};
 		}
 	}
 	/** Merge partial updates into `currentConfig` and persist. */
 	async updateConfig(updates) {
-		try {
-			log.debug("Updating configuration...");
-			const merged = {
+		const patch = structuredClone(updates);
+		return this.queueConfigWrite(async () => {
+			const result = await this.persistConfig({
 				...this.opts.getConfig(),
-				...updates
-			};
-			this.opts.setConfig(merged);
-			await this.writeConfigAndReloadFromDisk(merged);
-			this.scheduleChannelPluginsAfterPersist();
-			log.debug("Configuration updated successfully");
-			return { updated: true };
-		} catch (err) {
-			const em = err instanceof Error ? err.message : String(err);
-			log.error({
-				err,
-				errorMessage: em,
-				phase: "infra.config"
-			}, `Failed to update config: ${em}`);
+				...patch
+			});
 			return {
-				updated: false,
-				error: em
+				updated: result.saved,
+				...result.error ? { error: result.error } : {}
 			};
-		}
+		});
 	}
 	/**
 	* Persist `extensions.enabled` / `extensions.disabled` for a discovered extension.
@@ -339,8 +349,10 @@ var GatewayConfigCoordinator = class {
 	* runtime matches disk (PATCH merge objects can drift from Zod-normalized
 	* output).
 	*/
-	async writeConfigAndReloadFromDisk(configToWrite) {
+	async writeConfigAndReloadFromDisk(configToWrite, onPersisted) {
 		await saveConfig(configToWrite, this.opts.configPath);
+		onPersisted?.();
+		this.opts.setConfig(structuredClone(configToWrite));
 		const reloaded = loadConfig(this.opts.configPath);
 		this.opts.setConfig(reloaded);
 		await configureTracing(reloaded.observability?.tracing);

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

@@ -1,3 +1,4 @@
+import type { ClarificationSubmission } from '@xopcai/gateway-contract';
 import { WorkDiscoveryService } from '../work-discovery/service.js';
 import { ConnectionRecoveryService } from '../connectors/connection-recovery-service.js';
 import { AgentService } from '../agent/service.js';
@@ -203,8 +204,8 @@ export declare class GatewayService {
         idle: boolean;
     }>;
     getActiveWebchatRunId(conversationId: string): string | undefined;
-    answerEphemeralClarification(requestId: string, answer: string): boolean;
-    getClarificationState(conversationId: string): import("@xopcai/gateway-contract/src/clarifications.js").ClarificationWaitSnapshot;
+    answerEphemeralClarification(requestId: string, answer: ClarificationSubmission): boolean;
+    getClarificationState(conversationId: string): import("@xopcai/gateway-contract").ClarificationWaitSnapshot;
     resolveClarificationResponse(input: Parameters<GatewayAgentRunner['resolveClarificationResponse']>[0]): import("../storage/sqlite/clarification-wait-repository.js").ResolveClarificationResult;
     private initializeExtensionLoader;
     private registerExtensionChannelPlugins;
@@ -243,9 +244,11 @@ export declare class GatewayService {
     }>;
     afterWeixinCredentialsPersisted(): Promise<void>;
     afterFeishuCredentialsPersisted(): Promise<void>;
-    saveConfig(config: Config): Promise<{
+    saveConfig(config: Config, expectedConfig?: Config): Promise<{
         saved: boolean;
         error?: string;
+        persisted?: boolean;
+        conflict?: boolean;
     }>;
     syncVoiceLanguage(language: ProductLanguage): Promise<{
         applied: boolean;

package/dist/src/gateway/service.js

@@ -20,13 +20,13 @@ import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js
 import { init_session_repository, listSessionMetadata, patchSessionMetadata } from "../storage/sqlite/session-repository.js";
 import { getSessionConfig, init_config_repository } from "../storage/sqlite/config-repository.js";
 import { init_sqlite } from "../storage/sqlite/index.js";
+import { normalizeAgentId } from "../agent-catalog/id.js";
+import { init_agent_scope, listAgentEntries, resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agent/agent-scope.js";
 import { listKnowledgeItems } from "../knowledge-memory/repository.js";
 import { init_config, resolveKnowledgeReadPolicy } from "../user-context/config.js";
 import { init_agent_session_key, resolveAgentMainConversationId } from "../routing/agent-session-key.js";
 import { init_session_key, resolveConversationId, sanitizeSegment } from "../routing/session-key.js";
 import "../knowledge-memory/index.js";
-import { normalizeAgentId } from "../agent-catalog/id.js";
-import { init_agent_scope, listAgentEntries, resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agent/agent-scope.js";
 import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
 import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
@@ -1336,6 +1336,7 @@ var GatewayService = class {
 		}
 		registerClarificationChannelRuntime({
 			answerChoice: (requestId, choiceIndex, idempotencyKey) => this.agentRunner.answerClarificationChoice(requestId, choiceIndex, idempotencyKey),
+			answerDecision: (requestId, decision, idempotencyKey) => this.agentRunner.answerClarificationDecision(requestId, decision, idempotencyKey),
 			answerText: (conversationId, text, idempotencyKey) => this.agentRunner.answerClarificationText(conversationId, text, idempotencyKey)
 		});
 		this.ensureAgentService();
@@ -1695,8 +1696,8 @@ var GatewayService = class {
 	afterFeishuCredentialsPersisted() {
 		return this.configCoordinator.afterFeishuCredentialsPersisted();
 	}
-	saveConfig(config) {
-		return this.configCoordinator.saveConfig(config);
+	saveConfig(config, expectedConfig) {
+		return this.configCoordinator.saveConfig(config, expectedConfig);
 	}
 	async syncVoiceLanguage(language) {
 		const mode = this.config.voice?.languageMode ?? "auto";

package/dist/src/gateway/side-chat/run-service.d.ts

@@ -1,3 +1,4 @@
+import type { ClarificationSubmission } from '@xopcai/gateway-contract';
 import type { AgentService } from '../../agent/service.js';
 import type { GatewayAgentRunner } from '../service/agent-runner.js';
 import { type EphemeralSideChatManager } from './manager.js';
@@ -23,6 +24,6 @@ export declare class SideChatRunService {
     /** Disposal has already removed the transcript from the public manager. */
     cancelRun(sideChatId: string, clientInstanceId: string, runId?: string): Promise<boolean>;
     dispose(sideChatId: string, clientInstanceId: string): Promise<boolean>;
-    submitClarification(sideChatId: string, clientInstanceId: string, requestId: string, answer: string): boolean;
+    submitClarification(sideChatId: string, clientInstanceId: string, requestId: string, answer: ClarificationSubmission): boolean;
     private execute;
 }

package/dist/src/gateway/side-chat/run-service.js

@@ -1,10 +1,13 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { readClarificationPresentation } from "../../../packages/gateway-contract/src/clarifications.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { abortEmbeddedRun } from "../../agent/embedded/runs.js";
 import { SideChatError } from "./manager.js";
 import { ChatStreamMapper } from "../chat-stream/mapper.js";
 import { randomUUID } from "node:crypto";
 //#region src/gateway/side-chat/run-service.ts
+init_src();
 init_logger();
 const log = createLogger("Gateway:SideChatRun");
 var SideChatRunService = class {
@@ -76,11 +79,11 @@ var SideChatRunService = class {
 		const publishMapped = (event) => {
 			if (run.abortController.signal.aborted) return;
 			if (event.type === "clarify_request") this.options.manager.waitForInput(run.sideChatId, run.clientInstanceId, {
+				...readClarificationPresentation(event),
+				expiresAt: typeof event.expiresAt === "number" ? event.expiresAt : void 0,
 				requestId: String(event.requestId),
 				kind: event.kind === "approval" ? "approval" : "input",
-				question: String(event.question),
-				choices: Array.isArray(event.choices) ? event.choices.filter((choice) => typeof choice === "string") : void 0,
-				suggestedAnswer: typeof event.suggestedAnswer === "string" ? event.suggestedAnswer : void 0
+				question: String(event.question)
 			}, event.kind === "approval" ? "waiting-approval" : "waiting-input");
 			for (const mapped of mapper.map(event)) publish(mapped);
 		};

package/dist/src/gateway/side-chat/types.d.ts

@@ -1,3 +1,4 @@
+import type { ClarificationPresentation } from '@xopcai/gateway-contract';
 import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 export type SideChatStatus = 'idle' | 'running' | 'waiting-approval' | 'waiting-input' | 'promoting' | 'closing';
 export type SideChatSelection = {
@@ -52,12 +53,11 @@ export interface SideChatView {
     expiresAt: string | null;
     serverNow?: string;
     runId?: string;
-    clarification?: {
+    clarification?: ClarificationPresentation & {
         requestId: string;
         kind: 'input' | 'approval';
         question: string;
-        choices?: string[];
-        suggestedAnswer?: string;
+        expiresAt?: number;
     };
     messageCount: number;
     context: SideChatContextSnapshot;

package/dist/src/gateway/xopc-cloud-capability-setup.d.ts

@@ -1,5 +1,5 @@
-import type { Config } from '../config/schema.js';
-import type { AgentDefaults } from '../agent-config/index.js';
+import { type Config } from '../config/schema.js';
+import { type AgentDefaults } from '../agent-config/index.js';
 import type { CatalogSource } from '../providers/model-catalog-store.js';
 type CloudCapability = 'chat' | 'vision' | 'image-generation' | 'stt' | 'tts';
 export interface XopcCloudCapabilitySelection {

package/dist/src/gateway/xopc-cloud-capability-setup.js

@@ -1,13 +1,16 @@
+import "../agent-config/schema.js";
+import { init_agent_config } from "../agent-config/index.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
+import { ConfigSchema, init_schema } from "../config/schema.js";
 import { getModelCatalogStore, init_model_catalog_store } from "../providers/model-catalog-store.js";
-import { getAvailableModels, init_providers } from "../providers/index.js";
 import { compareCatalogModels } from "../providers/model-catalog-ranking.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
 import { prepareUpdateGlobalDefaults } from "./global-defaults-admin.js";
 //#region src/gateway/xopc-cloud-capability-setup.ts
+init_schema();
+init_agent_config();
 init_repository();
 init_model_catalog_store();
-init_providers();
 function supportsCapability(model, capability) {
 	if (model.availability !== "available") return false;
 	if (capability === "chat") return model.kind === "language" && (model.operations.includes("chat.completions") || model.operations.includes("responses"));
@@ -181,7 +184,6 @@ async function applyXopcCloudCapabilitySetup(service) {
 	};
 	const selection = selectXopcCloudCapabilities(source);
 	const currentDefaults = new AgentCatalogRepository().getSettings().defaults;
-	const availableModels = new Set((await getAvailableModels()).map((model) => `${model.provider}/${model.id}`));
 	const nextDefaults = structuredClone(currentDefaults);
 	const nextConfig = structuredClone(service.currentConfig);
 	const chat = recommendedModel(source, "chat");
@@ -192,7 +194,7 @@ async function applyXopcCloudCapabilitySetup(service) {
 	const realtimeStt = recommendedVoiceModel(source, "transcription.stream");
 	const realtimeTts = recommendedVoiceModel(source, "speech.stream");
 	const realtimeOmni = recommendedVoiceModel(source, "conversation");
-	if (chat && !availableModels.has(currentDefaults.models.chat.primary)) nextDefaults.models.chat = {
+	if (chat && currentDefaults.models.chat.primary === "xopc-cloud/auto" && currentDefaults.models.chat.fallbacks.length === 0) nextDefaults.models.chat = {
 		primary: `xopc-cloud/${chat.id}`,
 		fallbacks: []
 	};
@@ -232,6 +234,7 @@ async function applyXopcCloudCapabilitySetup(service) {
 			} }
 		};
 	}
+	if (!nextConfig.voice && (realtimeStt || realtimeTts || realtimeOmni)) nextConfig.voice = ConfigSchema.parse({ voice: { realtime: { enabled: true } } }).voice;
 	const realtime = nextConfig.voice?.realtime;
 	if (realtime?.enabled) {
 		if (realtimeStt && !realtime.stt) realtime.stt = {

package/dist/src/local-apps/service.js

@@ -5,10 +5,10 @@ import { currentOperationId, init_operation_context } from "../infra/operation-c
 import { afterSqliteCommit, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
 import { ExtensionCapabilityBindingsSchema, extensionCapabilityPermissions } from "../../packages/gateway-contract/src/extension-capabilities.js";
 import { init_src } from "../../packages/gateway-contract/src/index.js";
+import { CapabilityError } from "../capabilities/runtime/errors.js";
 import { init_paths, resolveExtensionsDir } from "../config/paths.js";
 import { slugifyProjectName } from "../projects/project-store.js";
 import { LocalAppStore } from "./store.js";
-import { CapabilityError } from "../capabilities/runtime/errors.js";
 import { DomainOutboxDispatcher } from "../infra/domain-outbox-dispatcher.js";
 import { validateLocalAppCapabilityContracts } from "./capabilities/contracts.js";
 import { buildLocalAppFixGuidance } from "./fix-guidance.js";

package/dist/src/memory-learning/service.js

@@ -85,8 +85,9 @@ var MemoryLearningService = class {
 						err,
 						jobId: job.job_id,
 						conversationId: job.conversation_id,
-						phase: "extract"
-					}, "Memory learning failed; retry queued");
+						phase: "extract",
+						attempts: job.attempts
+					}, job.attempts >= 3 ? "Memory learning failed; retry limit reached" : "Memory learning failed; retry queued");
 				} finally {
 					clearInterval(renew);
 				}

package/dist/src/personal-agent/proactivity/service.js

@@ -5,8 +5,8 @@ import { PersonalProactiveMessageSchema } from "../../../packages/gateway-contra
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { init_session_instance_repository, readCurrentTranscriptId } from "../../storage/sqlite/session-instance-repository.js";
 import { appendTranscriptEntry, init_transcript_repository } from "../../storage/sqlite/transcript-repository.js";
-import { resolveUserContextSessionAccess } from "../../user-context/access-policy.js";
 import { AgentCatalogRepository, init_repository } from "../../agent-catalog/repository.js";
+import { resolveUserContextSessionAccess } from "../../user-context/access-policy.js";
 import { init_providers, resolveModel } from "../../providers/index.js";
 import { completeWithResolvedCredentials } from "../../providers/model-call.js";
 import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../../providers/model-response.js";

package/dist/src/personal-agent/service.js

@@ -1,15 +1,15 @@
 import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
 import { init_session_repository, patchSessionMetadata } from "../storage/sqlite/session-repository.js";
 import { init_config_repository, setSessionConfig } from "../storage/sqlite/config-repository.js";
-import { createConversation, init_conversation_repository } from "../storage/sqlite/conversation-repository.js";
 import { ResponsePreferencesSchema } from "../agent-config/schema.js";
 import { init_agent_config } from "../agent-config/index.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
+import { createConversation, init_conversation_repository } from "../storage/sqlite/conversation-repository.js";
 import { getAvailableModels, init_providers } from "../providers/index.js";
 import { DEFAULT_PERSONAL_PREFERENCES, getPersonalAgent, personalAgentId } from "./repository.js";
 import { PERSONAL_MAIN_TOOL_IDS, PERSONAL_READ_TOOL_ALIASES } from "./policy.js";
 import { getModelThinking } from "../providers/model-thinking.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
 import { personalInstructions, upgradePersonalInstructions } from "./prompts.js";
 import { completePersonalOnboarding } from "./onboarding.js";
 import { z } from "zod";

package/dist/src/providers/model-catalog-persistence.js

@@ -1,7 +1,7 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { init_paths_state, resolveXopcCloudCatalogCachePath } from "../config/paths-state.js";
-import { ComputerProfileSchema, init_src } from "../../packages/computer-control-contract/src/index.js";
 import { init_write_file_atomic, writeTextAtomic } from "../infra/write-file-atomic.js";
+import { ComputerProfileSchema, init_src } from "../../packages/computer-control-contract/src/index.js";
 import { ImageGenerationCapabilitiesSchema, init_models_json } from "../config/models-json.js";
 import { voiceManifestSchema } from "../../packages/realtime-protocol/src/voice-catalog.js";
 import { init_voice } from "../../packages/realtime-protocol/src/voice.js";

package/dist/src/routing/resolve-route.js

@@ -1,9 +1,9 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { init_account_id, normalizeAccountId } from "./account-id.js";
+import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { getConversationRouting } from "../storage/sqlite/conversation-repository.js";
 import { init_agent_session_key, resolveAgentPeerConversationId } from "./agent-session-key.js";
 import { init_session_key, resolveConversationId } from "./session-key.js";
-import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_bindings, parseBindingRules, resolveRoute as resolveRoute$1 } from "./bindings.js";
 //#region src/routing/resolve-route.ts
 /**

package/dist/src/routing/resolve-tui-session-key.js

@@ -1,8 +1,8 @@
 import { validateConversationId } from "../../packages/gateway-contract/src/conversation-identity.js";
 import { init_src } from "../../packages/gateway-contract/src/index.js";
-import { init_agent_session_key, normalizeAgentId } from "./agent-session-key.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_agent_scope, listAgentEntries, resolveAgentIdByWorkspacePath, resolveDefaultAgentId } from "../agent/agent-scope.js";
+import { init_agent_session_key, normalizeAgentId } from "./agent-session-key.js";
 import { randomUUID } from "node:crypto";
 //#region src/routing/resolve-tui-session-key.ts
 init_src();

package/dist/src/scenes/execution.d.ts

@@ -5,8 +5,8 @@ import { SceneRepository } from './repository.js';
 import { SceneCapabilityRegistry } from './registry.js';
 export declare const readOnlyResultSchema: z.ZodObject<{
     kind: z.ZodEnum<{
-        artifact: "artifact";
         decision: "decision";
+        artifact: "artifact";
         observation: "observation";
         no_change: "no_change";
     }>;

package/dist/src/scenes/taskFollowUp/contracts.d.ts

@@ -30,7 +30,7 @@ export declare const taskFollowUpTemplate: {
             maxOutputTokens: number;
         };
     };
-    allowedOutcomeKinds: ("artifact" | "receipt" | "decision" | "observation" | "no_change" | "state_change" | "effect_proposal")[];
+    allowedOutcomeKinds: ("decision" | "artifact" | "receipt" | "observation" | "no_change" | "state_change" | "effect_proposal")[];
     allowedEffectHandlers: string[];
 };
 export declare const decisionLogTemplate: {
@@ -62,7 +62,7 @@ export declare const decisionLogTemplate: {
             maxOutputTokens: number;
         };
     };
-    allowedOutcomeKinds: ("artifact" | "receipt" | "decision" | "observation" | "no_change" | "state_change" | "effect_proposal")[];
+    allowedOutcomeKinds: ("decision" | "artifact" | "receipt" | "observation" | "no_change" | "state_change" | "effect_proposal")[];
     allowedEffectHandlers: string[];
 };
 export declare const sourceReferenceSchema: z.ZodObject<{

package/dist/src/scenes/taskFollowUp/service.d.ts

@@ -114,7 +114,7 @@ export declare class SceneTaskExecutionService implements SceneActivationAdapter
             taskId: string;
             rootRunId: string;
             attempt: number;
-            status: "failed" | "succeeded" | "waiting" | "cancelled" | "queued" | "running" | "verifying";
+            status: "failed" | "succeeded" | "queued" | "cancelled" | "waiting" | "running" | "verifying";
             executorKind: "agent" | "workflow" | "human" | "external";
             executorRef: Record<string, unknown>;
             trigger: Record<string, unknown>;
@@ -267,7 +267,7 @@ export declare class SceneTaskExecutionService implements SceneActivationAdapter
             taskId: string;
             rootRunId: string;
             attempt: number;
-            status: "failed" | "succeeded" | "waiting" | "cancelled" | "queued" | "running" | "verifying";
+            status: "failed" | "succeeded" | "queued" | "cancelled" | "waiting" | "running" | "verifying";
             executorKind: "agent" | "workflow" | "human" | "external";
             executorRef: Record<string, unknown>;
             trigger: Record<string, unknown>;
@@ -419,7 +419,7 @@ export declare class SceneTaskExecutionService implements SceneActivationAdapter
             taskId: string;
             rootRunId: string;
             attempt: number;
-            status: "failed" | "succeeded" | "waiting" | "cancelled" | "queued" | "running" | "verifying";
+            status: "failed" | "succeeded" | "queued" | "cancelled" | "waiting" | "running" | "verifying";
             executorKind: "agent" | "workflow" | "human" | "external";
             executorRef: Record<string, unknown>;
             trigger: Record<string, unknown>;
@@ -597,7 +597,7 @@ export declare class SceneTaskExecutionService implements SceneActivationAdapter
             taskId: string;
             rootRunId: string;
             attempt: number;
-            status: "failed" | "succeeded" | "waiting" | "cancelled" | "queued" | "running" | "verifying";
+            status: "failed" | "succeeded" | "queued" | "cancelled" | "waiting" | "running" | "verifying";
             executorKind: "agent" | "workflow" | "human" | "external";
             executorRef: Record<string, unknown>;
             trigger: Record<string, unknown>;
@@ -749,7 +749,7 @@ export declare class SceneTaskExecutionService implements SceneActivationAdapter
             taskId: string;
             rootRunId: string;
             attempt: number;
-            status: "failed" | "succeeded" | "waiting" | "cancelled" | "queued" | "running" | "verifying";
+            status: "failed" | "succeeded" | "queued" | "cancelled" | "waiting" | "running" | "verifying";
             executorKind: "agent" | "workflow" | "human" | "external";
             executorRef: Record<string, unknown>;
             trigger: Record<string, unknown>;

package/dist/src/scenes/templates.d.ts

@@ -27,7 +27,7 @@ export declare const mailFollowUpTemplate: {
             maxOutputTokens: number;
         };
     };
-    allowedOutcomeKinds: ("artifact" | "receipt" | "decision" | "observation" | "no_change" | "state_change" | "effect_proposal")[];
+    allowedOutcomeKinds: ("decision" | "artifact" | "receipt" | "observation" | "no_change" | "state_change" | "effect_proposal")[];
     allowedEffectHandlers: string[];
 };
 export declare const familyPlanTemplate: {
@@ -59,6 +59,6 @@ export declare const familyPlanTemplate: {
             maxOutputTokens: number;
         };
     };
-    allowedOutcomeKinds: ("artifact" | "receipt" | "decision" | "observation" | "no_change" | "state_change" | "effect_proposal")[];
+    allowedOutcomeKinds: ("decision" | "artifact" | "receipt" | "observation" | "no_change" | "state_change" | "effect_proposal")[];
     allowedEffectHandlers: string[];
 };

package/dist/src/storage/sqlite/clarification-wait-repository.d.ts

@@ -1,22 +1,20 @@
+import { type ClarificationPresentation, type ClarificationSubmission } from '@xopcai/gateway-contract';
 import type { ClarificationKind, ClarificationResponseAction, ClarificationWait, ClarificationWaitSnapshot } from '@xopcai/gateway-contract';
 import { type SessionInput } from './session-input-repository.js';
-export type CreateClarificationInput = {
+export type CreateClarificationInput = ClarificationPresentation & {
     conversationId: string;
     runId: string;
     toolCallId: string;
     kind: ClarificationKind;
     question: string;
-    choices?: string[];
-    suggestedAnswer?: string;
     approvalKey?: string;
     now?: number;
 };
-export type ResolveClarificationInput = {
+export type ResolveClarificationInput = ClarificationSubmission & {
     id: string;
     expectedVersion: number;
     idempotencyKey: string;
     action: ClarificationResponseAction;
-    answer?: string;
     now?: number;
 };
 export type ResolveClarificationResult = {

package/dist/src/storage/sqlite/clarification-wait-repository.js

@@ -1,6 +1,8 @@
 import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
 import { init_connection, isXopcDatabaseOpen } from "./connection.js";
 import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "./transaction.js";
+import { normalizeClarificationQuestion, normalizeClarificationSubmission } from "../../../packages/gateway-contract/src/clarifications.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { init_session_instance_repository, readCurrentTranscriptId } from "./session-instance-repository.js";
 import { bumpSessionInputRevision, getSessionInputById, getSessionInputState, init_session_input_repository, insertSessionInput } from "./session-input-repository.js";
 import { TaskRunRepository, init_task_run_repository } from "../../tasks/task-run-repository.js";
@@ -129,6 +131,7 @@ function getClarificationSnapshot(conversationId) {
 	};
 }
 function createClarificationWait(input) {
+	input = normalizeClarificationQuestion(input);
 	return runSqliteWriteTransaction((db) => {
 		const transcriptId = readCurrentTranscriptId(db, input.conversationId);
 		if (!transcriptId) throw new Error("Clarification requires a persisted session.");
@@ -166,8 +169,10 @@ function createClarificationWait(input) {
 			kind: input.kind,
 			status: "open",
 			question: input.question.trim(),
-			choices: input.choices,
-			suggestedAnswer: input.suggestedAnswer,
+			interactionMode: input.interactionMode,
+			choiceDetails: input.choiceDetails,
+			recommendedChoiceId: input.recommendedChoiceId,
+			approval: input.approval,
 			checkpoint: {
 				transcriptEntryId: lastEntry?.entry_id,
 				objectiveSummary: origin?.content ?? input.question.trim(),
@@ -217,38 +222,50 @@ function resolveClarification(input) {
 			code: "NOT_FOUND"
 		};
 		const now = input.now ?? Date.now();
-		if (wait.kind === "approval" && wait.expiresAt !== void 0 && wait.expiresAt <= now) return {
+		let normalized;
+		try {
+			if (input.action === "answer") normalized = normalizeClarificationSubmission(wait, {
+				response: input.response,
+				decision: input.decision
+			});
+			else if (input.response !== void 0 || input.decision !== void 0) return {
+				ok: false,
+				code: "INVALID"
+			};
+		} catch {
+			return {
+				ok: false,
+				code: "INVALID"
+			};
+		}
+		if (input.action === "agent_decide" && wait.kind === "approval") return {
+			ok: false,
+			code: "INVALID"
+		};
+		const resolution = input.action === "answer" ? "answered" : input.action === "agent_decide" ? "agent_decide" : "cancelled";
+		if (wait.responseIdempotencyKey === input.idempotencyKey) {
+			if (wait.resolution !== resolution || normalized && wait.answer !== normalized.answer) return {
+				ok: false,
+				code: "CONFLICT",
+				clarification: wait
+			};
+			return {
+				ok: true,
+				clarification: wait,
+				idempotent: true,
+				queued: wait.status === "queued"
+			};
+		}
+		if (wait.kind === "approval" && wait.expiresAt !== void 0 && wait.expiresAt <= now && (wait.status === "open" || wait.status === "queued")) return {
 			ok: false,
 			code: "EXPIRED",
 			clarification: expireApproval(wait, now)
 		};
-		if (db.prepare("SELECT id FROM session_inputs WHERE conversation_id = ? AND client_message_id = ?").get(wait.conversationId, input.idempotencyKey)) return {
-			ok: true,
-			clarification: wait,
-			idempotent: true,
-			queued: wait.status === "queued"
-		};
-		if (wait.responseIdempotencyKey === input.idempotencyKey) return {
-			ok: true,
-			clarification: wait,
-			idempotent: true,
-			queued: wait.status === "queued"
-		};
-		if (wait.version !== input.expectedVersion || wait.status !== "open") return {
+		if (db.prepare("SELECT id FROM session_inputs WHERE conversation_id = ? AND client_message_id = ?").get(wait.conversationId, input.idempotencyKey) || wait.version !== input.expectedVersion || wait.status !== "open") return {
 			ok: false,
 			code: "CONFLICT",
 			clarification: wait
 		};
-		const trimmed = input.answer?.trim() ?? "";
-		if (input.action === "answer" && !trimmed) return {
-			ok: false,
-			code: "INVALID"
-		};
-		if (input.action === "agent_decide" && wait.kind === "approval") return {
-			ok: false,
-			code: "INVALID"
-		};
-		const resolution = input.action === "answer" ? "answered" : input.action === "agent_decide" ? "agent_decide" : "cancelled";
 		if (input.action === "cancel") {
 			const cancelled = writeWait({
 				...wait,
@@ -273,10 +290,12 @@ function resolveClarification(input) {
 				queued: false
 			};
 		}
-		const answer = input.action === "agent_decide" ? "Use your best judgment and continue without additional user input." : trimmed;
+		const answer = input.action === "agent_decide" ? "Use your best judgment and continue without additional user input." : normalized.answer;
 		const queued = writeWait({
 			...wait,
 			status: "queued",
+			response: normalized?.response,
+			decision: normalized?.decision,
 			answer,
 			resolution,
 			responseIdempotencyKey: input.idempotencyKey,
@@ -380,7 +399,7 @@ function consumeClarificationApproval(conversationId, approvalKey) {
 		if (input?.kind !== "clarification_resume" || !input.payload) return void 0;
 		const wait = getClarification(input.payload.waitId);
 		if (!wait || wait.kind !== "approval" || wait.approvalKey !== approvalKey || wait.approvalConsumedAt) return;
-		const approved = wait.answer === "Allow once";
+		const approved = (wait.expiresAt === void 0 || wait.expiresAt > Date.now()) && wait.decision === "approve";
 		writeWait({
 			...wait,
 			approvalConsumedAt: Date.now(),
@@ -416,6 +435,7 @@ function supersedeActiveClarification(conversationId, now = Date.now()) {
 }
 var APPROVAL_TTL_MS, STALE_CONTEXT_MS;
 var init_clarification_wait_repository = __esmMin((() => {
+	init_src();
 	init_task_run_repository();
 	init_connection();
 	init_session_instance_repository();