@xopcai/xopc 0.0.252 → 0.0.254

package/dist/src/heartbeat/index.js

@@ -1,6 +1,6 @@
 import { DEFAULT_ACK_MAX_CHARS, HEARTBEAT_OK, NO_REPLY, shouldSilence, stripHeartbeatToken } from "./tokens.js";
-import { appendCronEventLines } from "./event-prompt.js";
 import { isWithinActiveHours } from "./active-hours.js";
 import { isHeartbeatContentEmpty } from "./content-check.js";
+import { appendCronEventLines } from "./event-prompt.js";
 import { createHeartbeatWake } from "./wake.js";
 export { DEFAULT_ACK_MAX_CHARS, HEARTBEAT_OK, NO_REPLY, appendCronEventLines, createHeartbeatWake, isHeartbeatContentEmpty, isWithinActiveHours, shouldSilence, stripHeartbeatToken };

package/dist/src/providers/auth-runtime/resolve-auth.js

@@ -1,5 +1,5 @@
-import { init_sync_provider_auth, resolveProviderApiKeyForAgentSync } from "../../auth/sync-provider-auth.js";
 import { getApiKeyFromEnv, init_env_keys } from "../env-keys.js";
+import { init_sync_provider_auth, resolveProviderApiKeyForAgentSync } from "../../auth/sync-provider-auth.js";
 import { getDefaultAuthProfileStore } from "./auth-profile-store.js";
 //#region src/providers/auth-runtime/resolve-auth.ts
 init_env_keys();

package/dist/src/providers/index.js

@@ -1,11 +1,11 @@
 import { __esmMin, __exportAll } from "../../_virtual/_rolldown/runtime.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
-import { getModelOAuthProviderIds, init_registry } from "../auth/oauth/registry.js";
-import { hasProviderAuthOnDiskSync, init_sync_provider_auth } from "../auth/sync-provider-auth.js";
 import { PROVIDER_ENV_MAP, getApiKeyFromEnv, init_env_keys } from "./env-keys.js";
 import { init_model_ref, splitProviderModelRef } from "./model-ref.js";
 import { ModelRegistry, getModelRegistry, init_model_registry, prewarmModelRegistry, resetModelRegistry } from "./model-registry.js";
+import { getModelOAuthProviderIds, init_registry } from "../auth/oauth/registry.js";
 import { CredentialResolver, hasCredentials, init_credentials } from "../auth/credentials.js";
+import { hasProviderAuthOnDiskSync, init_sync_provider_auth } from "../auth/sync-provider-auth.js";
 import { EXTENSION_PROVIDER_BASE_URL, init_constants } from "./constants.js";
 import { applyOfficialModelMetadataCorrections, getSupplementalModels, init_model_supplements } from "./model-supplements.js";
 import { getProviderRegistry, init_plugin_registry } from "./plugin-registry.js";

package/dist/src/providers/model-registry.js

@@ -1,8 +1,8 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { resolveModelsJsonPath } from "../config/paths.js";
 import { init_resolve_config_value, resolveConfigValue, resolveHeaders } from "../config/resolve-config-value.js";
+import { resolveModelsJsonPath } from "../config/paths.js";
 import { getDefaultModelValues, init_models_json, validateModelsConfig } from "../config/models-json.js";
 import { getApiKeyFromEnv, init_env_keys } from "./env-keys.js";
 import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";

package/dist/src/providers/model-thinking.js

@@ -1,5 +1,18 @@
 import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 //#region src/providers/model-thinking.ts
+const TOGGLE_THINKING_FORMATS = new Set([
+	"zai",
+	"qwen",
+	"qwen-chat-template",
+	"chat-template",
+	"deepseek",
+	"together",
+	"baseten",
+	"string-thinking"
+]);
+function preferredEnabledLevel(options) {
+	return options.includes("high") ? "high" : options.find((option) => option !== "off");
+}
 /** Use the same capability metadata as the provider runtime. */
 function getModelThinking(model) {
 	const base = { supportsAdaptive: false };
@@ -10,29 +23,53 @@ function getModelThinking(model) {
 		initialValue: "off"
 	};
 	const compat = model.compat;
-	const binaryFormat = [
-		"zai",
-		"qwen",
-		"qwen-chat-template",
-		"chat-template"
-	].includes(compat?.thinkingFormat ?? "");
-	const binaryProvider = model.provider === "zai" || model.provider === "z.ai";
-	if ((binaryFormat || binaryProvider) && compat?.supportsReasoningEffort !== true) return {
-		...base,
-		mode: "toggle",
-		options: ["off", "high"],
-		initialValue: "high"
-	};
-	if (compat?.supportsReasoningEffort === false) return {
-		...base,
-		mode: "unknown",
-		options: ["off"],
-		initialValue: "off"
-	};
 	const options = getSupportedThinkingLevels(model);
+	const enabledLevel = preferredEnabledLevel(options);
+	if ((TOGGLE_THINKING_FORMATS.has(compat?.thinkingFormat ?? "") || model.provider === "zai" || model.provider === "z.ai") && compat?.supportsReasoningEffort !== true && enabledLevel) {
+		if (options.includes("off")) return {
+			...base,
+			mode: "toggle",
+			options: ["off", enabledLevel],
+			initialValue: enabledLevel
+		};
+		return {
+			...base,
+			mode: "fixed",
+			options: [enabledLevel],
+			initialValue: enabledLevel
+		};
+	}
+	if (compat?.supportsReasoningEffort === false) {
+		if (enabledLevel) return {
+			...base,
+			mode: "fixed",
+			options: [enabledLevel],
+			initialValue: enabledLevel
+		};
+		return {
+			...base,
+			mode: "none",
+			options: ["off"],
+			initialValue: "off"
+		};
+	}
+	if (options.length === 1) {
+		const only = options[0] ?? "off";
+		return only === "off" ? {
+			...base,
+			mode: "none",
+			options: ["off"],
+			initialValue: "off"
+		} : {
+			...base,
+			mode: "fixed",
+			options: [only],
+			initialValue: only
+		};
+	}
 	return {
 		...base,
-		mode: options.length > 1 ? "levels" : "none",
+		mode: "levels",
 		options,
 		initialValue: options.includes("medium") ? "medium" : options[0] ?? "off"
 	};

package/dist/src/providers/register-runtime-providers.js

@@ -1,6 +1,6 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
-import { getOAuthProviderDefinition, init_registry } from "../auth/oauth/registry.js";
 import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
+import { getOAuthProviderDefinition, init_registry } from "../auth/oauth/registry.js";
 import { XOPC_CLOUD_PROVIDER_ID, init_xopc_cloud_config, resolveXopcModelRouterUrl } from "./xopc-cloud-config.js";
 //#region src/providers/register-runtime-providers.ts
 function registerRuntimeProvider(modelRuntime, source) {

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

@@ -0,0 +1,41 @@
+import type { ClarificationKind, ClarificationResponseAction, ClarificationWait, ClarificationWaitSnapshot } from '@xopcai/gateway-contract';
+import { type SessionInput } from './session-input-repository.js';
+export type CreateClarificationInput = {
+    sessionKey: string;
+    runId: string;
+    toolCallId: string;
+    kind: ClarificationKind;
+    question: string;
+    choices?: string[];
+    suggestedAnswer?: string;
+    approvalKey?: string;
+    now?: number;
+};
+export type ResolveClarificationInput = {
+    id: string;
+    expectedVersion: number;
+    idempotencyKey: string;
+    action: ClarificationResponseAction;
+    answer?: string;
+    now?: number;
+};
+export type ResolveClarificationResult = {
+    ok: true;
+    clarification: ClarificationWait;
+    idempotent: boolean;
+    queued: boolean;
+} | {
+    ok: false;
+    code: 'NOT_FOUND' | 'CONFLICT' | 'EXPIRED' | 'INVALID';
+    clarification?: ClarificationWait;
+};
+export declare function getClarification(id: string): ClarificationWait | undefined;
+export declare function getActiveClarification(sessionKey: string): ClarificationWait | undefined;
+export declare function getClarificationSnapshot(sessionKey: string): ClarificationWaitSnapshot | undefined;
+export declare function createClarificationWait(input: CreateClarificationInput): ClarificationWait;
+export declare function isClarificationSuspended(sessionKey: string, runId: string): boolean;
+export declare function resolveClarification(input: ResolveClarificationInput): ResolveClarificationResult;
+export declare function getClarificationResumeInput(sessionKey: string, runId: string): SessionInput | undefined;
+export declare function consumeClarificationResume(input: SessionInput): boolean;
+export declare function consumeClarificationApproval(sessionKey: string, approvalKey: string): 'approved' | 'denied' | undefined;
+export declare function supersedeActiveClarification(sessionKey: string, now?: number): ClarificationWait | undefined;

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

@@ -0,0 +1,418 @@
+import { isXopcDatabaseOpen } from "./connection.js";
+import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import { readCurrentSessionId } from "./session-instance-repository.js";
+import { bumpSessionInputRevision, getSessionInputById, getSessionInputState, insertSessionInput } from "./session-input-repository.js";
+import { TaskRunRepository } from "../../tasks/task-run-repository.js";
+import { randomUUID } from "node:crypto";
+//#region src/storage/sqlite/clarification-wait-repository.ts
+const APPROVAL_TTL_MS = 10 * 6e4;
+const STALE_CONTEXT_MS = 1440 * 6e4;
+function rowToWait(row) {
+	return JSON.parse(row.data_json);
+}
+function getRow(id) {
+	return getSqliteDatabase().prepare(`SELECT id, session_key, session_id, status, version, data_json
+     FROM session_clarification_waits WHERE id = ?`).get(id);
+}
+function writeWait(wait, expectedVersion) {
+	const next = {
+		...wait,
+		version: expectedVersion + 1,
+		updatedAt: wait.updatedAt || Date.now()
+	};
+	return getSqliteDatabase().prepare(`UPDATE session_clarification_waits
+     SET status = ?, version = ?, data_json = ?
+     WHERE id = ? AND version = ?`).run(next.status, next.version, JSON.stringify(next), next.id, expectedVersion).changes ? next : void 0;
+}
+function taskWaitsForClarification(taskId, clarificationId) {
+	return new TaskRunRepository().listActiveWaits(taskId).filter((wait) => wait.condition.clarificationId === clarificationId);
+}
+function resolveTaskWait(wait, resolution) {
+	if (!wait.taskRunId) return;
+	const runs = new TaskRunRepository();
+	const run = runs.get(wait.taskRunId);
+	if (!run) return;
+	for (const taskWait of taskWaitsForClarification(run.taskId, wait.id)) runs.resolveWait({
+		waitId: taskWait.id,
+		actor: {
+			kind: "user",
+			id: wait.principalId
+		},
+		resolution
+	});
+}
+function cancelTaskRun(wait, reason, now) {
+	if (!wait.taskRunId) return;
+	const runs = new TaskRunRepository();
+	const run = runs.get(wait.taskRunId);
+	if (!run || ![
+		"queued",
+		"running",
+		"waiting",
+		"verifying"
+	].includes(run.status)) return;
+	runs.finalize({
+		runId: run.id,
+		expectedVersion: run.version,
+		actor: {
+			kind: "user",
+			id: wait.principalId
+		},
+		terminalCode: "clarification_cancelled",
+		terminalMessage: reason,
+		now,
+		receipt: {
+			status: "cancelled",
+			summary: reason,
+			changes: [],
+			evidence: [],
+			verification: {
+				status: "unverified",
+				checks: []
+			},
+			remainingWork: [wait.checkpoint.objectiveSummary],
+			needsUser: false,
+			completionVerdict: "not_achieved"
+		}
+	});
+}
+function markTaskWaiting(wait) {
+	if (!wait.taskRunId) return;
+	const runs = new TaskRunRepository();
+	const run = runs.get(wait.taskRunId);
+	if (!run || run.status !== "running") return;
+	runs.createWait({
+		taskId: run.taskId,
+		taskRunId: run.id,
+		kind: wait.kind === "approval" ? "approval" : "user_input",
+		reason: wait.question,
+		condition: {
+			type: "clarification",
+			clarificationId: wait.id
+		}
+	});
+	runs.setStatus({
+		runId: run.id,
+		expectedVersion: run.version,
+		from: ["running"],
+		to: "waiting",
+		actor: { kind: "system" }
+	});
+}
+function getClarification(id) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const row = getRow(id);
+	return row ? rowToWait(row) : void 0;
+}
+function getActiveClarification(sessionKey) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const sessionId = readCurrentSessionId(getSqliteDatabase(), sessionKey);
+	if (!sessionId) return void 0;
+	const row = getSqliteDatabase().prepare(`SELECT id, session_key, session_id, status, version, data_json
+     FROM session_clarification_waits
+     WHERE session_key = ? AND session_id = ? AND status IN ('open', 'queued')
+     ORDER BY version DESC LIMIT 1`).get(sessionKey, sessionId);
+	return row ? rowToWait(row) : void 0;
+}
+function getClarificationSnapshot(sessionKey) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const sessionId = readCurrentSessionId(getSqliteDatabase(), sessionKey);
+	if (!sessionId) return void 0;
+	const state = getSessionInputState(sessionKey);
+	const now = Date.now();
+	const active = getActiveClarification(sessionKey);
+	const clarification = active?.kind === "approval" && active.expiresAt !== void 0 && active.expiresAt <= now ? expireApproval(active, now) : active;
+	return {
+		sessionId,
+		revision: state.revision,
+		serverTime: now,
+		clarification: clarification?.status === "open" || clarification?.status === "queued" ? clarification : null
+	};
+}
+function createClarificationWait(input) {
+	return runSqliteWriteTransaction((db) => {
+		const sessionId = readCurrentSessionId(db, input.sessionKey);
+		if (!sessionId) throw new Error("Clarification requires a persisted session.");
+		const duplicate = db.prepare(`SELECT id, session_key, session_id, status, version, data_json
+       FROM session_clarification_waits
+       WHERE session_id = ? AND origin_run_id = ? AND origin_tool_call_id = ?`).get(sessionId, input.runId, input.toolCallId);
+		if (duplicate) return rowToWait(duplicate);
+		const now = input.now ?? Date.now();
+		const runtime = getSessionInputState(input.sessionKey);
+		const origin = runtime.activeInputId ? getSessionInputById(input.sessionKey, runtime.activeInputId) : void 0;
+		const active = getActiveClarification(input.sessionKey);
+		if (active) {
+			writeWait({
+				...active,
+				status: "superseded",
+				resolution: "cancelled",
+				resolvedAt: now,
+				updatedAt: now
+			}, active.version);
+			resolveTaskWait(active, { superseded: true });
+			cancelTaskRun(active, "Task superseded by a newer clarification request.", now);
+		}
+		const lastEntry = db.prepare("SELECT entry_id FROM transcript_entries WHERE session_id = ? ORDER BY seq DESC LIMIT 1").get(sessionId);
+		const wait = {
+			id: randomUUID(),
+			principalId: "local-owner",
+			sessionKey: input.sessionKey,
+			sessionId,
+			objectiveId: origin?.id ?? input.runId,
+			objectiveRevision: (active?.objectiveRevision ?? 0) + 1,
+			originRunId: input.runId,
+			originInputId: origin?.id ?? input.runId,
+			originToolCallId: input.toolCallId,
+			taskRunId: origin?.taskRunId,
+			kind: input.kind,
+			status: "open",
+			question: input.question.trim(),
+			choices: input.choices,
+			suggestedAnswer: input.suggestedAnswer,
+			checkpoint: {
+				transcriptEntryId: lastEntry?.entry_id,
+				objectiveSummary: origin?.content ?? input.question.trim(),
+				completedSteps: [],
+				pendingSteps: [input.question.trim()],
+				originalRequestAt: origin?.createdAtMs ?? now
+			},
+			expiresAt: input.kind === "approval" ? now + APPROVAL_TTL_MS : void 0,
+			approvalKey: input.approvalKey,
+			version: 1,
+			createdAt: now,
+			updatedAt: now
+		};
+		db.prepare(`INSERT INTO session_clarification_waits (
+        id, principal_id, session_key, session_id, status, version, data_json,
+        origin_run_id, origin_tool_call_id
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(wait.id, wait.principalId, wait.sessionKey, wait.sessionId, wait.status, wait.version, JSON.stringify(wait), wait.originRunId, wait.originToolCallId);
+		markTaskWaiting(wait);
+		bumpSessionInputRevision(db, input.sessionKey);
+		return wait;
+	});
+}
+function isClarificationSuspended(sessionKey, runId) {
+	const wait = getActiveClarification(sessionKey);
+	return Boolean(wait?.status === "open" && wait.originRunId === runId);
+}
+function expireApproval(wait, now) {
+	const expired = {
+		...wait,
+		status: "expired",
+		resolution: "cancelled",
+		resolvedAt: now,
+		updatedAt: now
+	};
+	const updated = writeWait(expired, wait.version) ?? getClarification(wait.id) ?? expired;
+	resolveTaskWait(updated, { expired: true });
+	cancelTaskRun(updated, "Approval expired before the task could continue.", now);
+	bumpSessionInputRevision(getSqliteDatabase(), wait.sessionKey);
+	return updated;
+}
+function resolveClarification(input) {
+	return runSqliteWriteTransaction((db) => {
+		const wait = getClarification(input.id);
+		if (!wait || readCurrentSessionId(db, wait.sessionKey) !== wait.sessionId) return {
+			ok: false,
+			code: "NOT_FOUND"
+		};
+		const now = input.now ?? Date.now();
+		if (wait.kind === "approval" && wait.expiresAt !== void 0 && wait.expiresAt <= now) return {
+			ok: false,
+			code: "EXPIRED",
+			clarification: expireApproval(wait, now)
+		};
+		if (db.prepare("SELECT id FROM session_inputs WHERE session_key = ? AND client_message_id = ?").get(wait.sessionKey, 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 {
+			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,
+				status: "cancelled",
+				resolution,
+				responseIdempotencyKey: input.idempotencyKey,
+				resolvedAt: now,
+				updatedAt: now
+			}, wait.version);
+			if (!cancelled) return {
+				ok: false,
+				code: "CONFLICT",
+				clarification: getClarification(wait.id)
+			};
+			resolveTaskWait(cancelled, { cancelled: true });
+			cancelTaskRun(cancelled, "Task cancelled while waiting for clarification.", now);
+			bumpSessionInputRevision(db, wait.sessionKey);
+			return {
+				ok: true,
+				clarification: cancelled,
+				idempotent: false,
+				queued: false
+			};
+		}
+		const answer = input.action === "agent_decide" ? "Use your best judgment and continue without additional user input." : trimmed;
+		const queued = writeWait({
+			...wait,
+			status: "queued",
+			answer,
+			resolution,
+			responseIdempotencyKey: input.idempotencyKey,
+			updatedAt: now
+		}, wait.version);
+		if (!queued) return {
+			ok: false,
+			code: "CONFLICT",
+			clarification: getClarification(wait.id)
+		};
+		const stale = now - wait.checkpoint.originalRequestAt >= STALE_CONTEXT_MS;
+		const content = [
+			"Resume the objective that was waiting for clarification.",
+			`Original objective: ${wait.checkpoint.objectiveSummary}`,
+			`Clarification question: ${wait.question}`,
+			`User response: ${answer}`,
+			stale ? "The request is over 24 hours old. Re-check mutable state before acting." : "",
+			"Do not repeat completed side effects. Continue from the stored transcript and current state."
+		].filter(Boolean).join("\n");
+		const origin = getSessionInputById(wait.sessionKey, wait.originInputId);
+		insertSessionInput({
+			id: randomUUID(),
+			sessionKey: wait.sessionKey,
+			expectedSessionId: wait.sessionId,
+			clientMessageId: input.idempotencyKey,
+			requestedDelivery: "next",
+			effectiveDelivery: "next",
+			status: "queued",
+			content,
+			kind: "clarification_resume",
+			payload: {
+				waitId: wait.id,
+				objectiveRevision: wait.objectiveRevision,
+				resolution
+			},
+			taskRunId: wait.taskRunId,
+			contextRefs: origin?.contextRefs,
+			contextSnapshots: origin?.contextSnapshots,
+			thinking: origin?.thinking,
+			origin: {
+				type: "system",
+				source: "internal"
+			}
+		});
+		return {
+			ok: true,
+			clarification: queued,
+			idempotent: false,
+			queued: true
+		};
+	});
+}
+function getClarificationResumeInput(sessionKey, runId) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const state = getSessionInputState(sessionKey);
+	if (state.activeRunId !== runId || !state.activeInputId) return void 0;
+	const input = getSessionInputById(sessionKey, state.activeInputId);
+	return input?.kind === "clarification_resume" ? input : void 0;
+}
+function consumeClarificationResume(input) {
+	if (input.kind !== "clarification_resume") return true;
+	return runSqliteWriteTransaction((db) => {
+		const wait = input.payload ? getClarification(input.payload.waitId) : void 0;
+		if (!wait || wait.status !== "queued" || wait.objectiveRevision !== input.payload?.objectiveRevision) return false;
+		if (readCurrentSessionId(db, input.sessionKey) !== wait.sessionId) return false;
+		if (wait.taskRunId) {
+			const runs = new TaskRunRepository();
+			const run = runs.get(wait.taskRunId);
+			if (!run || run.status !== "waiting") return false;
+			if (runs.listActiveWaits(run.taskId).filter((item) => item.taskRunId === run.id).some((item) => item.condition.clarificationId !== wait.id)) return false;
+			resolveTaskWait(wait, {
+				clarificationId: wait.id,
+				resolution: wait.resolution
+			});
+			runs.setStatus({
+				runId: run.id,
+				expectedVersion: run.version,
+				from: ["waiting"],
+				to: "running",
+				actor: { kind: "system" }
+			});
+		} else resolveTaskWait(wait, {
+			clarificationId: wait.id,
+			resolution: wait.resolution
+		});
+		if (!writeWait({
+			...wait,
+			status: "resolved",
+			resolvedAt: Date.now(),
+			updatedAt: Date.now()
+		}, wait.version)) return false;
+		bumpSessionInputRevision(db, wait.sessionKey);
+		return true;
+	});
+}
+function consumeClarificationApproval(sessionKey, approvalKey) {
+	return runSqliteWriteTransaction(() => {
+		const state = getSessionInputState(sessionKey);
+		if (!state.activeInputId) return void 0;
+		const input = getSessionInputById(sessionKey, state.activeInputId);
+		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";
+		writeWait({
+			...wait,
+			approvalConsumedAt: Date.now(),
+			updatedAt: Date.now()
+		}, wait.version);
+		return approved ? "approved" : "denied";
+	});
+}
+function supersedeActiveClarification(sessionKey, now = Date.now()) {
+	return runSqliteWriteTransaction((db) => {
+		const wait = getActiveClarification(sessionKey);
+		if (!wait) return void 0;
+		if (wait.status === "queued") {
+			const queued = db.prepare(`SELECT id FROM session_inputs
+         WHERE session_key = ? AND kind = 'clarification_resume'
+           AND status = 'queued' AND json_extract(payload_json, '$.waitId') = ?`).get(sessionKey, wait.id);
+			if (queued) db.prepare(`UPDATE session_inputs SET status = 'cancelled', version = version + 1, updated_at_ms = ?
+           WHERE id = ? AND status = 'queued'`).run(now, queued.id);
+		}
+		const updated = writeWait({
+			...wait,
+			status: "superseded",
+			resolution: "cancelled",
+			resolvedAt: now,
+			updatedAt: now
+		}, wait.version);
+		if (!updated) return void 0;
+		resolveTaskWait(updated, { superseded: true });
+		cancelTaskRun(updated, "Task superseded by a newer instruction.", now);
+		bumpSessionInputRevision(db, sessionKey);
+		return updated;
+	});
+}
+//#endregion
+export { consumeClarificationApproval, consumeClarificationResume, createClarificationWait, getActiveClarification, getClarification, getClarificationResumeInput, getClarificationSnapshot, isClarificationSuspended, resolveClarification, supersedeActiveClarification };

package/dist/src/storage/sqlite/index.d.ts

@@ -14,7 +14,8 @@ export { closeTemporalAssertions, createTemporalAssertion, linkContextObjects, l
 export { createCollaborationRule, getCollaborationRule, listCollaborationRules, setCollaborationRuleStatus, type CollaborationRule, } from './collaboration-rule-repository.js';
 export { createContextEvidence, type ContextEvidence } from './context-evidence-repository.js';
 export { getUserPerson, getUserPeopleIndexState, listUserPeople, mergeUserPeople, replaceUserPeopleIndex, summarizeUserPeople, updateUserPerson, } from './user-people-repository.js';
-export { cancelQueuedSessionInput, claimNextSessionInput, findSessionInput, finishSessionInputRun, getSessionInputState, getSessionInputById, insertSessionInput, listActiveSessionInputRuns, mutateQueuedSessionInput, recoverSessionInputState, setSessionInputStatus, type SessionInput, type SessionInputDelivery, type SessionInputState, type SessionInputStatus, } from './session-input-repository.js';
+export { cancelQueuedSessionInput, claimNextSessionInput, findSessionInput, finishSessionInputRun, getSessionInputState, getSessionInputById, insertSessionInput, listActiveSessionInputRuns, mutateQueuedSessionInput, recoverSessionInputState, setSessionInputStatus, type SessionInput, type SessionInputDelivery, type SessionInputPayload, type SessionInputState, type SessionInputStatus, } from './session-input-repository.js';
+export { consumeClarificationApproval, consumeClarificationResume, createClarificationWait, getActiveClarification, getClarification, getClarificationResumeInput, getClarificationSnapshot, isClarificationSuspended, resolveClarification, supersedeActiveClarification, type CreateClarificationInput, type ResolveClarificationInput, type ResolveClarificationResult, } from './clarification-wait-repository.js';
 export { replaceLatestSessionTurnAndQueueInput, validateLatestSessionTurnTarget, type ReplaceLatestSessionTurnInput, type ReplaceLatestSessionTurnResult, } from './session-turn-replace-repository.js';
 export { acknowledgeHomeAttention, isHomeAttentionAcknowledged, type HomeAttentionSubjectKind, } from './home-attention-repository.js';
 export { claimNextConnectorLearningJob, enqueueConnectorLearningJob, listConnectorLearningJobs, recoverStaleConnectorLearningJobs, setConnectorLearningPaused, updateConnectorLearningJob, type ConnectorLearningJob, type ConnectorLearningMode, type ConnectorLearningPhase, type ConnectorLearningStatus, } from './connector-learning-repository.js';

package/dist/src/storage/sqlite/index.js

@@ -16,6 +16,7 @@ import { createCollaborationRule, getCollaborationRule, listCollaborationRules,
 import { createContextEvidence } from "./context-evidence-repository.js";
 import { getUserPeopleIndexState, getUserPerson, listUserPeople, mergeUserPeople, replaceUserPeopleIndex, summarizeUserPeople, updateUserPerson } from "./user-people-repository.js";
 import { cancelQueuedSessionInput, claimNextSessionInput, findSessionInput, finishSessionInputRun, getSessionInputById, getSessionInputState, insertSessionInput, listActiveSessionInputRuns, mutateQueuedSessionInput, recoverSessionInputState, setSessionInputStatus } from "./session-input-repository.js";
+import { consumeClarificationApproval, consumeClarificationResume, createClarificationWait, getActiveClarification, getClarification, getClarificationResumeInput, getClarificationSnapshot, isClarificationSuspended, resolveClarification, supersedeActiveClarification } from "./clarification-wait-repository.js";
 import { buildDefaultSessionMetadata } from "./session-metadata.js";
 import { buildGlobalSessionStats, classifyStoredRow, estimateTokensFromMessages, extractFtsContent, metadataToSessionInsert, sessionConfigRowToConfig, sessionRowToMetadata, transcriptEntryRowToStoredRow } from "./row-mappers.js";
 import { replaceLatestSessionTurnAndQueueInput, validateLatestSessionTurnTarget } from "./session-turn-replace-repository.js";
@@ -38,4 +39,4 @@ import { appendConnectorExecutionAudit, claimConnectorWebhookDelivery, completeC
 import { getConnectorAccount, listConnectorAccounts, reconcileConnectorAccount, refreshConnectorAccountCurrent } from "./connector-account-repository.js";
 import { getConnectorSyncPolicy, getConnectorSyncPolicyForConnection, listConnectorSyncPolicies, upsertConnectorSyncPolicy } from "./connector-sync-policy-repository.js";
 import { getUserTrustPolicy, setUserTrustPolicy } from "./user-trust-repository.js";
-export { COMPOSER_INPUT_HISTORY_LIMIT, DatabaseSchemaMigrationGapError, DatabaseSchemaTooNewError, SCHEMA_META_SCHEMA_VERSION_KEY, XOPC_DB_BASELINE_SCHEMA_VERSION, XOPC_DB_FILENAME, XOPC_DB_SCHEMA_VERSION, acknowledgeHomeAttention, appendCompactionBoundaryIfUnchanged, appendComposerInputHistory, appendConnectorExecutionAudit, appendTranscriptEntry, applyPendingMigrations, authenticateDeviceAccessToken, bindEndpointPrincipal, buildDefaultSessionMetadata, buildGlobalSessionStats, buildRefreshProofMessage, buildRelationshipPrompt, cancelQueuedSessionInput, claimConnectorWebhookDelivery, claimContextExtractionRun, claimKnowledgeSourceItems, claimNextConnectorLearningJob, claimNextSessionInput, classifyStoredRow, clearComposerInputHistory, clearGatewayIdentityForTest, closeTemporalAssertions, closeXopcDatabase, completeConnectorWebhookDelivery, completeKnowledgeSourceItemSynthesis, consumeConnectorApproval, consumeDevicePairingToken, countKnowledgeSourceItems, createCollaborationRule, createConnectorApproval, createContextEvidence, createDevice, createDevicePairingSetup, createEndpointPrincipal, createObjectLinkRecord, createTemporalAssertion, decideConnectorApproval, deleteConnectorConnection, deleteConnectorInstallation, deleteEndpointSessionBinding, deleteKnowledgeSourceItems, deleteNoteAgentContextRecord, deleteNoteRecord, deleteObjectLinkRecord, deleteSessionConfig, deleteSessionRecord, discoverSqlMigrations, enqueueConnectorLearningJob, ensureSessionRecord, ensureXopcDatabaseSchema, estimateTokensFromMessages, extractFtsContent, findSessionInput, findSessionKeyBySessionId, finishContextExtractionRun, finishEndpointToolInvocationAudit, finishKnowledgeSyncRun, finishSessionInputRun, getActivityEventRecord, getCachedConnectorCatalogEntry, getCollaborationRule, getConnectorAccount, getConnectorApproval, getConnectorConnection, getConnectorInstallation, getConnectorSyncPolicy, getConnectorSyncPolicyForConnection, getContextExtractionRun, getCurrentSessionId, getDevice, getEndpointPrincipal, getEndpointSessionBinding, getGlobalSessionStats, getInteractionState, getKnowledgeConsumerWatermark, getKnowledgeSourceCursor, getKnowledgeSourceItem, getNoteAgentContextRecord, getNoteRecord, getOrCreateGatewayIdentity, getRelationshipSettings, getSessionConfig, getSessionInputById, getSessionInputState, getSessionMetadata, getSessionPersistedLevels, getSessionTaskPlan, getSqliteDatabase, getUserPeopleIndexState, getUserPerson, getUserTrustPolicy, getXopcDatabase, hasIndependentExtractionOutput, hasSessionConfig, incrementSessionStatsOnAppend, insertSessionInput, inspectSchemaMigrationStatus, isDevicePairingSetupActive, isHomeAttentionAcknowledged, isProactiveSupportAllowed, isXopcDatabaseOpen, issueDeviceTokenPair, linkContextObjects, listActiveSessionInputRuns, listActivityRecords, listCachedConnectorCatalogEntries, listCollaborationRules, listCompactionBoundaries, listComposerInputHistory, listConnectorAccounts, listConnectorActionMetadata, listConnectorApprovals, listConnectorConnections, listConnectorExecutionAudit, listConnectorInstallations, listConnectorLearningJobs, listConnectorSyncPolicies, listContextExtractionOutputs, listContextExtractionRuns, listContextObjectRelations, listDevices, listEndpointPrincipals, listEndpointToolInvocationAudits, listKnowledgeSourceChanges, listKnowledgeSourceItems, listKnowledgeSyncRuns, listNoteRecords, listObjectActivityRecords, listObjectLinkRecords, listProjectActivityRecords, listRegisteredMigrationTargets, listSessionMetadata, listSessionsByAgent, listTemporalAssertions, listUserPeople, loadCompactionSourceSnapshot, loadLlmMessagesForSession, loadTranscriptHistoryRowsForSession, loadTranscriptRows, loadTranscriptRowsForSession, mergeUserPeople, metadataToSessionInsert, mutateQueuedSessionInput, openXopcDatabase, paginateTranscriptMessages, patchSessionMetadata, pruneBoundedKnowledgeSourceItems, readSchemaVersion, readSchemaVersionForTest, reconcileConnectorAccount, recordActivityEvent, recoverSessionInputState, recoverStaleConnectorLearningJobs, refreshConnectorAccountCurrent, releaseConnectorWebhookDelivery, replaceConnectorCatalogEntries, replaceLatestSessionTurnAndQueueInput, replaceTranscriptRows, replaceUserPeopleIndex, requireXopcDatabase, resetSessionRecord, resetXopcDatabaseSingletonForTest, resolveMigrationsDir, resolveSessionAgentId, resolveXopcDatabasePath, restoreBeforeCompactionBoundary, revokeDevice, revokeEndpointPrincipal, rotateDeviceRefreshToken, runSqliteWriteTransaction, searchSessionTranscript, sessionConfigRowToConfig, sessionRowToMetadata, setCollaborationRuleStatus, setConnectorLearningPaused, setEndpointSessionBinding, setInteractionState, setKnowledgeConsumerWatermark, setKnowledgeSourceCursor, setKnowledgeSourceItemSynthesisStatus, setSessionConfig, setSessionInputStatus, setSessionTaskPlan, setUserTrustPolicy, signGatewayPayload, startEndpointToolInvocationAudit, startKnowledgeSyncRun, summarizeUserPeople, touchEndpointPrincipal, transcriptEntryRowToStoredRow, updateConnectorLearningJob, updateInteractionStateFromMessage, updateRelationshipSettings, updateSessionConfig, updateSessionStats, updateUserPerson, upsertConnectorActionMetadata, upsertConnectorCatalogEntry, upsertConnectorConnection, upsertConnectorInstallation, upsertConnectorSyncPolicy, upsertKnowledgeSourceItems, upsertNoteAgentContextRecord, upsertNoteRecord, validateLatestSessionTurnTarget };
+export { COMPOSER_INPUT_HISTORY_LIMIT, DatabaseSchemaMigrationGapError, DatabaseSchemaTooNewError, SCHEMA_META_SCHEMA_VERSION_KEY, XOPC_DB_BASELINE_SCHEMA_VERSION, XOPC_DB_FILENAME, XOPC_DB_SCHEMA_VERSION, acknowledgeHomeAttention, appendCompactionBoundaryIfUnchanged, appendComposerInputHistory, appendConnectorExecutionAudit, appendTranscriptEntry, applyPendingMigrations, authenticateDeviceAccessToken, bindEndpointPrincipal, buildDefaultSessionMetadata, buildGlobalSessionStats, buildRefreshProofMessage, buildRelationshipPrompt, cancelQueuedSessionInput, claimConnectorWebhookDelivery, claimContextExtractionRun, claimKnowledgeSourceItems, claimNextConnectorLearningJob, claimNextSessionInput, classifyStoredRow, clearComposerInputHistory, clearGatewayIdentityForTest, closeTemporalAssertions, closeXopcDatabase, completeConnectorWebhookDelivery, completeKnowledgeSourceItemSynthesis, consumeClarificationApproval, consumeClarificationResume, consumeConnectorApproval, consumeDevicePairingToken, countKnowledgeSourceItems, createClarificationWait, createCollaborationRule, createConnectorApproval, createContextEvidence, createDevice, createDevicePairingSetup, createEndpointPrincipal, createObjectLinkRecord, createTemporalAssertion, decideConnectorApproval, deleteConnectorConnection, deleteConnectorInstallation, deleteEndpointSessionBinding, deleteKnowledgeSourceItems, deleteNoteAgentContextRecord, deleteNoteRecord, deleteObjectLinkRecord, deleteSessionConfig, deleteSessionRecord, discoverSqlMigrations, enqueueConnectorLearningJob, ensureSessionRecord, ensureXopcDatabaseSchema, estimateTokensFromMessages, extractFtsContent, findSessionInput, findSessionKeyBySessionId, finishContextExtractionRun, finishEndpointToolInvocationAudit, finishKnowledgeSyncRun, finishSessionInputRun, getActiveClarification, getActivityEventRecord, getCachedConnectorCatalogEntry, getClarification, getClarificationResumeInput, getClarificationSnapshot, getCollaborationRule, getConnectorAccount, getConnectorApproval, getConnectorConnection, getConnectorInstallation, getConnectorSyncPolicy, getConnectorSyncPolicyForConnection, getContextExtractionRun, getCurrentSessionId, getDevice, getEndpointPrincipal, getEndpointSessionBinding, getGlobalSessionStats, getInteractionState, getKnowledgeConsumerWatermark, getKnowledgeSourceCursor, getKnowledgeSourceItem, getNoteAgentContextRecord, getNoteRecord, getOrCreateGatewayIdentity, getRelationshipSettings, getSessionConfig, getSessionInputById, getSessionInputState, getSessionMetadata, getSessionPersistedLevels, getSessionTaskPlan, getSqliteDatabase, getUserPeopleIndexState, getUserPerson, getUserTrustPolicy, getXopcDatabase, hasIndependentExtractionOutput, hasSessionConfig, incrementSessionStatsOnAppend, insertSessionInput, inspectSchemaMigrationStatus, isClarificationSuspended, isDevicePairingSetupActive, isHomeAttentionAcknowledged, isProactiveSupportAllowed, isXopcDatabaseOpen, issueDeviceTokenPair, linkContextObjects, listActiveSessionInputRuns, listActivityRecords, listCachedConnectorCatalogEntries, listCollaborationRules, listCompactionBoundaries, listComposerInputHistory, listConnectorAccounts, listConnectorActionMetadata, listConnectorApprovals, listConnectorConnections, listConnectorExecutionAudit, listConnectorInstallations, listConnectorLearningJobs, listConnectorSyncPolicies, listContextExtractionOutputs, listContextExtractionRuns, listContextObjectRelations, listDevices, listEndpointPrincipals, listEndpointToolInvocationAudits, listKnowledgeSourceChanges, listKnowledgeSourceItems, listKnowledgeSyncRuns, listNoteRecords, listObjectActivityRecords, listObjectLinkRecords, listProjectActivityRecords, listRegisteredMigrationTargets, listSessionMetadata, listSessionsByAgent, listTemporalAssertions, listUserPeople, loadCompactionSourceSnapshot, loadLlmMessagesForSession, loadTranscriptHistoryRowsForSession, loadTranscriptRows, loadTranscriptRowsForSession, mergeUserPeople, metadataToSessionInsert, mutateQueuedSessionInput, openXopcDatabase, paginateTranscriptMessages, patchSessionMetadata, pruneBoundedKnowledgeSourceItems, readSchemaVersion, readSchemaVersionForTest, reconcileConnectorAccount, recordActivityEvent, recoverSessionInputState, recoverStaleConnectorLearningJobs, refreshConnectorAccountCurrent, releaseConnectorWebhookDelivery, replaceConnectorCatalogEntries, replaceLatestSessionTurnAndQueueInput, replaceTranscriptRows, replaceUserPeopleIndex, requireXopcDatabase, resetSessionRecord, resetXopcDatabaseSingletonForTest, resolveClarification, resolveMigrationsDir, resolveSessionAgentId, resolveXopcDatabasePath, restoreBeforeCompactionBoundary, revokeDevice, revokeEndpointPrincipal, rotateDeviceRefreshToken, runSqliteWriteTransaction, searchSessionTranscript, sessionConfigRowToConfig, sessionRowToMetadata, setCollaborationRuleStatus, setConnectorLearningPaused, setEndpointSessionBinding, setInteractionState, setKnowledgeConsumerWatermark, setKnowledgeSourceCursor, setKnowledgeSourceItemSynthesisStatus, setSessionConfig, setSessionInputStatus, setSessionTaskPlan, setUserTrustPolicy, signGatewayPayload, startEndpointToolInvocationAudit, startKnowledgeSyncRun, summarizeUserPeople, supersedeActiveClarification, touchEndpointPrincipal, transcriptEntryRowToStoredRow, updateConnectorLearningJob, updateInteractionStateFromMessage, updateRelationshipSettings, updateSessionConfig, updateSessionStats, updateUserPerson, upsertConnectorActionMetadata, upsertConnectorCatalogEntry, upsertConnectorConnection, upsertConnectorInstallation, upsertConnectorSyncPolicy, upsertKnowledgeSourceItems, upsertNoteAgentContextRecord, upsertNoteRecord, validateLatestSessionTurnTarget };