@lota-sdk/core 0.4.7 → 0.4.9

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

@@ -0,0 +1,1041 @@
+import type {
+  ChatMessage,
+  ExecutionPlanQueryArgs,
+  PlanDraft,
+  PlanRunRecord,
+  SerializableExecutionPlan,
+  SubmitPlanTurnResultArgs,
+  SubmitExecutionNodeResultArgs,
+} from '@lota-sdk/shared'
+import { PlanDraftSchema, PlanRunSchema, PlanSpecSchema } from '@lota-sdk/shared'
+import { Context, Schema, Effect, Layer, Match } from 'effect'
+import { RecordId } from 'surrealdb'
+
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId, recordIdToString } from '../../db/record-id'
+import type { SurrealDBService } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { BadRequestError } from '../../effect/errors'
+import { makeEffectTryPromiseWithMessage } from '../../effect/helpers'
+import { DatabaseServiceTag } from '../../effect/services'
+import { extractMessageText } from '../../runtime/thread-chat-helpers'
+import { nowDate } from '../../utils/date-time'
+import type { makeOwnershipDispatcherService } from '../ownership-dispatcher.service'
+import { OwnershipDispatcherServiceTag } from '../ownership-dispatcher.service'
+import type { makePlanBuilderService } from '../plan/plan-builder.service'
+import { PlanBuilderServiceTag } from '../plan/plan-builder.service'
+import type { makePlanCheckpointService } from '../plan/plan-checkpoint.service'
+import { PlanCheckpointServiceTag } from '../plan/plan-checkpoint.service'
+import type { makePlanCompilerService } from '../plan/plan-compiler.service'
+import { PlanCompilerServiceTag } from '../plan/plan-compiler.service'
+import type { makePlanEventDeliveryService } from '../plan/plan-event-delivery.service'
+import { PlanEventDeliveryServiceTag } from '../plan/plan-event-delivery.service'
+import type { HumanNodeResponsePayload } from '../plan/plan-executor-helpers'
+import { attachCheckpoint, emitEvent, saveCheckpoint } from '../plan/plan-executor-persistence'
+import type { makePlanExecutorService } from '../plan/plan-executor.service'
+import { PlanExecutorServiceTag } from '../plan/plan-executor.service'
+import { buildExecutionPlanToolResult, toRunData } from '../plan/plan-run-data'
+import { serializeRunFull } from '../plan/plan-run-serialization'
+import type { makePlanRunService } from '../plan/plan-run.service'
+import { PlanRunServiceTag } from '../plan/plan-run.service'
+import type { makePlanSchedulerService } from '../plan/plan-scheduler.service'
+import { PlanSchedulerServiceTag } from '../plan/plan-scheduler.service'
+import { withTransactionAndEventsEffect } from '../plan/plan-transaction-events'
+import type { makePlanValidatorService } from '../plan/plan-validator.service'
+import { PlanValidatorServiceTag } from '../plan/plan-validator.service'
+import { buildApprovalResponseFromMessages } from './execution-plan-approval'
+import {
+  aggregateBlockingIssues,
+  hasCrossThreadSourceContext,
+  isPlanVisibleInThreadContext,
+} from './execution-plan-context'
+import { createInitializedRunGraph } from './execution-plan-graph'
+import { attachPlanScheduleIfNeeded } from './execution-plan-schedule'
+import { buildCompiledSpecCreateData, toSpecData } from './execution-plan-spec'
+
+interface ExecutionPlanDeps {
+  db: SurrealDBService
+  ownershipDispatcher: ReturnType<typeof makeOwnershipDispatcherService>
+  planBuilder: ReturnType<typeof makePlanBuilderService>
+  planCheckpoint: ReturnType<typeof makePlanCheckpointService>
+  planCompiler: ReturnType<typeof makePlanCompilerService>
+  planEventDelivery: ReturnType<typeof makePlanEventDeliveryService>
+  planExecutor: ReturnType<typeof makePlanExecutorService>
+  planRun: ReturnType<typeof makePlanRunService>
+  planScheduler: ReturnType<typeof makePlanSchedulerService>
+  planValidator: ReturnType<typeof makePlanValidatorService>
+}
+
+type PreparedPlanDraft = Parameters<ExecutionPlanDeps['planValidator']['validateDraft']>[0]
+
+function saveCheckpointWithService(
+  deps: ExecutionPlanDeps,
+  params: Omit<Parameters<typeof saveCheckpoint>[0], 'planCheckpointService'>,
+) {
+  return saveCheckpoint({ ...params, planCheckpointService: deps.planCheckpoint })
+}
+
+class ExecutionPlanServiceError extends Schema.TaggedErrorClass<ExecutionPlanServiceError>()(
+  'ExecutionPlanServiceError',
+  { message: Schema.String, cause: Schema.optional(Schema.Defect) },
+) {}
+
+const effectTryPromise = makeEffectTryPromiseWithMessage(
+  (message, cause) => new ExecutionPlanServiceError({ message, cause }),
+)
+
+function toSerializablePlanEffect(
+  deps: ExecutionPlanDeps,
+  run: PlanRunRecord,
+  options?: Partial<ExecutionPlanQueryArgs>,
+) {
+  return deps.planRun
+    .toSerializablePlan(run, {
+      includeEvents: options?.includeEvents,
+      includeArtifacts: options?.includeArtifacts,
+      includeApprovals: options?.includeApprovals,
+      includeCheckpoints: options?.includeCheckpoints,
+      includeValidationIssues: options?.includeValidationIssues,
+    })
+    .pipe(
+      Effect.mapError(
+        (cause) => new ExecutionPlanServiceError({ message: 'Failed to serialize execution plan.', cause }),
+      ),
+    )
+}
+
+function serializeRunsEffect(
+  deps: ExecutionPlanDeps,
+  runs: PlanRunRecord[],
+  options?: Partial<ExecutionPlanQueryArgs>,
+) {
+  return Effect.all(runs.map((run) => toSerializablePlanEffect(deps, run, options)))
+}
+
+function assertDispatchExecutorsEffect(
+  deps: ExecutionPlanDeps,
+  preparedDraft: PreparedPlanDraft,
+): Effect.Effect<void, BadRequestError> {
+  return Effect.gen(function* () {
+    const issues = deps.ownershipDispatcher.validateDraftExecutors(preparedDraft)
+    if (issues.length > 0) {
+      return yield* new BadRequestError({ message: `Plan draft failed validation: ${aggregateBlockingIssues(issues)}` })
+    }
+  })
+}
+
+function finalizePlanSnapshotEffect(deps: ExecutionPlanDeps, params: { runId: RecordIdInput; emittedBy: string }) {
+  return deps.ownershipDispatcher
+    .dispatchRunToStableBoundary({ runId: params.runId, emittedBy: params.emittedBy })
+    .pipe(
+      Effect.mapError(
+        (cause) => new ExecutionPlanServiceError({ message: 'Failed to finalize execution plan snapshot.', cause }),
+      ),
+    )
+}
+
+function hasActivePlanEffect(deps: ExecutionPlanDeps, threadId: RecordIdInput) {
+  return Effect.gen(function* () {
+    const run = yield* deps.planRun.getActiveRunRecord(threadId)
+    return run !== null
+  })
+}
+
+function getActivePlanForThreadEffect(
+  deps: ExecutionPlanDeps,
+  threadId: RecordIdInput,
+  options?: Partial<ExecutionPlanQueryArgs> & { runId?: RecordIdInput },
+) {
+  return Effect.gen(function* () {
+    const plans = yield* getActivePlansForThreadEffect(deps, threadId, options)
+    return plans[0] ?? null
+  })
+}
+
+function getActivePlansForThreadEffect(
+  deps: ExecutionPlanDeps,
+  threadId: RecordIdInput,
+  options?: Partial<ExecutionPlanQueryArgs> & { runId?: RecordIdInput },
+) {
+  return Effect.gen(function* () {
+    const runId = options?.runId
+    if (runId) {
+      const run = yield* deps.planRun.getRunById(runId)
+      const plan = yield* toSerializablePlanEffect(deps, run, options)
+      return [plan]
+    }
+
+    const runs = yield* deps.planRun.getActiveRunRecords(threadId)
+    if (runs.length === 0) return []
+    return yield* serializeRunsEffect(deps, runs, options)
+  })
+}
+
+function getPlansCreatedInContextEffect(params: {
+  deps: ExecutionPlanDeps
+  organizationId: RecordIdInput
+  sourceThreadId?: RecordIdInput
+  createdByAgentId?: string
+  statuses?: ReadonlyArray<PlanRunRecord['status']>
+  includeEvents?: boolean
+  includeArtifacts?: boolean
+  includeApprovals?: boolean
+  includeCheckpoints?: boolean
+  includeValidationIssues?: boolean
+}) {
+  return Effect.gen(function* () {
+    const runs = yield* params.deps.planRun.getRunsCreatedInContext({
+      organizationId: params.organizationId,
+      sourceThreadId: params.sourceThreadId,
+      createdByAgentId: params.createdByAgentId,
+      statuses: params.statuses,
+    })
+    if (runs.length === 0) return []
+    return yield* serializeRunsEffect(params.deps, runs, params)
+  })
+}
+
+function listActivePlanSummariesEffect(deps: ExecutionPlanDeps, threadId: RecordIdInput) {
+  return Effect.gen(function* () {
+    const runs = yield* deps.planRun.getActiveRunRecords(threadId)
+    const plans = yield* Effect.all(
+      runs.map((run) =>
+        Effect.gen(function* () {
+          const [spec, nodeRuns] = yield* Effect.all([
+            deps.planRun.getPlanSpecById(run.planSpecId),
+            deps.planRun.listNodeRuns(run.id),
+          ])
+
+          return {
+            runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+            title: spec.title,
+            status: run.status,
+            objective: spec.objective,
+            nodeCount: nodeRuns.length,
+            completedCount: nodeRuns.filter((nodeRun) => nodeRun.status === 'completed' || nodeRun.status === 'partial')
+              .length,
+            failedCount: nodeRuns.filter((nodeRun) => nodeRun.status === 'failed').length,
+          }
+        }),
+      ),
+    )
+
+    return { plans, totalCount: plans.length }
+  })
+}
+
+function getActivePlanToolResultEffect(
+  deps: ExecutionPlanDeps,
+  params: {
+    threadId: RecordIdInput
+    runId?: string
+    includeEvents?: boolean
+    includeArtifacts?: boolean
+    includeApprovals?: boolean
+    includeCheckpoints?: boolean
+    includeValidationIssues?: boolean
+  },
+) {
+  const serializeOptions = {
+    includeEvents: params.includeEvents,
+    includeArtifacts: params.includeArtifacts,
+    includeApprovals: params.includeApprovals,
+    includeCheckpoints: params.includeCheckpoints,
+    includeValidationIssues: params.includeValidationIssues,
+  }
+
+  return Effect.gen(function* () {
+    const runId = params.runId
+    if (runId) {
+      const run = yield* deps.planRun.getRunById(runId)
+      const plan = yield* toSerializablePlanEffect(deps, run, serializeOptions)
+      return buildExecutionPlanToolResult({ action: 'loaded', plan, message: `Loaded execution run "${plan.title}".` })
+    }
+
+    const runs = yield* deps.planRun.getActiveRunRecords(params.threadId)
+    if (runs.length === 0) {
+      return buildExecutionPlanToolResult({ action: 'none', plan: null, message: 'No active execution run.' })
+    }
+
+    const plan = yield* toSerializablePlanEffect(deps, runs[0], serializeOptions)
+    return buildExecutionPlanToolResult({
+      action: 'loaded',
+      plan,
+      message:
+        runs.length === 1
+          ? `Loaded execution run "${plan.title}".`
+          : `Loaded ${runs.length} active execution runs. Showing most recent: "${plan.title}".`,
+    })
+  })
+}
+
+function createPlanEffect(
+  deps: ExecutionPlanDeps,
+  params: {
+    organizationId: RecordIdInput
+    threadId: RecordIdInput
+    sourceThreadId?: RecordIdInput
+    leadAgentId: string
+    createdByAgentId?: string
+    requireApproval?: boolean
+    input: PlanDraft
+  },
+) {
+  return Effect.gen(function* () {
+    const databaseService = deps.db
+    const requireApproval =
+      params.requireApproval ?? hasCrossThreadSourceContext(params.sourceThreadId, params.threadId)
+    const preparedDraft = deps.planBuilder.prepareDraft(PlanDraftSchema.parse(params.input))
+    const validation = deps.planValidator.validateDraft(preparedDraft)
+    if (validation.blocking.length > 0) {
+      return yield* new BadRequestError({
+        message: `Plan draft failed validation: ${aggregateBlockingIssues(validation.blocking)}`,
+      })
+    }
+    yield* assertDispatchExecutorsEffect(deps, preparedDraft)
+    const compiled = yield* deps.planCompiler.compile(preparedDraft)
+
+    const specId = new RecordId(TABLES.PLAN_SPEC, Bun.randomUUIDv7())
+    const runId = new RecordId(TABLES.PLAN_RUN, Bun.randomUUIDv7())
+
+    yield* withTransactionAndEventsEffect({
+      db: databaseService,
+      planEventDeliveryService: deps.planEventDelivery,
+      run: (tx, emittedEvents) =>
+        Effect.gen(function* () {
+          const createdSpec = yield* effectTryPromise(
+            () =>
+              tx
+                .create(specId)
+                .content(
+                  buildCompiledSpecCreateData({
+                    organizationId: params.organizationId,
+                    threadId: params.threadId,
+                    leadAgentId: params.leadAgentId,
+                    compiled,
+                    version: 1,
+                  }),
+                )
+                .output('after'),
+            'Failed to create execution plan spec.',
+          )
+          const spec = PlanSpecSchema.parse(createdSpec)
+
+          yield* effectTryPromise(
+            () =>
+              createInitializedRunGraph({
+                tx,
+                runId,
+                spec,
+                organizationId: params.organizationId,
+                threadId: params.threadId,
+                sourceThreadId: params.sourceThreadId,
+                leadAgentId: params.leadAgentId,
+                createdByAgentId: params.createdByAgentId,
+                requireApproval,
+                nodes: compiled.nodes,
+                emittedEvents,
+                createdEventType: 'plan-created',
+                createdEventMessage: `Created execution plan "${spec.title}".`,
+                createdEventDetail: { title: spec.title, objective: spec.objective },
+                checkpointReason: 'plan-created',
+                planExecutor: deps.planExecutor,
+              }),
+            'Failed to initialize execution plan graph.',
+          )
+        }),
+    })
+
+    if (!requireApproval) {
+      yield* effectTryPromise(
+        () =>
+          attachPlanScheduleIfNeeded({
+            db: databaseService,
+            planRunService: deps.planRun,
+            planSchedulerService: deps.planScheduler,
+            organizationId: params.organizationId,
+            threadId: params.threadId,
+            runId,
+            planSpecId: specId,
+          }),
+        'Failed to attach execution plan schedule.',
+      )
+    }
+
+    const plan = yield* finalizePlanSnapshotEffect(deps, { runId, emittedBy: params.leadAgentId })
+    return buildExecutionPlanToolResult({ action: 'created', plan, message: `Created execution plan "${plan.title}".` })
+  })
+}
+
+function replacePlanEffect(
+  deps: ExecutionPlanDeps,
+  params: {
+    threadId: RecordIdInput
+    organizationId: RecordIdInput
+    leadAgentId: string
+    createdByAgentId?: string
+    input: PlanDraft & { runId: string; reason: string; requireApproval?: boolean }
+  },
+) {
+  return Effect.gen(function* () {
+    const databaseService = deps.db
+    const activeRun = yield* deps.planRun.getRunById(params.input.runId)
+    const resolvedThreadId = activeRun.threadId
+    const activeRuns = yield* deps.planRun.getActiveRunRecords(resolvedThreadId)
+    if (activeRuns.length === 0) {
+      return yield* new BadRequestError({ message: 'No active execution run exists for this thread.' })
+    }
+    if (!activeRuns.some((run) => recordIdToString(run.id, TABLES.PLAN_RUN) === params.input.runId)) {
+      return yield* new BadRequestError({ message: 'Only an active execution run can be replaced.' })
+    }
+
+    const activeSpec = yield* deps.planRun.getPlanSpecById(activeRun.planSpecId)
+    const { runId: _runId, reason: _reason, requireApproval: requestedRequireApproval, ...draftInput } = params.input
+    const preparedDraft = deps.planBuilder.prepareDraft(PlanDraftSchema.parse(draftInput))
+    const validation = deps.planValidator.validateDraft(preparedDraft)
+    if (validation.blocking.length > 0) {
+      return yield* new BadRequestError({
+        message: `Plan draft failed validation: ${aggregateBlockingIssues(validation.blocking)}`,
+      })
+    }
+    yield* assertDispatchExecutorsEffect(deps, preparedDraft)
+    const compiled = yield* deps.planCompiler.compile(preparedDraft)
+    const requireApproval =
+      requestedRequireApproval ?? hasCrossThreadSourceContext(activeRun.sourceThreadId, resolvedThreadId)
+
+    const specId = new RecordId(TABLES.PLAN_SPEC, Bun.randomUUIDv7())
+    const runId = new RecordId(TABLES.PLAN_RUN, Bun.randomUUIDv7())
+
+    yield* withTransactionAndEventsEffect({
+      db: databaseService,
+      planEventDeliveryService: deps.planEventDelivery,
+      run: (tx, emittedEvents) =>
+        Effect.gen(function* () {
+          const updatedSpec = yield* effectTryPromise(
+            () =>
+              tx
+                .update(ensureRecordId(activeSpec.id, TABLES.PLAN_SPEC))
+                .content(toSpecData(activeSpec, { status: 'superseded' }))
+                .output('after'),
+            'Failed to update superseded execution plan spec.',
+          )
+          const supersededSpec = PlanSpecSchema.parse(updatedSpec)
+
+          const updatedRun = yield* effectTryPromise(
+            () =>
+              tx
+                .update(ensureRecordId(activeRun.id, TABLES.PLAN_RUN))
+                .content(
+                  toRunData(activeRun, {
+                    status: 'aborted',
+                    currentNodeId: null,
+                    waitingNodeId: null,
+                    readyNodeIds: [],
+                    completedAt: nowDate(),
+                  }),
+                )
+                .output('after'),
+            'Failed to abort previous execution run.',
+          )
+          const abortedRun = PlanRunSchema.parse(updatedRun)
+
+          const createdSpec = yield* effectTryPromise(
+            () =>
+              tx
+                .create(specId)
+                .content(
+                  buildCompiledSpecCreateData({
+                    organizationId: params.organizationId,
+                    threadId: resolvedThreadId,
+                    leadAgentId: params.leadAgentId,
+                    compiled,
+                    version: supersededSpec.version + 1,
+                    replacedSpecId: supersededSpec.id,
+                  }),
+                )
+                .output('after'),
+            'Failed to create replacement execution plan spec.',
+          )
+          const spec = PlanSpecSchema.parse(createdSpec)
+
+          yield* effectTryPromise(
+            () =>
+              createInitializedRunGraph({
+                tx,
+                runId,
+                spec,
+                organizationId: params.organizationId,
+                threadId: resolvedThreadId,
+                sourceThreadId: activeRun.sourceThreadId,
+                leadAgentId: params.leadAgentId,
+                createdByAgentId: params.createdByAgentId ?? params.leadAgentId,
+                requireApproval,
+                nodes: compiled.nodes,
+                emittedEvents,
+                runPatch: { replacedRunId: abortedRun.id },
+                createdEventType: 'plan-replaced',
+                createdEventMessage: `Replaced execution plan "${activeSpec.title}" with "${spec.title}".`,
+                createdEventDetail: {
+                  reason: params.input.reason,
+                  replacedRunId: recordIdToString(abortedRun.id, TABLES.PLAN_RUN),
+                },
+                checkpointReason: 'plan-replaced',
+                planExecutor: deps.planExecutor,
+              }),
+            'Failed to initialize replacement execution plan graph.',
+          )
+        }),
+    })
+
+    if (!requireApproval) {
+      yield* effectTryPromise(
+        () =>
+          attachPlanScheduleIfNeeded({
+            db: databaseService,
+            planRunService: deps.planRun,
+            planSchedulerService: deps.planScheduler,
+            organizationId: params.organizationId,
+            threadId: resolvedThreadId,
+            runId,
+            planSpecId: specId,
+          }),
+        'Failed to attach execution plan schedule.',
+      )
+    }
+
+    const plan = yield* finalizePlanSnapshotEffect(deps, { runId, emittedBy: params.leadAgentId })
+    return buildExecutionPlanToolResult({
+      action: 'replaced',
+      plan,
+      message: `Replaced execution plan with "${plan.title}".`,
+    })
+  })
+}
+
+function submitPlanTurnResultEffect(
+  deps: ExecutionPlanDeps,
+  params: {
+    threadId: RecordIdInput
+    runId: string
+    nodeId: string
+    emittedBy: string
+    input: SubmitPlanTurnResultArgs
+  },
+) {
+  return Effect.gen(function* () {
+    const result = yield* Effect.tryPromise({
+      try: () =>
+        deps.planExecutor.submitNodeResult({
+          threadId: params.threadId,
+          runId: params.runId,
+          nodeId: params.nodeId,
+          emittedBy: params.emittedBy,
+          result: params.input,
+        }),
+      catch: (cause) =>
+        new ExecutionPlanServiceError({ message: 'Failed to submit execution plan node result.', cause }),
+    })
+
+    const plan = yield* finalizePlanSnapshotEffect(deps, { runId: params.runId, emittedBy: params.emittedBy })
+    return buildExecutionPlanToolResult({
+      action: result.action,
+      plan,
+      message: result.message ?? `Submitted result for node "${params.nodeId}".`,
+    })
+  })
+}
+
+function resumeRunEffect(
+  deps: ExecutionPlanDeps,
+  params: { threadId: RecordIdInput; emittedBy: string; input: { runId: string } },
+) {
+  return Effect.gen(function* () {
+    const result = yield* Effect.tryPromise({
+      try: () =>
+        deps.planExecutor.resumeRun({
+          threadId: params.threadId,
+          runId: params.input.runId,
+          emittedBy: params.emittedBy,
+        }),
+      catch: (cause) => new ExecutionPlanServiceError({ message: 'Failed to resume execution run.', cause }),
+    })
+
+    const plan = yield* finalizePlanSnapshotEffect(deps, { runId: params.input.runId, emittedBy: params.emittedBy })
+    return buildExecutionPlanToolResult({
+      action: result.action,
+      plan,
+      message: result.message ?? `Resumed execution run "${params.input.runId}".`,
+    })
+  })
+}
+
+function approvePlanEffect(
+  deps: ExecutionPlanDeps,
+  params: { organizationId: RecordIdInput; threadId: RecordIdInput; runId: RecordIdInput; emittedBy: string },
+) {
+  return Effect.gen(function* () {
+    const databaseService = deps.db
+    const run = yield* deps.planRun.getRunById(params.runId)
+    if (
+      recordIdToString(run.organizationId, TABLES.ORGANIZATION) !==
+      recordIdToString(params.organizationId, TABLES.ORGANIZATION)
+    ) {
+      return yield* new BadRequestError({ message: 'Plan run belongs to a different organization.' })
+    }
+    if (!isPlanVisibleInThreadContext(params.threadId, run)) {
+      return yield* new BadRequestError({ message: 'Plan run is not available in this thread context.' })
+    }
+    if (run.status !== 'pending-approval') {
+      return yield* new BadRequestError({ message: 'Only pending-approval plans can be approved.' })
+    }
+
+    const [spec, nodeSpecs, nodeRuns, nextCheckpointSequence] = yield* Effect.all([
+      deps.planRun.getPlanSpecById(run.planSpecId),
+      deps.planRun.listNodeSpecs(run.planSpecId),
+      deps.planRun.listNodeRuns(run.id),
+      deps.planRun.getNextCheckpointSequence(run.id),
+    ])
+
+    yield* withTransactionAndEventsEffect({
+      db: databaseService,
+      planEventDeliveryService: deps.planEventDelivery,
+      run: (tx, emittedEvents) =>
+        Effect.gen(function* () {
+          const updatedRun = yield* effectTryPromise(
+            () =>
+              tx
+                .update(ensureRecordId(run.id, TABLES.PLAN_RUN))
+                .content(toRunData(run, { status: 'running', startedAt: run.startedAt ?? nowDate() }))
+                .output('after'),
+            'Failed to activate execution run.',
+          )
+          const activatedRun = PlanRunSchema.parse(updatedRun)
+
+          const synced = yield* effectTryPromise(
+            () =>
+              deps.planExecutor.syncRunGraph({
+                tx,
+                run: activatedRun,
+                spec,
+                nodeSpecs,
+                nodeRuns,
+                artifacts: [],
+                emittedBy: params.emittedBy,
+                capturedEvents: emittedEvents,
+              }),
+            'Failed to sync execution run graph.',
+          )
+
+          yield* emitEvent({
+            tx,
+            run: synced.run,
+            spec,
+            eventType: 'plan-approved',
+            fromStatus: run.status,
+            toStatus: synced.run.status,
+            message: `Approved execution plan "${spec.title}".`,
+            emittedBy: params.emittedBy,
+            detail: { title: spec.title, objective: spec.objective },
+            capturedEvents: emittedEvents,
+          })
+
+          const checkpoint = yield* saveCheckpointWithService(deps, {
+            tx,
+            run: synced.run,
+            spec,
+            nodeRuns: synced.nodeRuns,
+            artifacts: [],
+            sequence: nextCheckpointSequence,
+            reason: 'plan-approved',
+            capturedEvents: emittedEvents,
+          })
+          yield* attachCheckpoint(tx, synced.run, checkpoint)
+        }),
+    })
+
+    yield* effectTryPromise(
+      () =>
+        attachPlanScheduleIfNeeded({
+          db: databaseService,
+          planRunService: deps.planRun,
+          planSchedulerService: deps.planScheduler,
+          organizationId: run.organizationId,
+          threadId: run.threadId,
+          runId: run.id,
+          planSpecId: run.planSpecId,
+        }),
+      'Failed to attach execution plan schedule.',
+    )
+
+    return yield* finalizePlanSnapshotEffect(deps, { runId: run.id, emittedBy: params.emittedBy })
+  })
+}
+
+function rejectPlanEffect(
+  deps: ExecutionPlanDeps,
+  params: {
+    organizationId: RecordIdInput
+    threadId: RecordIdInput
+    runId: RecordIdInput
+    emittedBy: string
+    reason?: string
+    resolution?: 'rejected' | 'changes-requested'
+  },
+) {
+  return Effect.gen(function* () {
+    const databaseService = deps.db
+    const resolution = params.resolution ?? 'rejected'
+    const eventType = resolution === 'changes-requested' ? 'plan-changes-requested' : 'plan-rejected'
+    const run = yield* deps.planRun.getRunById(params.runId)
+    if (
+      recordIdToString(run.organizationId, TABLES.ORGANIZATION) !==
+      recordIdToString(params.organizationId, TABLES.ORGANIZATION)
+    ) {
+      return yield* new BadRequestError({ message: 'Plan run belongs to a different organization.' })
+    }
+    if (!isPlanVisibleInThreadContext(params.threadId, run)) {
+      return yield* new BadRequestError({ message: 'Plan run is not available in this thread context.' })
+    }
+    if (run.status !== 'pending-approval') {
+      return yield* new BadRequestError({ message: 'Only pending-approval plans can be rejected.' })
+    }
+
+    const [spec, nodeRuns, nextCheckpointSequence] = yield* Effect.all([
+      deps.planRun.getPlanSpecById(run.planSpecId),
+      deps.planRun.listNodeRuns(run.id),
+      deps.planRun.getNextCheckpointSequence(run.id),
+    ])
+
+    const checkpointReason = resolution === 'changes-requested' ? 'plan-changes-requested' : 'plan-rejected'
+
+    yield* withTransactionAndEventsEffect({
+      db: databaseService,
+      planEventDeliveryService: deps.planEventDelivery,
+      run: (tx, emittedEvents) =>
+        Effect.gen(function* () {
+          const updatedRun = yield* effectTryPromise(
+            () =>
+              tx
+                .update(ensureRecordId(run.id, TABLES.PLAN_RUN))
+                .content(
+                  toRunData(run, {
+                    status: 'aborted',
+                    currentNodeId: null,
+                    waitingNodeId: null,
+                    readyNodeIds: [],
+                    completedAt: nowDate(),
+                  }),
+                )
+                .output('after'),
+            'Failed to abort execution run.',
+          )
+          const rejectedRun = PlanRunSchema.parse(updatedRun)
+
+          yield* emitEvent({
+            tx,
+            run: rejectedRun,
+            spec,
+            eventType,
+            fromStatus: run.status,
+            toStatus: rejectedRun.status,
+            message:
+              resolution === 'changes-requested'
+                ? `Requested changes for execution plan "${spec.title}".`
+                : `Rejected execution plan "${spec.title}".`,
+            emittedBy: params.emittedBy,
+            detail: { resolution, ...(params.reason ? { reason: params.reason } : {}) },
+            capturedEvents: emittedEvents,
+          })
+
+          const checkpoint = yield* saveCheckpointWithService(deps, {
+            tx,
+            run: rejectedRun,
+            spec,
+            nodeRuns,
+            artifacts: [],
+            sequence: nextCheckpointSequence,
+            reason: checkpointReason,
+            capturedEvents: emittedEvents,
+          })
+          yield* attachCheckpoint(tx, rejectedRun, checkpoint)
+        }),
+    })
+
+    const latestRun = yield* deps.planRun.getRunById(run.id)
+    return yield* serializeRunFull(deps.planRun, latestRun)
+  })
+}
+
+function respondToApprovalEffect(
+  deps: ExecutionPlanDeps,
+  params: {
+    threadId: RecordIdInput
+    emittedBy: string
+    input: { approvalId: string; response: HumanNodeResponsePayload; approvalMessageId?: string }
+  },
+) {
+  return Effect.gen(function* () {
+    const run = yield* deps.planRun.getActiveRunRecord(params.threadId)
+    if (!run) return null
+
+    const plan = yield* Effect.tryPromise({
+      try: () =>
+        deps.planExecutor.submitHumanNodeResponse({
+          threadId: params.threadId,
+          approvalId: params.input.approvalId,
+          respondedBy: params.emittedBy,
+          response: params.input.response,
+          approvalMessageId: params.input.approvalMessageId,
+        }),
+      catch: (cause) => new ExecutionPlanServiceError({ message: 'Failed to submit human approval response.', cause }),
+    })
+    if (!plan) return null
+
+    return yield* finalizePlanSnapshotEffect(deps, { runId: run.id, emittedBy: params.emittedBy })
+  })
+}
+
+function applyHumanInputFromUserMessageEffect(
+  deps: ExecutionPlanDeps,
+  params: { threadId: RecordIdInput; message: ChatMessage; respondedBy: string },
+) {
+  return Effect.gen(function* () {
+    const run = yield* deps.planRun.getActiveRunRecord(params.threadId)
+    if (!run || run.status !== 'awaiting-human' || !run.waitingNodeId) return null
+
+    const waitingNodeId = run.waitingNodeId
+    const nodeSpec = yield* deps.planRun.getNodeSpecByNodeId(run.planSpecId, waitingNodeId)
+    const response: HumanNodeResponsePayload | null = Match.value(nodeSpec.type).pipe(
+      Match.when('human-input', () => ({
+        responseText: extractMessageText(params.message).trim(),
+        messageId: params.message.id,
+        approved: undefined,
+      })),
+      Match.when('human-review-edit', () => ({
+        responseText: extractMessageText(params.message).trim(),
+        messageId: params.message.id,
+        approved: undefined,
+      })),
+      Match.when('human-decision', () => ({
+        responseText: extractMessageText(params.message).trim(),
+        messageId: params.message.id,
+        approved: true as const,
+      })),
+      Match.orElse(() => null),
+    )
+    if (!response) return null
+
+    const plan = yield* Effect.tryPromise({
+      try: () =>
+        deps.planExecutor.submitHumanNodeResponse({
+          threadId: params.threadId,
+          respondedBy: params.respondedBy,
+          response,
+          approvalMessageId: params.message.id,
+        }),
+      catch: (cause) => new ExecutionPlanServiceError({ message: 'Failed to submit human node response.', cause }),
+    })
+    if (!plan) return null
+
+    return yield* finalizePlanSnapshotEffect(deps, { runId: run.id, emittedBy: params.respondedBy })
+  })
+}
+
+function applyApprovalResponseFromMessagesEffect(
+  deps: ExecutionPlanDeps,
+  params: { threadId: RecordIdInput; approvalMessages: ChatMessage[]; respondedBy: string },
+) {
+  const approvalResponse = buildApprovalResponseFromMessages(params.approvalMessages)
+  if (!approvalResponse) {
+    return Effect.succeed<SerializableExecutionPlan | null>(null)
+  }
+
+  return respondToApprovalEffect(deps, {
+    threadId: params.threadId,
+    emittedBy: params.respondedBy,
+    input: approvalResponse,
+  })
+}
+
+export function makeExecutionPlanService(deps: ExecutionPlanDeps) {
+  return {
+    hasActivePlan(threadId: RecordIdInput) {
+      return hasActivePlanEffect(deps, threadId)
+    },
+
+    getActivePlanForThread(
+      threadId: RecordIdInput,
+      options?: Partial<ExecutionPlanQueryArgs> & { runId?: RecordIdInput },
+    ) {
+      return getActivePlanForThreadEffect(deps, threadId, options)
+    },
+
+    getActivePlansForThread(
+      threadId: RecordIdInput,
+      options?: Partial<ExecutionPlanQueryArgs> & { runId?: RecordIdInput },
+    ) {
+      return getActivePlansForThreadEffect(deps, threadId, options)
+    },
+
+    getPlansCreatedInContext(params: {
+      organizationId: RecordIdInput
+      sourceThreadId?: RecordIdInput
+      createdByAgentId?: string
+      statuses?: ReadonlyArray<PlanRunRecord['status']>
+      includeEvents?: boolean
+      includeArtifacts?: boolean
+      includeApprovals?: boolean
+      includeCheckpoints?: boolean
+      includeValidationIssues?: boolean
+    }) {
+      return getPlansCreatedInContextEffect({ ...params, deps })
+    },
+
+    listActivePlanSummaries(threadId: RecordIdInput) {
+      return listActivePlanSummariesEffect(deps, threadId)
+    },
+
+    getActivePlanToolResult(params: {
+      threadId: RecordIdInput
+      runId?: string
+      includeEvents?: boolean
+      includeArtifacts?: boolean
+      includeApprovals?: boolean
+      includeCheckpoints?: boolean
+      includeValidationIssues?: boolean
+    }) {
+      return getActivePlanToolResultEffect(deps, params)
+    },
+
+    createPlan(params: {
+      organizationId: RecordIdInput
+      threadId: RecordIdInput
+      sourceThreadId?: RecordIdInput
+      leadAgentId: string
+      createdByAgentId?: string
+      requireApproval?: boolean
+      input: PlanDraft
+    }) {
+      return createPlanEffect(deps, params)
+    },
+
+    replacePlan(params: {
+      threadId: RecordIdInput
+      organizationId: RecordIdInput
+      leadAgentId: string
+      createdByAgentId?: string
+      input: PlanDraft & { runId: string; reason: string; requireApproval?: boolean }
+    }) {
+      return replacePlanEffect(deps, params)
+    },
+
+    submitPlanTurnResult(params: {
+      threadId: RecordIdInput
+      runId: string
+      nodeId: string
+      emittedBy: string
+      input: SubmitPlanTurnResultArgs
+    }) {
+      return submitPlanTurnResultEffect(deps, params)
+    },
+    submitNodeResult(params: { threadId: RecordIdInput; emittedBy: string; input: SubmitExecutionNodeResultArgs }) {
+      const { runId, nodeId, ...result } = params.input
+      return submitPlanTurnResultEffect(deps, {
+        threadId: params.threadId,
+        emittedBy: params.emittedBy,
+        runId,
+        nodeId,
+        input: result,
+      })
+    },
+
+    resumeRun(params: { threadId: RecordIdInput; emittedBy: string; input: { runId: string } }) {
+      return resumeRunEffect(deps, params)
+    },
+
+    approvePlan(params: {
+      organizationId: RecordIdInput
+      threadId: RecordIdInput
+      runId: RecordIdInput
+      emittedBy: string
+    }) {
+      return approvePlanEffect(deps, params)
+    },
+
+    rejectPlan(params: {
+      organizationId: RecordIdInput
+      threadId: RecordIdInput
+      runId: RecordIdInput
+      emittedBy: string
+      reason?: string
+      resolution?: 'rejected' | 'changes-requested'
+    }) {
+      return rejectPlanEffect(deps, params)
+    },
+
+    applyApprovalResponseFromMessages(params: {
+      threadId: RecordIdInput
+      approvalMessages: ChatMessage[]
+      respondedBy: string
+    }) {
+      return applyApprovalResponseFromMessagesEffect(deps, params)
+    },
+
+    respondToApproval(params: {
+      threadId: RecordIdInput
+      emittedBy: string
+      input: { approvalId: string; response: HumanNodeResponsePayload; approvalMessageId?: string }
+    }) {
+      return respondToApprovalEffect(deps, params)
+    },
+
+    applyHumanInputFromUserMessage(params: { threadId: RecordIdInput; message: ChatMessage; respondedBy: string }) {
+      return applyHumanInputFromUserMessageEffect(deps, params)
+    },
+
+    serializeRuns(runs: PlanRunRecord[], options?: Partial<ExecutionPlanQueryArgs>) {
+      return serializeRunsEffect(deps, runs, options)
+    },
+
+    assertDispatchExecutors(preparedDraft: PreparedPlanDraft) {
+      return assertDispatchExecutorsEffect(deps, preparedDraft)
+    },
+
+    finalizePlanSnapshot(params: { runId: RecordIdInput; emittedBy: string }) {
+      return finalizePlanSnapshotEffect(deps, params)
+    },
+  } as const
+}
+
+export class ExecutionPlanServiceTag extends Context.Service<
+  ExecutionPlanServiceTag,
+  ReturnType<typeof makeExecutionPlanService>
+>()('ExecutionPlanService') {}
+
+export const ExecutionPlanServiceLive = Layer.effect(
+  ExecutionPlanServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    const planRun = yield* PlanRunServiceTag
+    const planBuilder = yield* PlanBuilderServiceTag
+    const planCheckpoint = yield* PlanCheckpointServiceTag
+    const planCompiler = yield* PlanCompilerServiceTag
+    const planEventDelivery = yield* PlanEventDeliveryServiceTag
+    const planScheduler = yield* PlanSchedulerServiceTag
+    const planValidator = yield* PlanValidatorServiceTag
+    const ownershipDispatcher = yield* OwnershipDispatcherServiceTag
+    const planExecutor = yield* PlanExecutorServiceTag
+    return makeExecutionPlanService({
+      db,
+      ownershipDispatcher,
+      planBuilder,
+      planCheckpoint,
+      planCompiler,
+      planEventDelivery,
+      planExecutor,
+      planRun,
+      planScheduler,
+      planValidator,
+    })
+  }),
+)