@lota-sdk/core 0.1.20 → 0.1.22

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

@@ -0,0 +1,238 @@
+import type { PlanExecutionVisibility, PlanNodeSpecRecord, PlanRunRecord, PlanSpecRecord } from '@lota-sdk/shared'
+import { PlanRunSchema } from '@lota-sdk/shared'
+
+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 { resolvePlanNodeExecutionVisibility } from '../runtime/execution-plan-visibility'
+import { planDeadlineService } from './plan-deadline.service'
+import { planRunService } 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
+  workstreamId: string
+  runId: string
+  nodeId: string
+  agentId: string
+  status: 'ready' | 'running'
+  visibility: PlanExecutionVisibility
+}
+
+export interface ApproachingDeadlineNode {
+  organizationId: string
+  workstreamId: string
+  runId: string
+  nodeId: string
+  agentId?: string
+  visibility?: PlanExecutionVisibility
+  dueAt?: string
+  status: 'warning' | 'escalated' | 'missed'
+  nextTriggerAt?: string | null
+}
+
+export interface RecentlyUnblockedNode {
+  organizationId: string
+  workstreamId: 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 PlanAgentQueryService {
+  async getActionableNodesForAgent(params: {
+    agentId?: string
+    organizationId?: RecordIdInput
+  }): Promise<ActionablePlanAgentNode[]> {
+    const runs = await this.listActiveRuns(params.organizationId)
+    const actionable: ActionablePlanAgentNode[] = []
+
+    for (const run of runs) {
+      const spec = await planRunService.getPlanSpecById(run.planSpecId)
+      const currentNodeId = run.currentNodeId
+      if (!currentNodeId) {
+        continue
+      }
+
+      const [nodeSpec, nodeRun] = await Promise.all([
+        planRunService.getNodeSpecByNodeId(spec.id, currentNodeId),
+        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),
+        workstreamId: recordIdToString(run.workstreamId, TABLES.WORKSTREAM),
+        runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+        nodeId: nodeSpec.nodeId,
+        agentId: visibleTarget.agentId,
+        status: nodeRun.status as 'ready' | 'running',
+        visibility: visibleTarget.visibility,
+      })
+    }
+
+    return actionable
+  }
+
+  async getApproachingDeadlines(params?: {
+    organizationId?: RecordIdInput
+    withinMinutes?: number
+  }): Promise<ApproachingDeadlineNode[]> {
+    const now = new Date()
+    const maxWindowMs = (params?.withinMinutes ?? 60) * 60_000
+    const runs = await this.listActiveRuns(params?.organizationId)
+    const matches: ApproachingDeadlineNode[] = []
+
+    for (const run of runs) {
+      const spec = await planRunService.getPlanSpecById(run.planSpecId)
+      const [nodeSpecs, nodeRuns] = await Promise.all([
+        planRunService.listNodeSpecs(spec.id),
+        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 = planDeadlineService.evaluateDeadline({
+          deadline: nodeSpec.deadline,
+          nodeStartedAt: new Date(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),
+          workstreamId: recordIdToString(run.workstreamId, TABLES.WORKSTREAM),
+          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
+  }
+
+  async getRecentlyUnblockedNodes(params?: {
+    organizationId?: RecordIdInput
+    sinceMinutes?: number
+    agentId?: string
+  }): Promise<RecentlyUnblockedNode[]> {
+    const since = new Date(Date.now() - (params?.sinceMinutes ?? 30) * 60_000)
+    const runs = await this.listActiveRuns(params?.organizationId)
+    const matches: RecentlyUnblockedNode[] = []
+
+    for (const run of runs) {
+      const spec = await planRunService.getPlanSpecById(run.planSpecId)
+      const [nodeSpecs, events] = await Promise.all([
+        planRunService.listNodeSpecs(spec.id),
+        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 ||
+          new Date(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),
+          workstreamId: recordIdToString(run.workstreamId, TABLES.WORKSTREAM),
+          runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+          nodeId: currentNodeId,
+          agentId: visibleTarget.agentId,
+          visibility: visibleTarget.visibility,
+          unblockedAt: new Date(event.createdAt).toISOString(),
+          sourceEventType: event.eventType,
+        })
+      }
+    }
+
+    return matches
+  }
+
+  private async listActiveRuns(organizationId?: RecordIdInput): Promise<PlanRunRecord[]> {
+    const bindings = {
+      statuses: [...ACTIVE_PLAN_RUN_STATUSES],
+      ...(organizationId ? { organizationId: ensureRecordId(organizationId, TABLES.ORGANIZATION) } : {}),
+    }
+
+    const whereOrganization = organizationId ? ' AND organizationId = $organizationId' : ''
+    return databaseService.queryMany(
+      {
+        query: `SELECT * FROM ${TABLES.PLAN_RUN} WHERE status INSIDE $statuses${whereOrganization} ORDER BY updatedAt DESC`,
+        bindings,
+      },
+      PlanRunSchema,
+    )
+  }
+}
+
+export const planAgentQueryService = new PlanAgentQueryService()

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

@@ -1,5 +1,7 @@
 import type { PlanDraft } from '@lota-sdk/shared'
 
+import { isExecutableConditionExpression } from './plan-helpers'
+
 function buildImplicitLinearEdges(draft: PlanDraft) {
   if (draft.edges.length > 0 || draft.nodes.length <= 1) {
     return draft.edges
@@ -46,7 +48,15 @@ class PlanBuilderService {
           webPolicy: node.contextPolicy.webPolicy,
         },
       })),
-      edges: draft.edges.map((edge) => ({ ...edge, map: { ...edge.map } })),
+      edges: draft.edges.map((edge) => {
+        const normalizedWhen = edge.when?.trim()
+        const { when: _when, ...edgeWithoutWhen } = edge
+        return {
+          ...edgeWithoutWhen,
+          ...(normalizedWhen && isExecutableConditionExpression(normalizedWhen) ? { when: normalizedWhen } : {}),
+          map: { ...edge.map },
+        }
+      }),
       schemas: structuredClone(draft.schemas),
       entryNodeIds: [...(draft.entryNodeIds ?? [])],
     }

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

@@ -72,8 +72,10 @@ class PlanCompilerService {
         attachmentPolicy: node.contextPolicy.attachmentPolicy,
         webPolicy: node.contextPolicy.webPolicy,
       },
+      executionVisibility: node.executionVisibility,
       ...(node.schedule ? { schedule: node.schedule } : {}),
       ...(node.deadline ? { deadline: node.deadline } : {}),
+      ...(node.escalation ? { escalation: node.escalation } : {}),
       ...(node.monitoringConfig ? { monitoringConfig: node.monitoringConfig } : {}),
       ...(node.delayAfterPredecessorMs ? { delayAfterPredecessorMs: node.delayAfterPredecessorMs } : {}),
       ...(node.deliberationConfig ? { deliberationConfig: node.deliberationConfig } : {}),

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

@@ -2,17 +2,20 @@ import type {
   DeadlineAction,
   DeadlineReminder,
   DeadlineSpec,
+  PlanEventType,
   PlanNodeRunRecord,
   PlanNodeSpecRecord,
   PlanRunRecord,
 } from '@lota-sdk/shared'
-import { PlanNodeRunSchema, PlanNodeSpecRecordSchema, PlanRunSchema } from '@lota-sdk/shared'
+import { PlanEventSchema, PlanNodeRunSchema, PlanNodeSpecRecordSchema, PlanRunSchema } from '@lota-sdk/shared'
+import { 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 { getNotificationService } from './notification.service'
+import { planEventDeliveryService } from './plan-event-delivery.service'
+import { planRunService } from './plan-run.service'
 
 export type DeadlineEvaluationStatus = 'ok' | 'warning' | 'escalated' | 'missed'
 
@@ -89,45 +92,53 @@ class PlanDeadlineService {
         runCache.set(runIdStr, run)
       }
 
-      const organizationId = recordIdToString(run.organizationId, TABLES.ORGANIZATION)
-      const workstreamId = recordIdToString(run.workstreamId, TABLES.WORKSTREAM)
-      const notificationService = getNotificationService()
       const dedupeKeyBase = `plan-deadline:${runIdStr}:${entry.nodeRun.nodeId}`
 
       if (entry.evaluation.status === 'warning') {
-        await notificationService.remind({
-          organizationId,
-          workstreamId,
-          runId: runIdStr,
-          nodeId: entry.nodeRun.nodeId,
-          severity: 'warning',
-          title: 'Deadline approaching',
-          body:
+        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.`,
-          dedupeKey: `${dedupeKeyBase}:warning:${entry.evaluation.activeReminder?.beforeMs ?? 'default'}`,
+          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 notificationService.escalate({
-          organizationId,
-          workstreamId,
-          runId: runIdStr,
-          nodeId: entry.nodeRun.nodeId,
-          severity: 'urgent',
-          title: 'Deadline escalation',
-          body:
+        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.`,
-          dedupeKey: `${dedupeKeyBase}:escalated:${entry.evaluation.activeReminder?.beforeMs ?? 'default'}`,
+          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,
-          workstreamId,
-          organizationId,
+          workstreamId: recordIdToString(run.workstreamId, TABLES.WORKSTREAM),
+          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 =
@@ -222,37 +233,46 @@ class PlanDeadlineService {
     action: DeadlineAction
     emittedBy: string
   }): Promise<void> {
-    const notificationService = getNotificationService()
     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 notificationService.notify({
-          organizationId: params.organizationId,
-          workstreamId: params.workstreamId,
-          runId: runIdStr,
-          nodeId: params.nodeId,
-          severity: 'warning',
-          title: 'Deadline missed',
-          body: `Node "${params.nodeId}" has missed its deadline.`,
-          dedupeKey: `plan-deadline:${runIdStr}:${params.nodeId}:missed: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 notificationService.escalate({
-          organizationId: params.organizationId,
-          workstreamId: params.workstreamId,
-          runId: runIdStr,
-          nodeId: params.nodeId,
-          severity: 'urgent',
-          title: 'Deadline escalation',
-          body: `Node "${params.nodeId}" has missed its deadline and requires escalation.`,
-          dedupeKey: `plan-deadline:${runIdStr}:${params.nodeId}:missed: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({
           workstreamId: params.workstreamId,
@@ -266,6 +286,14 @@ class PlanDeadlineService {
       }
 
       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({
           workstreamId: params.workstreamId,
@@ -280,6 +308,120 @@ class PlanDeadlineService {
     }
   }
 
+  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(
+        {
+          query: `SELECT * FROM ${TABLES.PLAN_EVENT}
+            WHERE runId = $runId
+              AND nodeId = $nodeId
+              AND eventType = $eventType
+              AND detail.dedupeKey = $dedupeKey
+            LIMIT 1`,
+          bindings: {
+            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)