@lota-sdk/core 0.4.8 → 0.4.9

package/src/services/plan/plan-executor-helpers.ts

@@ -0,0 +1,322 @@
+import type {
+  PlanFailureAction,
+  PlanFailureClass,
+  PlanNodeResultSubmission,
+  PlanNodeRunRecord,
+  PlanNodeSpecRecord,
+  PlanSpecRecord,
+} from '@lota-sdk/shared'
+import {
+  HUMAN_NODE_TYPES as HUMAN_NODE_TYPE_VALUES,
+  STRUCTURAL_NODE_TYPES as STRUCTURAL_NODE_TYPE_VALUES,
+  isSafePath,
+  isSafePathOrRoot,
+} from '@lota-sdk/shared'
+import { Effect } from 'effect'
+
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId } from '../../db/record-id'
+import { TABLES } from '../../db/tables'
+import { ValidationError } from '../../effect/errors'
+import { toDatabaseDateTime } from '../../utils/date-time'
+import { createNullProtoRecord, setPathValue } from '../../utils/null-proto-record'
+import { isExecutableConditionExpression, readPathValue } from './plan-helpers'
+
+const SUCCESSFUL_TERMINAL_NODE_STATUSES = new Set(['completed', 'partial', 'skipped', 'scheduled', 'monitoring'])
+const HUMAN_NODE_TYPE_SET = new Set<string>(HUMAN_NODE_TYPE_VALUES)
+const STRUCTURAL_NODE_TYPE_SET = new Set<string>(STRUCTURAL_NODE_TYPE_VALUES)
+
+function parseLiteralValue(raw: string): Effect.Effect<unknown> {
+  const trimmed = raw.trim()
+  if (!trimmed.length) return Effect.succeed(undefined)
+  if (trimmed === 'true') return Effect.succeed(true)
+  if (trimmed === 'false') return Effect.succeed(false)
+  if (trimmed === 'null') return Effect.succeed(null)
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Effect.succeed(Number(trimmed))
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+    (trimmed.startsWith('`') && trimmed.endsWith('`'))
+  ) {
+    return Effect.succeed(trimmed.slice(1, -1))
+  }
+
+  return Effect.try({ try: (): unknown => JSON.parse(trimmed), catch: (cause) => cause }).pipe(
+    Effect.catch(() => Effect.succeed(trimmed)),
+  )
+}
+
+function buildArtifactContext(artifacts: Array<{ name: string; kind: string; payload?: unknown }>) {
+  return Object.fromEntries(
+    artifacts.map((artifact) => [artifact.name, { kind: artifact.kind, payload: artifact.payload }]),
+  )
+}
+
+export function buildNodeContext(params: {
+  nodeRun:
+    | { resolvedInput?: Record<string, unknown> | null; latestStructuredOutput?: Record<string, unknown> | null }
+    | undefined
+  artifacts: Array<{ name: string; kind: string; payload?: unknown }>
+}) {
+  return {
+    input: params.nodeRun?.resolvedInput ?? {},
+    output: params.nodeRun?.latestStructuredOutput ?? {},
+    artifact: buildArtifactContext(params.artifacts),
+  }
+}
+
+export function buildPublishedArtifactContent(params: {
+  artifact: PlanNodeResultSubmission['artifacts'][number]
+  notes: string
+}): string {
+  const { artifact, notes } = params
+  if (artifact.content?.trim()) {
+    return artifact.content
+  }
+
+  if (artifact.payload !== undefined) {
+    return `# ${artifact.name}\n\n\`\`\`json\n${JSON.stringify(artifact.payload, null, 2)}\n\`\`\``
+  }
+
+  return `# ${artifact.name}\n\n${notes.trim()}`
+}
+
+export function evaluateCondition(
+  expression: string | undefined,
+  context: Record<string, unknown>,
+): Effect.Effect<boolean> {
+  if (!expression?.trim()) return Effect.succeed(true)
+  const normalized = expression.trim()
+  if (normalized === 'always') return Effect.succeed(true)
+
+  const match = normalized.match(/^([a-zA-Z0-9_.]+)\s*(==|!=|>=|<=|>|<)\s*(.+)$/)
+  if (!match) {
+    if (!isExecutableConditionExpression(normalized)) {
+      return Effect.succeed(true)
+    }
+    return Effect.succeed(Boolean(readPathValue(context, normalized)))
+  }
+
+  return Effect.gen(function* () {
+    const [, leftPath, operator, rawRightValue] = match
+    const left = readPathValue(context, leftPath)
+    const right = yield* parseLiteralValue(rawRightValue)
+
+    if (operator === '==') return Object.is(left, right)
+    if (operator === '!=') return !Object.is(left, right)
+    if (typeof left !== 'number' || typeof right !== 'number') return false
+    if (operator === '>=') return left >= right
+    if (operator === '<=') return left <= right
+    if (operator === '>') return left > right
+    return left < right
+  })
+}
+
+export function isSuccessfulTerminalStatus(status: string): boolean {
+  return SUCCESSFUL_TERMINAL_NODE_STATUSES.has(status)
+}
+
+export function isHumanNodeType(type: string): boolean {
+  return HUMAN_NODE_TYPE_SET.has(type)
+}
+
+export function isStructuralNodeType(type: string): boolean {
+  return STRUCTURAL_NODE_TYPE_SET.has(type)
+}
+
+type PlanNodeRunUpdate = Omit<
+  Partial<PlanNodeRunRecord>,
+  | 'blockedReason'
+  | 'failureClass'
+  | 'resolvedInput'
+  | 'latestStructuredOutput'
+  | 'latestNotes'
+  | 'latestAttemptId'
+  | 'scheduledAt'
+  | 'readyAt'
+  | 'startedAt'
+  | 'completedAt'
+> & {
+  blockedReason?: string | null
+  failureClass?: PlanFailureClass | null
+  resolvedInput?: Record<string, unknown> | null
+  latestStructuredOutput?: Record<string, unknown> | null
+  latestNotes?: string | null
+  latestAttemptId?: RecordIdInput | null
+  scheduledAt?: string | Date | null
+  readyAt?: string | Date | null
+  startedAt?: string | Date | null
+  completedAt?: string | Date | null
+}
+
+export function toNodeRunData(nodeRun: PlanNodeRunRecord, patch: PlanNodeRunUpdate) {
+  return {
+    runId: ensureRecordId(nodeRun.runId, TABLES.PLAN_RUN),
+    planSpecId: ensureRecordId(nodeRun.planSpecId, TABLES.PLAN_SPEC),
+    nodeId: nodeRun.nodeId,
+    status: patch.status ?? nodeRun.status,
+    attemptCount: patch.attemptCount ?? nodeRun.attemptCount,
+    retryCount: patch.retryCount ?? nodeRun.retryCount,
+    ...(patch.resolvedInput === null
+      ? {}
+      : patch.resolvedInput !== undefined
+        ? { resolvedInput: patch.resolvedInput }
+        : nodeRun.resolvedInput
+          ? { resolvedInput: nodeRun.resolvedInput }
+          : {}),
+    ...(patch.latestStructuredOutput === null
+      ? {}
+      : patch.latestStructuredOutput !== undefined
+        ? { latestStructuredOutput: patch.latestStructuredOutput }
+        : nodeRun.latestStructuredOutput
+          ? { latestStructuredOutput: nodeRun.latestStructuredOutput }
+          : {}),
+    ...(patch.latestNotes === null
+      ? {}
+      : patch.latestNotes !== undefined
+        ? { latestNotes: patch.latestNotes }
+        : nodeRun.latestNotes
+          ? { latestNotes: nodeRun.latestNotes }
+          : {}),
+    ...(patch.latestAttemptId === null
+      ? {}
+      : patch.latestAttemptId !== undefined
+        ? { latestAttemptId: ensureRecordId(patch.latestAttemptId, TABLES.PLAN_NODE_ATTEMPT) }
+        : nodeRun.latestAttemptId
+          ? { latestAttemptId: ensureRecordId(nodeRun.latestAttemptId, TABLES.PLAN_NODE_ATTEMPT) }
+          : {}),
+    ...(patch.blockedReason === null
+      ? {}
+      : patch.blockedReason !== undefined
+        ? { blockedReason: patch.blockedReason }
+        : nodeRun.blockedReason
+          ? { blockedReason: nodeRun.blockedReason }
+          : {}),
+    ...(patch.failureClass === null
+      ? {}
+      : patch.failureClass !== undefined
+        ? { failureClass: patch.failureClass }
+        : nodeRun.failureClass
+          ? { failureClass: nodeRun.failureClass }
+          : {}),
+    ...(patch.scheduledAt === null
+      ? {}
+      : patch.scheduledAt !== undefined
+        ? { scheduledAt: toDatabaseDateTime(patch.scheduledAt) }
+        : nodeRun.scheduledAt
+          ? { scheduledAt: toDatabaseDateTime(nodeRun.scheduledAt) }
+          : {}),
+    ...(patch.readyAt === null
+      ? {}
+      : patch.readyAt !== undefined
+        ? { readyAt: toDatabaseDateTime(patch.readyAt) }
+        : nodeRun.readyAt
+          ? { readyAt: toDatabaseDateTime(nodeRun.readyAt) }
+          : {}),
+    ...(patch.startedAt === null
+      ? {}
+      : patch.startedAt !== undefined
+        ? { startedAt: toDatabaseDateTime(patch.startedAt) }
+        : nodeRun.startedAt
+          ? { startedAt: toDatabaseDateTime(nodeRun.startedAt) }
+          : {}),
+    ...(patch.completedAt === null
+      ? {}
+      : patch.completedAt !== undefined
+        ? { completedAt: toDatabaseDateTime(patch.completedAt) }
+        : nodeRun.completedAt
+          ? { completedAt: toDatabaseDateTime(nodeRun.completedAt) }
+          : {}),
+  }
+}
+
+export interface HumanNodeResponsePayload {
+  approved?: boolean
+  comments?: string
+  reason?: string
+  requiredEdits?: readonly string[]
+  responseText?: string
+  messageId?: string
+  [key: string]: unknown
+}
+
+export function readHumanResponseComments(response: HumanNodeResponsePayload): string | undefined {
+  const comments = response.comments
+  if (typeof comments === 'string' && comments.trim().length > 0) {
+    return comments
+  }
+
+  const reason = response.reason
+  return typeof reason === 'string' && reason.trim().length > 0 ? reason : undefined
+}
+
+export function readHumanRequiredEdits(response: HumanNodeResponsePayload): string[] | undefined {
+  if (!Array.isArray(response.requiredEdits)) {
+    return undefined
+  }
+
+  const requiredEdits = response.requiredEdits.filter(
+    (entry): entry is string => typeof entry === 'string' && entry.trim().length > 0,
+  )
+
+  return requiredEdits.length > 0 ? requiredEdits : undefined
+}
+
+export function deriveApprovalStatus(
+  response: HumanNodeResponsePayload,
+): 'approved' | 'rejected' | 'changes-requested' {
+  const approved = response.approved === true
+  const requiredEdits = readHumanRequiredEdits(response) ?? []
+
+  if (approved && requiredEdits.length === 0) return 'approved'
+  if (requiredEdits.length > 0) return 'changes-requested'
+  return 'rejected'
+}
+
+export function resolveFailureAction(
+  nodeSpec: Pick<PlanNodeSpecRecord, 'failurePolicy'>,
+  failureClass: PlanFailureClass | null,
+): PlanFailureAction {
+  if (!failureClass) return 'abort'
+
+  const matchedRule = nodeSpec.failurePolicy.find((rule) => rule.on === failureClass)
+  return matchedRule?.action ?? 'abort'
+}
+
+export function buildResolvedInput(params: {
+  spec: Pick<PlanSpecRecord, 'edges'>
+  nodeSpec: Pick<PlanNodeSpecRecord, 'nodeId'>
+  nodeRunsById: Map<string, Pick<PlanNodeRunRecord, 'status' | 'resolvedInput' | 'latestStructuredOutput'>>
+  artifactsByNodeId: Map<string, Array<{ name: string; kind: string; payload?: unknown }>>
+}): Effect.Effect<Record<string, unknown>, ValidationError> {
+  return Effect.gen(function* () {
+    const resolvedInput: Record<string, unknown> = createNullProtoRecord()
+
+    for (const edge of params.spec.edges.filter((candidate) => candidate.target === params.nodeSpec.nodeId)) {
+      const sourceRun = params.nodeRunsById.get(edge.source)
+      if (!sourceRun || !isSuccessfulTerminalStatus(sourceRun.status)) continue
+
+      const context = buildNodeContext({
+        nodeRun: sourceRun,
+        artifacts: params.artifactsByNodeId.get(edge.source) ?? [],
+      })
+      const matches = yield* evaluateCondition(edge.when, context)
+      if (!matches) continue
+
+      for (const [targetPath, sourcePath] of Object.entries(edge.map)) {
+        if (!isSafePath(targetPath)) {
+          return yield* new ValidationError({ message: `Unsafe edge target path "${targetPath}" in edge "${edge.id}"` })
+        }
+        if (!isSafePathOrRoot(sourcePath)) {
+          return yield* new ValidationError({ message: `Unsafe edge source path "${sourcePath}" in edge "${edge.id}"` })
+        }
+        const value = readPathValue(context, sourcePath)
+        if (value !== undefined) {
+          setPathValue(resolvedInput, targetPath, value)
+        }
+      }
+    }
+
+    return resolvedInput
+  })
+}

package/src/services/plan/plan-executor-persistence.ts

@@ -0,0 +1,209 @@
+import type {
+  PlanEventRecord,
+  PlanEventType,
+  PlanFailureClass,
+  PlanNodeResultSubmission,
+  PlanNodeRunRecord,
+  PlanRunRecord,
+  PlanSpecRecord,
+  PlanValidationIssueRecord,
+} from '@lota-sdk/shared'
+import { PlanEventSchema, PlanNodeAttemptSchema, PlanRunSchema, PlanValidationIssueSchema } from '@lota-sdk/shared'
+import { Effect } from 'effect'
+import { RecordId } from 'surrealdb'
+
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId, recordIdToString } from '../../db/record-id'
+import type { DatabaseTransaction } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { DatabaseError } from '../../effect/errors'
+import type { makePlanCheckpointService } from './plan-checkpoint.service'
+import type { PlanRunUpdate } from './plan-run-data'
+import { toRunData } from './plan-run-data'
+import type { PlanValidationIssueInput } from './plan-validator.service'
+
+export function createAttempt(params: {
+  tx: DatabaseTransaction
+  run: PlanRunRecord
+  nodeRun: PlanNodeRunRecord
+  emittedBy: string
+  result: PlanNodeResultSubmission
+  status: 'completed' | 'failed'
+  failureClass: PlanFailureClass | null
+}) {
+  return Effect.gen(function* () {
+    const attemptId = new RecordId(TABLES.PLAN_NODE_ATTEMPT, Bun.randomUUIDv7())
+    const created = yield* params.tx
+      .create(attemptId)
+      .content({
+        runId: ensureRecordId(params.run.id, TABLES.PLAN_RUN),
+        nodeRunId: ensureRecordId(params.nodeRun.id, TABLES.PLAN_NODE_RUN),
+        nodeId: params.nodeRun.nodeId,
+        emittedBy: params.emittedBy,
+        status: params.status,
+        ...(params.result.structuredOutput ? { structuredOutput: params.result.structuredOutput } : {}),
+        ...(params.result.notes ? { notes: params.result.notes } : {}),
+        validationIssueIds: [],
+        ...(params.failureClass ? { failureClass: params.failureClass } : {}),
+      })
+      .output('after')
+    return PlanNodeAttemptSchema.parse(created)
+  })
+}
+
+export function persistValidationIssues(params: {
+  tx: DatabaseTransaction
+  run: PlanRunRecord
+  spec: PlanSpecRecord
+  attemptId: RecordIdInput
+  nodeId: string
+  issues: PlanValidationIssueInput[]
+}) {
+  return Effect.gen(function* () {
+    const records: PlanValidationIssueRecord[] = []
+    yield* Effect.forEach(params.issues, (issue) =>
+      Effect.gen(function* () {
+        const issueId = new RecordId(TABLES.PLAN_VALIDATION_ISSUE, Bun.randomUUIDv7())
+        const created = yield* params.tx
+          .create(issueId)
+          .content({
+            planSpecId: ensureRecordId(params.spec.id, TABLES.PLAN_SPEC),
+            runId: ensureRecordId(params.run.id, TABLES.PLAN_RUN),
+            nodeId: issue.nodeId ?? params.nodeId,
+            attemptId: ensureRecordId(params.attemptId, TABLES.PLAN_NODE_ATTEMPT),
+            severity: issue.severity,
+            code: issue.code,
+            message: issue.message,
+            ...(issue.detail ? { detail: issue.detail } : {}),
+          })
+          .output('after')
+        const parsed = PlanValidationIssueSchema.parse(created)
+        records.push(parsed)
+        return parsed
+      }),
+    )
+
+    return records
+  })
+}
+
+export function emitEvent(params: {
+  tx: DatabaseTransaction
+  run: PlanRunRecord
+  spec: PlanSpecRecord
+  eventType: PlanEventType
+  message: string
+  emittedBy: string
+  nodeId?: string
+  attemptId?: RecordIdInput
+  approvalId?: RecordIdInput
+  fromStatus?: string
+  toStatus?: string
+  detail?: Record<string, unknown>
+  capturedEvents?: PlanEventRecord[]
+}) {
+  return Effect.gen(function* () {
+    const eventId = new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7())
+    const created = yield* params.tx
+      .create(eventId)
+      .content({
+        planSpecId: ensureRecordId(params.spec.id, TABLES.PLAN_SPEC),
+        runId: ensureRecordId(params.run.id, TABLES.PLAN_RUN),
+        eventType: params.eventType,
+        message: params.message,
+        emittedBy: params.emittedBy,
+        ...(params.nodeId ? { nodeId: params.nodeId } : {}),
+        ...(params.attemptId ? { attemptId: ensureRecordId(params.attemptId, TABLES.PLAN_NODE_ATTEMPT) } : {}),
+        ...(params.approvalId ? { approvalId: ensureRecordId(params.approvalId, TABLES.PLAN_APPROVAL) } : {}),
+        ...(params.fromStatus ? { fromStatus: params.fromStatus } : {}),
+        ...(params.toStatus ? { toStatus: params.toStatus } : {}),
+        ...(params.detail ? { detail: params.detail } : {}),
+      })
+      .output('after')
+    const event = PlanEventSchema.parse(created)
+    params.capturedEvents?.push(event)
+    return event
+  })
+}
+
+export function saveCheckpoint(params: {
+  tx: DatabaseTransaction
+  run: PlanRunRecord
+  spec: PlanSpecRecord
+  nodeRuns: PlanNodeRunRecord[]
+  artifacts: Array<{ id: RecordIdInput; nodeId: string }>
+  sequence: number
+  reason: string
+  includeWorkspace?: boolean
+  capturedEvents?: PlanEventRecord[]
+  planCheckpointService: ReturnType<typeof makePlanCheckpointService>
+}) {
+  return Effect.gen(function* () {
+    const checkpoint = yield* params.planCheckpointService.createCheckpoint({
+      tx: params.tx,
+      runId: params.run.id,
+      sequence: params.sequence,
+      runStatus: params.run.status,
+      readyNodeIds: params.run.readyNodeIds,
+      activeNodeIds: params.run.currentNodeId ? [params.run.currentNodeId] : [],
+      artifactIds: params.artifacts.map((artifact) => artifact.id),
+      lastCompletedNodeIds: params.nodeRuns
+        .filter((nodeRun) => nodeRun.status === 'completed' || nodeRun.status === 'partial')
+        .map((nodeRun) => nodeRun.nodeId),
+      snapshot: {
+        reason: params.reason,
+        runStatus: params.run.status,
+        currentNodeId: params.run.currentNodeId,
+        waitingNodeId: params.run.waitingNodeId,
+        readyNodeIds: params.run.readyNodeIds,
+        nodeStatuses: Object.fromEntries(params.nodeRuns.map((nodeRun) => [nodeRun.nodeId, nodeRun.status])),
+      },
+      includeWorkspace: params.includeWorkspace,
+    })
+
+    yield* emitEvent({
+      tx: params.tx,
+      run: params.run,
+      spec: params.spec,
+      eventType: 'checkpoint-saved',
+      message: `Saved checkpoint ${checkpoint.sequence}.`,
+      detail: { checkpointId: recordIdToString(checkpoint.id, TABLES.PLAN_CHECKPOINT), reason: params.reason },
+      emittedBy: 'system',
+      capturedEvents: params.capturedEvents,
+    })
+
+    return checkpoint
+  })
+}
+
+export function attachCheckpoint(tx: DatabaseTransaction, run: PlanRunRecord, checkpoint: { id: RecordIdInput }) {
+  return Effect.asVoid(
+    tx
+      .update(ensureRecordId(run.id, TABLES.PLAN_RUN))
+      .content(toRunData(run, { lastCheckpointId: checkpoint.id }))
+      .output('after'),
+  )
+}
+
+export function replaceRun(
+  tx: DatabaseTransaction,
+  run: PlanRunRecord,
+  patch: PlanRunUpdate,
+): Effect.Effect<PlanRunRecord, DatabaseError, never> {
+  return Effect.gen(function* () {
+    const updated = yield* tx
+      .update(ensureRecordId(run.id, TABLES.PLAN_RUN))
+      .content(toRunData(run, patch))
+      .output('after')
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new DatabaseError({
+              message: `Failed to update plan run ${recordIdToString(run.id, TABLES.PLAN_RUN)}.`,
+              cause,
+            }),
+        ),
+      )
+    return PlanRunSchema.parse(updated)
+  })
+}