@lota-sdk/core 0.1.5

package/src/services/execution-plan.service.ts

@@ -0,0 +1,890 @@
+import {
+  ExecutionPlanEventSchema,
+  ExecutionPlanSchema,
+  ExecutionPlanTaskResultStatusSchema,
+  ExecutionPlanTaskSchema,
+} from '@lota-sdk/shared/schemas/execution-plan'
+import type {
+  ExecutionPlanEventRecord,
+  ExecutionPlanRecord,
+  ExecutionPlanStatus,
+  ExecutionPlanTaskRecord,
+  ExecutionPlanTaskResultStatus,
+  ExecutionPlanTaskStatus,
+  SerializableExecutionPlan,
+  SerializableExecutionPlanCarriedTask,
+  SerializableExecutionPlanEvent,
+  SerializableExecutionPlanTask,
+} from '@lota-sdk/shared/schemas/execution-plan'
+import type {
+  CreateExecutionPlanArgs,
+  ExecutionPlanToolResultData,
+  ReplaceExecutionPlanArgs,
+  SetExecutionTaskStatusArgs,
+  RestartExecutionTaskArgs,
+} from '@lota-sdk/shared/schemas/tools'
+import { BoundQuery, RecordId } from 'surrealdb'
+
+import type { RecordIdInput, RecordIdRef } from '../db/record-id'
+import { ensureRecordId, recordIdToString } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+import { toIsoDateTimeString, toOptionalIsoDateTimeString } from '../utils/date-time'
+
+const ACTIVE_PLAN_STATUSES: ExecutionPlanStatus[] = ['draft', 'executing', 'blocked']
+const ACTIVE_PLAN_STATUS_SET = new Set<ExecutionPlanStatus>(ACTIVE_PLAN_STATUSES)
+const SUCCESSFUL_RESULT_STATUS_SET = new Set<ExecutionPlanTaskResultStatus>(['success', 'partial'])
+const CARRIED_RESULT_STATUS_SET = new Set<ExecutionPlanTaskResultStatus>(['success', 'partial'])
+const RESTART_REQUIRED_TASK_STATUS_SET = new Set<ExecutionPlanTaskStatus>(['completed', 'failed', 'skipped'])
+const TASK_STATUS_TRANSITIONS: Record<ExecutionPlanTaskStatus, ReadonlySet<ExecutionPlanTaskStatus>> = {
+  pending: new Set<ExecutionPlanTaskStatus>(['in-progress', 'blocked', 'skipped']),
+  'in-progress': new Set<ExecutionPlanTaskStatus>(['completed', 'blocked', 'failed', 'skipped']),
+  blocked: new Set<ExecutionPlanTaskStatus>(['in-progress', 'completed', 'failed', 'skipped']),
+  completed: new Set<ExecutionPlanTaskStatus>(),
+  failed: new Set<ExecutionPlanTaskStatus>(),
+  skipped: new Set<ExecutionPlanTaskStatus>(),
+}
+
+function normalizeTaskInput(
+  input: CreateExecutionPlanArgs['tasks'][number]['input'],
+): string | Record<string, unknown> | undefined {
+  if (input === undefined) return undefined
+  return typeof input === 'string' ? input : structuredClone(input)
+}
+
+function isExecutionPlanRecord(value: RecordIdInput | ExecutionPlanRecord): value is ExecutionPlanRecord {
+  return typeof value === 'object' && 'workstreamId' in value
+}
+
+function isExecutionPlanTaskRecord(value: RecordIdInput | ExecutionPlanTaskRecord): value is ExecutionPlanTaskRecord {
+  return typeof value === 'object' && 'position' in value
+}
+
+function toPlanId(planId: RecordIdInput | ExecutionPlanRecord): RecordIdRef {
+  return ensureRecordId(isExecutionPlanRecord(planId) ? planId.id : planId, TABLES.PLAN)
+}
+
+function toTaskId(taskId: RecordIdInput | ExecutionPlanTaskRecord): RecordIdRef {
+  return ensureRecordId(isExecutionPlanTaskRecord(taskId) ? taskId.id : taskId, TABLES.PLAN_TASK)
+}
+
+function toPlanIdString(planId: RecordIdInput | ExecutionPlanRecord): string {
+  return recordIdToString(toPlanId(planId), TABLES.PLAN)
+}
+
+function toTaskIdString(taskId: RecordIdInput | ExecutionPlanTaskRecord): string {
+  return recordIdToString(toTaskId(taskId), TABLES.PLAN_TASK)
+}
+
+function setDefinedOptionValue<TValue>(
+  target: Record<string, unknown>,
+  key: string,
+  value: TValue | null | undefined,
+  mapValue?: (value: TValue) => unknown,
+) {
+  if (value === undefined || value === null) return
+  target[key] = mapValue ? mapValue(value) : value
+}
+
+function pushOptionalAssignment<TValue>(
+  assignments: string[],
+  bindings: Record<string, unknown>,
+  key: string,
+  value: TValue | null | undefined,
+  mapValue?: (value: TValue) => unknown,
+) {
+  if (value === undefined) return
+  if (value === null) {
+    assignments.push(`${key} = NONE`)
+    return
+  }
+
+  assignments.push(`${key} = $${key}`)
+  bindings[key] = mapValue ? mapValue(value) : value
+}
+
+function serializeTask(task: ExecutionPlanTaskRecord): SerializableExecutionPlanTask {
+  return {
+    id: recordIdToString(task.id, TABLES.PLAN_TASK),
+    position: task.position,
+    title: task.title,
+    rationale: task.rationale,
+    kind: task.kind,
+    ownerType: task.ownerType,
+    ownerRef: task.ownerRef,
+    status: task.status,
+    resultStatus: task.resultStatus,
+    ...(task.input !== undefined ? { input: task.input } : {}),
+    outputSummary: task.outputSummary,
+    blockedReason: task.blockedReason,
+    externalRef: task.externalRef,
+    retryCount: task.retryCount,
+    idempotencyKey: task.idempotencyKey,
+    startedAt: toOptionalIsoDateTimeString(task.startedAt),
+    completedAt: toOptionalIsoDateTimeString(task.completedAt),
+  }
+}
+
+function serializeEvent(event: ExecutionPlanEventRecord): SerializableExecutionPlanEvent {
+  return {
+    id: recordIdToString(event.id, TABLES.PLAN_EVENT),
+    taskId: event.taskId ? recordIdToString(event.taskId, TABLES.PLAN_TASK) : undefined,
+    eventType: event.eventType,
+    fromStatus: event.fromStatus,
+    toStatus: event.toStatus,
+    message: event.message,
+    detail: event.detail,
+    emittedBy: event.emittedBy,
+    createdAt: toIsoDateTimeString(event.createdAt),
+  }
+}
+
+function buildProgress(tasks: ExecutionPlanTaskRecord[]) {
+  const counts = tasks.reduce(
+    (summary, task) => {
+      summary[task.status] += 1
+      return summary
+    },
+    { pending: 0, 'in-progress': 0, completed: 0, blocked: 0, failed: 0, skipped: 0 } satisfies Record<
+      ExecutionPlanTaskStatus,
+      number
+    >,
+  )
+  const total = tasks.length
+  const completedWork = counts.completed + counts.skipped
+
+  return {
+    total,
+    pending: counts.pending,
+    inProgress: counts['in-progress'],
+    completed: counts.completed,
+    blocked: counts.blocked,
+    failed: counts.failed,
+    skipped: counts.skipped,
+    completionRatio: total > 0 ? Number((completedWork / total).toFixed(4)) : undefined,
+  }
+}
+
+function findCurrentTask(
+  tasks: ExecutionPlanTaskRecord[],
+  currentTaskId: string | Record<string, unknown> | null | undefined,
+) {
+  if (currentTaskId) {
+    const normalized = recordIdToString(currentTaskId as RecordIdInput, TABLES.PLAN_TASK)
+    const matched = tasks.find((task) => recordIdToString(task.id, TABLES.PLAN_TASK) === normalized)
+    if (matched) return matched
+  }
+
+  return tasks.find((task) => task.status === 'in-progress') ?? tasks.find((task) => task.status === 'pending') ?? null
+}
+
+function assertTaskStatusTransition(
+  task: ExecutionPlanTaskRecord,
+  nextStatus: ExecutionPlanTaskStatus,
+  taskTitle: string,
+): void {
+  if (task.status === nextStatus) {
+    throw new Error(`Execution task "${taskTitle}" is already ${nextStatus}.`)
+  }
+
+  if (RESTART_REQUIRED_TASK_STATUS_SET.has(task.status)) {
+    throw new Error(`Use restartExecutionTask before changing execution task "${taskTitle}" from ${task.status}.`)
+  }
+
+  if (TASK_STATUS_TRANSITIONS[task.status].has(nextStatus)) {
+    return
+  }
+
+  throw new Error(`Cannot change execution task "${taskTitle}" from ${task.status} to ${nextStatus}.`)
+}
+
+class ExecutionPlanService {
+  private async getTaskById(taskId: RecordIdInput): Promise<ExecutionPlanTaskRecord> {
+    const recordId = ensureRecordId(taskId, TABLES.PLAN_TASK)
+    const row = await databaseService.findOne(TABLES.PLAN_TASK, { id: recordId }, ExecutionPlanTaskSchema)
+    if (!row) {
+      throw new Error(`Execution plan task not found: ${recordId.toString()}`)
+    }
+    return row
+  }
+
+  private async listPlanTasks(planId: RecordIdInput): Promise<ExecutionPlanTaskRecord[]> {
+    return await databaseService.findMany(
+      TABLES.PLAN_TASK,
+      { planId: ensureRecordId(planId, TABLES.PLAN) },
+      ExecutionPlanTaskSchema,
+      { orderBy: 'position', orderDir: 'ASC' },
+    )
+  }
+
+  private async listPlanEvents(planId: RecordIdInput, limit = 20): Promise<ExecutionPlanEventRecord[]> {
+    return (
+      await databaseService.findMany(
+        TABLES.PLAN_EVENT,
+        { planId: ensureRecordId(planId, TABLES.PLAN) },
+        ExecutionPlanEventSchema,
+        { orderBy: 'createdAt', orderDir: 'DESC', limit },
+      )
+    ).reverse()
+  }
+
+  private async emitEvent(params: {
+    planId: RecordIdInput
+    taskId?: RecordIdInput | null
+    eventType: ExecutionPlanEventRecord['eventType']
+    fromStatus?: string | null
+    toStatus?: string | null
+    message: string
+    detail?: Record<string, unknown> | null
+    emittedBy: string
+  }): Promise<void> {
+    const eventData: Record<string, unknown> = {
+      planId: ensureRecordId(params.planId, TABLES.PLAN),
+      eventType: params.eventType,
+      message: params.message,
+      emittedBy: params.emittedBy,
+    }
+    setDefinedOptionValue(eventData, 'taskId', params.taskId, (taskId) => ensureRecordId(taskId, TABLES.PLAN_TASK))
+    setDefinedOptionValue(eventData, 'fromStatus', params.fromStatus)
+    setDefinedOptionValue(eventData, 'toStatus', params.toStatus)
+    setDefinedOptionValue(eventData, 'detail', params.detail)
+
+    await databaseService.create(TABLES.PLAN_EVENT, eventData, ExecutionPlanEventSchema)
+  }
+
+  private async updatePlanStatus(params: {
+    plan: ExecutionPlanRecord
+    status: ExecutionPlanStatus
+    currentTaskId?: RecordIdInput | null
+    restartFromTaskId?: RecordIdInput | null
+    failureCount?: number
+    startedAt?: Date | null
+    completedAt?: Date | null
+    emittedBy: string
+    message?: string
+    detail?: Record<string, unknown>
+  }): Promise<ExecutionPlanRecord> {
+    const bindings: Record<string, unknown> = { status: params.status }
+    const assignments = ['status = $status']
+    pushOptionalAssignment(assignments, bindings, 'currentTaskId', params.currentTaskId, (taskId) =>
+      ensureRecordId(taskId, TABLES.PLAN_TASK),
+    )
+    pushOptionalAssignment(assignments, bindings, 'restartFromTaskId', params.restartFromTaskId, (taskId) =>
+      ensureRecordId(taskId, TABLES.PLAN_TASK),
+    )
+    if (params.failureCount !== undefined) {
+      assignments.push('failureCount = $failureCount')
+      bindings.failureCount = params.failureCount
+    }
+    pushOptionalAssignment(assignments, bindings, 'startedAt', params.startedAt)
+    pushOptionalAssignment(assignments, bindings, 'completedAt', params.completedAt)
+
+    const rows = await databaseService.query<unknown>(
+      new BoundQuery(`UPDATE ONLY ${toPlanIdString(params.plan)} SET ${assignments.join(', ')} RETURN AFTER`, bindings),
+    )
+    const next = rows.at(0) ? ExecutionPlanSchema.parse(rows[0]) : null
+
+    if (!next) {
+      throw new Error(`Failed to update execution plan ${recordIdToString(params.plan.id, TABLES.PLAN)}`)
+    }
+
+    if (params.plan.status !== next.status) {
+      await this.emitEvent({
+        planId: next.id,
+        eventType: 'plan-status-changed',
+        fromStatus: params.plan.status,
+        toStatus: next.status,
+        message: params.message ?? `Plan status changed from ${params.plan.status} to ${next.status}.`,
+        detail: params.detail,
+        emittedBy: params.emittedBy,
+      })
+    }
+
+    return next
+  }
+
+  private async updateTaskRecord(params: {
+    task: ExecutionPlanTaskRecord
+    status: ExecutionPlanTaskStatus
+    resultStatus: ExecutionPlanTaskResultStatus
+    outputSummary?: string | null
+    blockedReason?: string | null
+    externalRef?: string | null
+    startedAt?: Date | null
+    completedAt?: Date | null
+  }): Promise<ExecutionPlanTaskRecord> {
+    const bindings: Record<string, unknown> = { status: params.status, resultStatus: params.resultStatus }
+    const assignments = ['status = $status', 'resultStatus = $resultStatus']
+    pushOptionalAssignment(assignments, bindings, 'outputSummary', params.outputSummary)
+    pushOptionalAssignment(assignments, bindings, 'blockedReason', params.blockedReason)
+    pushOptionalAssignment(assignments, bindings, 'externalRef', params.externalRef)
+    pushOptionalAssignment(assignments, bindings, 'startedAt', params.startedAt)
+    pushOptionalAssignment(assignments, bindings, 'completedAt', params.completedAt)
+
+    const rows = await databaseService.query<unknown>(
+      new BoundQuery(`UPDATE ONLY ${toTaskIdString(params.task)} SET ${assignments.join(', ')} RETURN AFTER`, bindings),
+    )
+    const next = rows.at(0) ? ExecutionPlanTaskSchema.parse(rows[0]) : null
+    if (!next) {
+      throw new Error(`Failed to update execution task ${recordIdToString(params.task.id, TABLES.PLAN_TASK)}`)
+    }
+
+    return next
+  }
+
+  private async getActivePlanRecord(workstreamId: RecordIdInput): Promise<ExecutionPlanRecord | null> {
+    const plans = await databaseService.findMany(
+      TABLES.PLAN,
+      { workstreamId: ensureRecordId(workstreamId, TABLES.WORKSTREAM) },
+      ExecutionPlanSchema,
+      { orderBy: 'updatedAt', orderDir: 'DESC' },
+    )
+
+    return plans.find((plan) => ACTIVE_PLAN_STATUS_SET.has(plan.status)) ?? null
+  }
+
+  private async collectCarriedTasks(plan: ExecutionPlanRecord): Promise<SerializableExecutionPlanCarriedTask[]> {
+    const carried: SerializableExecutionPlanCarriedTask[] = []
+    let currentReplacedPlanId = plan.replacedPlanId ? ensureRecordId(plan.replacedPlanId, TABLES.PLAN) : null
+    let depth = 0
+
+    while (currentReplacedPlanId && depth < 5) {
+      const previousPlan = await databaseService.findOne(
+        TABLES.PLAN,
+        { id: currentReplacedPlanId },
+        ExecutionPlanSchema,
+      )
+      if (!previousPlan) break
+
+      const previousTasks = await this.listPlanTasks(previousPlan.id)
+      const currentPlanId = recordIdToString(previousPlan.id, TABLES.PLAN)
+      carried.unshift(
+        ...previousTasks
+          .filter(
+            (task) =>
+              CARRIED_RESULT_STATUS_SET.has(task.resultStatus) &&
+              typeof task.outputSummary === 'string' &&
+              task.outputSummary.trim().length > 0,
+          )
+          .map((task) => ({
+            planId: currentPlanId,
+            taskId: recordIdToString(task.id, TABLES.PLAN_TASK),
+            title: task.title,
+            resultStatus: task.resultStatus,
+            outputSummary: task.outputSummary ?? '',
+          })),
+      )
+
+      currentReplacedPlanId = previousPlan.replacedPlanId
+        ? ensureRecordId(previousPlan.replacedPlanId, TABLES.PLAN)
+        : null
+      depth += 1
+    }
+
+    return carried
+  }
+
+  private async toSerializablePlan(
+    plan: ExecutionPlanRecord,
+    options?: { includeEvents?: boolean },
+  ): Promise<SerializableExecutionPlan> {
+    const tasks = await this.listPlanTasks(plan.id)
+    const recentEvents = options?.includeEvents ? await this.listPlanEvents(plan.id, 20) : []
+    const carriedTasks = await this.collectCarriedTasks(plan)
+    const currentTask = findCurrentTask(tasks, plan.currentTaskId)
+
+    return {
+      planId: recordIdToString(plan.id, TABLES.PLAN),
+      workstreamId: recordIdToString(plan.workstreamId, TABLES.WORKSTREAM),
+      organizationId: recordIdToString(plan.organizationId, TABLES.ORGANIZATION),
+      title: plan.title,
+      objective: plan.objective,
+      status: plan.status,
+      leadAgentId: plan.leadAgentId,
+      currentTaskId: currentTask ? recordIdToString(currentTask.id, TABLES.PLAN_TASK) : undefined,
+      restartFromTaskId: plan.restartFromTaskId
+        ? recordIdToString(plan.restartFromTaskId, TABLES.PLAN_TASK)
+        : undefined,
+      replacedPlanId: plan.replacedPlanId ? recordIdToString(plan.replacedPlanId, TABLES.PLAN) : undefined,
+      failureCount: plan.failureCount,
+      startedAt: toOptionalIsoDateTimeString(plan.startedAt),
+      completedAt: toOptionalIsoDateTimeString(plan.completedAt),
+      progress: buildProgress(tasks),
+      tasks: tasks.map(serializeTask),
+      recentEvents: recentEvents.map(serializeEvent),
+      carriedTasks,
+    }
+  }
+
+  private buildToolResult(params: {
+    action: ExecutionPlanToolResultData['action']
+    plan: SerializableExecutionPlan | null
+    message?: string
+    changedTaskId?: string
+  }): ExecutionPlanToolResultData {
+    return {
+      action: params.action,
+      ...(params.message ? { message: params.message } : {}),
+      ...(params.changedTaskId !== undefined ? { changedTaskId: params.changedTaskId } : {}),
+      ...(params.plan ? { plan: params.plan } : {}),
+      hasPlan: params.plan !== null,
+      status: params.plan?.status,
+    }
+  }
+
+  async hasActivePlan(workstreamId: RecordIdInput): Promise<boolean> {
+    return (await this.getActivePlanRecord(workstreamId)) !== null
+  }
+
+  async getActivePlanForWorkstream(
+    workstreamId: RecordIdInput,
+    options?: { includeEvents?: boolean },
+  ): Promise<SerializableExecutionPlan | null> {
+    const plan = await this.getActivePlanRecord(workstreamId)
+    if (!plan) return null
+    return await this.toSerializablePlan(plan, options)
+  }
+
+  async createPlan(params: {
+    organizationId: RecordIdInput
+    workstreamId: RecordIdInput
+    leadAgentId: ExecutionPlanRecord['leadAgentId']
+    input: CreateExecutionPlanArgs
+  }): Promise<ExecutionPlanToolResultData> {
+    const activePlan = await this.getActivePlanRecord(params.workstreamId)
+    if (activePlan) {
+      throw new Error('An active execution plan already exists for this workstream. Replace it instead.')
+    }
+
+    const planId = new RecordId(TABLES.PLAN, Bun.randomUUIDv7())
+    const taskIds = params.input.tasks.map(() => new RecordId(TABLES.PLAN_TASK, Bun.randomUUIDv7()))
+    const organizationId = ensureRecordId(params.organizationId, TABLES.ORGANIZATION)
+    const workstreamId = ensureRecordId(params.workstreamId, TABLES.WORKSTREAM)
+    const planData: Record<string, unknown> = {
+      organizationId,
+      workstreamId,
+      title: params.input.title,
+      objective: params.input.objective,
+      status: 'draft',
+      leadAgentId: params.leadAgentId,
+      currentTaskId: taskIds[0],
+      failureCount: 0,
+    }
+
+    const plan = await databaseService.createWithId(TABLES.PLAN, planId, planData, ExecutionPlanSchema)
+
+    for (const [index, task] of params.input.tasks.entries()) {
+      const taskData: Record<string, unknown> = {
+        planId,
+        organizationId,
+        workstreamId,
+        position: index,
+        title: task.title,
+        rationale: task.rationale,
+        kind: task.kind,
+        ownerType: task.ownerType,
+        ownerRef: task.ownerRef,
+        status: 'pending',
+        resultStatus: 'not-started',
+        retryCount: 0,
+        idempotencyKey: `${planId.toString()}:${index}`,
+      }
+      setDefinedOptionValue(taskData, 'input', task.input, normalizeTaskInput)
+
+      await databaseService.createWithId(TABLES.PLAN_TASK, taskIds[index], taskData, ExecutionPlanTaskSchema)
+    }
+
+    await this.emitEvent({
+      planId: plan.id,
+      eventType: 'plan-created',
+      message: `Created execution plan "${plan.title}" with ${params.input.tasks.length} tasks.`,
+      detail: { title: plan.title, objective: plan.objective, taskCount: params.input.tasks.length },
+      emittedBy: params.leadAgentId,
+    })
+
+    const serializable = await this.toSerializablePlan(plan, { includeEvents: true })
+    return this.buildToolResult({
+      action: 'created',
+      plan: serializable,
+      message: `Created execution plan "${plan.title}".`,
+    })
+  }
+
+  async replacePlan(params: {
+    workstreamId: RecordIdInput
+    organizationId: RecordIdInput
+    leadAgentId: ExecutionPlanRecord['leadAgentId']
+    input: ReplaceExecutionPlanArgs
+  }): Promise<ExecutionPlanToolResultData> {
+    const activePlan = await this.getActivePlanRecord(params.workstreamId)
+    if (!activePlan) {
+      throw new Error('No active execution plan exists for this workstream.')
+    }
+    if (recordIdToString(activePlan.id, TABLES.PLAN) !== params.input.planId) {
+      throw new Error('Only the active execution plan can be replaced.')
+    }
+
+    const oldPlan = await this.updatePlanStatus({
+      plan: activePlan,
+      status: 'aborted',
+      currentTaskId: activePlan.currentTaskId,
+      restartFromTaskId: activePlan.restartFromTaskId,
+      emittedBy: params.leadAgentId,
+      message: `Plan "${activePlan.title}" was replaced.`,
+      detail: { reason: params.input.reason },
+    })
+
+    const planId = new RecordId(TABLES.PLAN, Bun.randomUUIDv7())
+    const taskIds = params.input.tasks.map(() => new RecordId(TABLES.PLAN_TASK, Bun.randomUUIDv7()))
+    const organizationId = ensureRecordId(params.organizationId, TABLES.ORGANIZATION)
+    const workstreamId = ensureRecordId(params.workstreamId, TABLES.WORKSTREAM)
+    const nextPlanData: Record<string, unknown> = {
+      organizationId,
+      workstreamId,
+      title: params.input.title,
+      objective: params.input.objective,
+      status: 'draft',
+      leadAgentId: params.leadAgentId,
+      currentTaskId: taskIds[0],
+      replacedPlanId: ensureRecordId(oldPlan.id, TABLES.PLAN),
+      failureCount: 0,
+    }
+
+    const nextPlan = await databaseService.createWithId(TABLES.PLAN, planId, nextPlanData, ExecutionPlanSchema)
+
+    for (const [index, task] of params.input.tasks.entries()) {
+      const taskData: Record<string, unknown> = {
+        planId,
+        organizationId,
+        workstreamId,
+        position: index,
+        title: task.title,
+        rationale: task.rationale,
+        kind: task.kind,
+        ownerType: task.ownerType,
+        ownerRef: task.ownerRef,
+        status: 'pending',
+        resultStatus: 'not-started',
+        retryCount: 0,
+        idempotencyKey: `${planId.toString()}:${index}`,
+      }
+      setDefinedOptionValue(taskData, 'input', task.input, normalizeTaskInput)
+
+      await databaseService.createWithId(TABLES.PLAN_TASK, taskIds[index], taskData, ExecutionPlanTaskSchema)
+    }
+
+    await this.emitEvent({
+      planId: oldPlan.id,
+      eventType: 'replan',
+      message: `Created replacement plan "${nextPlan.title}".`,
+      detail: {
+        reason: params.input.reason,
+        oldPlanId: recordIdToString(oldPlan.id, TABLES.PLAN),
+        newPlanId: recordIdToString(nextPlan.id, TABLES.PLAN),
+      },
+      emittedBy: params.leadAgentId,
+    })
+    await this.emitEvent({
+      planId: nextPlan.id,
+      eventType: 'plan-created',
+      message: `Created execution plan "${nextPlan.title}" with ${params.input.tasks.length} tasks.`,
+      detail: {
+        title: nextPlan.title,
+        objective: nextPlan.objective,
+        taskCount: params.input.tasks.length,
+        replacedPlanId: recordIdToString(oldPlan.id, TABLES.PLAN),
+      },
+      emittedBy: params.leadAgentId,
+    })
+    await this.emitEvent({
+      planId: nextPlan.id,
+      eventType: 'plan-replaced',
+      message: `Plan "${nextPlan.title}" replaces "${oldPlan.title}".`,
+      detail: { reason: params.input.reason, replacedPlanId: recordIdToString(oldPlan.id, TABLES.PLAN) },
+      emittedBy: params.leadAgentId,
+    })
+
+    const serializable = await this.toSerializablePlan(nextPlan, { includeEvents: true })
+    return this.buildToolResult({
+      action: 'replaced',
+      plan: serializable,
+      message: `Replaced execution plan with "${nextPlan.title}".`,
+    })
+  }
+
+  async getActivePlanToolResult(params: {
+    workstreamId: RecordIdInput
+    includeEvents?: boolean
+  }): Promise<ExecutionPlanToolResultData> {
+    const plan = await this.getActivePlanForWorkstream(params.workstreamId, { includeEvents: params.includeEvents })
+    return this.buildToolResult({
+      action: plan ? 'loaded' : 'none',
+      plan,
+      ...(plan ? { message: `Loaded execution plan "${plan.title}".` } : { message: 'No active execution plan.' }),
+    })
+  }
+
+  async setTaskStatus(params: {
+    workstreamId: RecordIdInput
+    emittedBy: string
+    input: SetExecutionTaskStatusArgs
+  }): Promise<ExecutionPlanToolResultData> {
+    const activePlan = await this.getActivePlanRecord(params.workstreamId)
+    if (!activePlan) {
+      throw new Error('No active execution plan exists for this workstream.')
+    }
+    if (recordIdToString(activePlan.id, TABLES.PLAN) !== params.input.planId) {
+      throw new Error('Task updates must target the active execution plan.')
+    }
+
+    const task = await this.getTaskById(params.input.taskId)
+    if (recordIdToString(task.planId, TABLES.PLAN) !== params.input.planId) {
+      throw new Error('Execution task does not belong to the provided plan.')
+    }
+    assertTaskStatusTransition(task, params.input.status, task.title)
+
+    const tasks = await this.listPlanTasks(activePlan.id)
+    const otherInProgressTask = tasks.find(
+      (candidate) =>
+        candidate.status === 'in-progress' &&
+        recordIdToString(candidate.id, TABLES.PLAN_TASK) !== recordIdToString(task.id, TABLES.PLAN_TASK),
+    )
+    if (params.input.status === 'in-progress' && otherInProgressTask) {
+      throw new Error('Only one execution-plan task may be in progress at a time.')
+    }
+
+    if (params.input.status === 'pending') {
+      throw new Error('Use restartExecutionTask to reset a task back to pending.')
+    }
+
+    if (params.input.status === 'completed') {
+      if (!params.input.resultStatus) {
+        throw new Error('Completed tasks require resultStatus.')
+      }
+      if (!SUCCESSFUL_RESULT_STATUS_SET.has(params.input.resultStatus)) {
+        throw new Error('Completed tasks require resultStatus to be success or partial.')
+      }
+      if (!params.input.outputSummary?.trim() && !params.input.externalRef?.trim()) {
+        throw new Error('Completed tasks require outputSummary or externalRef.')
+      }
+    }
+
+    if (params.input.status === 'blocked' && !params.input.blockedReason?.trim()) {
+      throw new Error('Blocked tasks require blockedReason.')
+    }
+
+    if (params.input.status === 'failed' && !params.input.outputSummary?.trim()) {
+      throw new Error('Failed tasks require outputSummary.')
+    }
+
+    const now = new Date()
+    let nextPlan = activePlan
+    let nextResultStatus = task.resultStatus
+    let nextFailureCount = activePlan.failureCount
+    let taskStartedAt: Date | null | undefined = task.startedAt
+      ? undefined
+      : params.input.status === 'in-progress'
+        ? now
+        : undefined
+    let taskCompletedAt: Date | null | undefined = undefined
+    let message = ''
+
+    if (params.input.status === 'in-progress') {
+      nextPlan = await this.updatePlanStatus({
+        plan: activePlan,
+        status: 'executing',
+        currentTaskId: task.id,
+        restartFromTaskId: null,
+        ...(activePlan.startedAt ? {} : { startedAt: now }),
+        emittedBy: params.emittedBy,
+      })
+      nextResultStatus = task.resultStatus
+      message = `Started task "${task.title}".`
+    } else if (params.input.status === 'completed' || params.input.status === 'skipped') {
+      nextResultStatus =
+        params.input.status === 'completed'
+          ? ExecutionPlanTaskResultStatusSchema.parse(params.input.resultStatus)
+          : (params.input.resultStatus ?? 'not-started')
+      taskCompletedAt = now
+
+      const refreshedTasks = tasks.map((candidate) =>
+        recordIdToString(candidate.id, TABLES.PLAN_TASK) === recordIdToString(task.id, TABLES.PLAN_TASK)
+          ? { ...candidate, status: params.input.status, resultStatus: nextResultStatus }
+          : candidate,
+      )
+      const nextPendingTask =
+        refreshedTasks.find((candidate) => candidate.position > task.position && candidate.status === 'pending') ??
+        refreshedTasks.find((candidate) => candidate.status === 'pending') ??
+        null
+
+      if (nextPendingTask) {
+        nextPlan = await this.updatePlanStatus({
+          plan: activePlan,
+          status: 'executing',
+          currentTaskId: nextPendingTask.id,
+          restartFromTaskId: null,
+          failureCount: 0,
+          emittedBy: params.emittedBy,
+        })
+      } else {
+        nextPlan = await this.updatePlanStatus({
+          plan: activePlan,
+          status: 'completed',
+          currentTaskId: null,
+          restartFromTaskId: null,
+          failureCount: 0,
+          completedAt: now,
+          ...(activePlan.startedAt ? {} : { startedAt: now }),
+          emittedBy: params.emittedBy,
+        })
+      }
+
+      nextFailureCount = 0
+      message =
+        params.input.status === 'completed' ? `Completed task "${task.title}".` : `Skipped task "${task.title}".`
+    } else {
+      nextFailureCount = activePlan.failureCount + 1
+      nextResultStatus =
+        params.input.status === 'failed'
+          ? 'failed'
+          : (params.input.resultStatus ?? (params.input.outputSummary?.trim() ? 'partial' : task.resultStatus))
+      nextPlan = await this.updatePlanStatus({
+        plan: activePlan,
+        status: 'blocked',
+        currentTaskId: task.id,
+        restartFromTaskId: task.id,
+        failureCount: nextFailureCount,
+        emittedBy: params.emittedBy,
+      })
+      if (params.input.status === 'failed') {
+        taskCompletedAt = now
+      }
+      message = params.input.status === 'failed' ? `Task "${task.title}" failed.` : `Task "${task.title}" is blocked.`
+    }
+
+    const updatedTask = await this.updateTaskRecord({
+      task,
+      status: params.input.status,
+      resultStatus: nextResultStatus,
+      ...(params.input.outputSummary !== undefined ? { outputSummary: params.input.outputSummary || null } : {}),
+      ...(params.input.blockedReason !== undefined ? { blockedReason: params.input.blockedReason || null } : {}),
+      ...(params.input.externalRef !== undefined ? { externalRef: params.input.externalRef || null } : {}),
+      ...(params.input.status === 'in-progress' && taskStartedAt ? { startedAt: taskStartedAt } : {}),
+      ...(taskCompletedAt !== undefined ? { completedAt: taskCompletedAt } : {}),
+    })
+
+    const eventType =
+      params.input.status === 'in-progress'
+        ? 'task-started'
+        : params.input.status === 'completed'
+          ? 'task-completed'
+          : params.input.status === 'blocked'
+            ? 'task-blocked'
+            : params.input.status === 'failed'
+              ? 'task-failed'
+              : 'task-skipped'
+
+    await this.emitEvent({
+      planId: nextPlan.id,
+      taskId: updatedTask.id,
+      eventType,
+      fromStatus: task.status,
+      toStatus: updatedTask.status,
+      message,
+      detail: {
+        resultStatus: updatedTask.resultStatus,
+        outputSummary: updatedTask.outputSummary,
+        blockedReason: updatedTask.blockedReason,
+        externalRef: updatedTask.externalRef,
+        failureCount: nextFailureCount,
+      },
+      emittedBy: params.emittedBy,
+    })
+
+    const serializable = await this.toSerializablePlan(nextPlan, { includeEvents: true })
+    return this.buildToolResult({
+      action: 'task-status-updated',
+      plan: serializable,
+      message:
+        nextFailureCount >= 2 && nextPlan.status === 'blocked'
+          ? `${message} Failure budget reached; the plan is paused until it is restarted or replaced.`
+          : message,
+      changedTaskId: recordIdToString(updatedTask.id, TABLES.PLAN_TASK),
+    })
+  }
+
+  async restartTask(params: {
+    workstreamId: RecordIdInput
+    emittedBy: string
+    input: RestartExecutionTaskArgs
+  }): Promise<ExecutionPlanToolResultData> {
+    const activePlan = await this.getActivePlanRecord(params.workstreamId)
+    if (!activePlan) {
+      throw new Error('No active execution plan exists for this workstream.')
+    }
+    if (recordIdToString(activePlan.id, TABLES.PLAN) !== params.input.planId) {
+      throw new Error('Only the active execution plan can restart tasks.')
+    }
+
+    const tasks = await this.listPlanTasks(activePlan.id)
+    const targetTask = tasks.find((task) => recordIdToString(task.id, TABLES.PLAN_TASK) === params.input.taskId)
+    if (!targetTask) {
+      throw new Error('Execution plan task not found for restart.')
+    }
+    if (targetTask.status !== 'blocked' && targetTask.status !== 'failed') {
+      throw new Error('Only blocked or failed execution tasks can be restarted.')
+    }
+
+    for (const task of tasks) {
+      const shouldReset =
+        recordIdToString(task.id, TABLES.PLAN_TASK) === params.input.taskId ||
+        (params.input.resetDownstream && task.position > targetTask.position)
+
+      if (!shouldReset) continue
+
+      const nextStatus: ExecutionPlanTaskStatus = 'pending'
+      await this.updateTaskRecord({
+        task,
+        status: nextStatus,
+        resultStatus: 'not-started',
+        outputSummary: null,
+        blockedReason: null,
+        externalRef: null,
+        startedAt: null,
+        completedAt: null,
+      })
+    }
+
+    const nextPlan = await this.updatePlanStatus({
+      plan: activePlan,
+      status: 'executing',
+      currentTaskId: targetTask.id,
+      restartFromTaskId: targetTask.id,
+      failureCount: 0,
+      completedAt: null,
+      ...(activePlan.startedAt ? {} : { startedAt: new Date() }),
+      emittedBy: params.emittedBy,
+    })
+
+    await this.emitEvent({
+      planId: nextPlan.id,
+      taskId: targetTask.id,
+      eventType: 'task-restarted',
+      fromStatus: targetTask.status,
+      toStatus: 'pending',
+      message: `Restarted task "${targetTask.title}".`,
+      detail: { resetDownstream: params.input.resetDownstream },
+      emittedBy: params.emittedBy,
+    })
+
+    const serializable = await this.toSerializablePlan(nextPlan, { includeEvents: true })
+    return this.buildToolResult({
+      action: 'task-restarted',
+      plan: serializable,
+      changedTaskId: recordIdToString(targetTask.id, TABLES.PLAN_TASK),
+      message: `Restarted task "${targetTask.title}".`,
+    })
+  }
+}
+
+export const executionPlanService = new ExecutionPlanService()