@xopcai/xopc 0.0.252 → 0.0.253

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

package/dist/src/storage/sqlite/migrations/154_session_clarification_waits.sql

@@ -0,0 +1,60 @@
+CREATE TABLE session_clarification_waits (
+  id TEXT PRIMARY KEY,
+  principal_id TEXT NOT NULL,
+  session_key TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  origin_run_id TEXT NOT NULL,
+  origin_tool_call_id TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN (
+    'open', 'queued', 'resolved', 'expired', 'cancelled', 'superseded'
+  )),
+  version INTEGER NOT NULL,
+  data_json TEXT NOT NULL,
+  UNIQUE(session_id, origin_run_id, origin_tool_call_id)
+);
+
+CREATE UNIQUE INDEX idx_clarification_wait_active
+  ON session_clarification_waits(principal_id, session_id)
+  WHERE status IN ('open', 'queued');
+
+CREATE INDEX idx_clarification_wait_session
+  ON session_clarification_waits(session_key, session_id, status);
+
+CREATE TABLE session_inputs_v154 (
+  id TEXT PRIMARY KEY,
+  session_key TEXT NOT NULL,
+  client_message_id TEXT NOT NULL,
+  requested_delivery TEXT NOT NULL CHECK (requested_delivery IN ('next', 'steer')),
+  effective_delivery TEXT NOT NULL CHECK (effective_delivery IN ('next', 'steer')),
+  status TEXT NOT NULL CHECK (status IN (
+    'queued', 'running', 'injecting',
+    'completed', 'cancelled', 'failed', 'interrupted', 'suspended'
+  )),
+  content TEXT NOT NULL,
+  attachments_json TEXT,
+  thinking TEXT,
+  origin_json TEXT NOT NULL,
+  position INTEGER NOT NULL,
+  target_run_id TEXT,
+  run_id TEXT,
+  version INTEGER NOT NULL DEFAULT 1,
+  error TEXT,
+  created_at_ms INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL,
+  expected_session_id TEXT,
+  context_refs_json TEXT,
+  context_snapshots_json TEXT,
+  kind TEXT NOT NULL DEFAULT 'message' CHECK (
+    kind IN ('message', 'connection_resume', 'clarification_resume')
+  ),
+  payload_json TEXT,
+  task_run_id TEXT,
+  UNIQUE(session_key, client_message_id)
+);
+
+INSERT INTO session_inputs_v154
+SELECT * FROM session_inputs;
+DROP TABLE session_inputs;
+ALTER TABLE session_inputs_v154 RENAME TO session_inputs;
+CREATE INDEX idx_session_inputs_pending
+  ON session_inputs(session_key,status,position,created_at_ms);

package/dist/src/storage/sqlite/migrations/runner.d.ts

@@ -3,7 +3,7 @@ import type { ApplyMigrationsOptions } from './types.js';
 /** Baseline schema version applied from schema.sql on first open. */
 export declare const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 /** Latest schema version this release supports (increment when adding migrations). */
-export declare const XOPC_DB_SCHEMA_VERSION = 153;
+export declare const XOPC_DB_SCHEMA_VERSION = 154;
 export declare function resolveMigrationsDir(override?: string): string;
 /**
  * Apply sequential SQL migrations from (currentVersion + 1) through targetVersion.

package/dist/src/storage/sqlite/migrations/runner.js

@@ -12,7 +12,7 @@ const log = createLogger("Sqlite:Migrations");
 /** Baseline schema version applied from schema.sql on first open. */
 const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 /** Latest schema version this release supports (increment when adding migrations). */
-const XOPC_DB_SCHEMA_VERSION = 153;
+const XOPC_DB_SCHEMA_VERSION = 154;
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 function backupBeforeTaskCutover(db, databasePath) {
 	db.exec("PRAGMA wal_checkpoint(FULL)");
@@ -57,7 +57,7 @@ function applySingleMigration(db, migration) {
 * Each step runs in its own transaction and updates schema_meta on success.
 */
 function applyPendingMigrations(db, options = {}) {
-	const targetVersion = options.targetVersion ?? 153;
+	const targetVersion = options.targetVersion ?? 154;
 	let currentVersion = readSchemaVersion(db);
 	if (currentVersion > targetVersion) throw new DatabaseSchemaTooNewError(currentVersion, targetVersion);
 	if (currentVersion >= targetVersion) return currentVersion;
@@ -94,7 +94,7 @@ function applyPendingMigrations(db, options = {}) {
 }
 /** Inspect schema version without mutating the database. */
 function inspectSchemaMigrationStatus(db, options = {}) {
-	const appVersion = options.targetVersion ?? 153;
+	const appVersion = options.targetVersion ?? 154;
 	const dbVersion = readSchemaVersion(db);
 	if (dbVersion > appVersion) return {
 		dbVersion,

package/dist/src/storage/sqlite/migrations/runner.ts

@@ -19,7 +19,7 @@ const log = createLogger('Sqlite:Migrations');
 export const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 
 /** Latest schema version this release supports (increment when adding migrations). */
-export const XOPC_DB_SCHEMA_VERSION = 153;
+export const XOPC_DB_SCHEMA_VERSION = 154;
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 

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

@@ -32,7 +32,7 @@ function ensureXopcDatabaseSchema(db, options = {}) {
 		currentVersion = 11;
 	}
 	applyPendingMigrations(db, {
-		targetVersion: 153,
+		targetVersion: 154,
 		databasePath: options.databasePath
 	});
 }

package/dist/src/storage/sqlite/session-input-repository.d.ts

@@ -3,6 +3,15 @@ import { type TurnOrigin } from '@xopcai/endpoint-tools-protocol';
 import type { AgentSourceContext, SourceContextRefSummary } from '../../agent/source-context/types.js';
 export type SessionInputDelivery = 'next' | 'steer';
 export type SessionInputStatus = 'queued' | 'running' | 'injecting' | 'completed' | 'cancelled' | 'failed' | 'interrupted' | 'suspended';
+export type SessionInputPayload = {
+    waitId: string;
+    objectiveRevision: number;
+    resolution: 'continued' | 'skipped';
+} | {
+    waitId: string;
+    objectiveRevision: number;
+    resolution: 'answered' | 'agent_decide' | 'cancelled';
+};
 export type SessionInput = {
     id: string;
     sessionKey: string;
@@ -13,12 +22,8 @@ export type SessionInput = {
     status: SessionInputStatus;
     content: string;
     taskRunId?: string;
-    kind: 'message' | 'connection_resume';
-    payload?: {
-        waitId: string;
-        objectiveRevision: number;
-        resolution: 'continued' | 'skipped';
-    };
+    kind: 'message' | 'connection_resume' | 'clarification_resume';
+    payload?: SessionInputPayload;
     attachments?: unknown[];
     contextRefs?: SourceContextRefSummary[];
     contextSnapshots?: AgentSourceContext[];

package/dist/src/voice/realtime/agentEngine.js

@@ -167,7 +167,7 @@ function createAgentVoiceEngine(options) {
 			if (response.abortController.signal.aborted || closed) return;
 			for await (const event of options.runtime.runAgent(text, claim.request.sessionKey, response.abortController.signal)) {
 				if (activeResponse !== response || response.abortController.signal.aborted) return;
-				if (event.type === "assistant_delta" || event.type === "tool_end") response.awaitingClarification = false;
+				if (event.type === "assistant_delta" || event.type === "tool_end" && event.payload?.toolName !== "clarify") response.awaitingClarification = false;
 				if (event.type === "assistant_delta" && typeof event.payload?.delta === "string") {
 					if (response.text.length + event.payload.delta.length > 32e3) throw new Error("Voice response text limit reached");
 					if (!response.firstTextSeen) {
@@ -196,8 +196,13 @@ function createAgentVoiceEngine(options) {
 					send("response.clarification", {
 						responseId: response.id,
 						requestId: event.payload.requestId.slice(0, 160),
+						kind: event.payload.kind === "approval" ? "approval" : "input",
 						question: event.payload.question.slice(0, 8e3),
-						...Array.isArray(event.payload.choices) ? { choices: event.payload.choices.filter((choice) => typeof choice === "string").slice(0, 20).map((choice) => choice.slice(0, 1e3)) } : {}
+						...Array.isArray(event.payload.choices) ? { choices: event.payload.choices.filter((choice) => typeof choice === "string").slice(0, 20).map((choice) => choice.slice(0, 1e3)) } : {},
+						...typeof event.payload.suggestedAnswer === "string" ? { suggestedAnswer: event.payload.suggestedAnswer.slice(0, 1e3) } : {},
+						version: typeof event.payload.version === "number" ? event.payload.version : 1,
+						createdAt: typeof event.payload.createdAt === "number" ? event.payload.createdAt : Date.now(),
+						...typeof event.payload.expiresAt === "number" ? { expiresAt: event.payload.expiresAt } : {}
 					});
 				}
 				if (event.type === "error") throw new Error(typeof event.payload?.message === "string" ? event.payload.message : "Agent response failed");

package/dist/src/voice/realtime/runtime.types.d.ts

@@ -46,8 +46,13 @@ interface VoiceAgentEvent {
         toolCallId?: unknown;
         toolName?: unknown;
         requestId?: unknown;
+        kind?: unknown;
         question?: unknown;
         choices?: unknown;
+        suggestedAnswer?: unknown;
+        version?: unknown;
+        createdAt?: unknown;
+        expiresAt?: unknown;
     };
 }
 export interface VoiceRealtimeRuntimeOptions {