@lota-sdk/core 0.1.15 → 0.1.16

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

@@ -0,0 +1,284 @@
+import { PlanArtifactSchema, PlanCycleRecordSchema, PlanRunSchema } from '@lota-sdk/shared'
+import type {
+  CarryForwardPolicy,
+  CycleSchedule,
+  PlanArtifactRecord,
+  PlanCycleRecord,
+  PlanDraft,
+  PlanRunStatus,
+  PlanScheduleSpec,
+  PlanTemplateRecord,
+} 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 { planSchedulerService } from './plan-scheduler.service'
+import { planTemplateService } from './plan-template.service'
+
+const TERMINAL_RUN_STATUSES: ReadonlySet<PlanRunStatus> = new Set(['completed', 'failed', 'aborted'])
+
+function cycleScheduleToSpec(schedule: CycleSchedule): PlanScheduleSpec {
+  const startAt = schedule.startAt ? new Date(schedule.startAt) : undefined
+  const isFutureStart = startAt && startAt.getTime() > Date.now()
+
+  if (isFutureStart) {
+    return { type: 'absolute', at: startAt.toISOString(), missedPolicy: 'run-immediately' }
+  }
+
+  const cron = frequencyToCron(schedule.frequency, schedule.customIntervalMs)
+  if (cron) {
+    return { type: 'cron', cron, missedPolicy: 'run-immediately' }
+  }
+
+  if (schedule.frequency === 'biweekly') {
+    return { type: 'monitoring', intervalMs: 14 * 24 * 60 * 60 * 1000, missedPolicy: 'run-immediately' }
+  }
+
+  if (schedule.frequency === 'custom' && schedule.customIntervalMs) {
+    return { type: 'monitoring', intervalMs: schedule.customIntervalMs, missedPolicy: 'run-immediately' }
+  }
+
+  return { type: 'cron', cron: '0 0 * * *', missedPolicy: 'run-immediately' }
+}
+
+function frequencyToCron(frequency: CycleSchedule['frequency'], _customIntervalMs?: number): string | null {
+  switch (frequency) {
+    case 'daily':
+      return '0 0 * * *'
+    case 'weekly':
+      return '0 0 * * 1'
+    case 'monthly':
+      return '0 0 1 * *'
+    case 'quarterly':
+      return '0 0 1 */3 *'
+    case 'biweekly':
+    case 'custom':
+      return null
+  }
+}
+
+class PlanCycleService {
+  cycleScheduleToSpec = cycleScheduleToSpec
+
+  async createCycle(params: {
+    organizationId: RecordIdInput
+    workstreamId: RecordIdInput
+    templateId: RecordIdInput
+    name: string
+    schedule: CycleSchedule
+    carryForwardPolicy?: CarryForwardPolicy
+    leadAgentId: string
+  }): Promise<PlanCycleRecord> {
+    const now = new Date()
+
+    const cycle = await databaseService.create(
+      TABLES.PLAN_CYCLE,
+      {
+        organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+        workstreamId: ensureRecordId(params.workstreamId, TABLES.WORKSTREAM),
+        templateId: ensureRecordId(params.templateId, TABLES.PLAN_TEMPLATE),
+        name: params.name,
+        schedule: params.schedule,
+        carryForwardPolicy: params.carryForwardPolicy ?? 'incomplete-only',
+        status: 'active',
+        currentIteration: 0,
+        createdAt: now,
+      },
+      PlanCycleRecordSchema,
+    )
+
+    const createResult = await planTemplateService.instantiate({
+      templateId: params.templateId,
+      organizationId: params.organizationId,
+      workstreamId: params.workstreamId,
+      leadAgentId: params.leadAgentId,
+    })
+
+    const createdRunId = createResult.plan?.runId
+
+    const scheduleSpec = cycleScheduleToSpec(params.schedule)
+    const scheduleRecord = await planSchedulerService.createSchedule({
+      organizationId: params.organizationId,
+      workstreamId: params.workstreamId,
+      ...(createdRunId ? { runId: ensureRecordId(createdRunId, TABLES.PLAN_RUN) } : {}),
+      scheduleSpec,
+    })
+
+    const updated = await databaseService.update(
+      TABLES.PLAN_CYCLE,
+      ensureRecordId(cycle.id, TABLES.PLAN_CYCLE),
+      {
+        scheduleId: ensureRecordId(scheduleRecord.id, TABLES.PLAN_SCHEDULE),
+        ...(createdRunId ? { currentRunId: ensureRecordId(createdRunId, TABLES.PLAN_RUN) } : {}),
+        currentIteration: 1,
+      },
+      PlanCycleRecordSchema,
+    )
+
+    return updated ?? cycle
+  }
+
+  async advanceCycle(cycleId: RecordIdInput): Promise<void> {
+    const cycle = await this.getCycle(cycleId)
+    if (!cycle) {
+      throw new Error(`Cycle not found: ${recordIdToString(cycleId, TABLES.PLAN_CYCLE)}`)
+    }
+
+    if (cycle.status !== 'active') {
+      return
+    }
+
+    if (cycle.currentRunId) {
+      const runRecord = await databaseService.findOne(
+        TABLES.PLAN_RUN,
+        { id: ensureRecordId(cycle.currentRunId, TABLES.PLAN_RUN) },
+        PlanRunSchema,
+      )
+      if (runRecord && !TERMINAL_RUN_STATUSES.has(runRecord.status)) {
+        return
+      }
+    }
+
+    const template = await planTemplateService.getTemplate(cycle.templateId)
+    if (!template) {
+      throw new Error(`Template not found for cycle: ${recordIdToString(cycle.templateId, TABLES.PLAN_TEMPLATE)}`)
+    }
+
+    const previousRunArtifacts = cycle.currentRunId
+      ? await databaseService.findMany(
+          TABLES.PLAN_ARTIFACT,
+          { runId: ensureRecordId(cycle.currentRunId, TABLES.PLAN_RUN) },
+          PlanArtifactSchema,
+          { orderBy: 'createdAt', orderDir: 'ASC' },
+        )
+      : []
+
+    const draft = this.buildCarryForwardDraft({ template, previousRunArtifacts, policy: cycle.carryForwardPolicy })
+
+    const result = await planTemplateService.instantiate({
+      templateId: cycle.templateId,
+      organizationId: cycle.organizationId,
+      workstreamId: cycle.workstreamId,
+      leadAgentId: 'system',
+      overrides: draft,
+    })
+
+    const newRunId = result.plan?.runId
+
+    await databaseService.update(
+      TABLES.PLAN_CYCLE,
+      ensureRecordId(cycleId, TABLES.PLAN_CYCLE),
+      {
+        ...(newRunId ? { currentRunId: ensureRecordId(newRunId, TABLES.PLAN_RUN) } : {}),
+        currentIteration: cycle.currentIteration + 1,
+      },
+      PlanCycleRecordSchema,
+    )
+
+    // TODO: re-enable when playbook records exist and IDs align
+    // The previous implementation passed a PLAN_TEMPLATE record ID as a PLAYBOOK ID,
+    // causing refineFromCycle to always fail silently.
+  }
+
+  buildCarryForwardDraft(params: {
+    template: PlanTemplateRecord
+    previousRunArtifacts: PlanArtifactRecord[]
+    policy: CarryForwardPolicy
+  }): PlanDraft {
+    const draft = { ...params.template.draft }
+
+    if (params.policy === 'none' || params.previousRunArtifacts.length === 0) {
+      return draft
+    }
+
+    let artifacts: PlanArtifactRecord[]
+    if (params.policy === 'incomplete-only') {
+      artifacts = params.previousRunArtifacts.filter((a) => a.kind === 'markdown' || a.kind === 'json')
+    } else {
+      // 'all-pending'
+      artifacts = [...params.previousRunArtifacts]
+    }
+
+    if (artifacts.length > 0) {
+      const carryContext = artifacts.map((a) => `[carry-forward] ${a.name}: ${a.pointer}`)
+      draft.objective = `${draft.objective}\n\nCarry-forward context:\n${carryContext.join('\n')}`
+    }
+
+    return draft
+  }
+
+  async cancelCycle(cycleId: RecordIdInput): Promise<void> {
+    const cycle = await this.getCycle(cycleId)
+    if (!cycle) {
+      throw new Error(`Cycle not found: ${recordIdToString(cycleId, TABLES.PLAN_CYCLE)}`)
+    }
+
+    if (cycle.scheduleId) {
+      await planSchedulerService.cancelSchedule(cycle.scheduleId)
+    }
+
+    await databaseService.update(
+      TABLES.PLAN_CYCLE,
+      ensureRecordId(cycleId, TABLES.PLAN_CYCLE),
+      { status: 'cancelled' },
+      PlanCycleRecordSchema,
+    )
+  }
+
+  async pauseCycle(cycleId: RecordIdInput): Promise<void> {
+    const cycle = await this.getCycle(cycleId)
+    if (!cycle) {
+      throw new Error(`Cycle not found: ${recordIdToString(cycleId, TABLES.PLAN_CYCLE)}`)
+    }
+
+    if (cycle.scheduleId) {
+      await planSchedulerService.pauseSchedule(cycle.scheduleId)
+    }
+
+    await databaseService.update(
+      TABLES.PLAN_CYCLE,
+      ensureRecordId(cycleId, TABLES.PLAN_CYCLE),
+      { status: 'paused' },
+      PlanCycleRecordSchema,
+    )
+  }
+
+  async resumeCycle(cycleId: RecordIdInput): Promise<void> {
+    const cycle = await this.getCycle(cycleId)
+    if (!cycle) {
+      throw new Error(`Cycle not found: ${recordIdToString(cycleId, TABLES.PLAN_CYCLE)}`)
+    }
+
+    if (cycle.scheduleId) {
+      await planSchedulerService.resumeSchedule(cycle.scheduleId)
+    }
+
+    await databaseService.update(
+      TABLES.PLAN_CYCLE,
+      ensureRecordId(cycleId, TABLES.PLAN_CYCLE),
+      { status: 'active' },
+      PlanCycleRecordSchema,
+    )
+  }
+
+  async listCycles(workstreamId: RecordIdInput): Promise<PlanCycleRecord[]> {
+    return databaseService.findMany(
+      TABLES.PLAN_CYCLE,
+      { workstreamId: ensureRecordId(workstreamId, TABLES.WORKSTREAM) },
+      PlanCycleRecordSchema,
+      { orderBy: 'createdAt', orderDir: 'ASC' },
+    )
+  }
+
+  async getCycle(cycleId: RecordIdInput): Promise<PlanCycleRecord | null> {
+    return databaseService.findOne(
+      TABLES.PLAN_CYCLE,
+      { id: ensureRecordId(cycleId, TABLES.PLAN_CYCLE) },
+      PlanCycleRecordSchema,
+    )
+  }
+}
+
+export const planCycleService = new PlanCycleService()

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

@@ -0,0 +1,287 @@
+import type {
+  DeadlineAction,
+  DeadlineReminder,
+  DeadlineSpec,
+  PlanNodeRunRecord,
+  PlanNodeSpecRecord,
+  PlanRunRecord,
+} from '@lota-sdk/shared'
+import { PlanNodeRunSchema, PlanNodeSpecRecordSchema, 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 { getNotificationService } from './notification.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 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:
+            entry.evaluation.activeReminder?.message ?? `Node "${entry.nodeRun.nodeId}" is approaching its deadline.`,
+          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:
+            entry.evaluation.activeReminder?.message ?? `Node "${entry.nodeRun.nodeId}" deadline requires escalation.`,
+          dedupeKey: `${dedupeKeyBase}:escalated:${entry.evaluation.activeReminder?.beforeMs ?? 'default'}`,
+        })
+      } else {
+        await this.applyDeadlineMissAction({
+          runId: entry.nodeRun.runId,
+          nodeId: entry.nodeRun.nodeId,
+          workstreamId,
+          organizationId,
+          action: deadline.missAction,
+          emittedBy: 'plan-deadline-checker',
+        })
+      }
+    }
+
+    const nextTriggerAt: Date | null =
+      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())[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: Date | null =
+      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())[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(
+      {
+        query: `SELECT * FROM ${TABLES.PLAN_NODE_RUN} WHERE status IN $statuses`,
+        bindings: { 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
+    workstreamId: string
+    organizationId: string
+    action: DeadlineAction
+    emittedBy: string
+  }): Promise<void> {
+    const notificationService = getNotificationService()
+    const runIdStr = recordIdToString(params.runId, TABLES.PLAN_RUN)
+
+    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`,
+        })
+        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`,
+        })
+        break
+
+      case 'block': {
+        const { planExecutorService } = await import('./plan-executor.service')
+        await planExecutorService.blockNodeOnDispatchFailure({
+          workstreamId: params.workstreamId,
+          runId: runIdStr,
+          nodeId: params.nodeId,
+          emittedBy: params.emittedBy,
+          message: 'Deadline missed — node blocked',
+          failureClass: 'timeout_exceeded',
+        })
+        break
+      }
+
+      case 'fail': {
+        const { planExecutorService } = await import('./plan-executor.service')
+        await planExecutorService.blockNodeOnDispatchFailure({
+          workstreamId: params.workstreamId,
+          runId: runIdStr,
+          nodeId: params.nodeId,
+          emittedBy: params.emittedBy,
+          message: 'Deadline missed — node failed',
+          failureClass: 'timeout_exceeded',
+        })
+        break
+      }
+    }
+  }
+
+  private async enqueueDeadlineCheck(scheduledFor: Date): Promise<void> {
+    const { enqueueDeadlineCheck } = await import('../queues/plan-scheduler.queue')
+    await enqueueDeadlineCheck(scheduledFor)
+  }
+}
+
+export const planDeadlineService = new PlanDeadlineService()