@lota-sdk/core 0.4.8 → 0.4.10

package/src/services/execution-plan/execution-plan-graph.ts

@@ -0,0 +1,278 @@
+import type { PlanEventRecord, PlanNodeRunRecord, PlanNodeSpecRecord, PlanSpecRecord } from '@lota-sdk/shared'
+import {
+  PlanCheckpointSchema,
+  PlanEventSchema,
+  PlanNodeRunSchema,
+  PlanNodeSpecRecordSchema,
+  PlanRunSchema,
+} from '@lota-sdk/shared'
+import { Effect } from 'effect'
+import { RecordId } from 'surrealdb'
+import type { z } from 'zod'
+
+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 { ServiceError } from '../../effect/errors'
+import { runPromise } from '../../effect/runtime'
+import { nowDate } from '../../utils/date-time'
+import type { CompiledPlanNode } from '../plan/plan-compiler.service'
+import type { syncRunGraph } from '../plan/plan-executor-graph'
+import { toRunData } from '../plan/plan-run-data'
+
+function parseRowOrFail<TSchema extends z.ZodTypeAny>(
+  schema: TSchema,
+  value: unknown,
+  operation: string,
+): Effect.Effect<z.infer<TSchema>, ServiceError> {
+  return Effect.try({
+    try: () => schema.parse(value) as z.infer<TSchema>,
+    catch: (cause) => new ServiceError({ message: `Failed to parse row for ${operation}.`, cause }),
+  })
+}
+
+type SyncRunGraphParams = Parameters<typeof syncRunGraph>[1]
+type SyncRunGraphResult = Awaited<ReturnType<typeof syncRunGraph>>
+
+interface ExecutionPlanGraphExecutor {
+  syncRunGraph(params: SyncRunGraphParams): Promise<SyncRunGraphResult>
+}
+
+function buildNodeSpecCreateContent(compiledNode: CompiledPlanNode, planSpecId: RecordIdInput) {
+  return {
+    planSpecId: ensureRecordId(planSpecId, TABLES.PLAN_SPEC),
+    nodeId: compiledNode.node.id,
+    position: compiledNode.position,
+    type: compiledNode.node.type,
+    label: compiledNode.node.label,
+    owner: compiledNode.node.owner,
+    objective: compiledNode.node.objective,
+    instructions: compiledNode.node.instructions,
+    ...(compiledNode.node.inputSchemaRef ? { inputSchemaRef: compiledNode.node.inputSchemaRef } : {}),
+    ...(compiledNode.node.outputSchemaRef ? { outputSchemaRef: compiledNode.node.outputSchemaRef } : {}),
+    deliverables: [...compiledNode.node.deliverables],
+    successCriteria: [...compiledNode.node.successCriteria],
+    completionChecks: [...compiledNode.node.completionChecks],
+    retryPolicy: { ...compiledNode.node.retryPolicy, retryOn: [...compiledNode.node.retryPolicy.retryOn] },
+    failurePolicy: [...compiledNode.node.failurePolicy],
+    ...(compiledNode.node.timeoutMs ? { timeoutMs: compiledNode.node.timeoutMs } : {}),
+    toolPolicy: { allow: [...compiledNode.node.toolPolicy.allow], deny: [...compiledNode.node.toolPolicy.deny] },
+    contextPolicy: {
+      retrievalScopes: [...compiledNode.node.contextPolicy.retrievalScopes],
+      attachmentPolicy: compiledNode.node.contextPolicy.attachmentPolicy,
+      webPolicy: compiledNode.node.contextPolicy.webPolicy,
+    },
+    executionVisibility: compiledNode.node.executionVisibility,
+    ...(compiledNode.node.schedule ? { schedule: compiledNode.node.schedule } : {}),
+    ...(compiledNode.node.deadline ? { deadline: compiledNode.node.deadline } : {}),
+    ...(compiledNode.node.escalation ? { escalation: compiledNode.node.escalation } : {}),
+    ...(compiledNode.node.monitoringConfig ? { monitoringConfig: compiledNode.node.monitoringConfig } : {}),
+    ...(compiledNode.node.delayAfterPredecessorMs
+      ? { delayAfterPredecessorMs: compiledNode.node.delayAfterPredecessorMs }
+      : {}),
+    ...(compiledNode.node.deliberationConfig ? { deliberationConfig: compiledNode.node.deliberationConfig } : {}),
+    upstreamNodeIds: [...compiledNode.upstreamNodeIds],
+    downstreamNodeIds: [...compiledNode.downstreamNodeIds],
+  }
+}
+
+function buildNodeRunCreateContent(runId: RecordIdInput, planSpecId: RecordIdInput, nodeSpec: PlanNodeSpecRecord) {
+  return {
+    runId: ensureRecordId(runId, TABLES.PLAN_RUN),
+    planSpecId: ensureRecordId(planSpecId, TABLES.PLAN_SPEC),
+    nodeId: nodeSpec.nodeId,
+    status: 'pending' as const,
+    attemptCount: 0,
+    retryCount: 0,
+  }
+}
+
+function createNodeSpecs(tx: DatabaseTransaction, planSpecId: RecordIdInput, nodes: CompiledPlanNode[]) {
+  return Effect.gen(function* () {
+    const createdRecords: PlanNodeSpecRecord[] = []
+
+    // Sequential: SurrealDB transactions require ordered operations
+    for (const compiledNode of nodes) {
+      const nodeSpecId = new RecordId(TABLES.PLAN_NODE_SPEC, Bun.randomUUIDv7())
+      const created = yield* tx
+        .create(nodeSpecId)
+        .content(buildNodeSpecCreateContent(compiledNode, planSpecId))
+        .output('after')
+      createdRecords.push(yield* parseRowOrFail(PlanNodeSpecRecordSchema, created, 'createNodeSpecs'))
+    }
+
+    return createdRecords
+  })
+}
+
+function createNodeRuns(
+  tx: DatabaseTransaction,
+  runId: RecordIdInput,
+  planSpecId: RecordIdInput,
+  nodeSpecs: PlanNodeSpecRecord[],
+) {
+  return Effect.gen(function* () {
+    const createdNodeRuns: PlanNodeRunRecord[] = []
+
+    // Sequential: SurrealDB transactions require ordered operations
+    for (const nodeSpec of nodeSpecs) {
+      const nodeRunId = new RecordId(TABLES.PLAN_NODE_RUN, Bun.randomUUIDv7())
+      const created = yield* tx
+        .create(nodeRunId)
+        .content(buildNodeRunCreateContent(runId, planSpecId, nodeSpec))
+        .output('after')
+      createdNodeRuns.push(yield* parseRowOrFail(PlanNodeRunSchema, created, 'createNodeRuns'))
+    }
+
+    return createdNodeRuns
+  })
+}
+
+export function createInitializedRunGraph(params: {
+  tx: DatabaseTransaction
+  runId: RecordIdInput
+  spec: PlanSpecRecord
+  organizationId: RecordIdInput
+  threadId: RecordIdInput
+  sourceThreadId?: RecordIdInput
+  leadAgentId: string
+  createdByAgentId?: string
+  requireApproval: boolean
+  nodes: CompiledPlanNode[]
+  emittedEvents: PlanEventRecord[]
+  createdEventType: 'plan-created' | 'plan-replaced'
+  createdEventMessage: string
+  createdEventDetail: Record<string, unknown>
+  checkpointReason: 'plan-created' | 'plan-replaced'
+  runPatch?: { replacedRunId?: RecordIdInput }
+  planExecutor: ExecutionPlanGraphExecutor
+}) {
+  return runPromise(
+    Effect.gen(function* () {
+      const nodeSpecs = yield* createNodeSpecs(params.tx, params.spec.id, params.nodes)
+      const runRaw = yield* params.tx
+        .create(ensureRecordId(params.runId, TABLES.PLAN_RUN))
+        .content({
+          planSpecId: ensureRecordId(params.spec.id, TABLES.PLAN_SPEC),
+          organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+          threadId: ensureRecordId(params.threadId, TABLES.THREAD),
+          ...(params.sourceThreadId ? { sourceThreadId: ensureRecordId(params.sourceThreadId, TABLES.THREAD) } : {}),
+          leadAgentId: params.leadAgentId,
+          ...(params.createdByAgentId ? { createdByAgentId: params.createdByAgentId } : {}),
+          status: params.requireApproval ? 'pending-approval' : 'running',
+          readyNodeIds: [],
+          failureCount: 0,
+          ...(params.runPatch?.replacedRunId
+            ? { replacedRunId: ensureRecordId(params.runPatch.replacedRunId, TABLES.PLAN_RUN) }
+            : {}),
+          ...(params.requireApproval ? {} : { startedAt: nowDate() }),
+        })
+        .output('after')
+      const run = yield* parseRowOrFail(PlanRunSchema, runRaw, 'createInitializedRunGraph:run')
+
+      const nodeRuns = yield* createNodeRuns(params.tx, run.id, params.spec.id, nodeSpecs)
+      const synced = params.requireApproval
+        ? { run, nodeRuns }
+        : yield* Effect.tryPromise(() =>
+            params.planExecutor.syncRunGraph({
+              tx: params.tx,
+              run,
+              spec: params.spec,
+              nodeSpecs,
+              nodeRuns,
+              artifacts: [],
+              emittedBy: params.leadAgentId,
+              capturedEvents: params.emittedEvents,
+            }),
+          )
+
+      const event = yield* params.tx
+        .create(new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7()))
+        .content({
+          planSpecId: ensureRecordId(params.spec.id, TABLES.PLAN_SPEC),
+          runId: ensureRecordId(synced.run.id, TABLES.PLAN_RUN),
+          eventType: params.createdEventType,
+          message: params.createdEventMessage,
+          emittedBy: params.leadAgentId,
+          detail: { ...params.createdEventDetail, nodeCount: nodeSpecs.length },
+        })
+        .output('after')
+      params.emittedEvents.push(yield* parseRowOrFail(PlanEventSchema, event, 'createInitializedRunGraph:createdEvent'))
+
+      if (params.requireApproval) {
+        const pendingApprovalEvent = yield* params.tx
+          .create(new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7()))
+          .content({
+            planSpecId: ensureRecordId(params.spec.id, TABLES.PLAN_SPEC),
+            runId: ensureRecordId(synced.run.id, TABLES.PLAN_RUN),
+            eventType: 'plan-pending-approval',
+            toStatus: synced.run.status,
+            message: `Execution plan "${params.spec.title}" is pending approval.`,
+            emittedBy: params.leadAgentId,
+            detail: { ...params.createdEventDetail, nodeCount: nodeSpecs.length },
+          })
+          .output('after')
+        params.emittedEvents.push(
+          yield* parseRowOrFail(
+            PlanEventSchema,
+            pendingApprovalEvent,
+            'createInitializedRunGraph:pendingApprovalEvent',
+          ),
+        )
+      }
+
+      const checkpointRaw = yield* params.tx
+        .create(new RecordId(TABLES.PLAN_CHECKPOINT, Bun.randomUUIDv7()))
+        .content({
+          runId: ensureRecordId(synced.run.id, TABLES.PLAN_RUN),
+          sequence: 1,
+          runStatus: synced.run.status,
+          readyNodeIds: [...synced.run.readyNodeIds],
+          activeNodeIds: synced.run.currentNodeId ? [synced.run.currentNodeId] : [],
+          artifactIds: [],
+          lastCompletedNodeIds: synced.nodeRuns
+            .filter((nodeRun) => nodeRun.status === 'completed' || nodeRun.status === 'partial')
+            .map((nodeRun) => nodeRun.nodeId),
+          snapshot: {
+            reason: params.checkpointReason,
+            currentNodeId: synced.run.currentNodeId,
+            waitingNodeId: synced.run.waitingNodeId,
+            readyNodeIds: synced.run.readyNodeIds,
+          },
+        })
+        .output('after')
+      const checkpoint = yield* parseRowOrFail(
+        PlanCheckpointSchema,
+        checkpointRaw,
+        'createInitializedRunGraph:checkpoint',
+      )
+
+      const updatedRunRaw = yield* params.tx
+        .update(ensureRecordId(synced.run.id, TABLES.PLAN_RUN))
+        .content(toRunData(synced.run, { lastCheckpointId: checkpoint.id }))
+        .output('after')
+      const updatedRun = yield* parseRowOrFail(PlanRunSchema, updatedRunRaw, 'createInitializedRunGraph:updatedRun')
+
+      const checkpointEvent = yield* params.tx
+        .create(new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7()))
+        .content({
+          planSpecId: ensureRecordId(params.spec.id, TABLES.PLAN_SPEC),
+          runId: ensureRecordId(updatedRun.id, TABLES.PLAN_RUN),
+          eventType: 'checkpoint-saved',
+          message: 'Saved checkpoint 1.',
+          emittedBy: 'system',
+          detail: {
+            checkpointId: recordIdToString(checkpoint.id, TABLES.PLAN_CHECKPOINT),
+            reason: params.checkpointReason,
+          },
+        })
+        .output('after')
+      params.emittedEvents.push(
+        yield* parseRowOrFail(PlanEventSchema, checkpointEvent, 'createInitializedRunGraph:checkpointEvent'),
+      )
+
+      return updatedRun
+    }),
+  )
+}

package/src/services/execution-plan/execution-plan-schedule.ts

@@ -0,0 +1,84 @@
+import type { PlanRunRecord } from '@lota-sdk/shared'
+import { PlanRunSchema } from '@lota-sdk/shared'
+import { Schema, Effect } from 'effect'
+
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId } from '../../db/record-id'
+import type { SurrealDBService } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { runPromise } from '../../effect/runtime'
+import { toDatabaseDateTime } from '../../utils/date-time'
+import { toRunData } from '../plan/plan-run-data'
+import type { makePlanRunService } from '../plan/plan-run.service'
+import type { makePlanSchedulerService } from '../plan/plan-scheduler.service'
+
+class PlanScheduleAttachError extends Schema.TaggedErrorClass<PlanScheduleAttachError>()('PlanScheduleAttachError', {
+  cause: Schema.String,
+}) {}
+
+function toPlanScheduleAttachError(operation: string, cause: unknown) {
+  const detail = cause instanceof Error ? cause.message : String(cause)
+  return new PlanScheduleAttachError({ cause: `${operation}: ${detail}` })
+}
+
+function attachPlanScheduleIfNeededEffect(params: {
+  db: SurrealDBService
+  planRunService: ReturnType<typeof makePlanRunService>
+  planSchedulerService: ReturnType<typeof makePlanSchedulerService>
+  organizationId: RecordIdInput
+  threadId: RecordIdInput
+  runId: RecordIdInput
+  planSpecId: RecordIdInput
+}) {
+  return Effect.gen(function* () {
+    const [run, spec] = yield* Effect.all([
+      params.planRunService
+        .getRunById(params.runId)
+        .pipe(Effect.mapError((cause) => toPlanScheduleAttachError('get-run-by-id', cause))),
+      params.planRunService
+        .getPlanSpecById(params.planSpecId)
+        .pipe(Effect.mapError((cause) => toPlanScheduleAttachError('get-plan-spec-by-id', cause))),
+    ])
+
+    const scheduleSpec = spec.schedule
+    if (!scheduleSpec || run.scheduleId) {
+      return run
+    }
+
+    const schedule = yield* params.planSchedulerService
+      .createSchedule({
+        organizationId: params.organizationId,
+        threadId: params.threadId,
+        planSpecId: params.planSpecId,
+        runId: params.runId,
+        scheduleSpec,
+      })
+      .pipe(Effect.mapError((cause) => toPlanScheduleAttachError('create-schedule', cause)))
+
+    const updatedRun = yield* params.db
+      .update(
+        TABLES.PLAN_RUN,
+        ensureRecordId(params.runId, TABLES.PLAN_RUN),
+        toRunData(run, {
+          scheduleId: schedule.id,
+          scheduledAt: schedule.nextFireAt ? toDatabaseDateTime(schedule.nextFireAt) : undefined,
+        }),
+        PlanRunSchema,
+      )
+      .pipe(Effect.mapError((cause) => toPlanScheduleAttachError('attach-plan-schedule', cause)))
+
+    return updatedRun ?? run
+  })
+}
+
+export function attachPlanScheduleIfNeeded(params: {
+  db: SurrealDBService
+  planRunService: ReturnType<typeof makePlanRunService>
+  planSchedulerService: ReturnType<typeof makePlanSchedulerService>
+  organizationId: RecordIdInput
+  threadId: RecordIdInput
+  runId: RecordIdInput
+  planSpecId: RecordIdInput
+}): Promise<PlanRunRecord> {
+  return runPromise(attachPlanScheduleIfNeededEffect(params))
+}

package/src/services/execution-plan/execution-plan-spec.ts

@@ -0,0 +1,75 @@
+import type { PlanDraft, PlanSpecRecord } from '@lota-sdk/shared'
+
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId } from '../../db/record-id'
+import { TABLES } from '../../db/tables'
+import { nowDate, toDatabaseDateTime } from '../../utils/date-time'
+
+export function toSpecData(
+  spec: PlanSpecRecord,
+  patch: Partial<PlanSpecRecord> & { replacedSpecId?: RecordIdInput | null },
+) {
+  return {
+    organizationId: ensureRecordId(spec.organizationId, TABLES.ORGANIZATION),
+    threadId: ensureRecordId(spec.threadId, TABLES.THREAD),
+    title: patch.title ?? spec.title,
+    objective: patch.objective ?? spec.objective,
+    version: patch.version ?? spec.version,
+    status: patch.status ?? spec.status,
+    leadAgentId: patch.leadAgentId ?? spec.leadAgentId,
+    schemaRegistry: patch.schemaRegistry ? structuredClone(patch.schemaRegistry) : structuredClone(spec.schemaRegistry),
+    edges: patch.edges ? [...patch.edges] : [...spec.edges],
+    entryNodeIds: patch.entryNodeIds ? [...patch.entryNodeIds] : [...spec.entryNodeIds],
+    defaultExecutionVisibility: patch.defaultExecutionVisibility ?? spec.defaultExecutionVisibility,
+    executionMode: patch.executionMode ?? spec.executionMode,
+    ...(patch.schedule !== undefined ? { schedule: patch.schedule } : spec.schedule ? { schedule: spec.schedule } : {}),
+    ...(patch.dependencies !== undefined
+      ? { dependencies: patch.dependencies }
+      : spec.dependencies
+        ? { dependencies: spec.dependencies }
+        : {}),
+    ...(spec.contextEnrichments ? { contextEnrichments: spec.contextEnrichments } : {}),
+    ...(patch.replacedSpecId
+      ? { replacedSpecId: ensureRecordId(patch.replacedSpecId, TABLES.PLAN_SPEC) }
+      : spec.replacedSpecId
+        ? { replacedSpecId: ensureRecordId(spec.replacedSpecId, TABLES.PLAN_SPEC) }
+        : {}),
+    ...(patch.compiledAt !== undefined
+      ? { compiledAt: toDatabaseDateTime(patch.compiledAt) }
+      : spec.compiledAt
+        ? { compiledAt: toDatabaseDateTime(spec.compiledAt) }
+        : {}),
+  }
+}
+
+export function buildCompiledSpecCreateData(params: {
+  organizationId: RecordIdInput
+  threadId: RecordIdInput
+  leadAgentId: string
+  compiled: { draft: PlanDraft }
+  version: number
+  replacedSpecId?: RecordIdInput
+  contextEnrichments?: PlanSpecRecord['contextEnrichments']
+}) {
+  return {
+    organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+    threadId: ensureRecordId(params.threadId, TABLES.THREAD),
+    title: params.compiled.draft.title,
+    objective: params.compiled.draft.objective,
+    version: params.version,
+    status: 'compiled' as const,
+    leadAgentId: params.leadAgentId,
+    schemaRegistry: structuredClone(params.compiled.draft.schemas),
+    defaultExecutionVisibility: params.compiled.draft.defaultExecutionVisibility,
+    ...(params.contextEnrichments?.length
+      ? { contextEnrichments: params.contextEnrichments.map((entry) => ({ ...entry })) }
+      : {}),
+    edges: [...params.compiled.draft.edges],
+    entryNodeIds: [...(params.compiled.draft.entryNodeIds ?? [])],
+    executionMode: params.compiled.draft.executionMode ?? 'linear',
+    ...(params.compiled.draft.schedule ? { schedule: params.compiled.draft.schedule } : {}),
+    ...(params.compiled.draft.dependencies ? { dependencies: params.compiled.draft.dependencies } : {}),
+    ...(params.replacedSpecId ? { replacedSpecId: ensureRecordId(params.replacedSpecId, TABLES.PLAN_SPEC) } : {}),
+    compiledAt: nowDate(),
+  }
+}