@lota-sdk/core 0.4.7 → 0.4.9

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

@@ -1,430 +0,0 @@
-import type {
-  DeadlineAction,
-  DeadlineReminder,
-  DeadlineSpec,
-  PlanEventType,
-  PlanNodeRunRecord,
-  PlanNodeSpecRecord,
-  PlanRunRecord,
-} from '@lota-sdk/shared'
-import { PlanEventSchema, PlanNodeRunSchema, PlanNodeSpecRecordSchema, PlanRunSchema } from '@lota-sdk/shared'
-import { BoundQuery, RecordId } from 'surrealdb'
-
-import type { RecordIdInput } from '../db/record-id'
-import { ensureRecordId, recordIdToString } from '../db/record-id'
-import { databaseService } from '../db/service'
-import { TABLES } from '../db/tables'
-import { planEventDeliveryService } from './plan-event-delivery.service'
-import { planRunService } from './plan-run.service'
-
-export type DeadlineEvaluationStatus = 'ok' | 'warning' | 'escalated' | 'missed'
-
-export interface DeadlineEvaluationResult {
-  status: DeadlineEvaluationStatus
-  activeReminder?: DeadlineReminder
-  nextTriggerAt?: Date | null
-}
-
-class PlanDeadlineService {
-  evaluateDeadline(params: { deadline: DeadlineSpec; nodeStartedAt: Date; now?: Date }): DeadlineEvaluationResult {
-    const now = params.now ?? new Date()
-    const deadlineTime = this.resolveDeadlineTime(params.deadline, params.nodeStartedAt)
-
-    if (!deadlineTime) {
-      return { status: 'ok', nextTriggerAt: null }
-    }
-
-    const reminderEntries = [...params.deadline.reminders]
-      .map((reminder) => ({ reminder, triggerAt: new Date(deadlineTime.getTime() - reminder.beforeMs) }))
-      .sort((a, b) => a.triggerAt.getTime() - b.triggerAt.getTime())
-
-    let activeReminder: DeadlineReminder | undefined
-    let nextTriggerAt: Date | null = null
-
-    for (const entry of reminderEntries) {
-      if (now.getTime() < entry.triggerAt.getTime()) {
-        nextTriggerAt = entry.triggerAt
-        break
-      }
-
-      activeReminder = entry.reminder
-    }
-
-    if (now.getTime() >= deadlineTime.getTime()) {
-      return { status: 'missed', nextTriggerAt: null }
-    }
-
-    if (activeReminder) {
-      const status: DeadlineEvaluationStatus = activeReminder.action === 'escalate' ? 'escalated' : 'warning'
-      return { status, activeReminder, nextTriggerAt: nextTriggerAt ?? deadlineTime }
-    }
-
-    return { status: 'ok', nextTriggerAt: nextTriggerAt ?? deadlineTime }
-  }
-
-  async checkDeadlines(now?: Date): Promise<void> {
-    const currentTime = now ?? new Date()
-
-    const sweep = await this.collectDeadlineSweep(currentTime)
-    if (sweep.entries.length === 0) {
-      return
-    }
-
-    // Query parent runs lazily only for node runs that need notification or escalation handling.
-    const runCache = new Map<string, PlanRunRecord>()
-
-    for (const entry of sweep.entries) {
-      if (entry.evaluation.status === 'ok') continue
-
-      const deadline = entry.nodeSpec.deadline
-      if (!deadline) continue
-
-      const runIdStr = recordIdToString(entry.nodeRun.runId, TABLES.PLAN_RUN)
-      let run = runCache.get(runIdStr)
-      if (!run) {
-        const found = await databaseService.findOne(
-          TABLES.PLAN_RUN,
-          { id: ensureRecordId(entry.nodeRun.runId, TABLES.PLAN_RUN) },
-          PlanRunSchema,
-        )
-        if (!found) continue
-        run = found
-        runCache.set(runIdStr, run)
-      }
-
-      const dedupeKeyBase = `plan-deadline:${runIdStr}:${entry.nodeRun.nodeId}`
-
-      if (entry.evaluation.status === 'warning') {
-        await this.emitDeadlineEvent({
-          run,
-          nodeRun: entry.nodeRun,
-          eventType: 'deadline-warning',
-          emittedBy: 'plan-deadline-checker',
-          message:
-            entry.evaluation.activeReminder?.message ?? `Node "${entry.nodeRun.nodeId}" is approaching its deadline.`,
-          detail: {
-            title: 'Deadline approaching',
-            reminderBeforeMs: entry.evaluation.activeReminder?.beforeMs ?? null,
-            dedupeKey: `${dedupeKeyBase}:warning:${entry.evaluation.activeReminder?.beforeMs ?? 'default'}`,
-          },
-        })
-      } else if (entry.evaluation.status === 'escalated') {
-        await this.emitDeadlineEvent({
-          run,
-          nodeRun: entry.nodeRun,
-          eventType: 'escalation-triggered',
-          emittedBy: 'plan-deadline-checker',
-          message:
-            entry.evaluation.activeReminder?.message ?? `Node "${entry.nodeRun.nodeId}" deadline requires escalation.`,
-          detail: {
-            title: 'Deadline escalation',
-            reminderBeforeMs: entry.evaluation.activeReminder?.beforeMs ?? null,
-            dedupeKey: `${dedupeKeyBase}:escalated:${entry.evaluation.activeReminder?.beforeMs ?? 'default'}`,
-          },
-        })
-      } else {
-        await this.applyDeadlineMissAction({
-          runId: entry.nodeRun.runId,
-          nodeId: entry.nodeRun.nodeId,
-          threadId: recordIdToString(run.threadId, TABLES.THREAD),
-          organizationId: recordIdToString(run.organizationId, TABLES.ORGANIZATION),
-          action: deadline.missAction,
-          emittedBy: 'plan-deadline-checker',
-        })
-      }
-
-      await this.maybeEmitEscalationPolicyEvent({
-        run,
-        nodeRun: entry.nodeRun,
-        nodeSpec: entry.nodeSpec,
-        now: currentTime,
-      })
-    }
-
-    const nextTriggerAt =
-      sweep.entries
-        .map((entry) => entry.evaluation.nextTriggerAt)
-        .filter((value): value is Date => {
-          if (!value) return false
-          return value.getTime() > currentTime.getTime()
-        })
-        .sort((a, b) => a.getTime() - b.getTime())
-        .at(0) ?? null
-
-    if (nextTriggerAt) {
-      await this.enqueueDeadlineCheck(nextTriggerAt)
-    }
-  }
-
-  async recoverDeadlineChecks(now = new Date()): Promise<void> {
-    const sweep = await this.collectDeadlineSweep(now)
-    const hasDueAction = sweep.entries.some((entry) => entry.evaluation.status !== 'ok')
-    if (hasDueAction) {
-      await this.enqueueDeadlineCheck(now)
-      return
-    }
-
-    const nextTriggerAt =
-      sweep.entries
-        .map((entry) => entry.evaluation.nextTriggerAt)
-        .filter((value): value is Date => {
-          if (!value) return false
-          return value.getTime() > now.getTime()
-        })
-        .sort((a, b) => a.getTime() - b.getTime())
-        .at(0) ?? null
-
-    if (nextTriggerAt) {
-      await this.enqueueDeadlineCheck(nextTriggerAt)
-    }
-  }
-
-  private async collectDeadlineSweep(
-    now: Date,
-  ): Promise<{
-    entries: Array<{ nodeRun: PlanNodeRunRecord; nodeSpec: PlanNodeSpecRecord; evaluation: DeadlineEvaluationResult }>
-  }> {
-    const activeNodeRuns = await databaseService.queryMany(
-      new BoundQuery(`SELECT * FROM ${TABLES.PLAN_NODE_RUN} WHERE status IN $statuses`, {
-        statuses: ['running', 'awaiting-human'],
-      }),
-      PlanNodeRunSchema,
-    )
-
-    const entries = []
-
-    for (const nodeRun of activeNodeRuns) {
-      const nodeSpec = await this.loadNodeSpec(nodeRun)
-      if (!nodeSpec?.deadline) continue
-
-      const evaluation = this.evaluateDeadline({
-        deadline: nodeSpec.deadline,
-        nodeStartedAt: new Date(nodeRun.startedAt ?? nodeRun.createdAt),
-        now,
-      })
-
-      entries.push({ nodeRun, nodeSpec, evaluation })
-    }
-
-    return { entries }
-  }
-
-  private resolveDeadlineTime(deadline: DeadlineSpec, nodeStartedAt: Date): Date | null {
-    return (
-      (deadline.dueAt ? new Date(deadline.dueAt) : null) ??
-      (deadline.durationMs !== undefined ? new Date(nodeStartedAt.getTime() + deadline.durationMs) : null)
-    )
-  }
-
-  private async loadNodeSpec(nodeRun: PlanNodeRunRecord): Promise<PlanNodeSpecRecord | null> {
-    return databaseService.findOne(
-      TABLES.PLAN_NODE_SPEC,
-      { planSpecId: ensureRecordId(nodeRun.planSpecId, TABLES.PLAN_SPEC), nodeId: nodeRun.nodeId },
-      PlanNodeSpecRecordSchema,
-    )
-  }
-
-  async applyDeadlineMissAction(params: {
-    runId: RecordIdInput
-    nodeId: string
-    threadId: string
-    organizationId: string
-    action: DeadlineAction
-    emittedBy: string
-  }): Promise<void> {
-    const runIdStr = recordIdToString(params.runId, TABLES.PLAN_RUN)
-    const run = await planRunService.getRunById(params.runId)
-    const nodeRun = await planRunService.getNodeRunByNodeId(params.runId, params.nodeId)
-
-    switch (params.action) {
-      case 'notify':
-        await this.emitDeadlineEvent({
-          run,
-          nodeRun,
-          eventType: 'deadline-missed',
-          emittedBy: params.emittedBy,
-          message: `Node "${params.nodeId}" has missed its deadline.`,
-          detail: { title: 'Deadline missed', dedupeKey: `plan-deadline:${runIdStr}:${params.nodeId}:missed:notify` },
-        })
-        break
-
-      case 'escalate':
-        await this.emitDeadlineEvent({
-          run,
-          nodeRun,
-          eventType: 'escalation-triggered',
-          emittedBy: params.emittedBy,
-          message: `Node "${params.nodeId}" has missed its deadline and requires escalation.`,
-          detail: {
-            title: 'Deadline escalation',
-            dedupeKey: `plan-deadline:${runIdStr}:${params.nodeId}:missed:escalate`,
-            missedDeadline: true,
-          },
-        })
-        break
-
-      case 'block': {
-        await this.emitDeadlineEvent({
-          run,
-          nodeRun,
-          eventType: 'deadline-missed',
-          emittedBy: params.emittedBy,
-          message: `Node "${params.nodeId}" has missed its deadline.`,
-          detail: { title: 'Deadline missed', dedupeKey: `plan-deadline:${runIdStr}:${params.nodeId}:missed:block` },
-        })
-        const { planExecutorService } = await import('./plan-executor.service')
-        await planExecutorService.blockNodeOnDispatchFailure({
-          threadId: params.threadId,
-          runId: runIdStr,
-          nodeId: params.nodeId,
-          emittedBy: params.emittedBy,
-          message: 'Deadline missed — node blocked',
-          failureClass: 'timeout_exceeded',
-        })
-        break
-      }
-
-      case 'fail': {
-        await this.emitDeadlineEvent({
-          run,
-          nodeRun,
-          eventType: 'deadline-missed',
-          emittedBy: params.emittedBy,
-          message: `Node "${params.nodeId}" has missed its deadline.`,
-          detail: { title: 'Deadline missed', dedupeKey: `plan-deadline:${runIdStr}:${params.nodeId}:missed:fail` },
-        })
-        const { planExecutorService } = await import('./plan-executor.service')
-        await planExecutorService.blockNodeOnDispatchFailure({
-          threadId: params.threadId,
-          runId: runIdStr,
-          nodeId: params.nodeId,
-          emittedBy: params.emittedBy,
-          message: 'Deadline missed — node failed',
-          failureClass: 'timeout_exceeded',
-        })
-        break
-      }
-    }
-  }
-
-  private async maybeEmitEscalationPolicyEvent(params: {
-    run: PlanRunRecord
-    nodeRun: PlanNodeRunRecord
-    nodeSpec: PlanNodeSpecRecord
-    now: Date
-  }): Promise<void> {
-    const escalation = params.nodeSpec.escalation
-    if (!escalation) return
-
-    const startedAt = new Date(params.nodeRun.startedAt ?? params.nodeRun.createdAt)
-    const runIdStr = recordIdToString(params.run.id, TABLES.PLAN_RUN)
-    const baseKey = `plan-escalation:${runIdStr}:${params.nodeRun.nodeId}`
-
-    if (escalation.autoEscalateAfterMinutes) {
-      const thresholdMs = escalation.autoEscalateAfterMinutes * 60_000
-      if (params.now.getTime() - startedAt.getTime() >= thresholdMs) {
-        await this.emitDeadlineEvent({
-          run: params.run,
-          nodeRun: params.nodeRun,
-          eventType: 'escalation-triggered',
-          emittedBy: 'plan-deadline-checker',
-          message: `Node "${params.nodeRun.nodeId}" exceeded its auto-escalation threshold.`,
-          detail: {
-            title: 'Execution escalation',
-            dedupeKey: `${baseKey}:auto:${escalation.autoEscalateAfterMinutes}`,
-            autoEscalateAfterMinutes: escalation.autoEscalateAfterMinutes,
-            ...(escalation.escalateToAgent ? { escalateToAgent: escalation.escalateToAgent } : {}),
-            ...(escalation.escalateToUser ? { escalateToUser: escalation.escalateToUser } : {}),
-          },
-        })
-      }
-    }
-
-    if (escalation.deadlineThresholdMinutes && params.nodeSpec.deadline) {
-      const dueAt = this.resolveDeadlineTime(params.nodeSpec.deadline, startedAt)
-      if (!dueAt) return
-
-      const thresholdMs = escalation.deadlineThresholdMinutes * 60_000
-      if (dueAt.getTime() - params.now.getTime() <= thresholdMs && dueAt.getTime() > params.now.getTime()) {
-        await this.emitDeadlineEvent({
-          run: params.run,
-          nodeRun: params.nodeRun,
-          eventType: 'escalation-triggered',
-          emittedBy: 'plan-deadline-checker',
-          message: `Node "${params.nodeRun.nodeId}" is inside its escalation threshold.`,
-          detail: {
-            title: 'Deadline escalation threshold',
-            dedupeKey: `${baseKey}:threshold:${escalation.deadlineThresholdMinutes}`,
-            deadlineThresholdMinutes: escalation.deadlineThresholdMinutes,
-            ...(escalation.escalateToAgent ? { escalateToAgent: escalation.escalateToAgent } : {}),
-            ...(escalation.escalateToUser ? { escalateToUser: escalation.escalateToUser } : {}),
-          },
-        })
-      }
-    }
-  }
-
-  private async emitDeadlineEvent(params: {
-    run: PlanRunRecord
-    nodeRun: PlanNodeRunRecord
-    eventType: Extract<PlanEventType, 'deadline-warning' | 'deadline-missed' | 'escalation-triggered'>
-    emittedBy: string
-    message: string
-    detail: Record<string, unknown>
-  }): Promise<void> {
-    const dedupeKey =
-      typeof params.detail.dedupeKey === 'string' && params.detail.dedupeKey.trim().length > 0
-        ? params.detail.dedupeKey.trim()
-        : null
-
-    if (dedupeKey) {
-      const existing = await databaseService.queryMany(
-        new BoundQuery(
-          `SELECT * FROM ${TABLES.PLAN_EVENT}
-            WHERE runId = $runId
-              AND nodeId = $nodeId
-              AND eventType = $eventType
-              AND detail.dedupeKey = $dedupeKey
-            LIMIT 1`,
-          {
-            runId: ensureRecordId(params.run.id, TABLES.PLAN_RUN),
-            nodeId: params.nodeRun.nodeId,
-            eventType: params.eventType,
-            dedupeKey,
-          },
-        ),
-        PlanEventSchema,
-      )
-      if (existing.length > 0) {
-        return
-      }
-    }
-
-    const spec = await planRunService.getPlanSpecById(params.run.planSpecId)
-    const event = PlanEventSchema.parse(
-      await databaseService.create(
-        TABLES.PLAN_EVENT,
-        {
-          id: new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7()),
-          planSpecId: ensureRecordId(spec.id, TABLES.PLAN_SPEC),
-          runId: ensureRecordId(params.run.id, TABLES.PLAN_RUN),
-          nodeId: params.nodeRun.nodeId,
-          eventType: params.eventType,
-          message: params.message,
-          emittedBy: params.emittedBy,
-          detail: params.detail,
-        },
-        PlanEventSchema,
-      ),
-    )
-
-    await planEventDeliveryService.dispatchEvent(event)
-  }
-
-  private async enqueueDeadlineCheck(scheduledFor: Date): Promise<void> {
-    const { enqueueDeadlineCheck } = await import('../queues/plan-scheduler.queue')
-    await enqueueDeadlineCheck(scheduledFor)
-  }
-}
-
-export const planDeadlineService = new PlanDeadlineService()

package/src/services/plan-event-delivery.service.ts

@@ -1,166 +0,0 @@
-import { PlanEventSchema } from '@lota-sdk/shared'
-import type { PlanEventRecord } from '@lota-sdk/shared'
-
-import { ensureRecordId, recordIdToString } from '../db/record-id'
-import { databaseService } from '../db/service'
-import { TABLES } from '../db/tables'
-import { getRedisConnection } from '../redis'
-import { resolvePlanNodeExecutionVisibility } from '../runtime/execution-plan-visibility'
-import { getRuntimeAdapters } from '../runtime/runtime-extensions'
-import type { LotaRuntimePlanEventEnvelope } from '../runtime/runtime-extensions'
-import { planRunService } from './plan-run.service'
-import { ThreadSchema } from './thread.types'
-import { userService } from './user.service'
-
-const PLAN_EVENT_DELIVERED_TTL_MS = 7 * 24 * 60 * 60 * 1000
-
-function buildDeliveredKey(eventId: string): string {
-  return `plan-event:delivered:${eventId}`
-}
-
-class PlanEventDeliveryService {
-  async dispatchEvents(events: PlanEventRecord[]): Promise<void> {
-    const runIds = new Set(events.map((event) => recordIdToString(event.runId, TABLES.PLAN_RUN)))
-    for (const runId of runIds) {
-      await this.dispatchUndeliveredEvents(runId)
-    }
-  }
-
-  async dispatchEvent(rawEvent: PlanEventRecord): Promise<void> {
-    const event = PlanEventSchema.parse(rawEvent)
-    const eventId = recordIdToString(event.id, TABLES.PLAN_EVENT)
-    const deliveredKey = buildDeliveredKey(eventId)
-    if (await getRedisConnection().exists(deliveredKey)) {
-      return
-    }
-
-    await this.deliverEvent(event)
-    await getRedisConnection().set(deliveredKey, '1', 'PX', PLAN_EVENT_DELIVERED_TTL_MS)
-  }
-
-  private async deliverEvent(rawEvent: PlanEventRecord): Promise<void> {
-    const event = PlanEventSchema.parse(rawEvent)
-    const run = await planRunService.getRunById(event.runId)
-    const [spec, nodeSpecs, nodeRuns, thread] = await Promise.all([
-      planRunService.getPlanSpecById(run.planSpecId),
-      planRunService.listNodeSpecs(run.planSpecId),
-      planRunService.listNodeRuns(run.id),
-      databaseService.findOne(TABLES.THREAD, { id: ensureRecordId(run.threadId, TABLES.THREAD) }, ThreadSchema),
-    ])
-    const nodeSpecsById = new Map(nodeSpecs.map((nodeSpec) => [nodeSpec.nodeId, nodeSpec]))
-    const nodeRunsById = new Map(nodeRuns.map((nodeRun) => [nodeRun.nodeId, nodeRun]))
-    const organizationId = recordIdToString(run.organizationId, TABLES.ORGANIZATION)
-    const threadId = recordIdToString(run.threadId, TABLES.THREAD)
-    const runIdString = recordIdToString(run.id, TABLES.PLAN_RUN)
-    const planSpecId = recordIdToString(spec.id, TABLES.PLAN_SPEC)
-    const userId = thread?.userId
-      ? recordIdToString(ensureRecordId(thread.userId, TABLES.USER), TABLES.USER)
-      : undefined
-    const userName =
-      userId === undefined
-        ? undefined
-        : await userService
-            .getUser(userId)
-            .then((user) => user.name)
-            .catch(() => undefined)
-
-    const envelope: LotaRuntimePlanEventEnvelope = {
-      event,
-      spec,
-      run,
-      ...(event.nodeId ? { nodeSpec: nodeSpecsById.get(event.nodeId) } : {}),
-      ...(event.nodeId ? { nodeRun: nodeRunsById.get(event.nodeId) } : {}),
-      organizationId,
-      threadId,
-      runId: runIdString,
-      planSpecId,
-      ...(userId ? { userId } : {}),
-      ...(userName ? { userName } : {}),
-    }
-
-    await this.dispatchAdapterEvent(envelope)
-    await this.enqueueWakeIfNeeded(envelope, nodeSpecsById)
-  }
-
-  async dispatchUndeliveredEvents(runId: string, options?: { limit?: number }): Promise<void> {
-    const run = await planRunService.getRunById(runId)
-    const events = await planRunService.listEvents(run.id, options?.limit ?? 200)
-
-    for (const rawEvent of events) {
-      const event = PlanEventSchema.parse(rawEvent)
-      const eventId = recordIdToString(event.id, TABLES.PLAN_EVENT)
-      const deliveredKey = buildDeliveredKey(eventId)
-      if (await getRedisConnection().exists(deliveredKey)) {
-        continue
-      }
-
-      await this.dispatchEvent(event)
-    }
-  }
-
-  private async dispatchAdapterEvent(envelope: LotaRuntimePlanEventEnvelope): Promise<void> {
-    const adapter = getRuntimeAdapters().planEventAdapter
-    if (!adapter) {
-      return
-    }
-
-    await adapter.onPlanEvent(envelope)
-  }
-
-  private async enqueueWakeIfNeeded(
-    envelope: LotaRuntimePlanEventEnvelope,
-    nodeSpecsById: Map<string, NonNullable<LotaRuntimePlanEventEnvelope['nodeSpec']>>,
-  ): Promise<void> {
-    const wakeTarget = this.resolveWakeTarget(envelope, nodeSpecsById)
-    if (!wakeTarget) {
-      return
-    }
-
-    const { enqueuePlanAgentHeartbeatWake } = await import('../queues/plan-agent-heartbeat.queue')
-    await enqueuePlanAgentHeartbeatWake({
-      organizationId: envelope.organizationId,
-      threadId: envelope.threadId,
-      runId: envelope.runId,
-      nodeId: wakeTarget.nodeId,
-      agentId: wakeTarget.agentId,
-      reason: wakeTarget.reason,
-    })
-  }
-
-  private resolveWakeTarget(
-    envelope: LotaRuntimePlanEventEnvelope,
-    nodeSpecsById: Map<string, NonNullable<LotaRuntimePlanEventEnvelope['nodeSpec']>>,
-  ): { nodeId: string; agentId: string; reason: string } | null {
-    const currentNodeId = envelope.run.currentNodeId ?? envelope.event.nodeId
-    if (!currentNodeId) {
-      return null
-    }
-
-    const effectiveNodeSpec =
-      (envelope.event.nodeId === currentNodeId ? envelope.nodeSpec : undefined) ?? nodeSpecsById.get(currentNodeId)
-    if (!effectiveNodeSpec || effectiveNodeSpec.owner.executorType !== 'agent') {
-      return null
-    }
-
-    const isVisible = resolvePlanNodeExecutionVisibility(envelope.spec, effectiveNodeSpec) === 'visible'
-    if (!isVisible) {
-      return null
-    }
-
-    const supportedEventTypes = new Set([
-      'node-ready',
-      'node-unblocked',
-      'approval-resolved',
-      'run-resumed',
-      'deadline-warning',
-      'escalation-triggered',
-    ])
-    if (!supportedEventTypes.has(envelope.event.eventType)) {
-      return null
-    }
-
-    return { nodeId: currentNodeId, agentId: effectiveNodeSpec.owner.ref, reason: envelope.event.eventType }
-  }
-}
-
-export const planEventDeliveryService = new PlanEventDeliveryService()