@xopcai/xopc 0.0.199 → 0.0.201

package/dist/src/storage/sqlite/migrations/120_task_conversation.sql

@@ -0,0 +1,112 @@
+ALTER TABLE task_sessions ADD COLUMN agent_id TEXT;
+ALTER TABLE task_sessions ADD COLUMN run_id TEXT;
+ALTER TABLE task_sessions ADD COLUMN assignment_epoch INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE task_sessions ADD COLUMN status TEXT NOT NULL DEFAULT 'completed'
+  CHECK (status IN ('active', 'completed', 'superseded', 'failed'));
+ALTER TABLE task_sessions ADD COLUMN started_at INTEGER;
+ALTER TABLE task_sessions ADD COLUMN ended_at INTEGER;
+
+UPDATE task_sessions
+SET agent_id = (
+  SELECT sessions.agent_id FROM sessions WHERE sessions.session_key = task_sessions.session_key
+), started_at = created_at;
+
+UPDATE task_sessions
+SET run_id = (
+  SELECT task_runs.run_id
+  FROM task_runs
+  WHERE task_runs.task_id = task_sessions.task_id
+    AND task_runs.session_key = task_sessions.session_key
+  ORDER BY task_runs.queued_at DESC
+  LIMIT 1
+)
+WHERE role = 'execution';
+
+UPDATE task_sessions
+SET status = 'superseded', ended_at = created_at
+WHERE role = 'execution';
+
+DELETE FROM task_sessions
+WHERE role = 'execution'
+  AND session_key IS NOT NULL
+  AND task_session_id NOT IN (
+    SELECT canonical.task_session_id
+    FROM task_sessions AS canonical
+    WHERE canonical.role = 'execution'
+      AND canonical.session_key IS NOT NULL
+      AND canonical.task_session_id = (
+        SELECT candidate.task_session_id
+        FROM task_sessions AS candidate
+        WHERE candidate.role = 'execution'
+          AND candidate.session_key = canonical.session_key
+        ORDER BY candidate.created_at DESC, candidate.task_session_id DESC
+        LIMIT 1
+      )
+  );
+
+UPDATE task_sessions
+SET status = 'active', ended_at = NULL, assignment_epoch = 1
+WHERE task_session_id IN (
+  SELECT latest.task_session_id FROM task_sessions AS latest
+  WHERE latest.role = 'execution'
+    AND latest.task_session_id = (
+      SELECT candidate.task_session_id
+      FROM task_sessions AS candidate
+      WHERE candidate.task_id = latest.task_id AND candidate.role = 'execution'
+      ORDER BY candidate.created_at DESC, candidate.task_session_id DESC
+      LIMIT 1
+    )
+);
+
+CREATE UNIQUE INDEX idx_task_sessions_active_execution
+  ON task_sessions(task_id)
+  WHERE role = 'execution' AND status = 'active';
+CREATE UNIQUE INDEX idx_task_sessions_execution_owner
+  ON task_sessions(session_key)
+  WHERE role = 'execution' AND session_key IS NOT NULL;
+
+CREATE TABLE task_conversation_state (
+  task_id TEXT PRIMARY KEY,
+  active_session_key TEXT,
+  current_executor_agent_id TEXT,
+  assignment_epoch INTEGER NOT NULL DEFAULT 0,
+  status TEXT NOT NULL DEFAULT 'idle'
+    CHECK (status IN ('idle', 'active')),
+  updated_at INTEGER NOT NULL,
+  FOREIGN KEY (task_id) REFERENCES tasks(task_id) ON DELETE CASCADE,
+  FOREIGN KEY (active_session_key) REFERENCES sessions(session_key) ON DELETE SET NULL
+);
+
+INSERT INTO task_conversation_state (
+  task_id, active_session_key, current_executor_agent_id,
+  assignment_epoch, status, updated_at
+)
+SELECT
+  tasks.task_id,
+  active.session_key,
+  COALESCE(active.agent_id, tasks.delegate_agent_id, tasks.owner_id),
+  COALESCE(active.assignment_epoch, 0),
+  CASE WHEN active.session_key IS NULL THEN 'idle' ELSE 'active' END,
+  tasks.updated_at
+FROM tasks
+LEFT JOIN task_sessions AS active
+  ON active.task_id = tasks.task_id
+  AND active.role = 'execution'
+  AND active.status = 'active';
+
+CREATE TABLE task_handoff_snapshots (
+  snapshot_id TEXT PRIMARY KEY,
+  task_id TEXT NOT NULL,
+  from_session_key TEXT,
+  to_session_key TEXT NOT NULL,
+  from_agent_id TEXT,
+  to_agent_id TEXT NOT NULL,
+  assignment_epoch INTEGER NOT NULL,
+  payload_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  FOREIGN KEY (task_id) REFERENCES tasks(task_id) ON DELETE CASCADE,
+  FOREIGN KEY (from_session_key) REFERENCES sessions(session_key) ON DELETE SET NULL,
+  FOREIGN KEY (to_session_key) REFERENCES sessions(session_key) ON DELETE CASCADE
+);
+CREATE INDEX idx_task_handoffs_task
+  ON task_handoff_snapshots(task_id, assignment_epoch DESC);

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 = 119;
+export declare const XOPC_DB_SCHEMA_VERSION = 120;
 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 = 119;
+const XOPC_DB_SCHEMA_VERSION = 120;
 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 ?? 119;
+	const targetVersion = options.targetVersion ?? 120;
 	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 ?? 119;
+	const appVersion = options.targetVersion ?? 120;
 	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 = 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;
+}