@xopcai/xopc 0.0.199 → 0.0.200

package/dist/src/gateway/hono/routes/tasks.js

@@ -1,10 +1,12 @@
 import { runSqliteWriteTransaction } from "../../../storage/sqlite/transaction.js";
 import { TaskRepository } from "../../../tasks/task-repository.js";
+import { TaskConversationRepository } from "../../../tasks/task-conversation-repository.js";
 import { TaskRunRepository } from "../../../tasks/task-run-repository.js";
 import { TaskReadModelProjector } from "../../../tasks/task-read-model-projector.js";
 import { TaskPhaseSchema } from "../../../../packages/gateway-contract/src/task-lifecycle.js";
-import { TaskBoardPositionRequestSchema, TaskCommandRequestSchema, TaskContextInputSchema, TaskCreateRequestSchema, TaskDependencyUpdateRequestSchema, TaskPatchRequestSchema } from "../../../../packages/gateway-contract/src/tasks.js";
+import { TaskBoardPositionRequestSchema, TaskCommandRequestSchema, TaskContextInputSchema, TaskCreateRequestSchema, TaskDependencyUpdateRequestSchema, TaskHandoffRequestSchema, TaskPatchRequestSchema } from "../../../../packages/gateway-contract/src/tasks.js";
 import { ProjectMonitoringUpdateSchema } from "../../../../packages/gateway-contract/src/project-monitoring.js";
+import { resolveProjectAgentId } from "../../../projects/project-agent.js";
 import { TaskContextRepository } from "../../../tasks/task-context-repository.js";
 import { enqueueTaskChangedEvent } from "../../../tasks/task-change-events.js";
 import { TaskDependencyError, TaskDependencyService } from "../../../tasks/task-dependency-service.js";
@@ -12,7 +14,10 @@ import { TaskApplicationService } from "../../../tasks/task-application-service.
 import { ProjectMonitoringService } from "../../../tasks/project-monitoring-service.js";
 import { ProjectOperatingViewService } from "../../../tasks/project-operating-view-service.js";
 import { TaskValueMetricsService } from "../../../tasks/task-value-metrics-service.js";
+import { TaskHandoffService } from "../../../tasks/task-handoff-service.js";
 import { TaskSignalService } from "../../../tasks/task-signal-service.js";
+import { submitSessionInput } from "./session-input-handler.js";
+import { TaskConversationQueryService } from "../../service/task-conversation-query-service.js";
 //#region src/gateway/hono/routes/tasks.ts
 function registerTaskRoutes(authenticated, deps) {
 	const taskRateLimit = deps.taskRateLimitMiddleware ?? deps.strictRateLimitMiddleware;
@@ -23,9 +28,17 @@ function registerTaskRoutes(authenticated, deps) {
 	const tasks = new TaskRepository();
 	const runs = new TaskRunRepository();
 	const context = new TaskContextRepository();
+	const conversations = new TaskConversationRepository();
+	const conversationQuery = new TaskConversationQueryService(deps.service.sessions);
 	const projector = new TaskReadModelProjector();
 	const signals = new TaskSignalService(() => deps.service.dispatchTaskRuns());
 	const dependencies = new TaskDependencyService();
+	const handoffs = new TaskHandoffService({
+		getConfig: () => deps.service.currentConfig,
+		sessionIndex: deps.service.sessionIndexInstance,
+		getActiveRunId: (sessionKey) => deps.service.getActiveWebchatRunId(sessionKey),
+		abortRun: (runId) => deps.service.abortAgentRun(runId)
+	});
 	authenticated.get("/api/tasks", (c) => {
 		const phase = TaskPhaseSchema.safeParse(c.req.query("phase"));
 		const rawLimit = Number(c.req.query("limit") ?? 50);
@@ -53,7 +66,25 @@ function registerTaskRoutes(authenticated, deps) {
 			error: "Invalid task request"
 		}, 400);
 		try {
-			const created = application.create(parsed.data);
+			const requestedAgentId = parsed.data.delegateAgentId ?? (parsed.data.activation.mode === "start" && parsed.data.activation.executor?.kind === "agent" ? parsed.data.activation.executor.agentId : void 0);
+			const agentId = resolveProjectAgentId({
+				config: deps.service.currentConfig,
+				projects: deps.service.projects,
+				explicitAgentId: requestedAgentId,
+				projectId: parsed.data.projectId
+			});
+			const input = {
+				...parsed.data,
+				delegateAgentId: agentId,
+				activation: parsed.data.activation.mode === "start" ? {
+					...parsed.data.activation,
+					executor: parsed.data.activation.executor?.kind === "agent" || !parsed.data.activation.executor ? {
+						kind: "agent",
+						agentId
+					} : parsed.data.activation.executor
+				} : parsed.data.activation
+			};
+			const created = application.create(input);
 			if (created.ok === false) return c.json({
 				ok: false,
 				code: created.reason,
@@ -95,12 +126,140 @@ function registerTaskRoutes(authenticated, deps) {
 			runs: runs.listByTask(task.id),
 			receipts: runs.listReceipts(task.id),
 			context: context.list(task.id),
+			conversation: conversations.requireState(task.id),
+			sessions: conversations.listSessions(task.id),
 			authorityGrants: context.listActiveGrants(task.id),
 			dependencies: dependencies.listDependencies(task.id),
 			dependents: dependencies.listDependents(task.id),
 			allowedCommands: model.allowedCommands
 		});
 	});
+	authenticated.post("/api/tasks/:id/conversation", taskRateLimit, async (c) => {
+		try {
+			const result = await deps.service.ensureTaskConversation(c.req.param("id"));
+			if (result.created) {
+				const task = tasks.require(c.req.param("id"));
+				runSqliteWriteTransaction((db) => enqueueTaskChangedEvent(db, {
+					taskId: task.id,
+					projectId: task.projectId,
+					version: task.version,
+					changedFields: ["conversation"],
+					actor: { kind: "user" }
+				}));
+				deps.service.dispatchTaskEvents();
+			}
+			return c.json({
+				ok: true,
+				...result
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return c.json({
+				ok: false,
+				error: message
+			}, message.startsWith("Task not found") ? 404 : 409);
+		}
+	});
+	authenticated.post("/api/tasks/:id/handoff", taskRateLimit, async (c) => {
+		const parsed = TaskHandoffRequestSchema.safeParse(await c.req.json().catch(() => ({})));
+		if (!parsed.success) return c.json({
+			ok: false,
+			error: "Invalid task handoff request"
+		}, 400);
+		try {
+			const result = await handoffs.handoff({
+				taskId: c.req.param("id"),
+				...parsed.data
+			});
+			runSqliteWriteTransaction((db) => enqueueTaskChangedEvent(db, {
+				taskId: result.task.id,
+				projectId: result.task.projectId,
+				version: result.task.version,
+				changedFields: ["delegateAgentId", "conversation"],
+				actor: { kind: "user" }
+			}));
+			deps.service.dispatchTaskEvents();
+			return c.json({
+				ok: true,
+				task: result.task,
+				conversation: result.conversation,
+				...result.fromAgentId ? { fromAgentId: result.fromAgentId } : {},
+				toAgentId: result.toAgentId,
+				activeSessionKey: result.activeSessionKey,
+				assignmentEpoch: result.assignmentEpoch
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return c.json({
+				ok: false,
+				error: message
+			}, message.startsWith("Agent not found") || message.startsWith("Task not found") ? 404 : 409);
+		}
+	});
+	authenticated.post("/api/tasks/:id/inputs", deps.chatRateLimitMiddleware, async (c) => {
+		const active = conversations.getActiveSession(c.req.param("id"));
+		if (!active?.sessionKey) return c.json({
+			ok: false,
+			error: {
+				code: "NOT_FOUND",
+				message: "Task has no active conversation"
+			}
+		}, 404);
+		const expectedSessionKey = c.req.header("X-Xopc-Expected-Session-Key")?.trim();
+		if (expectedSessionKey && expectedSessionKey !== active.sessionKey) return c.json({
+			ok: false,
+			error: {
+				code: "CONFLICT",
+				message: "Task executor changed; refresh the conversation"
+			}
+		}, 409);
+		return submitSessionInput(c, deps, active.sessionKey);
+	});
+	authenticated.patch("/api/tasks/:id/conversation/config", taskRateLimit, async (c) => {
+		const body = await c.req.json().catch(() => null);
+		const model = typeof body?.model === "string" ? body.model.trim() : "";
+		if (!model) return c.json({
+			ok: false,
+			error: "Missing model"
+		}, 400);
+		const active = conversations.getActiveSession(c.req.param("id"));
+		if (!active?.sessionKey) return c.json({
+			ok: false,
+			error: "Task has no active conversation"
+		}, 404);
+		const result = await deps.service.sessions.patchAgentConfig(active.sessionKey, { model });
+		if (!result.ok) return c.json({
+			ok: false,
+			error: result.error
+		}, 400);
+		return c.json({
+			ok: true,
+			activeSessionKey: active.sessionKey
+		});
+	});
+	authenticated.get("/api/tasks/:id/conversation/history", async (c) => {
+		const parsedLimit = Number.parseInt(c.req.query("limit") ?? "50", 10);
+		const parsedOffset = Number.parseInt(c.req.query("offset") ?? "0", 10);
+		const rawBefore = c.req.query("before")?.trim();
+		const before = rawBefore === void 0 ? void 0 : Number.parseInt(rawBefore, 10);
+		if (rawBefore !== void 0 && (!Number.isInteger(before) || before < 0)) return c.json({ error: "Invalid conversation history cursor" }, 400);
+		const result = await conversationQuery.getMessagePage(c.req.param("id"), {
+			limit: Number.isFinite(parsedLimit) ? Math.min(200, Math.max(1, parsedLimit)) : 50,
+			offset: Number.isFinite(parsedOffset) ? Math.max(0, parsedOffset) : 0,
+			...before === void 0 ? {} : { before }
+		});
+		return result ? c.json(result) : c.json({ error: "Task conversation not found" }, 404);
+	});
+	authenticated.get("/api/tasks/:id/conversation/timeline", async (c) => {
+		const items = await conversationQuery.getTimeline(c.req.param("id"));
+		return items ? c.json({
+			ok: true,
+			items
+		}) : c.json({
+			ok: false,
+			error: "Task conversation not found"
+		}, 404);
+	});
 	authenticated.patch("/api/tasks/:id", taskRateLimit, async (c) => {
 		const parsed = TaskPatchRequestSchema.safeParse(await c.req.json().catch(() => ({})));
 		if (!parsed.success) return c.json({

package/dist/src/gateway/service/task-conversation-query-service.d.ts

@@ -0,0 +1,58 @@
+import type { SessionTimelineItem } from '../../session/transcript-outline.js';
+import { TaskConversationRepository } from '../../tasks/task-conversation-repository.js';
+import type { GatewaySessionsApi } from './sessions-api.js';
+export declare class TaskConversationQueryService {
+    #private;
+    private readonly sessions;
+    private readonly conversations;
+    constructor(sessions: Pick<GatewaySessionsApi, 'getMessagePage' | 'getTimeline'>, conversations?: Pick<TaskConversationRepository, 'listSessions'>);
+    getMessagePage(taskId: string, options: {
+        limit: number;
+        offset: number;
+        before?: number;
+    }): Promise<{
+        session: {
+            messages: import("../../session/types.js").Message[];
+            transcriptSummary?: import("../../session/types.js").SessionTranscriptSummary;
+            transcriptRows?: import("../../session/session-context-for-llm.js").TranscriptStoredRow[];
+            key: string;
+            name?: string;
+            status: import("../../session/types.js").SessionStatus;
+            tags: string[];
+            createdAt: string;
+            updatedAt: string;
+            lastAccessedAt: string;
+            messageCount: number;
+            estimatedTokens: number;
+            compactedCount: number;
+            lastFlushedAt?: string;
+            flushCount?: number;
+            sourceChannel: string;
+            sourceChatId: string;
+            customData?: Record<string, unknown>;
+            projectId?: string;
+            routing?: import("../../session/types.js").SessionRoutingMeta;
+            stats?: import("../../session/types.js").SessionStats;
+            sessionType: import("../../session/types.js").SessionType;
+            hiddenFromSessionList?: boolean;
+            parentSessionKey?: string;
+            workflowRunId?: string;
+            workflowDefinitionId?: string;
+            workflowAgentId?: string;
+            workflowAgentLabel?: string;
+            sessionId?: string;
+            cwd?: string;
+            sessionStartedAt?: string;
+            lastInteractionAt?: string;
+        };
+        pagination: {
+            nextBeforeCursor?: string;
+            before?: string;
+            total: number;
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+        };
+    }>;
+    getTimeline(taskId: string): Promise<SessionTimelineItem[] | null>;
+}

package/dist/src/gateway/service/task-conversation-query-service.js

@@ -0,0 +1,84 @@
+import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
+//#region src/gateway/service/task-conversation-query-service.ts
+var TaskConversationQueryService = class {
+	constructor(sessions, conversations = new TaskConversationRepository()) {
+		this.sessions = sessions;
+		this.conversations = conversations;
+	}
+	async getMessagePage(taskId, options) {
+		const links = this.#executionSessions(taskId);
+		if (links.length === 0) return null;
+		const probes = await Promise.all(links.map((link) => this.sessions.getMessagePage(link.sessionKey, { limit: 1 })));
+		if (probes.some((page) => !page)) return null;
+		const pages = probes;
+		const total = pages.reduce((sum, page) => sum + page.pagination.total, 0);
+		const end = Math.min(total, Math.max(0, options.before ?? total - options.offset));
+		const start = Math.max(0, end - options.limit);
+		const messages = [];
+		let cursor = 0;
+		for (let index = 0; index < links.length; index += 1) {
+			const sessionTotal = pages[index].pagination.total;
+			const localStart = Math.max(0, start - cursor);
+			const localEnd = Math.min(sessionTotal, end - cursor);
+			if (localStart < localEnd) {
+				const page = await this.sessions.getMessagePage(links[index].sessionKey, {
+					offset: sessionTotal - localEnd,
+					limit: localEnd - localStart
+				});
+				if (!page) return null;
+				messages.push(...page.session.messages);
+			}
+			cursor += sessionTotal;
+		}
+		const activeIndex = links.findIndex((link) => link.status === "active");
+		return {
+			session: {
+				...pages[activeIndex >= 0 ? activeIndex : pages.length - 1].session,
+				messages
+			},
+			pagination: {
+				total,
+				limit: options.limit,
+				offset: options.offset,
+				hasMore: start > 0,
+				...options.before === void 0 ? {} : { before: String(end) },
+				...start > 0 ? { nextBeforeCursor: String(start) } : {}
+			}
+		};
+	}
+	async getTimeline(taskId) {
+		const links = this.#executionSessions(taskId);
+		if (links.length === 0) return null;
+		const output = [];
+		let displayOffset = 0;
+		let turnOffset = 0;
+		for (const [index, link] of links.entries()) {
+			const [items, page] = await Promise.all([this.sessions.getTimeline(link.sessionKey), this.sessions.getMessagePage(link.sessionKey, { limit: 1 })]);
+			if (!items || !page) return null;
+			if (index > 0) output.push({
+				id: `assignment:${link.id}`,
+				kind: "branch",
+				title: link.agentId ? `Execution continued by ${link.agentId}` : "Execution continued",
+				timestamp: link.startedAt,
+				depth: 0,
+				turn: turnOffset,
+				displayIndex: displayOffset
+			});
+			output.push(...items.map((item) => ({
+				...item,
+				id: `${link.id}:${item.id}`,
+				turn: item.turn + turnOffset,
+				...item.displayIndex === void 0 ? {} : { displayIndex: item.displayIndex + displayOffset }
+			})));
+			displayOffset += page.pagination.total;
+			const highestTurn = items.reduce((max, item) => Math.max(max, item.turn), -1);
+			turnOffset += highestTurn + 1;
+		}
+		return output;
+	}
+	#executionSessions(taskId) {
+		return this.conversations.listSessions(taskId).filter((link) => link.role === "execution").sort((a, b) => a.assignmentEpoch - b.assignmentEpoch || a.startedAt - b.startedAt);
+	}
+};
+//#endregion
+export { TaskConversationQueryService };

package/dist/src/gateway/service.d.ts

@@ -12,6 +12,7 @@ import { type ResolvedGatewayAuth } from './auth.js';
 import { ModelCatalogSyncService } from '../providers/model-catalog-sync-service.js';
 import { ProjectService } from '../projects/index.js';
 import { LocalAppService } from '../local-apps/index.js';
+import { TaskConversationRepository } from '../tasks/task-conversation-repository.js';
 import { type BrowserRecipeService } from '../browser/recipes/index.js';
 import { listInsights, ProactiveEventService, ProactiveInboxService, ProactiveInboxWorker, ProactiveScenarioService, ProactiveTemporalWorker, ProactiveWorker } from '../proactive/index.js';
 import { GatewaySessionsApi } from './service/sessions-api.js';
@@ -120,6 +121,15 @@ export declare class GatewayService {
     private createTaskRunDispatcher;
     private createMobileNotificationService;
     dispatchTaskRuns(): void;
+    ensureTaskConversation(taskId: string, options?: {
+        runId?: string;
+        requestedAgentId?: string;
+    }): Promise<{
+        sessionKey: string;
+        agentId: string;
+        created: boolean;
+        conversation: ReturnType<TaskConversationRepository['requireState']>;
+    }>;
     dispatchTaskEvents(): void;
     runAgent(...args: Parameters<GatewayAgentRunner['runAgent']>): ReturnType<GatewayAgentRunner['runAgent']>;
     submitSessionInput(...args: Parameters<GatewayAgentRunner['submitSessionInput']>): Promise<{

package/dist/src/gateway/service.js

@@ -19,19 +19,20 @@ import { loadConfig, saveConfig } from "../config/loader.js";
 import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { init_providers, providers_exports } from "../providers/index.js";
 import { TaskRepository } from "../tasks/task-repository.js";
+import { TaskConversationRepository } from "../tasks/task-conversation-repository.js";
 import { disposeAllSessionMcpRuntimes } from "../agent/mcp/bundle-mcp-runtime.js";
 import { resolveEffectiveGatewayPort } from "./host.js";
 import { AutomationService } from "../automations/service/automation-service.js";
 import { onAutomationProductEvent, publishAutomationProductEvent } from "../automations/product-events.js";
 import "../automations/index.js";
 import { ProjectService } from "../projects/project-service.js";
+import { resolveProjectAgentId } from "../projects/project-agent.js";
 import "../projects/index.js";
 import { sanitizeTunnelConfig } from "../tunnel/tunnel-config.js";
 import { wireTunnelEventsToGateway } from "../tunnel/gateway-lifecycle.js";
 import { buckets } from "./rate-limit/buckets.js";
 import { isGatewayStrictSecurityEnabled } from "./rate-limit/env-flags.js";
 import "./rate-limit/index.js";
-import { TaskContextRepository } from "../tasks/task-context-repository.js";
 import { TaskApplicationService } from "../tasks/task-application-service.js";
 import { ProactiveScenarioService } from "../proactive/scenarios/service.js";
 import { TaskOutboxDispatcher } from "../tasks/task-outbox-dispatcher.js";
@@ -541,42 +542,10 @@ var GatewayService = class {
 		if (!this.taskRunDispatcher) this.taskRunDispatcher = new TaskRunDispatcher({
 			workerId: "gateway-agent",
 			ensureSession: async (taskId, runId, requestedAgentId) => {
-				const task = new TaskRepository().require(taskId);
-				const agentId = requestedAgentId || task.delegateAgentId || getDefaultAgentId(this.config);
-				const peerId = `task-${sanitizeSegment(taskId) || Date.now()}`;
-				const sessionKey = buildSessionKey({
-					agentId,
-					source: "webchat",
-					accountId: "default",
-					peerKind: "direct",
-					peerId
-				});
-				if (!await this.sessionIndex.getSessionMetadata(sessionKey)) await this.sessionIndex.saveMessages(sessionKey, [], { metadata: {
-					sourceChannel: "webchat",
-					sourceChatId: `default:direct:${peerId}`,
-					sessionType: "chat",
-					routing: {
-						agentId,
-						source: "webchat",
-						accountId: "default",
-						peerKind: "direct",
-						peerId
-					},
-					projectId: task.projectId,
-					customData: {
-						taskId,
-						origin: "task",
-						triggerKind: "user",
-						taskRunId: runId
-					}
-				} });
-				if (task.projectId) this.projects.attachSession(sessionKey, task.projectId);
-				new TaskContextRepository().linkSession({
-					taskId,
-					sessionKey,
-					role: "execution"
-				});
-				return sessionKey;
+				return (await this.ensureTaskConversation(taskId, {
+					runId,
+					requestedAgentId
+				})).sessionKey;
 			},
 			runAgent: async (runId, sessionKey, message) => {
 				const stream = this.agentRunner.runAgent(message, "webchat", sessionKey, {
@@ -598,6 +567,70 @@ var GatewayService = class {
 		this.createTaskRunDispatcher().dispatch();
 		this.createWorkflowRunService().dispatchTaskRuns();
 	}
+	async ensureTaskConversation(taskId, options = {}) {
+		const task = new TaskRepository().require(taskId);
+		const agentId = resolveProjectAgentId({
+			config: this.config,
+			projects: this.projects,
+			explicitAgentId: options.requestedAgentId ?? task.delegateAgentId,
+			projectId: task.projectId
+		});
+		const conversations = new TaskConversationRepository();
+		const active = conversations.getActiveSession(task.id);
+		if (active) {
+			if (active.agentId && active.agentId !== agentId) throw new Error("Task executor differs from the active conversation");
+			const conversation = conversations.activateExecutionSession({
+				taskId: task.id,
+				sessionKey: active.sessionKey,
+				agentId,
+				runId: options.runId
+			});
+			return {
+				sessionKey: active.sessionKey,
+				agentId,
+				created: false,
+				conversation
+			};
+		}
+		const peerId = `task-${sanitizeSegment(task.id) || Date.now()}`;
+		const sessionKey = buildSessionKey({
+			agentId,
+			source: "webchat",
+			accountId: "default",
+			peerKind: "direct",
+			peerId
+		});
+		if (!await this.sessionIndex.getSessionMetadata(sessionKey)) await this.sessionIndex.saveMessages(sessionKey, [], { metadata: {
+			sourceChannel: "webchat",
+			sourceChatId: `default:direct:${peerId}`,
+			sessionType: "chat",
+			routing: {
+				agentId,
+				source: "webchat",
+				accountId: "default",
+				peerKind: "direct",
+				peerId
+			},
+			projectId: task.projectId,
+			customData: {
+				origin: "task",
+				triggerKind: "user",
+				...options.runId ? { taskRunId: options.runId } : {}
+			}
+		} });
+		if (task.projectId) this.projects.attachSession(sessionKey, task.projectId);
+		return {
+			sessionKey,
+			agentId,
+			created: true,
+			conversation: conversations.activateExecutionSession({
+				taskId: task.id,
+				sessionKey,
+				agentId,
+				runId: options.runId
+			})
+		};
+	}
 	dispatchTaskEvents() {
 		new TaskOutboxDispatcher(publishAutomationProductEvent).drain();
 	}

package/dist/src/projects/project-agent.js

@@ -8,7 +8,7 @@ function normalizeAgentId(value) {
 function resolveProjectAgentId(input) {
 	const fallback = getDefaultAgentId(input.config);
 	const explicitAgentId = normalizeAgentId(input.explicitAgentId);
-	if (explicitAgentId) return agentExists(explicitAgentId, input.config) ? explicitAgentId : fallback;
+	if (explicitAgentId && agentExists(explicitAgentId, input.config)) return explicitAgentId;
 	const projectId = input.projectId?.trim();
 	const projectAgentId = projectId ? normalizeAgentId(input.projects.get(projectId)?.defaultAgentId) : void 0;
 	if (projectAgentId && agentExists(projectAgentId, input.config)) return projectAgentId;

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,