@lota-sdk/core 0.4.8 → 0.4.9

package/src/services/plan/plan-agent-heartbeat.service.ts

@@ -0,0 +1,234 @@
+import { Context, Schema, Effect, Layer } from 'effect'
+
+import { serverLogger } from '../../config/logger'
+import { ensureRecordId } from '../../db/record-id'
+import { TABLES } from '../../db/tables'
+import { effectTryPromise } from '../../effect/helpers'
+import { RedisServiceTag } from '../../effect/services'
+import type { RedisConnectionManager } from '../../redis/connection'
+import { withLeaseLock } from '../../redis/redis-lease-lock'
+import { resolvePlanNodeExecutionVisibility } from '../../runtime/execution-plan-visibility'
+import type { makeThreadService } from '../thread/thread.service'
+import { ThreadServiceTag } from '../thread/thread.service'
+import type { makePlanAgentQueryService } from './plan-agent-query.service'
+import { PlanAgentQueryServiceTag } from './plan-agent-query.service'
+import type { makePlanExecutorService } from './plan-executor.service'
+import { PlanExecutorServiceTag } from './plan-executor.service'
+import type { makePlanRunService } from './plan-run.service'
+import { PlanRunServiceTag } from './plan-run.service'
+
+const PLAN_AGENT_HEARTBEAT_LOCK_TTL_MS = 300_000
+const PLAN_AGENT_HEARTBEAT_LOCK_REFRESH_MS = 20_000
+
+function buildHeartbeatLockKey(runId: string, nodeId: string): string {
+  return `plan-agent-heartbeat:${runId}:${nodeId}`
+}
+
+function buildWakeDedupeKey(params: {
+  organizationId: string
+  threadId: string
+  runId: string
+  nodeId: string
+  agentId: string
+}) {
+  return `${params.organizationId}:${params.threadId}:${params.runId}:${params.nodeId}:${params.agentId}`
+}
+
+class PlanAgentHeartbeatError extends Schema.TaggedErrorClass<PlanAgentHeartbeatError>()('PlanAgentHeartbeatError', {
+  operation: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+function tryHeartbeatPromise<A>(
+  operation: string,
+  thunk: () => PromiseLike<A> | Effect.Effect<A, unknown>,
+): Effect.Effect<A, PlanAgentHeartbeatError> {
+  return effectTryPromise(thunk, (cause) => new PlanAgentHeartbeatError({ operation, cause }))
+}
+
+function heartbeatServiceEffect<A, E>(
+  operation: string,
+  effect: Effect.Effect<A, E>,
+): Effect.Effect<A, PlanAgentHeartbeatError> {
+  return effect.pipe(Effect.mapError((cause) => new PlanAgentHeartbeatError({ operation, cause })))
+}
+
+interface PlanAgentHeartbeatDeps {
+  redis: RedisConnectionManager
+  planAgentQueryService: ReturnType<typeof makePlanAgentQueryService>
+  planExecutorService: ReturnType<typeof makePlanExecutorService>
+  planRunService: ReturnType<typeof makePlanRunService>
+  threadService: ReturnType<typeof makeThreadService>
+}
+
+export function makePlanAgentHeartbeatService(deps: PlanAgentHeartbeatDeps) {
+  const { planExecutorService, planRunService, redis, planAgentQueryService, threadService } = deps
+
+  const wakeNodeEffect = (params: {
+    organizationId: string
+    threadId: string
+    runId: string
+    nodeId: string
+    agentId: string
+    reason: string
+  }): Effect.Effect<boolean, PlanAgentHeartbeatError> =>
+    Effect.gen(function* () {
+      const threadRef = ensureRecordId(params.threadId, TABLES.THREAD)
+      yield* heartbeatServiceEffect(
+        'clear-stale-active-run',
+        threadService.clearStaleActiveRunIfMissingFromRegistry(threadRef),
+      )
+      if (yield* heartbeatServiceEffect('get-active-run-id', threadService.getActiveRunId(threadRef))) {
+        return false
+      }
+
+      return yield* withLeaseLock(
+        {
+          redis: redis.getConnection(),
+          lockKey: buildHeartbeatLockKey(params.runId, params.nodeId),
+          lockTtlMs: PLAN_AGENT_HEARTBEAT_LOCK_TTL_MS,
+          refreshIntervalMs: PLAN_AGENT_HEARTBEAT_LOCK_REFRESH_MS,
+          label: 'plan agent heartbeat',
+          maxWaitMs: 5_000,
+          logger: serverLogger,
+        },
+        () =>
+          Effect.gen(function* () {
+            yield* heartbeatServiceEffect(
+              'clear-stale-active-run',
+              threadService.clearStaleActiveRunIfMissingFromRegistry(threadRef),
+            )
+            if (yield* heartbeatServiceEffect('has-active-run-lease', threadService.hasActiveRunLease(threadRef))) {
+              return false
+            }
+            if (yield* heartbeatServiceEffect('get-active-run-id', threadService.getActiveRunId(threadRef))) {
+              return false
+            }
+
+            const run = yield* heartbeatServiceEffect('get-run-by-id', planRunService.getRunById(params.runId))
+            const spec = yield* heartbeatServiceEffect(
+              'get-plan-spec-by-id',
+              planRunService.getPlanSpecById(run.planSpecId),
+            )
+            const [nodeSpec, nodeRun] = yield* Effect.all([
+              heartbeatServiceEffect(
+                'get-node-spec-by-node-id',
+                planRunService.getNodeSpecByNodeId(spec.id, params.nodeId),
+              ),
+              heartbeatServiceEffect(
+                'get-node-run-by-node-id',
+                planRunService.getNodeRunByNodeId(run.id, params.nodeId),
+              ),
+            ])
+
+            if (nodeSpec.owner.executorType !== 'agent' || nodeSpec.owner.ref !== params.agentId) {
+              return false
+            }
+
+            const visibility = resolvePlanNodeExecutionVisibility(spec, nodeSpec)
+            if (visibility !== 'visible') {
+              return false
+            }
+
+            if (nodeRun.status !== 'running' && nodeRun.status !== 'ready') {
+              return false
+            }
+
+            if (nodeRun.status === 'ready' && run.currentNodeId === params.nodeId) {
+              yield* tryHeartbeatPromise('transition-node-to-running', () =>
+                planExecutorService.transitionNodeToRunning({ runId: params.runId, nodeId: params.nodeId }),
+              )
+            }
+
+            const { triggerPlanNodeTurn } = yield* tryHeartbeatPromise(
+              'import-thread-turn',
+              () => import('../thread/thread-turn'),
+            )
+
+            yield* tryHeartbeatPromise('trigger-plan-node-turn', () =>
+              triggerPlanNodeTurn({ runId: params.runId, nodeId: params.nodeId }),
+            )
+            return true
+          }),
+      ).pipe(Effect.mapError((cause) => new PlanAgentHeartbeatError({ operation: 'wake-node-lock', cause })))
+    })
+
+  const sweepEffect = (params?: { organizationId?: string }): Effect.Effect<void, PlanAgentHeartbeatError> =>
+    Effect.gen(function* () {
+      const { enqueuePlanAgentHeartbeatWake } = yield* tryHeartbeatPromise(
+        'import-heartbeat-queue',
+        () => import('../../queues/plan-agent-heartbeat.queue'),
+      )
+      const [actionable, recentlyUnblocked, approachingDeadlines] = yield* Effect.all([
+        heartbeatServiceEffect(
+          'get-actionable-nodes-for-agent',
+          planAgentQueryService.getActionableNodesForAgent({ organizationId: params?.organizationId }),
+        ),
+        heartbeatServiceEffect(
+          'get-recently-unblocked-nodes',
+          planAgentQueryService.getRecentlyUnblockedNodes({ organizationId: params?.organizationId }),
+        ),
+        heartbeatServiceEffect(
+          'get-approaching-deadlines',
+          planAgentQueryService.getApproachingDeadlines({ organizationId: params?.organizationId, withinMinutes: 60 }),
+        ),
+      ])
+
+      const wakeTargets = new Map<
+        string,
+        { organizationId: string; threadId: string; runId: string; nodeId: string; agentId: string; reason: string }
+      >()
+
+      for (const node of actionable) {
+        wakeTargets.set(buildWakeDedupeKey(node), { ...node, reason: 'heartbeat-actionable' })
+      }
+
+      for (const node of recentlyUnblocked) {
+        wakeTargets.set(buildWakeDedupeKey(node), { ...node, reason: node.sourceEventType })
+      }
+
+      for (const node of approachingDeadlines) {
+        if (!node.agentId || node.visibility !== 'visible') {
+          continue
+        }
+        const wakeTarget = {
+          organizationId: node.organizationId,
+          threadId: node.threadId,
+          runId: node.runId,
+          nodeId: node.nodeId,
+          agentId: node.agentId,
+          reason: `deadline-${node.status}`,
+        }
+        wakeTargets.set(buildWakeDedupeKey(wakeTarget), wakeTarget)
+      }
+
+      for (const target of wakeTargets.values()) {
+        yield* tryHeartbeatPromise('enqueue-heartbeat-wake', () => enqueuePlanAgentHeartbeatWake(target))
+      }
+    })
+
+  return { wakeNode: wakeNodeEffect, sweep: sweepEffect }
+}
+
+export class PlanAgentHeartbeatServiceTag extends Context.Service<
+  PlanAgentHeartbeatServiceTag,
+  ReturnType<typeof makePlanAgentHeartbeatService>
+>()('PlanAgentHeartbeatService') {}
+
+export const PlanAgentHeartbeatServiceLive = Layer.effect(
+  PlanAgentHeartbeatServiceTag,
+  Effect.gen(function* () {
+    const redis = yield* RedisServiceTag
+    const planAgentQueryService = yield* PlanAgentQueryServiceTag
+    const planRunService = yield* PlanRunServiceTag
+    const planExecutor = yield* PlanExecutorServiceTag
+    const threadSvc = yield* ThreadServiceTag
+    return makePlanAgentHeartbeatService({
+      redis,
+      planAgentQueryService,
+      planExecutorService: planExecutor,
+      planRunService,
+      threadService: threadSvc,
+    })
+  }),
+)

package/src/services/plan/plan-agent-query.service.ts

@@ -0,0 +1,322 @@
+import type { PlanExecutionVisibility, PlanNodeSpecRecord, PlanRunRecord, PlanSpecRecord } from '@lota-sdk/shared'
+import { PlanRunSchema } from '@lota-sdk/shared'
+import { Context, Schema, Effect, Layer } from 'effect'
+import { BoundQuery } 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 { effectTryPromise } from '../../effect/helpers'
+import { DatabaseServiceTag } from '../../effect/services'
+import { resolvePlanNodeExecutionVisibility } from '../../runtime/execution-plan-visibility'
+import { nowDate, unsafeDateFrom } from '../../utils/date-time'
+import { evaluateDeadline } from './plan-deadline.service'
+import type { makePlanRunService } from './plan-run.service'
+import { PlanRunServiceTag } from './plan-run.service'
+
+const ACTIVE_PLAN_RUN_STATUSES = ['running', 'awaiting-human', 'blocked'] as const
+const ACTIONABLE_NODE_STATUSES = new Set(['ready', 'running'])
+const DEADLINE_TRACKED_NODE_STATUSES = new Set(['ready', 'running', 'awaiting-human'])
+
+export interface ActionablePlanAgentNode {
+  organizationId: string
+  threadId: string
+  runId: string
+  nodeId: string
+  agentId: string
+  status: 'ready' | 'running'
+  visibility: PlanExecutionVisibility
+}
+
+export interface ApproachingDeadlineNode {
+  organizationId: string
+  threadId: string
+  runId: string
+  nodeId: string
+  agentId?: string
+  visibility?: PlanExecutionVisibility
+  dueAt?: string
+  status: 'warning' | 'escalated' | 'missed'
+  nextTriggerAt?: string | null
+}
+
+export interface RecentlyUnblockedNode {
+  organizationId: string
+  threadId: string
+  runId: string
+  nodeId: string
+  agentId: string
+  visibility: PlanExecutionVisibility
+  unblockedAt: string
+  sourceEventType: 'node-unblocked' | 'approval-resolved'
+}
+
+function isVisibleAgentNode(params: {
+  nodeSpec: PlanNodeSpecRecord
+  spec: PlanSpecRecord
+}): { agentId: string; visibility: PlanExecutionVisibility } | null {
+  if (params.nodeSpec.owner.executorType !== 'agent') {
+    return null
+  }
+
+  const visibility = resolvePlanNodeExecutionVisibility(params.spec, params.nodeSpec)
+  const isVisible = visibility === 'visible'
+  if (!isVisible) {
+    return null
+  }
+
+  return { agentId: params.nodeSpec.owner.ref, visibility }
+}
+
+class PlanAgentQueryError extends Schema.TaggedErrorClass<PlanAgentQueryError>()('PlanAgentQueryError', {
+  operation: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+function toPlanAgentQueryError(operation: string, cause: unknown): PlanAgentQueryError {
+  return new PlanAgentQueryError({ operation, cause })
+}
+
+function queryEffect<A>(
+  operation: string,
+  thunk: () => PromiseLike<A> | Effect.Effect<A, unknown>,
+): Effect.Effect<A, PlanAgentQueryError> {
+  return effectTryPromise(thunk, (cause) => toPlanAgentQueryError(operation, cause))
+}
+
+function queryServiceEffect<A, E>(
+  operation: string,
+  effect: Effect.Effect<A, E>,
+): Effect.Effect<A, PlanAgentQueryError> {
+  return effect.pipe(Effect.mapError((cause) => toPlanAgentQueryError(operation, cause)))
+}
+
+interface PlanAgentQueryDeps {
+  db: SurrealDBService
+  planRunService: ReturnType<typeof makePlanRunService>
+}
+
+export function makePlanAgentQueryService(deps: PlanAgentQueryDeps) {
+  const { db, planRunService } = deps
+
+  function listActiveRunsEffect(organizationId?: RecordIdInput): Effect.Effect<PlanRunRecord[], PlanAgentQueryError> {
+    const bindings = {
+      statuses: [...ACTIVE_PLAN_RUN_STATUSES],
+      ...(organizationId ? { organizationId: ensureRecordId(organizationId, TABLES.ORGANIZATION) } : {}),
+    }
+
+    const whereOrganization = organizationId ? ' AND organizationId = $organizationId' : ''
+    return queryEffect('list-active-runs', () =>
+      db.queryMany(
+        new BoundQuery(
+          `SELECT * FROM ${TABLES.PLAN_RUN} WHERE status INSIDE $statuses${whereOrganization} ORDER BY updatedAt DESC`,
+          bindings,
+        ),
+        PlanRunSchema,
+      ),
+    )
+  }
+
+  const getActionableNodesForAgentEffect = (params: {
+    agentId?: string
+    organizationId?: RecordIdInput
+  }): Effect.Effect<ActionablePlanAgentNode[], PlanAgentQueryError> =>
+    Effect.gen(function* () {
+      const runs = yield* listActiveRunsEffect(params.organizationId)
+      const actionable: ActionablePlanAgentNode[] = []
+
+      for (const run of runs) {
+        const spec = yield* queryServiceEffect('get-plan-spec-by-id', planRunService.getPlanSpecById(run.planSpecId))
+
+        if (spec.executionMode === 'graph-full') {
+          const [nodeSpecs, nodeRuns] = yield* Effect.all([
+            queryServiceEffect('list-node-specs', planRunService.listNodeSpecs(spec.id)),
+            queryServiceEffect('list-node-runs', planRunService.listNodeRuns(run.id)),
+          ])
+          for (const nodeRun of nodeRuns) {
+            if (!ACTIONABLE_NODE_STATUSES.has(nodeRun.status)) continue
+            const nodeSpec = nodeSpecs.find((ns) => ns.nodeId === nodeRun.nodeId)
+            if (!nodeSpec) continue
+            const visibleTarget = isVisibleAgentNode({ nodeSpec, spec })
+            if (!visibleTarget) continue
+            if (params.agentId && params.agentId !== visibleTarget.agentId) continue
+            actionable.push({
+              organizationId: recordIdToString(run.organizationId, TABLES.ORGANIZATION),
+              threadId: recordIdToString(run.threadId, TABLES.THREAD),
+              runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+              nodeId: nodeSpec.nodeId,
+              agentId: visibleTarget.agentId,
+              status: nodeRun.status as 'ready' | 'running',
+              visibility: visibleTarget.visibility,
+            })
+          }
+          continue
+        }
+
+        const currentNodeId = run.currentNodeId
+        if (!currentNodeId) {
+          continue
+        }
+
+        const [nodeSpec, nodeRun] = yield* Effect.all([
+          queryServiceEffect('get-node-spec-by-node-id', planRunService.getNodeSpecByNodeId(spec.id, currentNodeId)),
+          queryServiceEffect('get-node-run-by-node-id', planRunService.getNodeRunByNodeId(run.id, currentNodeId)),
+        ])
+        if (!ACTIONABLE_NODE_STATUSES.has(nodeRun.status)) {
+          continue
+        }
+
+        const visibleTarget = isVisibleAgentNode({ nodeSpec, spec })
+        if (!visibleTarget) {
+          continue
+        }
+        if (params.agentId && params.agentId !== visibleTarget.agentId) {
+          continue
+        }
+
+        actionable.push({
+          organizationId: recordIdToString(run.organizationId, TABLES.ORGANIZATION),
+          threadId: recordIdToString(run.threadId, TABLES.THREAD),
+          runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+          nodeId: nodeSpec.nodeId,
+          agentId: visibleTarget.agentId,
+          status: nodeRun.status as 'ready' | 'running',
+          visibility: visibleTarget.visibility,
+        })
+      }
+      return actionable
+    })
+
+  const getApproachingDeadlinesEffect = (params?: {
+    organizationId?: RecordIdInput
+    withinMinutes?: number
+  }): Effect.Effect<ApproachingDeadlineNode[], PlanAgentQueryError> =>
+    Effect.gen(function* () {
+      const now = nowDate()
+      const maxWindowMs = (params?.withinMinutes ?? 60) * 60_000
+      const runs = yield* listActiveRunsEffect(params?.organizationId)
+      const matches: ApproachingDeadlineNode[] = []
+
+      for (const run of runs) {
+        const spec = yield* queryServiceEffect('get-plan-spec-by-id', planRunService.getPlanSpecById(run.planSpecId))
+        const [nodeSpecs, nodeRuns] = yield* Effect.all([
+          queryServiceEffect('list-node-specs', planRunService.listNodeSpecs(spec.id)),
+          queryServiceEffect('list-node-runs', planRunService.listNodeRuns(run.id)),
+        ])
+        const nodeRunsById = new Map(nodeRuns.map((nodeRun) => [nodeRun.nodeId, nodeRun]))
+
+        for (const nodeSpec of nodeSpecs) {
+          const nodeRun = nodeRunsById.get(nodeSpec.nodeId)
+          if (!nodeRun || !nodeSpec.deadline || !DEADLINE_TRACKED_NODE_STATUSES.has(nodeRun.status)) {
+            continue
+          }
+
+          const evaluation = evaluateDeadline({
+            deadline: nodeSpec.deadline,
+            nodeStartedAt: unsafeDateFrom(nodeRun.startedAt ?? nodeRun.createdAt),
+            now,
+          })
+          if (evaluation.status === 'ok') {
+            continue
+          }
+
+          const nextTriggerTime = evaluation.nextTriggerAt?.getTime()
+          if (nextTriggerTime && nextTriggerTime - now.getTime() > maxWindowMs && evaluation.status !== 'missed') {
+            continue
+          }
+
+          const visibleTarget = isVisibleAgentNode({ nodeSpec, spec })
+          matches.push({
+            organizationId: recordIdToString(run.organizationId, TABLES.ORGANIZATION),
+            threadId: recordIdToString(run.threadId, TABLES.THREAD),
+            runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+            nodeId: nodeSpec.nodeId,
+            ...(visibleTarget ? { agentId: visibleTarget.agentId, visibility: visibleTarget.visibility } : {}),
+            ...(nodeSpec.deadline.dueAt ? { dueAt: nodeSpec.deadline.dueAt } : {}),
+            status: evaluation.status,
+            nextTriggerAt: evaluation.nextTriggerAt?.toISOString() ?? null,
+          })
+        }
+      }
+
+      return matches
+    })
+
+  const getRecentlyUnblockedNodesEffect = (params?: {
+    organizationId?: RecordIdInput
+    sinceMinutes?: number
+    agentId?: string
+  }): Effect.Effect<RecentlyUnblockedNode[], PlanAgentQueryError> =>
+    Effect.gen(function* () {
+      const since = unsafeDateFrom(nowDate().getTime() - (params?.sinceMinutes ?? 30) * 60_000)
+      const runs = yield* listActiveRunsEffect(params?.organizationId)
+      const matches: RecentlyUnblockedNode[] = []
+
+      for (const run of runs) {
+        const spec = yield* queryServiceEffect('get-plan-spec-by-id', planRunService.getPlanSpecById(run.planSpecId))
+        const [nodeSpecs, events] = yield* Effect.all([
+          queryServiceEffect('list-node-specs', planRunService.listNodeSpecs(spec.id)),
+          queryServiceEffect('list-events', planRunService.listEvents(run.id, 200)),
+        ])
+        const nodeSpecsById = new Map(nodeSpecs.map((nodeSpec) => [nodeSpec.nodeId, nodeSpec]))
+
+        for (const event of events) {
+          if (
+            (event.eventType !== 'node-unblocked' && event.eventType !== 'approval-resolved') ||
+            !event.nodeId ||
+            unsafeDateFrom(event.createdAt).getTime() < since.getTime()
+          ) {
+            continue
+          }
+
+          const currentNodeId = run.currentNodeId ?? event.nodeId
+          const nodeSpec = nodeSpecsById.get(currentNodeId)
+          if (!nodeSpec) {
+            continue
+          }
+
+          const visibleTarget = isVisibleAgentNode({ nodeSpec, spec })
+          if (!visibleTarget) {
+            continue
+          }
+          if (params?.agentId && params.agentId !== visibleTarget.agentId) {
+            continue
+          }
+
+          matches.push({
+            organizationId: recordIdToString(run.organizationId, TABLES.ORGANIZATION),
+            threadId: recordIdToString(run.threadId, TABLES.THREAD),
+            runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+            nodeId: currentNodeId,
+            agentId: visibleTarget.agentId,
+            visibility: visibleTarget.visibility,
+            unblockedAt: unsafeDateFrom(event.createdAt).toISOString(),
+            sourceEventType: event.eventType,
+          })
+        }
+      }
+
+      return matches
+    })
+
+  return {
+    getActionableNodesForAgent: getActionableNodesForAgentEffect,
+    getApproachingDeadlines: getApproachingDeadlinesEffect,
+    getRecentlyUnblockedNodes: getRecentlyUnblockedNodesEffect,
+  }
+}
+
+export class PlanAgentQueryServiceTag extends Context.Service<
+  PlanAgentQueryServiceTag,
+  ReturnType<typeof makePlanAgentQueryService>
+>()('PlanAgentQueryService') {}
+
+export const PlanAgentQueryServiceLive = Layer.effect(
+  PlanAgentQueryServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    const planRunService = yield* PlanRunServiceTag
+    return makePlanAgentQueryService({ db, planRunService })
+  }),
+)

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

@@ -0,0 +1,102 @@
+import { PlanApprovalSchema } from '@lota-sdk/shared'
+import type { PlanApprovalRecord, PlanApprovalStatus } from '@lota-sdk/shared'
+import { Context, Effect, Layer } from 'effect'
+import { RecordId } from 'surrealdb'
+
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId } from '../../db/record-id'
+import type { DatabaseTransaction, SurrealDBService } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { DatabaseServiceTag } from '../../effect/services'
+import { nowDate } from '../../utils/date-time'
+import type { HumanNodeResponsePayload } from './plan-executor-helpers'
+
+export function makePlanApprovalService(db: SurrealDBService) {
+  const createPendingApprovalEffect = (params: {
+    tx: DatabaseTransaction
+    runId: RecordIdInput
+    nodeRunId: RecordIdInput
+    nodeId: string
+    requestedBy: string
+    presented: Record<string, unknown>
+  }) =>
+    Effect.gen(function* () {
+      const approvalId = new RecordId(TABLES.PLAN_APPROVAL, Bun.randomUUIDv7())
+      const created = yield* params.tx
+        .create(approvalId)
+        .content({
+          runId: ensureRecordId(params.runId, TABLES.PLAN_RUN),
+          nodeRunId: ensureRecordId(params.nodeRunId, TABLES.PLAN_NODE_RUN),
+          nodeId: params.nodeId,
+          status: 'pending',
+          requestedBy: params.requestedBy,
+          presented: params.presented,
+          requiredEdits: [],
+        })
+        .output('after')
+
+      return PlanApprovalSchema.parse(created)
+    })
+
+  const getApprovalByIdEffect = (approvalId: RecordIdInput) =>
+    db.findOne(TABLES.PLAN_APPROVAL, { id: ensureRecordId(approvalId, TABLES.PLAN_APPROVAL) }, PlanApprovalSchema)
+
+  const getPendingApprovalForNodeRunEffect = (nodeRunId: RecordIdInput) =>
+    Effect.gen(function* () {
+      const approvals = yield* db.findMany(
+        TABLES.PLAN_APPROVAL,
+        { nodeRunId: ensureRecordId(nodeRunId, TABLES.PLAN_NODE_RUN), status: 'pending' },
+        PlanApprovalSchema,
+        { orderBy: 'createdAt', orderDir: 'DESC', limit: 1 },
+      )
+
+      return approvals.at(0) ?? null
+    })
+
+  const updateApprovalResponseEffect = (params: {
+    tx: DatabaseTransaction
+    approval: PlanApprovalRecord
+    status: PlanApprovalStatus
+    response: HumanNodeResponsePayload
+    respondedBy: string
+    approvalMessageId?: string
+    comments?: string
+    requiredEdits?: string[]
+  }) =>
+    Effect.gen(function* () {
+      const updated = yield* params.tx
+        .update(ensureRecordId(params.approval.id, TABLES.PLAN_APPROVAL))
+        .merge({
+          status: params.status,
+          response: params.response,
+          respondedBy: params.respondedBy,
+          ...(params.approvalMessageId ? { approvalMessageId: params.approvalMessageId } : {}),
+          ...(params.comments ? { comments: params.comments } : {}),
+          ...(params.requiredEdits ? { requiredEdits: params.requiredEdits } : {}),
+          respondedAt: nowDate(),
+        })
+        .output('after')
+
+      return PlanApprovalSchema.parse(updated)
+    })
+
+  return {
+    createPendingApproval: createPendingApprovalEffect,
+    getApprovalById: getApprovalByIdEffect,
+    getPendingApprovalForNodeRun: getPendingApprovalForNodeRunEffect,
+    updateApprovalResponse: updateApprovalResponseEffect,
+  }
+}
+
+export class PlanApprovalServiceTag extends Context.Service<
+  PlanApprovalServiceTag,
+  ReturnType<typeof makePlanApprovalService>
+>()('PlanApprovalService') {}
+
+export const PlanApprovalServiceLive = Layer.effect(
+  PlanApprovalServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    return makePlanApprovalService(db)
+  }),
+)