@lota-sdk/core 0.1.14 → 0.1.16

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

@@ -3,6 +3,8 @@ import type {
   CreateExecutionPlanArgs,
   ExecutionPlanToolResultData,
   GetActiveExecutionPlanArgs,
+  ListExecutionPlansSummary,
+  ListExecutionPlansToolResultData,
   PlanNodeRunRecord,
   PlanNodeSpecRecord,
   PlanRunRecord,
@@ -22,6 +24,7 @@ import {
 } from '@lota-sdk/shared'
 import { RecordId } from 'surrealdb'
 
+import { serverLogger } from '../config/logger'
 import type { RecordIdInput } from '../db/record-id'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
 import { databaseService } from '../db/service'
@@ -29,13 +32,27 @@ import type { DatabaseTransaction } from '../db/service'
 import { TABLES } from '../db/tables'
 import { readApprovalContinuationResponse } from '../runtime/approval-continuation'
 import { extractMessageText } from '../runtime/workstream-chat-helpers'
+import { toDatabaseDateTime } from '../utils/date-time'
+import { contextEnrichmentService } from './context-enrichment.service'
+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 { 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
@@ -68,15 +85,23 @@ 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],
+    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: patch.compiledAt }
+      ? { compiledAt: toDatabaseDateTime(patch.compiledAt) }
       : spec.compiledAt
-        ? { compiledAt: spec.compiledAt }
+        ? { compiledAt: toDatabaseDateTime(spec.compiledAt) }
         : {}),
   }
 }
@@ -89,8 +114,8 @@ type PlanRunUpdate = Omit<
   waitingNodeId?: string | null
   replacedRunId?: RecordIdInput | null
   lastCheckpointId?: RecordIdInput | null
-  startedAt?: Date | null
-  completedAt?: Date | null
+  startedAt?: string | Date | null
+  completedAt?: string | Date | null
 }
 
 function toRunData(run: PlanRunRecord, patch: PlanRunUpdate) {
@@ -133,16 +158,16 @@ function toRunData(run: PlanRunRecord, patch: PlanRunUpdate) {
     ...(patch.startedAt === null
       ? {}
       : patch.startedAt !== undefined
-        ? { startedAt: patch.startedAt }
+        ? { startedAt: toDatabaseDateTime(patch.startedAt) }
         : run.startedAt
-          ? { startedAt: run.startedAt }
+          ? { startedAt: toDatabaseDateTime(run.startedAt) }
           : {}),
     ...(patch.completedAt === null
       ? {}
       : patch.completedAt !== undefined
-        ? { completedAt: patch.completedAt }
+        ? { completedAt: toDatabaseDateTime(patch.completedAt) }
         : run.completedAt
-          ? { completedAt: run.completedAt }
+          ? { completedAt: toDatabaseDateTime(run.completedAt) }
           : {}),
   }
 }
@@ -176,54 +201,142 @@ class ExecutionPlanService {
 
   async getActivePlanForWorkstream(
     workstreamId: RecordIdInput,
-    options?: Partial<GetActiveExecutionPlanArgs>,
+    options?: Partial<GetActiveExecutionPlanArgs> & { runId?: RecordIdInput },
   ): Promise<SerializableExecutionPlan | null> {
-    const run = await planRunService.getActiveRunRecord(workstreamId)
-    if (!run) return null
+    const plans = await this.getActivePlansForWorkstream(workstreamId, options)
+    return plans[0] ?? null
+  }
 
-    return await planRunService.toSerializablePlan(run, {
-      includeEvents: options?.includeEvents,
-      includeArtifacts: options?.includeArtifacts,
-      includeApprovals: options?.includeApprovals,
-      includeCheckpoints: options?.includeCheckpoints,
-      includeValidationIssues: options?.includeValidationIssues,
-    })
+  async getActivePlansForWorkstream(
+    workstreamId: RecordIdInput,
+    options?: Partial<GetActiveExecutionPlanArgs> & { runId?: RecordIdInput },
+  ): Promise<SerializableExecutionPlan[]> {
+    if (options?.runId) {
+      const run = await planRunService.getRunById(options.runId)
+      return [
+        await planRunService.toSerializablePlan(run, {
+          includeEvents: options.includeEvents,
+          includeArtifacts: options.includeArtifacts,
+          includeApprovals: options.includeApprovals,
+          includeCheckpoints: options.includeCheckpoints,
+          includeValidationIssues: options.includeValidationIssues,
+        }),
+      ]
+    }
+
+    const runs = await planRunService.getActiveRunRecords(workstreamId)
+    if (runs.length === 0) return []
+
+    return await Promise.all(
+      runs.map((run) =>
+        planRunService.toSerializablePlan(run, {
+          includeEvents: options?.includeEvents,
+          includeArtifacts: options?.includeArtifacts,
+          includeApprovals: options?.includeApprovals,
+          includeCheckpoints: options?.includeCheckpoints,
+          includeValidationIssues: options?.includeValidationIssues,
+        }),
+      ),
+    )
+  }
+
+  async listActivePlanSummaries(workstreamId: RecordIdInput): Promise<ListExecutionPlansToolResultData> {
+    const runs = await planRunService.getActiveRunRecords(workstreamId)
+    const plans: ListExecutionPlansSummary[] = await Promise.all(
+      runs.map(async (run) => {
+        const spec = await planRunService.getPlanSpecById(run.planSpecId)
+        const nodeRuns = await planRunService.listNodeRuns(run.id)
+        return {
+          runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+          title: spec.title,
+          status: run.status,
+          objective: spec.objective,
+          nodeCount: nodeRuns.length,
+          completedCount: nodeRuns.filter((n) => n.status === 'completed' || n.status === 'partial').length,
+          failedCount: nodeRuns.filter((n) => n.status === 'failed').length,
+        }
+      }),
+    )
+    return { plans, totalCount: plans.length }
   }
 
   async getActivePlanToolResult(params: {
     workstreamId: RecordIdInput
+    runId?: string
     includeEvents?: boolean
     includeArtifacts?: boolean
     includeApprovals?: boolean
     includeCheckpoints?: boolean
     includeValidationIssues?: boolean
   }): Promise<ExecutionPlanToolResultData> {
-    const plan = await this.getActivePlanForWorkstream(params.workstreamId, params)
-    return buildToolResult({
-      action: plan ? 'loaded' : 'none',
-      plan,
-      message: plan ? `Loaded execution run "${plan.title}".` : 'No active execution run.',
-    })
+    const serializeOptions = {
+      includeEvents: params.includeEvents,
+      includeArtifacts: params.includeArtifacts,
+      includeApprovals: params.includeApprovals,
+      includeCheckpoints: params.includeCheckpoints,
+      includeValidationIssues: params.includeValidationIssues,
+    }
+
+    if (params.runId) {
+      const plan = await planRunService
+        .getRunById(params.runId)
+        .then((run) => planRunService.toSerializablePlan(run, serializeOptions))
+      return buildToolResult({ action: 'loaded', plan, message: `Loaded execution run "${plan.title}".` })
+    }
+
+    const runs = await planRunService.getActiveRunRecords(params.workstreamId)
+    if (runs.length === 0) {
+      return buildToolResult({ action: 'none', plan: null, message: 'No active execution run.' })
+    }
+
+    const plan = await planRunService.toSerializablePlan(runs[0], serializeOptions)
+    const planSummaries = await Promise.all(
+      runs.map(async (run) => {
+        const spec = await planRunService.getPlanSpecById(run.planSpecId)
+        return { runId: recordIdToString(run.id, TABLES.PLAN_RUN), title: spec.title, status: run.status }
+      }),
+    )
+
+    return {
+      ...buildToolResult({
+        action: 'loaded',
+        plan,
+        message:
+          runs.length === 1
+            ? `Loaded execution run "${plan.title}".`
+            : `Loaded ${runs.length} active execution runs. Showing most recent: "${plan.title}".`,
+      }),
+      planCount: runs.length,
+      planSummaries,
+    }
   }
 
   async createPlan(params: {
     organizationId: RecordIdInput
     workstreamId: RecordIdInput
     leadAgentId: string
+    dispatchMode: ExecutionPlanDispatchMode
     input: CreateExecutionPlanArgs
   }): Promise<ExecutionPlanToolResultData> {
-    const activeRun = await planRunService.getActiveRunRecord(params.workstreamId)
-    if (activeRun) {
-      throw new Error('An active execution run already exists for this workstream. Replace it instead.')
-    }
-
     const preparedDraft = planBuilderService.prepareDraft(params.input)
     const validation = planValidatorService.validateDraft(preparedDraft)
     if (validation.blocking.length > 0) {
       throw new Error(`Plan draft failed validation: ${aggregateBlockingIssues(validation.blocking)}`)
     }
+    await this.assertDispatchExecutors(preparedDraft)
     const compiled = planCompilerService.compile(preparedDraft)
 
+    // Context enrichment — best-effort, failures do not block plan creation
+    const enrichments = await contextEnrichmentService
+      .enrichForPlanCreation({
+        objective: compiled.draft.objective,
+        organizationId: recordIdToString(params.organizationId, TABLES.ORGANIZATION),
+      })
+      .catch((error: unknown) => {
+        serverLogger.error`Context enrichment failed: ${error instanceof Error ? error.message : String(error)}`
+        return []
+      })
+
     const specId = new RecordId(TABLES.PLAN_SPEC, Bun.randomUUIDv7())
     const runId = new RecordId(TABLES.PLAN_RUN, Bun.randomUUIDv7())
 
@@ -240,8 +353,14 @@ class ExecutionPlanService {
             status: 'compiled',
             leadAgentId: params.leadAgentId,
             schemaRegistry: structuredClone(compiled.draft.schemas),
+            ...(enrichments.length > 0
+              ? { contextEnrichments: enrichments.map((e) => ({ type: e.domain, content: JSON.stringify(e.data) })) }
+              : {}),
             edges: [...compiled.draft.edges],
             entryNodeIds: [...(compiled.draft.entryNodeIds ?? [])],
+            executionMode: compiled.draft.executionMode ?? 'linear',
+            ...(compiled.draft.schedule ? { schedule: compiled.draft.schedule } : {}),
+            ...(compiled.draft.dependencies ? { dependencies: compiled.draft.dependencies } : {}),
             compiledAt: new Date(),
           })
           .output('after'),
@@ -332,12 +451,31 @@ class ExecutionPlanService {
       PlanEventSchema.parse(checkpointEvent)
     })
 
-    const plan = await planRunService.toSerializablePlan(await planRunService.getRunById(runId), {
-      includeEvents: true,
-      includeArtifacts: true,
-      includeApprovals: true,
-      includeCheckpoints: true,
-      includeValidationIssues: true,
+    // Create a plan-level schedule record if the draft specifies a schedule
+    if (compiled.draft.schedule) {
+      const schedule = await planSchedulerService.createSchedule({
+        organizationId: params.organizationId,
+        workstreamId: params.workstreamId,
+        planSpecId: specId,
+        runId,
+        scheduleSpec: compiled.draft.schedule,
+      })
+
+      await databaseService.update(
+        TABLES.PLAN_RUN,
+        ensureRecordId(runId, TABLES.PLAN_RUN),
+        {
+          scheduleId: ensureRecordId(schedule.id, TABLES.PLAN_SCHEDULE),
+          scheduledAt: schedule.nextFireAt ? toDatabaseDateTime(schedule.nextFireAt) : undefined,
+        },
+        PlanRunSchema,
+      )
+    }
+
+    const plan = await this.finalizePlanSnapshot({
+      runId,
+      emittedBy: params.leadAgentId,
+      dispatchMode: params.dispatchMode,
     })
 
     return buildToolResult({ action: 'created', plan, message: `Created execution plan "${plan.title}".` })
@@ -347,14 +485,23 @@ class ExecutionPlanService {
     workstreamId: RecordIdInput
     organizationId: RecordIdInput
     leadAgentId: string
+    dispatchMode: ExecutionPlanDispatchMode
     input: ReplaceExecutionPlanArgs
   }): Promise<ExecutionPlanToolResultData> {
-    const activeRun = await planRunService.getActiveRunRecord(params.workstreamId)
-    if (!activeRun) {
+    const activeRun = await planRunService.getRunById(params.input.runId)
+    if (
+      recordIdToString(activeRun.workstreamId, TABLES.WORKSTREAM) !==
+      recordIdToString(params.workstreamId, TABLES.WORKSTREAM)
+    ) {
+      throw new Error('Execution run belongs to a different workstream.')
+    }
+
+    const activeRuns = await planRunService.getActiveRunRecords(params.workstreamId)
+    if (activeRuns.length === 0) {
       throw new Error('No active execution run exists for this workstream.')
     }
-    if (recordIdToString(activeRun.id, TABLES.PLAN_RUN) !== params.input.runId) {
-      throw new Error('Only the active execution run can be replaced.')
+    if (!activeRuns.some((run) => recordIdToString(run.id, TABLES.PLAN_RUN) === params.input.runId)) {
+      throw new Error('Only an active execution run can be replaced.')
     }
 
     const activeSpec = await planRunService.getPlanSpecById(activeRun.planSpecId)
@@ -365,11 +512,15 @@ class ExecutionPlanService {
       edges: params.input.edges,
       entryNodeIds: params.input.entryNodeIds,
       schemas: params.input.schemas,
+      executionMode: params.input.executionMode,
+      schedule: params.input.schedule,
+      dependencies: params.input.dependencies,
     })
     const validation = planValidatorService.validateDraft(preparedDraft)
     if (validation.blocking.length > 0) {
       throw new Error(`Plan draft failed validation: ${aggregateBlockingIssues(validation.blocking)}`)
     }
+    await this.assertDispatchExecutors(preparedDraft)
     const compiled = planCompilerService.compile(preparedDraft)
 
     const specId = new RecordId(TABLES.PLAN_SPEC, Bun.randomUUIDv7())
@@ -412,6 +563,9 @@ class ExecutionPlanService {
             schemaRegistry: structuredClone(compiled.draft.schemas),
             edges: [...compiled.draft.edges],
             entryNodeIds: [...(compiled.draft.entryNodeIds ?? [])],
+            executionMode: compiled.draft.executionMode ?? 'linear',
+            ...(compiled.draft.schedule ? { schedule: compiled.draft.schedule } : {}),
+            ...(compiled.draft.dependencies ? { dependencies: compiled.draft.dependencies } : {}),
             replacedSpecId: ensureRecordId(supersededSpec.id, TABLES.PLAN_SPEC),
             compiledAt: new Date(),
           })
@@ -504,12 +658,10 @@ class ExecutionPlanService {
       PlanEventSchema.parse(checkpointEvent)
     })
 
-    const plan = await planRunService.toSerializablePlan(await planRunService.getRunById(runId), {
-      includeEvents: true,
-      includeArtifacts: true,
-      includeApprovals: true,
-      includeCheckpoints: true,
-      includeValidationIssues: true,
+    const plan = await this.finalizePlanSnapshot({
+      runId,
+      emittedBy: params.leadAgentId,
+      dispatchMode: params.dispatchMode,
     })
 
     return buildToolResult({ action: 'replaced', plan, message: `Replaced execution plan with "${plan.title}".` })
@@ -520,13 +672,24 @@ class ExecutionPlanService {
     emittedBy: string
     input: SubmitExecutionNodeResultArgs
   }): Promise<ExecutionPlanToolResultData> {
-    return await planExecutorService.submitNodeResult({
+    const result = await planExecutorService.submitNodeResult({
       workstreamId: params.workstreamId,
       runId: params.input.runId,
       nodeId: params.input.nodeId,
       emittedBy: params.emittedBy,
       result: params.input.result,
     })
+    const plan = await ownershipDispatcherService.dispatchRunToStableBoundary({
+      runId: params.input.runId,
+      emittedBy: params.emittedBy,
+    })
+
+    return buildToolResult({
+      action: result.action,
+      plan,
+      message: result.message ?? `Submitted result for node "${params.input.nodeId}".`,
+      changedNodeId: result.changedNodeId ?? undefined,
+    })
   }
 
   async resumeRun(params: {
@@ -534,11 +697,22 @@ class ExecutionPlanService {
     emittedBy: string
     input: ResumeExecutionPlanRunArgs
   }): Promise<ExecutionPlanToolResultData> {
-    return await planExecutorService.resumeRun({
+    const result = await planExecutorService.resumeRun({
       workstreamId: params.workstreamId,
       runId: params.input.runId,
       emittedBy: params.emittedBy,
     })
+    const plan = await ownershipDispatcherService.dispatchRunToStableBoundary({
+      runId: params.input.runId,
+      emittedBy: params.emittedBy,
+    })
+
+    return buildToolResult({
+      action: result.action,
+      plan,
+      message: result.message ?? `Resumed execution run "${params.input.runId}".`,
+      changedNodeId: result.changedNodeId ?? undefined,
+    })
   }
 
   async applyApprovalResponseFromMessages(params: {
@@ -549,12 +723,18 @@ class ExecutionPlanService {
     const approvalResponse = buildApprovalResponseFromMessages(params.approvalMessages)
     if (!approvalResponse) return null
 
-    return await planExecutorService.submitHumanNodeResponse({
+    const run = await planRunService.getActiveRunRecord(params.workstreamId)
+    if (!run) return null
+
+    const plan = await planExecutorService.submitHumanNodeResponse({
       workstreamId: params.workstreamId,
       approvalId: approvalResponse.approvalId,
       respondedBy: params.respondedBy,
       response: approvalResponse.response,
     })
+    if (!plan) return null
+
+    return ownershipDispatcherService.dispatchRunToStableBoundary({ runId: run.id, emittedBy: params.respondedBy })
   }
 
   async respondToApproval(params: {
@@ -562,13 +742,19 @@ class ExecutionPlanService {
     emittedBy: string
     input: { approvalId: string; response: Record<string, unknown>; approvalMessageId?: string }
   }): Promise<SerializableExecutionPlan | null> {
-    return await planExecutorService.submitHumanNodeResponse({
+    const run = await planRunService.getActiveRunRecord(params.workstreamId)
+    if (!run) return null
+
+    const plan = await planExecutorService.submitHumanNodeResponse({
       workstreamId: params.workstreamId,
       approvalId: params.input.approvalId,
       respondedBy: params.emittedBy,
       response: params.input.response,
       approvalMessageId: params.input.approvalMessageId,
     })
+    if (!plan) return null
+
+    return ownershipDispatcherService.dispatchRunToStableBoundary({ runId: run.id, emittedBy: params.emittedBy })
   }
 
   async applyHumanInputFromUserMessage(params: {
@@ -597,12 +783,38 @@ class ExecutionPlanService {
       approved: nodeSpec.type === 'human-decision' ? true : undefined,
     } satisfies Record<string, unknown>
 
-    return await planExecutorService.submitHumanNodeResponse({
+    const plan = await planExecutorService.submitHumanNodeResponse({
       workstreamId: params.workstreamId,
       respondedBy: params.respondedBy,
       response,
       approvalMessageId: params.message.id,
     })
+    if (!plan) return null
+
+    return ownershipDispatcherService.dispatchRunToStableBoundary({ runId: run.id, emittedBy: params.respondedBy })
+  }
+
+  private async assertDispatchExecutors(preparedDraft: Parameters<typeof planValidatorService.validateDraft>[0]) {
+    const issues = ownershipDispatcherService.validateDraftExecutors(preparedDraft)
+    if (issues.length > 0) {
+      throw new Error(`Plan draft failed validation: ${aggregateBlockingIssues(issues)}`)
+    }
+  }
+
+  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)
   }
 
   private async createNodeSpecs(
@@ -612,6 +824,7 @@ class ExecutionPlanService {
   ): Promise<PlanNodeSpecRecord[]> {
     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 = await tx
@@ -639,6 +852,13 @@ class ExecutionPlanService {
             attachmentPolicy: compiledNode.node.contextPolicy.attachmentPolicy,
             webPolicy: compiledNode.node.contextPolicy.webPolicy,
           },
+          ...(compiledNode.node.schedule ? { schedule: compiledNode.node.schedule } : {}),
+          ...(compiledNode.node.deadline ? { deadline: compiledNode.node.deadline } : {}),
+          ...(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],
         })
@@ -657,6 +877,7 @@ class ExecutionPlanService {
     nodeSpecs: PlanNodeSpecRecord[],
   ): Promise<PlanNodeRunRecord[]> {
     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 = await tx

package/src/services/feedback-loop.service.ts

@@ -0,0 +1,96 @@
+import type { Recommendation } from '@lota-sdk/shared'
+
+import { ensureRecordId, recordIdToString } from '../db/record-id'
+import { TABLES } from '../db/tables'
+import { toIsoDateTimeString } from '../utils/date-time'
+import { planRunService } from './plan-run.service'
+
+class FeedbackLoopService {
+  async analyzeOutcomes(params: { runId: string; organizationId: string }): Promise<Recommendation[]> {
+    const run = await planRunService.getRunById(params.runId)
+    const nodeRuns = await planRunService.listNodeRuns(run.id)
+    const attempts = await planRunService.listAttempts(run.id)
+    const nodeSpecs = await planRunService.listNodeSpecs(ensureRecordId(run.planSpecId, TABLES.PLAN_SPEC))
+    const nodeSpecsByNodeId = new Map(nodeSpecs.map((ns) => [ns.nodeId, ns]))
+
+    const recommendations: Recommendation[] = []
+
+    for (const nodeRun of nodeRuns) {
+      const nodeSpec = nodeSpecsByNodeId.get(nodeRun.nodeId)
+      if (!nodeSpec) continue
+
+      const nodeAttempts = attempts.filter((a) => a.nodeId === nodeRun.nodeId)
+      const failedAttempts = nodeAttempts.filter((a) => a.status === 'failed')
+
+      if (failedAttempts.length >= 2) {
+        recommendations.push({
+          type: 'warning',
+          target: 'node',
+          targetId: nodeRun.nodeId,
+          description: `Node "${nodeSpec.label}" failed ${failedAttempts.length} times before ${nodeRun.status === 'completed' || nodeRun.status === 'partial' ? 'succeeding' : 'giving up'}. Consider adjusting retry policy or node instructions.`,
+          evidence: failedAttempts.map((a) => ({
+            sourceType: 'metric',
+            sourceId: recordIdToString(a.id, TABLES.PLAN_NODE_ATTEMPT),
+            summary: `Attempt failed with class: ${a.failureClass ?? 'unknown'}`,
+            confidence: 0.9,
+          })),
+          confidence: Math.min(0.5 + failedAttempts.length * 0.15, 0.95),
+        })
+      }
+    }
+
+    const completedNodeRuns = nodeRuns.filter(
+      (nr) => nr.startedAt && nr.completedAt && (nr.status === 'completed' || nr.status === 'partial'),
+    )
+    if (completedNodeRuns.length >= 2) {
+      const durations = completedNodeRuns.map((nr) => {
+        const start = new Date(toIsoDateTimeString(nr.startedAt)).getTime()
+        const end = new Date(toIsoDateTimeString(nr.completedAt)).getTime()
+        return { nodeId: nr.nodeId, durationMs: end - start }
+      })
+
+      const avgDuration = durations.reduce((sum, d) => sum + d.durationMs, 0) / durations.length
+
+      for (const d of durations) {
+        if (d.durationMs > avgDuration * 2.5 && d.durationMs > 5000) {
+          const nodeSpec = nodeSpecsByNodeId.get(d.nodeId)
+          recommendations.push({
+            type: 'optimization',
+            target: 'node',
+            targetId: d.nodeId,
+            description: `Node "${nodeSpec?.label ?? d.nodeId}" took ${Math.round(d.durationMs / 1000)}s, which is ${Math.round((d.durationMs / avgDuration) * 10) / 10}x the average. Consider splitting or optimizing.`,
+            evidence: [
+              {
+                sourceType: 'metric',
+                sourceId: d.nodeId,
+                summary: `Execution time: ${d.durationMs}ms vs average ${Math.round(avgDuration)}ms`,
+                confidence: 0.85,
+              },
+            ],
+            confidence: 0.7,
+          })
+        }
+      }
+    }
+
+    const skippedNodes = nodeRuns.filter((nr) => nr.status === 'skipped')
+    if (skippedNodes.length > 0 && skippedNodes.length >= nodeRuns.length * 0.3) {
+      recommendations.push({
+        type: 'pattern',
+        target: 'plan',
+        description: `${skippedNodes.length} of ${nodeRuns.length} nodes were skipped. The plan may have overly broad conditional branches.`,
+        evidence: skippedNodes.map((nr) => ({
+          sourceType: 'pattern',
+          sourceId: nr.nodeId,
+          summary: `Node "${nodeSpecsByNodeId.get(nr.nodeId)?.label ?? nr.nodeId}" was skipped`,
+          confidence: 0.8,
+        })),
+        confidence: 0.65,
+      })
+    }
+
+    return recommendations
+  }
+}
+
+export const feedbackLoopService = new FeedbackLoopService()