@xopcai/xopc 0.0.197 → 0.0.200

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

@@ -3,6 +3,7 @@ import { TaskRepository } from "./task-repository.js";
 import { TaskRunRepository } from "./task-run-repository.js";
 import { TaskReadModelProjector } from "./task-read-model-projector.js";
 import { TaskContextRepository } from "./task-context-repository.js";
+import { enqueueTaskChangedEvent } from "./task-change-events.js";
 import { TaskDependencyService } from "./task-dependency-service.js";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/tasks/task-application-service.ts
@@ -24,6 +25,27 @@ function executorRef(executor) {
 		};
 	}
 }
+function commandChangedFields(command) {
+	switch (command.type) {
+		case "move":
+		case "mark_ready":
+		case "request_review":
+		case "close":
+		case "reopen": return [
+			"phase",
+			"resolution",
+			"attention"
+		];
+		case "start": return [
+			"phase",
+			"runs",
+			"attention"
+		];
+		case "add_wait":
+		case "resolve_wait": return ["runs", "attention"];
+		case "revise_contract": return ["contract"];
+	}
+}
 var TaskApplicationService = class {
 	#tasks = new TaskRepository();
 	#runs = new TaskRunRepository();
@@ -58,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,
@@ -86,16 +112,48 @@ var TaskApplicationService = class {
 				phase: current.phase,
 				projectId: current.projectId
 			});
+			enqueueTaskChangedEvent(db, {
+				taskId: current.id,
+				projectId: current.projectId,
+				version: current.version,
+				changedFields: [
+					"title",
+					"body",
+					"phase",
+					"priority",
+					"contract",
+					"dependencies",
+					"context"
+				],
+				actor
+			});
 			if (input.activation.mode === "capture") return {
 				ok: true,
 				model: this.#projector.project(current)
 			};
-			return 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,
 				correlationId: input.idempotencyKey
 			});
+			if (started.ok) enqueueTaskChangedEvent(db, {
+				taskId: started.model.task.id,
+				projectId: started.model.task.projectId,
+				version: started.model.task.version,
+				changedFields: [
+					"phase",
+					"runs",
+					"attention"
+				],
+				actor
+			});
+			return started;
 		});
 	}
 	execute(input) {
@@ -118,6 +176,13 @@ var TaskApplicationService = class {
 		return runSqliteWriteTransaction((db) => {
 			let result;
 			switch (input.command.type) {
+				case "move":
+					result = task.phase !== "closed" && task.phase !== input.command.phase && !this.#runs.getActiveRoot(task.id) && this.#runs.listActiveWaits(task.id).length === 0 ? this.lifecycle(task.id, task.version, input.command.phase) : {
+						ok: false,
+						reason: "invalid_transition",
+						model
+					};
+					break;
 				case "mark_ready":
 					result = task.phase === "backlog" ? this.lifecycle(task.id, task.version, "ready") : {
 						ok: false,
@@ -191,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,
@@ -257,11 +307,18 @@ var TaskApplicationService = class {
 				resolution: result.model.task.resolution,
 				projectId: result.model.task.projectId
 			});
+			enqueueTaskChangedEvent(db, {
+				taskId: result.model.task.id,
+				projectId: result.model.task.projectId,
+				version: result.model.task.version,
+				changedFields: commandChangedFields(input.command),
+				actor
+			});
 			return result;
 		});
 	}
 	completeRun(input) {
-		return runSqliteWriteTransaction(() => {
+		return runSqliteWriteTransaction((db) => {
 			const run = this.#runs.get(input.runId);
 			if (!run) return {
 				ok: false,
@@ -285,10 +342,25 @@ var TaskApplicationService = class {
 				model: this.#projector.get(run.taskId)
 			};
 			const task = this.#tasks.require(run.taskId);
-			if (input.receipt.status !== "succeeded") return {
-				ok: true,
-				model: this.#projector.project(task)
-			};
+			if (input.receipt.status !== "succeeded") {
+				const model = this.#projector.project(task);
+				enqueueTaskChangedEvent(db, {
+					taskId: task.id,
+					projectId: task.projectId,
+					version: task.version,
+					changedFields: [
+						"runs",
+						"receipts",
+						"attention"
+					],
+					actor: input.actor,
+					source: input.actor ? void 0 : "runtime"
+				});
+				return {
+					ok: true,
+					model
+				};
+			}
 			const verified = input.receipt.verification.status === "passed";
 			const phase = task.contract?.acceptancePolicy === "verified_auto" && verified ? "closed" : "review";
 			const updated = this.#tasks.setLifecycle({
@@ -298,6 +370,20 @@ var TaskApplicationService = class {
 				...phase === "closed" ? { resolution: "done" } : {}
 			});
 			if (!updated) throw new Error("Task changed while its run was being finalized");
+			enqueueTaskChangedEvent(db, {
+				taskId: updated.id,
+				projectId: updated.projectId,
+				version: updated.version,
+				changedFields: [
+					"phase",
+					"resolution",
+					"runs",
+					"receipts",
+					"attention"
+				],
+				actor: input.actor,
+				source: input.actor ? void 0 : "runtime"
+			});
 			return {
 				ok: true,
 				model: this.#projector.project(updated)

package/dist/src/tasks/task-change-events.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ActorRef, TaskChangedField } from '@xopcai/gateway-contract';
+export type TaskChangeInput = {
+    taskId: string;
+    projectId?: string;
+    version: number;
+    changedFields: TaskChangedField[];
+    actor?: ActorRef;
+    source?: 'user' | 'agent' | 'runtime';
+    occurredAt?: number;
+};
+export declare function enqueueTaskChangedEvent(db: DatabaseSync, input: TaskChangeInput): void;
+export declare function enqueueTaskChanged(input: TaskChangeInput): void;

package/dist/src/tasks/task-change-events.js

@@ -0,0 +1,29 @@
+import { runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { randomUUID } from "node:crypto";
+//#region src/tasks/task-change-events.ts
+function eventSource(input) {
+	if (input.source) return input.source;
+	return input.actor?.kind === "user" || input.actor?.kind === "agent" ? input.actor.kind : "runtime";
+}
+function enqueueTaskChangedEvent(db, input) {
+	const occurredAt = input.occurredAt ?? Date.now();
+	const changedFields = [...new Set(input.changedFields)];
+	if (changedFields.length === 0) return;
+	db.prepare(`INSERT INTO domain_outbox (
+      event_id, event_type, subject_kind, subject_id, correlation_id,
+      payload_json, created_at
+    ) VALUES (?, 'task.changed.v2', 'task', ?, ?, ?, ?)`).run(randomUUID(), input.taskId, randomUUID(), JSON.stringify({
+		taskId: input.taskId,
+		...input.projectId ? { projectId: input.projectId } : {},
+		version: input.version,
+		changedFields,
+		source: eventSource(input),
+		...input.actor?.id ? { actorId: input.actor.id } : {},
+		occurredAt
+	}), occurredAt);
+}
+function enqueueTaskChanged(input) {
+	runSqliteWriteTransaction((db) => enqueueTaskChangedEvent(db, input));
+}
+//#endregion
+export { enqueueTaskChanged, enqueueTaskChangedEvent };

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