@xopcai/xopc 0.0.199 → 0.0.200

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 = 119;
+export const XOPC_DB_SCHEMA_VERSION = 120;
 
 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: 119,
+		targetVersion: 120,
 		databasePath: options.databasePath
 	});
 }

package/dist/src/tasks/execution-context.js

@@ -1,3 +1,6 @@
+import { isXopcDatabaseOpen } from "../storage/sqlite/connection.js";
+import "../storage/sqlite/index.js";
+import { TaskConversationRepository } from "./task-conversation-repository.js";
 //#region src/tasks/execution-context.ts
 const ORIGINS = new Set([
 	"chat",
@@ -17,10 +20,10 @@ const TRIGGERS = new Set([
 function optionalString(value) {
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
-function metadataOrigin(metadata) {
+function metadataOrigin(metadata, taskId) {
 	const explicit = optionalString(metadata.customData?.origin);
 	if (explicit && ORIGINS.has(explicit)) return explicit;
-	if (optionalString(metadata.customData?.taskId)) return "task";
+	if (taskId) return "task";
 	if (metadata.sessionType === "workflow-run" || metadata.sessionType === "workflow-subagent") return "workflow";
 	if (metadata.sessionType === "cron") return "automation";
 	if (metadata.sessionType === "heartbeat") return "proactive";
@@ -35,14 +38,15 @@ function metadataTrigger(metadata) {
 	return "user";
 }
 function resolveExecutionContext(input) {
+	const taskId = isXopcDatabaseOpen() ? new TaskConversationRepository().resolveActiveExecutionSession(input.sessionKey)?.taskId : void 0;
 	return {
 		runId: input.runId,
 		sessionKey: input.sessionKey,
 		channel: input.channel,
 		agentId: input.agentId,
 		projectId: input.metadata.projectId,
-		taskId: optionalString(input.metadata.customData?.taskId),
-		origin: metadataOrigin(input.metadata),
+		taskId,
+		origin: metadataOrigin(input.metadata, taskId),
 		triggerKind: metadataTrigger(input.metadata),
 		parentRunId: optionalString(input.metadata.customData?.parentRunId),
 		contextTraceId: optionalString(input.metadata.customData?.contextTraceId),

package/dist/src/tasks/index.d.ts

@@ -13,6 +13,8 @@ export * from './task-value-metrics-service.js';
 export * from './task-application-service.js';
 export * from './task-change-events.js';
 export * from './task-context-repository.js';
+export * from './task-conversation-repository.js';
+export * from './task-handoff-service.js';
 export * from './task-dependency-service.js';
 export * from './task-read-model-projector.js';
 export * from './task-outbox-dispatcher.js';

package/dist/src/tasks/index.js

@@ -1,4 +1,5 @@
 import { TaskRepository } from "./task-repository.js";
+import { TaskConversationConflictError, TaskConversationRepository } from "./task-conversation-repository.js";
 import { TaskRunRepository } from "./task-run-repository.js";
 import { TaskReadModelProjector } from "./task-read-model-projector.js";
 import { resolveExecutionContext } from "./execution-context.js";
@@ -16,7 +17,8 @@ import { TaskRunCoordinator } from "./task-run-coordinator.js";
 import { ProjectMonitoringService, decideProactiveDisposition, isInQuietHours, nextQuietHoursEnd, proactiveDispositionReason } from "./project-monitoring-service.js";
 import { ProjectOperatingViewService, summarizeProjectOperatingView } from "./project-operating-view-service.js";
 import { TaskValueMetricsService } from "./task-value-metrics-service.js";
+import { TaskHandoffService } from "./task-handoff-service.js";
 import { TaskOutboxDispatcher } from "./task-outbox-dispatcher.js";
 import { TaskRunDispatcher } from "./task-run-dispatcher.js";
 import { TaskSignalService } from "./task-signal-service.js";
-export { AttentionGovernor, HomeQueryService, ModelTaskContractPlanner, ProjectMonitoringService, ProjectOperatingViewService, TaskApplicationService, TaskContextRepository, TaskDependencyError, TaskDependencyService, TaskOutboxDispatcher, TaskReadModelProjector, TaskRepository, TaskRunCoordinator, TaskRunDispatcher, TaskRunRepository, TaskSignalService, TaskValueMetricsService, TaskWorkflowCoordinator, assembleTaskContext, buildHomeBriefing, buildHomeFocusItems, buildTaskExecutionDirective, decideProactiveDisposition, decisionFromTask, defineTaskContract, enqueueTaskChanged, enqueueTaskChangedEvent, getTaskContextManifest, getTaskExecutionBrief, isInQuietHours, nextQuietHoursEnd, parseTaskContractResponse, proactiveDispositionReason, resolveExecutionContext, summarizeProjectOperatingView };
+export { AttentionGovernor, HomeQueryService, ModelTaskContractPlanner, ProjectMonitoringService, ProjectOperatingViewService, TaskApplicationService, TaskContextRepository, TaskConversationConflictError, TaskConversationRepository, TaskDependencyError, TaskDependencyService, TaskHandoffService, TaskOutboxDispatcher, TaskReadModelProjector, TaskRepository, TaskRunCoordinator, TaskRunDispatcher, TaskRunRepository, TaskSignalService, TaskValueMetricsService, TaskWorkflowCoordinator, assembleTaskContext, buildHomeBriefing, buildHomeFocusItems, buildTaskExecutionDirective, decideProactiveDisposition, decisionFromTask, defineTaskContract, enqueueTaskChanged, enqueueTaskChangedEvent, getTaskContextManifest, getTaskExecutionBrief, isInQuietHours, nextQuietHoursEnd, parseTaskContractResponse, proactiveDispositionReason, resolveExecutionContext, summarizeProjectOperatingView };

package/dist/src/tasks/task-application-service.js

@@ -43,7 +43,6 @@ function commandChangedFields(command) {
 		];
 		case "add_wait":
 		case "resolve_wait": return ["runs", "attention"];
-		case "delegate": return ["delegateAgentId"];
 		case "revise_contract": return ["contract"];
 	}
 }
@@ -81,6 +80,10 @@ var TaskApplicationService = class {
 				...input.contract,
 				createdBy: actor
 			});
+			db.prepare(`INSERT INTO task_conversation_state (
+          task_id, active_session_key, current_executor_agent_id,
+          assignment_epoch, status, updated_at
+        ) VALUES (?, NULL, ?, 0, 'idle', ?)`).run(task.id, task.delegateAgentId ?? task.ownerId ?? null, task.createdAt);
 			let current = task;
 			if (input.dependencies.length > 0) current = this.#dependencies.replace({
 				taskId: task.id,
@@ -128,7 +131,12 @@ var TaskApplicationService = class {
 				ok: true,
 				model: this.#projector.project(current)
 			};
-			const started = this.start(current.id, current.version, input.activation.executor, {
+			const executor = input.activation.executor ?? (current.delegateAgentId ? {
+				kind: "agent",
+				agentId: current.delegateAgentId
+			} : void 0);
+			if (!executor) throw new Error("Task start executor was not resolved");
+			const started = this.start(current.id, current.version, executor, {
 				idempotencyKey: `${input.idempotencyKey}:start`,
 				scheduleAt: input.activation.scheduleAt,
 				actor,
@@ -248,21 +256,6 @@ var TaskApplicationService = class {
 					}
 					break;
 				}
-				case "delegate": {
-					const updated = this.#tasks.update(task.id, {
-						expectedVersion: task.version,
-						delegateAgentId: input.command.agentId ?? null
-					});
-					result = updated ? {
-						ok: true,
-						model: this.#projector.project(updated)
-					} : {
-						ok: false,
-						reason: "conflict",
-						model: this.#projector.get(task.id)
-					};
-					break;
-				}
 				case "revise_contract": {
 					const updated = this.#tasks.reviseContract({
 						taskId: task.id,

package/dist/src/tasks/task-context-assembler.js

@@ -1,7 +1,7 @@
 import { isXopcDatabaseOpen } from "../storage/sqlite/connection.js";
-import { getSessionMetadata } from "../storage/sqlite/session-repository.js";
 import "../storage/sqlite/index.js";
 import { TaskRepository } from "./task-repository.js";
+import { TaskConversationRepository } from "./task-conversation-repository.js";
 import { TaskRunRepository } from "./task-run-repository.js";
 import { TaskContextRepository } from "./task-context-repository.js";
 //#region src/tasks/task-context-assembler.ts
@@ -12,8 +12,7 @@ const STANDARD = {
 	reason: "No active task requires expanded context."
 };
 function taskIdForSession(sessionKey) {
-	const value = getSessionMetadata(sessionKey)?.customData?.taskId;
-	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+	return new TaskConversationRepository().resolveActiveExecutionSession(sessionKey)?.taskId;
 }
 function getTaskExecutionBrief(taskId) {
 	if (!isXopcDatabaseOpen()) return void 0;
@@ -87,6 +86,8 @@ function assembleTaskContext(sessionKey, userQuery) {
 		allocation: STANDARD
 	};
 	const { task, latestReceipt, remainingCriteria, allocation, manifest } = brief;
+	const handoff = new TaskConversationRepository().getLatestHandoff(taskId);
+	const handoffPayload = handoff?.toSessionKey === sessionKey ? JSON.stringify(handoff.payload).slice(0, 12e3) : "";
 	const contract = task.contract;
 	return {
 		taskId,
@@ -97,7 +98,8 @@ function assembleTaskContext(sessionKey, userQuery) {
 			remainingCriteria.length ? `Remaining acceptance criteria: ${remainingCriteria.join("; ")}` : "",
 			contract.constraints.length ? `Constraints: ${contract.constraints.join("; ")}` : "",
 			contract.risks.length ? `Risks: ${contract.risks.join("; ")}` : "",
-			latestReceipt?.summary ? `Latest run: ${latestReceipt.summary}` : ""
+			latestReceipt?.summary ? `Latest run: ${latestReceipt.summary}` : "",
+			handoffPayload ? `Handoff snapshot: ${handoffPayload}` : ""
 		].filter(Boolean).join("\n"),
 		allocation,
 		manifest
@@ -108,6 +110,8 @@ function buildTaskExecutionDirective(sessionKey) {
 	const brief = taskId ? getTaskExecutionBrief(taskId) : void 0;
 	if (!brief) return "";
 	const { task, remainingCriteria } = brief;
+	const handoff = new TaskConversationRepository().getLatestHandoff(task.id);
+	const handoffPayload = handoff?.toSessionKey === sessionKey ? JSON.stringify(handoff.payload).slice(0, 12e3) : "";
 	const contract = task.contract;
 	return [
 		"<xopc_task_execution>",
@@ -117,6 +121,7 @@ function buildTaskExecutionDirective(sessionKey) {
 		`Remaining acceptance criteria: ${remainingCriteria.join("; ")}`,
 		contract.constraints.length ? `Constraints: ${contract.constraints.join("; ")}` : "",
 		contract.approvalRequired.length ? `Authority required: ${contract.approvalRequired.join("; ")}` : "",
+		handoffPayload ? `Handoff snapshot: ${handoffPayload}` : "",
 		"Take safe in-scope steps and produce inspectable evidence. Do not claim completion without verification.",
 		"</xopc_task_execution>"
 	].filter(Boolean).join("\n");

package/dist/src/tasks/task-context-repository.d.ts

@@ -42,11 +42,5 @@ export declare class TaskContextRepository {
     }): TaskAuthorityGrant;
     listActiveGrants(taskId: string, now?: number): TaskAuthorityGrant[];
     revoke(grantId: string, now?: number): boolean;
-    linkSession(input: {
-        taskId: string;
-        sessionKey: string;
-        role: 'primary' | 'discussion' | 'execution';
-        now?: number;
-    }): void;
     private requireGrant;
 }

package/dist/src/tasks/task-context-repository.js

@@ -82,10 +82,6 @@ var TaskContextRepository = class {
 	revoke(grantId, now = Date.now()) {
 		return getSqliteDatabase().prepare(`UPDATE task_authority_grants SET revoked_at = ?
        WHERE grant_id = ? AND revoked_at IS NULL`).run(now, grantId).changes > 0;
-	}
-	linkSession(input) {
-		getSqliteDatabase().prepare(`INSERT OR IGNORE INTO task_sessions (task_session_id, task_id, session_key, role, created_at)
-       VALUES (?, ?, ?, ?, ?)`).run(randomUUID(), input.taskId, input.sessionKey, input.role, input.now ?? Date.now());
 	}
 	requireGrant(id) {
 		const row = getSqliteDatabase().prepare("SELECT * FROM task_authority_grants WHERE grant_id = ?").get(id);

package/dist/src/tasks/task-conversation-repository.d.ts

@@ -0,0 +1,71 @@
+export type TaskConversationStatus = 'idle' | 'active';
+export type TaskSessionRole = 'primary' | 'discussion' | 'execution';
+export type TaskSessionStatus = 'active' | 'completed' | 'superseded' | 'failed';
+export interface TaskConversationState {
+    taskId: string;
+    activeSessionKey?: string;
+    currentExecutorAgentId?: string;
+    assignmentEpoch: number;
+    status: TaskConversationStatus;
+    updatedAt: number;
+}
+export interface TaskSessionLink {
+    id: string;
+    taskId: string;
+    sessionKey: string;
+    role: TaskSessionRole;
+    agentId?: string;
+    runId?: string;
+    assignmentEpoch: number;
+    status: TaskSessionStatus;
+    startedAt: number;
+    endedAt?: number;
+    createdAt: number;
+}
+export interface TaskHandoffSnapshot {
+    id: string;
+    taskId: string;
+    fromSessionKey?: string;
+    toSessionKey: string;
+    fromAgentId?: string;
+    toAgentId: string;
+    assignmentEpoch: number;
+    payload: Record<string, unknown>;
+    createdAt: number;
+}
+export declare class TaskConversationConflictError extends Error {
+}
+export declare class TaskConversationRepository {
+    findHandoffByIdempotencyKey(input: {
+        taskId: string;
+        expectedTaskVersion: number;
+        toAgentId: string;
+        idempotencyKey: string;
+    }): TaskHandoffSnapshot | undefined;
+    getState(taskId: string): TaskConversationState | undefined;
+    requireState(taskId: string): TaskConversationState;
+    listSessions(taskId: string): TaskSessionLink[];
+    getActiveSession(taskId: string): TaskSessionLink | undefined;
+    resolveActiveExecutionSession(sessionKey: string): TaskSessionLink | undefined;
+    activateExecutionSession(input: {
+        taskId: string;
+        sessionKey: string;
+        agentId: string;
+        runId?: string;
+        now?: number;
+    }): TaskConversationState;
+    completeHandoff(input: {
+        taskId: string;
+        expectedTaskVersion: number;
+        toSessionKey: string;
+        toAgentId: string;
+        idempotencyKey: string;
+        payload: Record<string, unknown>;
+        now?: number;
+    }): {
+        state: TaskConversationState;
+        snapshot: TaskHandoffSnapshot;
+        taskVersion: number;
+    };
+    getLatestHandoff(taskId: string): TaskHandoffSnapshot | undefined;
+}

package/dist/src/tasks/task-conversation-repository.js

@@ -0,0 +1,194 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/tasks/task-conversation-repository.ts
+var TaskConversationConflictError = class extends Error {};
+function stateFromRow(row) {
+	return {
+		taskId: row.task_id,
+		...row.active_session_key ? { activeSessionKey: row.active_session_key } : {},
+		...row.current_executor_agent_id ? { currentExecutorAgentId: row.current_executor_agent_id } : {},
+		assignmentEpoch: row.assignment_epoch,
+		status: row.status,
+		updatedAt: row.updated_at
+	};
+}
+function linkFromRow(row) {
+	if (!row.session_key) return void 0;
+	return {
+		id: row.task_session_id,
+		taskId: row.task_id,
+		sessionKey: row.session_key,
+		role: row.role,
+		...row.agent_id ? { agentId: row.agent_id } : {},
+		...row.run_id ? { runId: row.run_id } : {},
+		assignmentEpoch: row.assignment_epoch,
+		status: row.status,
+		startedAt: row.started_at ?? row.created_at,
+		...row.ended_at === null ? {} : { endedAt: row.ended_at },
+		createdAt: row.created_at
+	};
+}
+function snapshotFromRow(row) {
+	return {
+		id: row.snapshot_id,
+		taskId: row.task_id,
+		...row.from_session_key ? { fromSessionKey: row.from_session_key } : {},
+		toSessionKey: row.to_session_key,
+		...row.from_agent_id ? { fromAgentId: row.from_agent_id } : {},
+		toAgentId: row.to_agent_id,
+		assignmentEpoch: row.assignment_epoch,
+		payload: JSON.parse(row.payload_json),
+		createdAt: row.created_at
+	};
+}
+function handoffRequestHash(input) {
+	return createHash("sha256").update(JSON.stringify(input)).digest("hex");
+}
+var TaskConversationRepository = class {
+	findHandoffByIdempotencyKey(input) {
+		const row = getSqliteDatabase().prepare(`SELECT request_hash, result_json FROM command_deduplication
+       WHERE idempotency_key = ?`).get(input.idempotencyKey);
+		if (!row) return void 0;
+		const requestHash = handoffRequestHash(input);
+		if (row.request_hash !== requestHash) throw new TaskConversationConflictError("Idempotency key was reused with different input");
+		const result = JSON.parse(row.result_json);
+		const snapshot = getSqliteDatabase().prepare("SELECT * FROM task_handoff_snapshots WHERE snapshot_id = ?").get(result.snapshotId);
+		if (!snapshot || snapshot.task_id !== input.taskId) throw new Error(`Task handoff snapshot not found: ${result.snapshotId}`);
+		return snapshotFromRow(snapshot);
+	}
+	getState(taskId) {
+		const row = getSqliteDatabase().prepare("SELECT * FROM task_conversation_state WHERE task_id = ?").get(taskId);
+		return row ? stateFromRow(row) : void 0;
+	}
+	requireState(taskId) {
+		const state = this.getState(taskId);
+		if (!state) throw new Error(`Task conversation state not found: ${taskId}`);
+		return state;
+	}
+	listSessions(taskId) {
+		return getSqliteDatabase().prepare(`SELECT * FROM task_sessions WHERE task_id = ? AND session_key IS NOT NULL
+       ORDER BY assignment_epoch DESC, created_at DESC, task_session_id DESC`).all(taskId).flatMap((row) => {
+			const link = linkFromRow(row);
+			return link ? [link] : [];
+		});
+	}
+	getActiveSession(taskId) {
+		const row = getSqliteDatabase().prepare(`SELECT * FROM task_sessions
+       WHERE task_id = ? AND role = 'execution' AND status = 'active'
+       LIMIT 1`).get(taskId);
+		return row ? linkFromRow(row) : void 0;
+	}
+	resolveActiveExecutionSession(sessionKey) {
+		const row = getSqliteDatabase().prepare(`SELECT * FROM task_sessions
+       WHERE session_key = ? AND role = 'execution' AND status = 'active'
+       LIMIT 1`).get(sessionKey);
+		return row ? linkFromRow(row) : void 0;
+	}
+	activateExecutionSession(input) {
+		const now = input.now ?? Date.now();
+		return runSqliteWriteTransaction((db) => {
+			const existing = db.prepare("SELECT * FROM task_conversation_state WHERE task_id = ?").get(input.taskId);
+			const current = db.prepare(`SELECT * FROM task_sessions
+         WHERE task_id = ? AND role = 'execution' AND status = 'active'`).get(input.taskId);
+			const sameSession = current?.session_key === input.sessionKey;
+			const assignmentEpoch = sameSession ? current.assignment_epoch : (existing?.assignment_epoch ?? 0) + 1;
+			if (!sameSession) db.prepare(`UPDATE task_sessions SET status = 'superseded', ended_at = ?
+           WHERE task_id = ? AND role = 'execution' AND status = 'active'`).run(now, input.taskId);
+			db.prepare(`INSERT INTO task_sessions (
+          task_session_id, task_id, session_key, role, created_at,
+          agent_id, run_id, assignment_epoch, status, started_at, ended_at
+        ) VALUES (?, ?, ?, 'execution', ?, ?, ?, ?, 'active', ?, NULL)
+        ON CONFLICT(task_id, session_key, role) WHERE session_key IS NOT NULL DO UPDATE SET
+          agent_id = excluded.agent_id,
+          run_id = COALESCE(excluded.run_id, task_sessions.run_id),
+          assignment_epoch = excluded.assignment_epoch,
+          status = 'active',
+          started_at = excluded.started_at,
+          ended_at = NULL`).run(randomUUID(), input.taskId, input.sessionKey, now, input.agentId, input.runId ?? null, assignmentEpoch, sameSession ? current.started_at ?? now : now);
+			db.prepare(`INSERT INTO task_conversation_state (
+          task_id, active_session_key, current_executor_agent_id,
+          assignment_epoch, status, updated_at
+        ) VALUES (?, ?, ?, ?, 'active', ?)
+        ON CONFLICT(task_id) DO UPDATE SET
+          active_session_key = excluded.active_session_key,
+          current_executor_agent_id = excluded.current_executor_agent_id,
+          assignment_epoch = excluded.assignment_epoch,
+          status = 'active',
+          updated_at = excluded.updated_at`).run(input.taskId, input.sessionKey, input.agentId, assignmentEpoch, now);
+			return stateFromRow(db.prepare("SELECT * FROM task_conversation_state WHERE task_id = ?").get(input.taskId));
+		});
+	}
+	completeHandoff(input) {
+		const now = input.now ?? Date.now();
+		return runSqliteWriteTransaction((db) => {
+			const requestHash = handoffRequestHash({
+				taskId: input.taskId,
+				expectedTaskVersion: input.expectedTaskVersion,
+				toAgentId: input.toAgentId
+			});
+			const duplicate = db.prepare(`SELECT request_hash, result_json FROM command_deduplication
+         WHERE idempotency_key = ?`).get(input.idempotencyKey);
+			if (duplicate) {
+				if (duplicate.request_hash !== requestHash) throw new TaskConversationConflictError("Idempotency key was reused with different input");
+				const result = JSON.parse(duplicate.result_json);
+				const snapshotRow = db.prepare("SELECT * FROM task_handoff_snapshots WHERE snapshot_id = ?").get(result.snapshotId);
+				const taskRow = db.prepare("SELECT version FROM tasks WHERE task_id = ?").get(input.taskId);
+				return {
+					state: stateFromRow(db.prepare("SELECT * FROM task_conversation_state WHERE task_id = ?").get(input.taskId)),
+					snapshot: snapshotFromRow(snapshotRow),
+					taskVersion: taskRow.version
+				};
+			}
+			const existing = db.prepare("SELECT * FROM task_conversation_state WHERE task_id = ?").get(input.taskId);
+			if (!existing) throw new Error(`Task conversation state not found: ${input.taskId}`);
+			const current = db.prepare(`SELECT * FROM task_sessions
+         WHERE task_id = ? AND role = 'execution' AND status = 'active'`).get(input.taskId);
+			if (current?.session_key === input.toSessionKey && current.agent_id === input.toAgentId) throw new TaskConversationConflictError("Executor is already active");
+			const assignmentEpoch = existing.assignment_epoch + 1;
+			if (db.prepare(`UPDATE tasks SET delegate_agent_id = ?, version = version + 1, updated_at = ?
+         WHERE task_id = ? AND version = ?`).run(input.toAgentId, now, input.taskId, input.expectedTaskVersion).changes === 0) throw new TaskConversationConflictError("Task changed");
+			db.prepare(`UPDATE task_sessions SET status = 'superseded', ended_at = ?
+         WHERE task_id = ? AND role = 'execution' AND status = 'active'`).run(now, input.taskId);
+			db.prepare(`INSERT INTO task_sessions (
+          task_session_id, task_id, session_key, role, created_at,
+          agent_id, assignment_epoch, status, started_at, ended_at
+        ) VALUES (?, ?, ?, 'execution', ?, ?, ?, 'active', ?, NULL)`).run(randomUUID(), input.taskId, input.toSessionKey, now, input.toAgentId, assignmentEpoch, now);
+			const snapshotId = randomUUID();
+			db.prepare(`INSERT INTO task_handoff_snapshots (
+          snapshot_id, task_id, from_session_key, to_session_key,
+          from_agent_id, to_agent_id, assignment_epoch, payload_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(snapshotId, input.taskId, current?.session_key ?? null, input.toSessionKey, current?.agent_id ?? existing.current_executor_agent_id ?? null, input.toAgentId, assignmentEpoch, JSON.stringify(input.payload), now);
+			db.prepare(`UPDATE task_conversation_state SET
+          active_session_key = ?, current_executor_agent_id = ?,
+          assignment_epoch = ?, status = 'active', updated_at = ?
+         WHERE task_id = ?`).run(input.toSessionKey, input.toAgentId, assignmentEpoch, now, input.taskId);
+			db.prepare(`INSERT INTO command_deduplication (
+          idempotency_key, command_type, subject_kind, subject_id,
+          request_hash, result_json, created_at
+        ) VALUES (?, 'task.handoff', 'task', ?, ?, ?, ?)`).run(input.idempotencyKey, input.taskId, requestHash, JSON.stringify({ snapshotId }), now);
+			return {
+				state: stateFromRow(db.prepare("SELECT * FROM task_conversation_state WHERE task_id = ?").get(input.taskId)),
+				taskVersion: input.expectedTaskVersion + 1,
+				snapshot: {
+					id: snapshotId,
+					taskId: input.taskId,
+					...current?.session_key ? { fromSessionKey: current.session_key } : {},
+					toSessionKey: input.toSessionKey,
+					...current?.agent_id || existing.current_executor_agent_id ? { fromAgentId: current?.agent_id ?? existing.current_executor_agent_id } : {},
+					toAgentId: input.toAgentId,
+					assignmentEpoch,
+					payload: input.payload,
+					createdAt: now
+				}
+			};
+		});
+	}
+	getLatestHandoff(taskId) {
+		const row = getSqliteDatabase().prepare(`SELECT * FROM task_handoff_snapshots
+       WHERE task_id = ? ORDER BY assignment_epoch DESC LIMIT 1`).get(taskId);
+		if (!row) return void 0;
+		return snapshotFromRow(row);
+	}
+};
+//#endregion
+export { TaskConversationConflictError, TaskConversationRepository };

package/dist/src/tasks/task-handoff-service.d.ts

@@ -0,0 +1,31 @@
+import type { Config } from '../config/schema.js';
+import type { SessionIndex } from '../session/index.js';
+import { type TaskConversationState, type TaskHandoffSnapshot } from './task-conversation-repository.js';
+import { type TaskAggregate } from './task-repository.js';
+export interface TaskHandoffResult {
+    task: TaskAggregate;
+    conversation: TaskConversationState;
+    snapshot: TaskHandoffSnapshot;
+    fromAgentId?: string;
+    toAgentId: string;
+    activeSessionKey: string;
+    assignmentEpoch: number;
+}
+export declare class TaskHandoffService {
+    #private;
+    private readonly deps;
+    constructor(deps: {
+        getConfig: () => Config;
+        sessionIndex: SessionIndex;
+        getActiveRunId: (sessionKey: string) => string | undefined;
+        abortRun: (runId: string) => Promise<unknown>;
+    });
+    handoff(input: {
+        taskId: string;
+        toAgentId: string;
+        expectedVersion: number;
+        idempotencyKey: string;
+    }): Promise<TaskHandoffResult>;
+    private performHandoff;
+    private abortPreviousSession;
+}

package/dist/src/tasks/task-handoff-service.js

@@ -0,0 +1,143 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { init_agent_scope, listAgentEntries, normalizeAgentId } from "../agent/agent-scope.js";
+import { buildSessionKey, init_session_key, sanitizeSegment } from "../routing/session-key.js";
+import { TaskRepository } from "./task-repository.js";
+import { TaskConversationRepository } from "./task-conversation-repository.js";
+import { TaskRunRepository } from "./task-run-repository.js";
+import { TaskContextRepository } from "./task-context-repository.js";
+//#region src/tasks/task-handoff-service.ts
+init_agent_scope();
+init_session_key();
+init_logger();
+const log = createLogger("TaskHandoff");
+var TaskHandoffService = class {
+	#inflight = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.deps = deps;
+	}
+	handoff(input) {
+		const previous = this.#inflight.get(input.taskId);
+		const pending = (previous ? previous.catch(() => void 0) : Promise.resolve()).then(() => this.performHandoff(input));
+		this.#inflight.set(input.taskId, pending);
+		pending.finally(() => {
+			if (this.#inflight.get(input.taskId) === pending) this.#inflight.delete(input.taskId);
+		});
+		return pending;
+	}
+	async performHandoff(input) {
+		const config = this.deps.getConfig();
+		const toAgentId = normalizeAgentId(input.toAgentId);
+		if (!listAgentEntries(config).find((entry) => entry.enabled !== false && normalizeAgentId(entry.id) === toAgentId)) throw new Error(`Agent not found: ${toAgentId}`);
+		const tasks = new TaskRepository();
+		const task = tasks.require(input.taskId);
+		const conversations = new TaskConversationRepository();
+		const duplicate = conversations.findHandoffByIdempotencyKey({
+			taskId: task.id,
+			expectedTaskVersion: input.expectedVersion,
+			toAgentId,
+			idempotencyKey: input.idempotencyKey
+		});
+		if (duplicate) {
+			await this.abortPreviousSession(duplicate.fromSessionKey);
+			return {
+				task,
+				conversation: conversations.requireState(task.id),
+				snapshot: duplicate,
+				...duplicate.fromAgentId ? { fromAgentId: duplicate.fromAgentId } : {},
+				toAgentId,
+				activeSessionKey: duplicate.toSessionKey,
+				assignmentEpoch: duplicate.assignmentEpoch
+			};
+		}
+		if (task.version !== input.expectedVersion) throw new Error("Task changed");
+		const previousState = conversations.requireState(task.id);
+		if (previousState.currentExecutorAgentId === toAgentId) throw new Error("Executor is already active");
+		const assignmentEpoch = previousState.assignmentEpoch + 1;
+		const peerId = sanitizeSegment(`task-${task.id}-assignment-${assignmentEpoch}`);
+		const sessionKey = buildSessionKey({
+			agentId: toAgentId,
+			source: "webchat",
+			accountId: "default",
+			peerKind: "direct",
+			peerId
+		});
+		const runs = new TaskRunRepository();
+		const latestRun = runs.getLatestRoot(task.id);
+		const latestReceipt = latestRun ? runs.getReceipt(latestRun.id) : void 0;
+		const remainingCriteria = latestReceipt?.verification.checks.length ? latestReceipt.verification.checks.filter((check) => check.status !== "passed").map((check) => check.criterion) : task.contract?.acceptanceCriteria ?? [];
+		const payload = {
+			objective: task.contract?.objective ?? task.title,
+			expectedOutputs: task.contract?.expectedOutputs ?? [],
+			remainingCriteria,
+			constraints: task.contract?.constraints ?? [],
+			risks: task.contract?.risks ?? [],
+			approvalRequired: task.contract?.approvalRequired ?? [],
+			context: new TaskContextRepository().list(task.id),
+			...latestReceipt ? {
+				latestReceipt,
+				completedWork: latestReceipt.changes,
+				remainingWork: latestReceipt.remainingWork
+			} : {}
+		};
+		await this.deps.sessionIndex.saveMessages(sessionKey, [], { metadata: {
+			sourceChannel: "webchat",
+			sourceChatId: `default:direct:${peerId}`,
+			sessionType: "chat",
+			routing: {
+				agentId: toAgentId,
+				source: "webchat",
+				accountId: "default",
+				peerKind: "direct",
+				peerId
+			},
+			projectId: task.projectId,
+			customData: {
+				origin: "task",
+				triggerKind: "user",
+				assignmentEpoch
+			}
+		} });
+		let completed;
+		try {
+			completed = conversations.completeHandoff({
+				taskId: task.id,
+				expectedTaskVersion: input.expectedVersion,
+				toSessionKey: sessionKey,
+				toAgentId,
+				idempotencyKey: input.idempotencyKey,
+				payload
+			});
+		} catch (error) {
+			await this.deps.sessionIndex.delete(sessionKey);
+			throw error;
+		}
+		const oldSessionKey = completed.snapshot.fromSessionKey;
+		await this.abortPreviousSession(oldSessionKey);
+		return {
+			task: tasks.require(task.id),
+			conversation: completed.state,
+			snapshot: completed.snapshot,
+			...completed.snapshot.fromAgentId ? { fromAgentId: completed.snapshot.fromAgentId } : {},
+			toAgentId,
+			activeSessionKey: sessionKey,
+			assignmentEpoch: completed.state.assignmentEpoch
+		};
+	}
+	async abortPreviousSession(sessionKey) {
+		if (!sessionKey) return;
+		const activeRunId = this.deps.getActiveRunId(sessionKey);
+		if (!activeRunId) return;
+		try {
+			await this.deps.abortRun(activeRunId);
+		} catch (error) {
+			log.warn({
+				err: error,
+				sessionKey,
+				runId: activeRunId
+			}, "Previous task executor did not stop cleanly");
+		}
+	}
+};
+//#endregion
+export { TaskHandoffService };