@lota-sdk/core 0.1.8 → 0.1.11

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

@@ -0,0 +1,422 @@
+import {
+  PlanApprovalSchema,
+  PlanArtifactSchema,
+  PlanCheckpointSchema,
+  PlanEventSchema,
+  PlanNodeAttemptSchema,
+  PlanNodeRunSchema,
+  PlanNodeSpecRecordSchema,
+  PlanRunSchema,
+  PlanSpecSchema,
+  PlanValidationIssueSchema,
+} from '@lota-sdk/shared/schemas/execution-plan'
+import type {
+  PlanApprovalRecord,
+  PlanArtifactRecord,
+  PlanCheckpointRecord,
+  PlanEventRecord,
+  PlanNodeAttemptRecord,
+  PlanNodeRunRecord,
+  PlanNodeRunStatus,
+  PlanNodeSpecRecord,
+  PlanRunRecord,
+  PlanSpecRecord,
+  PlanValidationIssueRecord,
+  SerializableExecutionPlan,
+  SerializablePlanApproval,
+  SerializablePlanArtifact,
+  SerializablePlanCheckpoint,
+  SerializablePlanEvent,
+  SerializablePlanNode,
+  SerializablePlanValidationIssue,
+} from '@lota-sdk/shared/schemas/execution-plan'
+
+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 { toIsoDateTimeString, toOptionalIsoDateTimeString } from '../utils/date-time'
+
+const ACTIVE_RUN_STATUSES = new Set(['running', 'awaiting-human', 'blocked'])
+
+function buildProgress(nodeRuns: PlanNodeRunRecord[]) {
+  const counts = nodeRuns.reduce(
+    (summary, nodeRun) => {
+      summary[nodeRun.status] += 1
+      return summary
+    },
+    {
+      pending: 0,
+      ready: 0,
+      running: 0,
+      'awaiting-human': 0,
+      completed: 0,
+      partial: 0,
+      blocked: 0,
+      failed: 0,
+      skipped: 0,
+    } satisfies Record<PlanNodeRunStatus, number>,
+  )
+
+  const total = nodeRuns.length
+  const completedWork = counts.completed + counts.partial + counts.skipped
+
+  return {
+    total,
+    pending: counts.pending,
+    ready: counts.ready,
+    running: counts.running,
+    awaitingHuman: counts['awaiting-human'],
+    completed: counts.completed,
+    partial: counts.partial,
+    blocked: counts.blocked,
+    failed: counts.failed,
+    skipped: counts.skipped,
+    completionRatio: total > 0 ? Number((completedWork / total).toFixed(4)) : undefined,
+  }
+}
+
+function serializeArtifact(artifact: PlanArtifactRecord): SerializablePlanArtifact {
+  return {
+    id: recordIdToString(artifact.id, TABLES.PLAN_ARTIFACT),
+    nodeId: artifact.nodeId,
+    attemptId: recordIdToString(artifact.attemptId, TABLES.PLAN_NODE_ATTEMPT),
+    name: artifact.name,
+    kind: artifact.kind,
+    pointer: artifact.pointer,
+    schemaRef: artifact.schemaRef,
+    description: artifact.description,
+    payload: artifact.payload,
+    createdAt: toIsoDateTimeString(artifact.createdAt),
+  }
+}
+
+function serializeValidationIssue(issue: PlanValidationIssueRecord): SerializablePlanValidationIssue {
+  return {
+    id: recordIdToString(issue.id, TABLES.PLAN_VALIDATION_ISSUE),
+    nodeId: issue.nodeId,
+    attemptId: issue.attemptId ? recordIdToString(issue.attemptId, TABLES.PLAN_NODE_ATTEMPT) : undefined,
+    severity: issue.severity,
+    code: issue.code,
+    message: issue.message,
+    detail: issue.detail,
+    createdAt: toIsoDateTimeString(issue.createdAt),
+  }
+}
+
+function serializeApproval(approval: PlanApprovalRecord): SerializablePlanApproval {
+  return {
+    id: recordIdToString(approval.id, TABLES.PLAN_APPROVAL),
+    nodeId: approval.nodeId,
+    status: approval.status,
+    presented: approval.presented,
+    response: approval.response,
+    requestedBy: approval.requestedBy,
+    respondedBy: approval.respondedBy,
+    approvalMessageId: approval.approvalMessageId,
+    comments: approval.comments,
+    requiredEdits: [...approval.requiredEdits],
+    createdAt: toIsoDateTimeString(approval.createdAt),
+    respondedAt: toOptionalIsoDateTimeString(approval.respondedAt),
+  }
+}
+
+function serializeCheckpoint(checkpoint: PlanCheckpointRecord): SerializablePlanCheckpoint {
+  return {
+    id: recordIdToString(checkpoint.id, TABLES.PLAN_CHECKPOINT),
+    sequence: checkpoint.sequence,
+    runStatus: checkpoint.runStatus,
+    readyNodeIds: [...checkpoint.readyNodeIds],
+    activeNodeIds: [...checkpoint.activeNodeIds],
+    artifactIds: checkpoint.artifactIds.map((artifactId) => recordIdToString(artifactId, TABLES.PLAN_ARTIFACT)),
+    lastCompletedNodeIds: [...checkpoint.lastCompletedNodeIds],
+    snapshot: checkpoint.snapshot,
+    createdAt: toIsoDateTimeString(checkpoint.createdAt),
+  }
+}
+
+function serializeEvent(event: PlanEventRecord): SerializablePlanEvent {
+  return {
+    id: recordIdToString(event.id, TABLES.PLAN_EVENT),
+    nodeId: event.nodeId,
+    attemptId: event.attemptId ? recordIdToString(event.attemptId, TABLES.PLAN_NODE_ATTEMPT) : undefined,
+    approvalId: event.approvalId ? recordIdToString(event.approvalId, TABLES.PLAN_APPROVAL) : undefined,
+    eventType: event.eventType,
+    fromStatus: event.fromStatus,
+    toStatus: event.toStatus,
+    message: event.message,
+    detail: event.detail,
+    emittedBy: event.emittedBy,
+    createdAt: toIsoDateTimeString(event.createdAt),
+  }
+}
+
+class PlanRunService {
+  async getPlanSpecById(planSpecId: RecordIdInput): Promise<PlanSpecRecord> {
+    const spec = await databaseService.findOne(
+      TABLES.PLAN_SPEC,
+      { id: ensureRecordId(planSpecId, TABLES.PLAN_SPEC) },
+      PlanSpecSchema,
+    )
+    if (!spec) {
+      throw new Error(`Plan spec not found: ${recordIdToString(planSpecId, TABLES.PLAN_SPEC)}`)
+    }
+    return spec
+  }
+
+  async listNodeSpecs(planSpecId: RecordIdInput): Promise<PlanNodeSpecRecord[]> {
+    return await databaseService.findMany(
+      TABLES.PLAN_NODE_SPEC,
+      { planSpecId: ensureRecordId(planSpecId, TABLES.PLAN_SPEC) },
+      PlanNodeSpecRecordSchema,
+      { orderBy: 'position', orderDir: 'ASC' },
+    )
+  }
+
+  async getNodeSpecByNodeId(planSpecId: RecordIdInput, nodeId: string): Promise<PlanNodeSpecRecord> {
+    const nodeSpec = await databaseService.findOne(
+      TABLES.PLAN_NODE_SPEC,
+      { planSpecId: ensureRecordId(planSpecId, TABLES.PLAN_SPEC), nodeId },
+      PlanNodeSpecRecordSchema,
+    )
+    if (!nodeSpec) {
+      throw new Error(`Plan node spec "${nodeId}" not found.`)
+    }
+    return nodeSpec
+  }
+
+  async getRunById(runId: RecordIdInput): Promise<PlanRunRecord> {
+    const run = await databaseService.findOne(
+      TABLES.PLAN_RUN,
+      { id: ensureRecordId(runId, TABLES.PLAN_RUN) },
+      PlanRunSchema,
+    )
+    if (!run) {
+      throw new Error(`Plan run not found: ${recordIdToString(runId, TABLES.PLAN_RUN)}`)
+    }
+    return run
+  }
+
+  async getActiveRunRecord(workstreamId: RecordIdInput): Promise<PlanRunRecord | null> {
+    const runs = await databaseService.findMany(
+      TABLES.PLAN_RUN,
+      { workstreamId: ensureRecordId(workstreamId, TABLES.WORKSTREAM) },
+      PlanRunSchema,
+      { orderBy: 'updatedAt', orderDir: 'DESC' },
+    )
+
+    return runs.find((run) => ACTIVE_RUN_STATUSES.has(run.status)) ?? null
+  }
+
+  async listNodeRuns(runId: RecordIdInput): Promise<PlanNodeRunRecord[]> {
+    return await databaseService.findMany(
+      TABLES.PLAN_NODE_RUN,
+      { runId: ensureRecordId(runId, TABLES.PLAN_RUN) },
+      PlanNodeRunSchema,
+      { orderBy: 'nodeId', orderDir: 'ASC' },
+    )
+  }
+
+  async getNodeRunByNodeId(runId: RecordIdInput, nodeId: string): Promise<PlanNodeRunRecord> {
+    const nodeRun = await databaseService.findOne(
+      TABLES.PLAN_NODE_RUN,
+      { runId: ensureRecordId(runId, TABLES.PLAN_RUN), nodeId },
+      PlanNodeRunSchema,
+    )
+    if (!nodeRun) {
+      throw new Error(`Plan node run "${nodeId}" not found.`)
+    }
+    return nodeRun
+  }
+
+  async listArtifacts(runId: RecordIdInput): Promise<PlanArtifactRecord[]> {
+    return await databaseService.findMany(
+      TABLES.PLAN_ARTIFACT,
+      { runId: ensureRecordId(runId, TABLES.PLAN_RUN) },
+      PlanArtifactSchema,
+      { orderBy: 'createdAt', orderDir: 'ASC' },
+    )
+  }
+
+  async listAttempts(runId: RecordIdInput): Promise<PlanNodeAttemptRecord[]> {
+    return await databaseService.findMany(
+      TABLES.PLAN_NODE_ATTEMPT,
+      { runId: ensureRecordId(runId, TABLES.PLAN_RUN) },
+      PlanNodeAttemptSchema,
+      { orderBy: 'createdAt', orderDir: 'ASC' },
+    )
+  }
+
+  async listValidationIssues(params: {
+    runId?: RecordIdInput
+    planSpecId?: RecordIdInput
+    attemptId?: RecordIdInput
+  }): Promise<PlanValidationIssueRecord[]> {
+    const filter: Record<string, unknown> = {}
+    if (params.runId) filter.runId = ensureRecordId(params.runId, TABLES.PLAN_RUN)
+    if (params.planSpecId) filter.planSpecId = ensureRecordId(params.planSpecId, TABLES.PLAN_SPEC)
+    if (params.attemptId) filter.attemptId = ensureRecordId(params.attemptId, TABLES.PLAN_NODE_ATTEMPT)
+
+    return await databaseService.findMany(TABLES.PLAN_VALIDATION_ISSUE, filter, PlanValidationIssueSchema, {
+      orderBy: 'createdAt',
+      orderDir: 'ASC',
+    })
+  }
+
+  async listApprovals(runId: RecordIdInput): Promise<PlanApprovalRecord[]> {
+    return await databaseService.findMany(
+      TABLES.PLAN_APPROVAL,
+      { runId: ensureRecordId(runId, TABLES.PLAN_RUN) },
+      PlanApprovalSchema,
+      { orderBy: 'createdAt', orderDir: 'ASC' },
+    )
+  }
+
+  async getLatestCheckpoint(runId: RecordIdInput): Promise<PlanCheckpointRecord | null> {
+    const checkpoints = await databaseService.findMany(
+      TABLES.PLAN_CHECKPOINT,
+      { runId: ensureRecordId(runId, TABLES.PLAN_RUN) },
+      PlanCheckpointSchema,
+      { orderBy: 'sequence', orderDir: 'DESC', limit: 1 },
+    )
+
+    return checkpoints.at(0) ?? null
+  }
+
+  async getNextCheckpointSequence(runId: RecordIdInput): Promise<number> {
+    const latestCheckpoint = await this.getLatestCheckpoint(runId)
+    return latestCheckpoint ? latestCheckpoint.sequence + 1 : 1
+  }
+
+  async listEvents(runId: RecordIdInput, limit = 20): Promise<PlanEventRecord[]> {
+    return (
+      await databaseService.findMany(
+        TABLES.PLAN_EVENT,
+        { runId: ensureRecordId(runId, TABLES.PLAN_RUN) },
+        PlanEventSchema,
+        { orderBy: 'createdAt', orderDir: 'DESC', limit },
+      )
+    ).reverse()
+  }
+
+  async toSerializablePlan(
+    run: PlanRunRecord,
+    options?: {
+      includeArtifacts?: boolean
+      includeApprovals?: boolean
+      includeCheckpoints?: boolean
+      includeEvents?: boolean
+      includeValidationIssues?: boolean
+    },
+  ): Promise<SerializableExecutionPlan> {
+    const spec = await this.getPlanSpecById(run.planSpecId)
+    const nodeSpecs = await this.listNodeSpecs(spec.id)
+    const nodeRuns = await this.listNodeRuns(run.id)
+    const artifacts = options?.includeArtifacts === false ? [] : await this.listArtifacts(run.id)
+    const lineageArtifacts = options?.includeArtifacts === false ? [] : await this.collectLineageArtifacts(run)
+    const approvals = options?.includeApprovals === false ? [] : await this.listApprovals(run.id)
+    const validationIssues =
+      options?.includeValidationIssues === false
+        ? []
+        : await this.listValidationIssues({ runId: run.id, planSpecId: spec.id })
+    const latestCheckpoint = options?.includeCheckpoints ? await this.getLatestCheckpoint(run.id) : null
+    const recentEvents = options?.includeEvents === false ? [] : await this.listEvents(run.id, 20)
+    const nodeRunsById = new Map(nodeRuns.map((nodeRun) => [nodeRun.nodeId, nodeRun]))
+
+    const nodes: SerializablePlanNode[] = nodeSpecs.map((nodeSpec) => {
+      const nodeRun = nodeRunsById.get(nodeSpec.nodeId)
+      if (!nodeRun) {
+        throw new Error(
+          `Plan run ${recordIdToString(run.id, TABLES.PLAN_RUN)} is missing node run "${nodeSpec.nodeId}".`,
+        )
+      }
+
+      return {
+        id: nodeSpec.nodeId,
+        type: nodeSpec.type,
+        label: nodeSpec.label,
+        owner: nodeSpec.owner,
+        objective: nodeSpec.objective,
+        instructions: nodeSpec.instructions,
+        inputSchemaRef: nodeSpec.inputSchemaRef,
+        outputSchemaRef: nodeSpec.outputSchemaRef,
+        deliverables: [...nodeSpec.deliverables],
+        successCriteria: [...nodeSpec.successCriteria],
+        completionChecks: [...nodeSpec.completionChecks],
+        retryPolicy: { ...nodeSpec.retryPolicy, retryOn: [...nodeSpec.retryPolicy.retryOn] },
+        failurePolicy: [...nodeSpec.failurePolicy],
+        timeoutMs: nodeSpec.timeoutMs,
+        toolPolicy: { allow: [...nodeSpec.toolPolicy.allow], deny: [...nodeSpec.toolPolicy.deny] },
+        contextPolicy: {
+          retrievalScopes: [...nodeSpec.contextPolicy.retrievalScopes],
+          attachmentPolicy: nodeSpec.contextPolicy.attachmentPolicy,
+          webPolicy: nodeSpec.contextPolicy.webPolicy,
+        },
+        status: nodeRun.status,
+        attemptCount: nodeRun.attemptCount,
+        retryCount: nodeRun.retryCount,
+        resolvedInput: nodeRun.resolvedInput,
+        latestStructuredOutput: nodeRun.latestStructuredOutput,
+        latestNotes: nodeRun.latestNotes,
+        blockedReason: nodeRun.blockedReason,
+        failureClass: nodeRun.failureClass,
+        upstreamNodeIds: [...nodeSpec.upstreamNodeIds],
+        downstreamNodeIds: [...nodeSpec.downstreamNodeIds],
+        readyAt: toOptionalIsoDateTimeString(nodeRun.readyAt),
+        startedAt: toOptionalIsoDateTimeString(nodeRun.startedAt),
+        completedAt: toOptionalIsoDateTimeString(nodeRun.completedAt),
+      }
+    })
+
+    return {
+      specId: recordIdToString(spec.id, TABLES.PLAN_SPEC),
+      runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+      workstreamId: recordIdToString(run.workstreamId, TABLES.WORKSTREAM),
+      organizationId: recordIdToString(run.organizationId, TABLES.ORGANIZATION),
+      title: spec.title,
+      objective: spec.objective,
+      version: spec.version,
+      status: run.status,
+      leadAgentId: run.leadAgentId,
+      schemaRegistry: structuredClone(spec.schemaRegistry),
+      entryNodeIds: [...spec.entryNodeIds],
+      edges: [...spec.edges],
+      activeNodeIds: run.currentNodeId ? [run.currentNodeId] : [],
+      readyNodeIds: [...run.readyNodeIds],
+      waitingNodeId: run.waitingNodeId,
+      replacedRunId: run.replacedRunId ? recordIdToString(run.replacedRunId, TABLES.PLAN_RUN) : undefined,
+      failureCount: run.failureCount,
+      startedAt: toOptionalIsoDateTimeString(run.startedAt),
+      completedAt: toOptionalIsoDateTimeString(run.completedAt),
+      progress: buildProgress(nodeRuns),
+      nodes,
+      artifacts: artifacts.map(serializeArtifact),
+      lineageArtifacts,
+      validationIssues: validationIssues.map(serializeValidationIssue),
+      approvals: approvals.map(serializeApproval),
+      latestCheckpoint: latestCheckpoint ? serializeCheckpoint(latestCheckpoint) : null,
+      recentEvents: recentEvents.map(serializeEvent),
+    }
+  }
+
+  private async collectLineageArtifacts(run: PlanRunRecord): Promise<SerializablePlanArtifact[]> {
+    const lineageArtifacts: SerializablePlanArtifact[] = []
+    let currentRunId = run.replacedRunId ? ensureRecordId(run.replacedRunId, TABLES.PLAN_RUN) : null
+    let depth = 0
+
+    while (currentRunId && depth < 5) {
+      const previousRun = await databaseService.findOne(TABLES.PLAN_RUN, { id: currentRunId }, PlanRunSchema)
+      if (!previousRun) break
+
+      const artifacts = await this.listArtifacts(previousRun.id)
+      lineageArtifacts.unshift(...artifacts.map(serializeArtifact))
+
+      currentRunId = previousRun.replacedRunId ? ensureRecordId(previousRun.replacedRunId, TABLES.PLAN_RUN) : null
+      depth += 1
+    }
+
+    return lineageArtifacts
+  }
+}
+
+export const planRunService = new PlanRunService()