@lota-sdk/core 0.1.21 → 0.1.23

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

@@ -5,6 +5,7 @@ import type {
   GetActiveExecutionPlanArgs,
   ListExecutionPlansSummary,
   ListExecutionPlansToolResultData,
+  PlanEventRecord,
   PlanNodeRunRecord,
   PlanNodeSpecRecord,
   PlanRunRecord,
@@ -12,6 +13,7 @@ import type {
   ReplaceExecutionPlanArgs,
   ResumeExecutionPlanRunArgs,
   SerializableExecutionPlan,
+  SubmitPlanTurnResultArgs,
   SubmitExecutionNodeResultArgs,
 } from '@lota-sdk/shared'
 import {
@@ -38,21 +40,12 @@ import { ownershipDispatcherService } from './ownership-dispatcher.service'
 import { planBuilderService } from './plan-builder.service'
 import type { CompiledPlanNode } from './plan-compiler.service'
 import { planCompilerService } from './plan-compiler.service'
+import { planEventDeliveryService } from './plan-event-delivery.service'
 import { planExecutorService } from './plan-executor.service'
 import { planRunService } from './plan-run.service'
 import { planSchedulerService } from './plan-scheduler.service'
 import { planValidatorService } from './plan-validator.service'
 
-export type ExecutionPlanDispatchMode = 'deferred' | 'stable-boundary'
-
-const TOOL_RESULT_SERIALIZE_OPTIONS = {
-  includeEvents: true,
-  includeArtifacts: true,
-  includeApprovals: true,
-  includeCheckpoints: true,
-  includeValidationIssues: true,
-} as const
-
 function buildToolResult(params: {
   action: ExecutionPlanToolResultData['action']
   plan: SerializableExecutionPlan | null
@@ -85,6 +78,7 @@ function toSpecData(spec: PlanSpecRecord, patch: Partial<PlanSpecRecord> & { rep
     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
@@ -315,7 +309,6 @@ class ExecutionPlanService {
     organizationId: RecordIdInput
     workstreamId: RecordIdInput
     leadAgentId: string
-    dispatchMode: ExecutionPlanDispatchMode
     input: CreateExecutionPlanArgs
   }): Promise<ExecutionPlanToolResultData> {
     const preparedDraft = planBuilderService.prepareDraft(params.input)
@@ -339,6 +332,7 @@ class ExecutionPlanService {
 
     const specId = new RecordId(TABLES.PLAN_SPEC, Bun.randomUUIDv7())
     const runId = new RecordId(TABLES.PLAN_RUN, Bun.randomUUIDv7())
+    const emittedEvents: PlanEventRecord[] = []
 
     await databaseService.withTransaction(async (tx) => {
       const spec = PlanSpecSchema.parse(
@@ -353,6 +347,7 @@ class ExecutionPlanService {
             status: 'compiled',
             leadAgentId: params.leadAgentId,
             schemaRegistry: structuredClone(compiled.draft.schemas),
+            defaultExecutionVisibility: compiled.draft.defaultExecutionVisibility,
             ...(enrichments.length > 0
               ? { contextEnrichments: enrichments.map((e) => ({ type: e.domain, content: JSON.stringify(e.data) })) }
               : {}),
@@ -392,6 +387,7 @@ class ExecutionPlanService {
         nodeRuns,
         artifacts: [],
         emittedBy: params.leadAgentId,
+        capturedEvents: emittedEvents,
       })
 
       const event = await tx
@@ -405,7 +401,7 @@ class ExecutionPlanService {
           detail: { title: spec.title, objective: spec.objective, nodeCount: nodeSpecs.length },
         })
         .output('after')
-      PlanEventSchema.parse(event)
+      emittedEvents.push(PlanEventSchema.parse(event))
 
       const checkpoint = PlanCheckpointSchema.parse(
         await tx
@@ -448,9 +444,11 @@ class ExecutionPlanService {
           detail: { checkpointId: recordIdToString(checkpoint.id, TABLES.PLAN_CHECKPOINT), reason: 'plan-created' },
         })
         .output('after')
-      PlanEventSchema.parse(checkpointEvent)
+      emittedEvents.push(PlanEventSchema.parse(checkpointEvent))
     })
 
+    await planEventDeliveryService.dispatchEvents(emittedEvents)
+
     // Create a plan-level schedule record if the draft specifies a schedule
     if (compiled.draft.schedule) {
       const schedule = await planSchedulerService.createSchedule({
@@ -472,11 +470,7 @@ class ExecutionPlanService {
       )
     }
 
-    const plan = await this.finalizePlanSnapshot({
-      runId,
-      emittedBy: params.leadAgentId,
-      dispatchMode: params.dispatchMode,
-    })
+    const plan = await this.finalizePlanSnapshot({ runId, emittedBy: params.leadAgentId })
 
     return buildToolResult({ action: 'created', plan, message: `Created execution plan "${plan.title}".` })
   }
@@ -485,7 +479,6 @@ class ExecutionPlanService {
     workstreamId: RecordIdInput
     organizationId: RecordIdInput
     leadAgentId: string
-    dispatchMode: ExecutionPlanDispatchMode
     input: ReplaceExecutionPlanArgs
   }): Promise<ExecutionPlanToolResultData> {
     const activeRun = await planRunService.getRunById(params.input.runId)
@@ -512,6 +505,7 @@ class ExecutionPlanService {
       edges: params.input.edges,
       entryNodeIds: params.input.entryNodeIds,
       schemas: params.input.schemas,
+      defaultExecutionVisibility: params.input.defaultExecutionVisibility,
       executionMode: params.input.executionMode,
       schedule: params.input.schedule,
       dependencies: params.input.dependencies,
@@ -525,6 +519,7 @@ class ExecutionPlanService {
 
     const specId = new RecordId(TABLES.PLAN_SPEC, Bun.randomUUIDv7())
     const runId = new RecordId(TABLES.PLAN_RUN, Bun.randomUUIDv7())
+    const emittedEvents: PlanEventRecord[] = []
 
     await databaseService.withTransaction(async (tx) => {
       const supersededSpec = PlanSpecSchema.parse(
@@ -561,6 +556,7 @@ class ExecutionPlanService {
             status: 'compiled',
             leadAgentId: params.leadAgentId,
             schemaRegistry: structuredClone(compiled.draft.schemas),
+            defaultExecutionVisibility: compiled.draft.defaultExecutionVisibility,
             edges: [...compiled.draft.edges],
             entryNodeIds: [...(compiled.draft.entryNodeIds ?? [])],
             executionMode: compiled.draft.executionMode ?? 'linear',
@@ -599,6 +595,7 @@ class ExecutionPlanService {
         nodeRuns,
         artifacts: [],
         emittedBy: params.leadAgentId,
+        capturedEvents: emittedEvents,
       })
 
       const replaceEvent = await tx
@@ -612,7 +609,7 @@ class ExecutionPlanService {
           detail: { reason: params.input.reason, replacedRunId: recordIdToString(abortedRun.id, TABLES.PLAN_RUN) },
         })
         .output('after')
-      PlanEventSchema.parse(replaceEvent)
+      emittedEvents.push(PlanEventSchema.parse(replaceEvent))
 
       const checkpoint = PlanCheckpointSchema.parse(
         await tx
@@ -655,14 +652,12 @@ class ExecutionPlanService {
           detail: { checkpointId: recordIdToString(checkpoint.id, TABLES.PLAN_CHECKPOINT), reason: 'plan-replaced' },
         })
         .output('after')
-      PlanEventSchema.parse(checkpointEvent)
+      emittedEvents.push(PlanEventSchema.parse(checkpointEvent))
     })
 
-    const plan = await this.finalizePlanSnapshot({
-      runId,
-      emittedBy: params.leadAgentId,
-      dispatchMode: params.dispatchMode,
-    })
+    await planEventDeliveryService.dispatchEvents(emittedEvents)
+
+    const plan = await this.finalizePlanSnapshot({ runId, emittedBy: params.leadAgentId })
 
     return buildToolResult({ action: 'replaced', plan, message: `Replaced execution plan with "${plan.title}".` })
   }
@@ -692,6 +687,33 @@ class ExecutionPlanService {
     })
   }
 
+  async submitPlanTurnResult(params: {
+    workstreamId: RecordIdInput
+    runId: string
+    nodeId: string
+    emittedBy: string
+    input: SubmitPlanTurnResultArgs
+  }): Promise<ExecutionPlanToolResultData> {
+    const result = await planExecutorService.submitNodeResult({
+      workstreamId: params.workstreamId,
+      runId: params.runId,
+      nodeId: params.nodeId,
+      emittedBy: params.emittedBy,
+      result: params.input,
+    })
+    const plan = await ownershipDispatcherService.dispatchRunToStableBoundary({
+      runId: params.runId,
+      emittedBy: params.emittedBy,
+    })
+
+    return buildToolResult({
+      action: result.action,
+      plan,
+      message: result.message ?? `Submitted result for node "${params.nodeId}".`,
+      changedNodeId: result.changedNodeId ?? undefined,
+    })
+  }
+
   async resumeRun(params: {
     workstreamId: RecordIdInput
     emittedBy: string
@@ -804,17 +826,8 @@ class ExecutionPlanService {
   private async finalizePlanSnapshot(params: {
     runId: RecordIdInput
     emittedBy: string
-    dispatchMode: ExecutionPlanDispatchMode
   }): Promise<SerializableExecutionPlan> {
-    if (params.dispatchMode === 'stable-boundary') {
-      return ownershipDispatcherService.dispatchRunToStableBoundary({
-        runId: params.runId,
-        emittedBy: params.emittedBy,
-      })
-    }
-
-    const run = await planRunService.getRunById(params.runId)
-    return planRunService.toSerializablePlan(run, TOOL_RESULT_SERIALIZE_OPTIONS)
+    return ownershipDispatcherService.dispatchRunToStableBoundary({ runId: params.runId, emittedBy: params.emittedBy })
   }
 
   private async createNodeSpecs(
@@ -852,8 +865,10 @@ class ExecutionPlanService {
             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 }

package/src/services/index.ts

@@ -20,6 +20,9 @@ export * from './organization.service'
 export * from './plan-coordination.service'
 export * from './plan-cycle.service'
 export * from './plan-deadline.service'
+export * from './plan-agent-query.service'
+export * from './plan-agent-heartbeat.service'
+export * from './plan-event-delivery.service'
 export * from './plan-workspace.service'
 export * from './plan-run.service'
 export * from './plan-scheduler.service'

package/src/services/ownership-dispatcher.service.ts

@@ -13,6 +13,7 @@ import type {
   PlanSpecRecord,
   PlanDraft,
   SerializableExecutionPlan,
+  UpstreamHandoff,
 } from '@lota-sdk/shared'
 
 import { agentRoster } from '../config/agent-defaults'
@@ -20,6 +21,7 @@ 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, shouldPlanNodeUseVisibleTurn } from '../runtime/execution-plan-visibility'
 import { getRuntimeAdapters } from '../runtime/runtime-extensions'
 import { agentExecutorService } from './agent-executor.service'
 import { domainAgentExecutorService } from './domain-agent-executor.service'
@@ -58,8 +60,10 @@ function toPlanNodeSpec(nodeSpec: PlanNodeSpecRecord): PlanNodeSpec {
       attachmentPolicy: nodeSpec.contextPolicy.attachmentPolicy,
       webPolicy: nodeSpec.contextPolicy.webPolicy,
     },
+    executionVisibility: nodeSpec.executionVisibility,
     ...(nodeSpec.schedule ? { schedule: nodeSpec.schedule } : {}),
     ...(nodeSpec.deadline ? { deadline: nodeSpec.deadline } : {}),
+    ...(nodeSpec.escalation ? { escalation: nodeSpec.escalation } : {}),
     ...(nodeSpec.monitoringConfig ? { monitoringConfig: nodeSpec.monitoringConfig } : {}),
     ...(nodeSpec.delayAfterPredecessorMs ? { delayAfterPredecessorMs: nodeSpec.delayAfterPredecessorMs } : {}),
     ...(nodeSpec.deliberationConfig ? { deliberationConfig: nodeSpec.deliberationConfig } : {}),
@@ -174,10 +178,13 @@ class OwnershipDispatcherService {
       if (nodeRun.status !== 'running') {
         return this.serializeRun(run.id)
       }
+      if (shouldPlanNodeUseVisibleTurn(spec, nodeSpecRecord)) {
+        return this.serializeRun(run.id)
+      }
 
       const [artifacts, dispatchContext] = await Promise.all([
         planRunService.listArtifacts(run.id),
-        this.buildDispatchContext(run),
+        this.buildDispatchContext(run, spec, nodeSpecRecord),
       ])
       const inputArtifacts = artifacts
         .filter((artifact) => nodeSpecRecord.upstreamNodeIds.includes(artifact.nodeId))
@@ -230,10 +237,16 @@ class OwnershipDispatcherService {
     spec: PlanSpecRecord
     executionModeOverride?: ExecutionMode
   }): Promise<PlanNodeResultSubmission> {
+    if (shouldPlanNodeUseVisibleTurn(params.spec, params.nodeSpecRecord)) {
+      throw new Error(
+        `Node "${params.nodeSpecRecord.nodeId}" requires a visible plan turn and cannot be silently dispatched.`,
+      )
+    }
+
     const planNode = toPlanNodeSpec(params.nodeSpecRecord)
     const [artifacts, dispatchContext] = await Promise.all([
       planRunService.listArtifacts(params.run.id),
-      this.buildDispatchContext(params.run),
+      this.buildDispatchContext(params.run, params.spec, params.nodeSpecRecord),
     ])
     const inputArtifacts = artifacts
       .filter((artifact) => params.nodeSpecRecord.upstreamNodeIds.includes(artifact.nodeId))
@@ -261,15 +274,27 @@ class OwnershipDispatcherService {
     return lifecycleState?.bootstrapActive !== true
   }
 
-  private async buildDispatchContext(run: PlanRunRecord): Promise<Omit<OwnershipDispatchContext, 'nodeId'>> {
+  resolveExecutionVisibility(params: { spec: PlanSpecRecord; nodeSpecRecord: PlanNodeSpecRecord }) {
+    return resolvePlanNodeExecutionVisibility(params.spec, params.nodeSpecRecord)
+  }
+
+  private async buildDispatchContext(
+    run: PlanRunRecord,
+    spec: PlanSpecRecord,
+    nodeSpecRecord: PlanNodeSpecRecord,
+  ): Promise<Omit<OwnershipDispatchContext, 'nodeId'>> {
     const organizationId = recordIdToString(run.organizationId, TABLES.ORGANIZATION)
     const workstreamId = recordIdToString(run.workstreamId, TABLES.WORKSTREAM)
     const planId = recordIdToString(run.id, TABLES.PLAN_RUN)
-    const workstream = await databaseService.findOne(
-      TABLES.WORKSTREAM,
-      { id: ensureRecordId(run.workstreamId, TABLES.WORKSTREAM) },
-      WorkstreamSchema,
-    )
+    const [workstream, nodeSpecs, nodeRuns] = await Promise.all([
+      databaseService.findOne(
+        TABLES.WORKSTREAM,
+        { id: ensureRecordId(run.workstreamId, TABLES.WORKSTREAM) },
+        WorkstreamSchema,
+      ),
+      planRunService.listNodeSpecs(spec.id),
+      planRunService.listNodeRuns(run.id),
+    ])
     const userId = workstream?.userId ? recordIdToString(workstream.userId, TABLES.USER) : undefined
     const userName = userId
       ? await userService
@@ -277,6 +302,22 @@ class OwnershipDispatcherService {
           .then((user) => user.name)
           .catch(() => undefined)
       : undefined
+    const nodeSpecsById = new Map(nodeSpecs.map((candidate) => [candidate.nodeId, candidate]))
+    const upstreamHandoffs: UpstreamHandoff[] = nodeRuns
+      .filter(
+        (candidate): candidate is typeof candidate & { handoffContext: NonNullable<typeof candidate.handoffContext> } =>
+          nodeSpecRecord.upstreamNodeIds.includes(candidate.nodeId) && candidate.handoffContext !== undefined,
+      )
+      .map((candidate) => {
+        const upstreamNodeSpec = nodeSpecsById.get(candidate.nodeId)
+        return {
+          nodeId: candidate.nodeId,
+          label: upstreamNodeSpec?.label ?? candidate.nodeId,
+          ownerRef: upstreamNodeSpec?.owner.ref ?? 'unknown',
+          ownerType: upstreamNodeSpec?.owner.executorType ?? 'system',
+          handoffContext: candidate.handoffContext,
+        }
+      })
 
     return {
       organizationId,
@@ -285,6 +326,7 @@ class OwnershipDispatcherService {
       leadAgentId: run.leadAgentId,
       ...(userId ? { userId } : {}),
       ...(userName ? { userName } : {}),
+      ...(upstreamHandoffs.length > 0 ? { upstreamHandoffs } : {}),
     }
   }
 

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

@@ -0,0 +1,136 @@
+import { serverLogger } from '../config/logger'
+import { ensureRecordId } from '../db/record-id'
+import { TABLES } from '../db/tables'
+import { getRedisConnection, withRedisLeaseLock } from '../redis'
+import { resolvePlanNodeExecutionVisibility } from '../runtime/execution-plan-visibility'
+import { planAgentQueryService } from './plan-agent-query.service'
+import { planExecutorService } from './plan-executor.service'
+import { planRunService } from './plan-run.service'
+import { workstreamService } from './workstream.service'
+
+const PLAN_AGENT_HEARTBEAT_LOCK_TTL_MS = 300_000
+const PLAN_AGENT_HEARTBEAT_LOCK_REFRESH_MS = 20_000
+
+function buildHeartbeatLockKey(runId: string, nodeId: string): string {
+  return `plan-agent-heartbeat:${runId}:${nodeId}`
+}
+
+function buildWakeDedupeKey(params: {
+  organizationId: string
+  workstreamId: string
+  runId: string
+  nodeId: string
+  agentId: string
+}) {
+  return `${params.organizationId}:${params.workstreamId}:${params.runId}:${params.nodeId}:${params.agentId}`
+}
+
+class PlanAgentHeartbeatService {
+  async wakeNode(params: {
+    organizationId: string
+    workstreamId: string
+    runId: string
+    nodeId: string
+    agentId: string
+    reason: string
+  }): Promise<boolean> {
+    const workstreamRef = ensureRecordId(params.workstreamId, TABLES.WORKSTREAM)
+    await workstreamService.clearStaleActiveRunIfMissingFromRegistry(workstreamRef)
+    if (await workstreamService.getActiveRunId(workstreamRef)) {
+      return false
+    }
+
+    return withRedisLeaseLock(
+      {
+        redis: getRedisConnection(),
+        lockKey: buildHeartbeatLockKey(params.runId, params.nodeId),
+        lockTtlMs: PLAN_AGENT_HEARTBEAT_LOCK_TTL_MS,
+        refreshIntervalMs: PLAN_AGENT_HEARTBEAT_LOCK_REFRESH_MS,
+        label: 'plan agent heartbeat',
+        maxWaitMs: 5_000,
+        logger: serverLogger,
+      },
+      async () => {
+        await workstreamService.clearStaleActiveRunIfMissingFromRegistry(workstreamRef)
+        if (await workstreamService.hasActiveRunLease(workstreamRef)) {
+          return false
+        }
+        if (await workstreamService.getActiveRunId(workstreamRef)) {
+          return false
+        }
+
+        const run = await planRunService.getRunById(params.runId)
+        const spec = await planRunService.getPlanSpecById(run.planSpecId)
+        const [nodeSpec, nodeRun] = await Promise.all([
+          planRunService.getNodeSpecByNodeId(spec.id, params.nodeId),
+          planRunService.getNodeRunByNodeId(run.id, params.nodeId),
+        ])
+
+        if (nodeSpec.owner.executorType !== 'agent' || nodeSpec.owner.ref !== params.agentId) {
+          return false
+        }
+
+        const visibility = resolvePlanNodeExecutionVisibility(spec, nodeSpec)
+        if (visibility !== 'visible') {
+          return false
+        }
+
+        if (nodeRun.status !== 'running' && nodeRun.status !== 'ready') {
+          return false
+        }
+
+        if (nodeRun.status === 'ready' && run.currentNodeId === params.nodeId) {
+          await planExecutorService.transitionNodeToRunning({ runId: params.runId, nodeId: params.nodeId })
+        }
+
+        const { triggerPlanNodeTurn } = await import('./workstream-turn')
+
+        await triggerPlanNodeTurn({ runId: params.runId, nodeId: params.nodeId })
+        return true
+      },
+    )
+  }
+
+  async sweep(params?: { organizationId?: string }): Promise<void> {
+    const { enqueuePlanAgentHeartbeatWake } = await import('../queues/plan-agent-heartbeat.queue')
+    const [actionable, recentlyUnblocked, approachingDeadlines] = await Promise.all([
+      planAgentQueryService.getActionableNodesForAgent({ organizationId: params?.organizationId }),
+      planAgentQueryService.getRecentlyUnblockedNodes({ organizationId: params?.organizationId }),
+      planAgentQueryService.getApproachingDeadlines({ organizationId: params?.organizationId, withinMinutes: 60 }),
+    ])
+
+    const wakeTargets = new Map<
+      string,
+      { organizationId: string; workstreamId: string; runId: string; nodeId: string; agentId: string; reason: string }
+    >()
+
+    for (const node of actionable) {
+      wakeTargets.set(buildWakeDedupeKey(node), { ...node, reason: 'heartbeat-actionable' })
+    }
+
+    for (const node of recentlyUnblocked) {
+      wakeTargets.set(buildWakeDedupeKey(node), { ...node, reason: node.sourceEventType })
+    }
+
+    for (const node of approachingDeadlines) {
+      if (!node.agentId || node.visibility !== 'visible') {
+        continue
+      }
+      const wakeTarget = {
+        organizationId: node.organizationId,
+        workstreamId: node.workstreamId,
+        runId: node.runId,
+        nodeId: node.nodeId,
+        agentId: node.agentId,
+        reason: `deadline-${node.status}`,
+      }
+      wakeTargets.set(buildWakeDedupeKey(wakeTarget), wakeTarget)
+    }
+
+    for (const target of wakeTargets.values()) {
+      await enqueuePlanAgentHeartbeatWake(target)
+    }
+  }
+}
+
+export const planAgentHeartbeatService = new PlanAgentHeartbeatService()