@pikku/core 0.11.2 → 0.12.1

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -1,25 +1,30 @@
 import { runPikkuFunc } from '../../function/function-runner.js'
-import { pikkuState } from '../../pikku-state.js'
-import { getDurationInMilliseconds } from '../../time-utils.js'
 import {
-  CoreConfig,
-  CoreSingletonServices,
-  CreateWireServices,
-  PikkuWire,
-  SerializedError,
-} from '../../types/core.types.js'
-import { QueueService } from '../queue/queue.types.js'
+  getSingletonServices,
+  getCreateWireServices,
+  pikkuState,
+} from '../../pikku-state.js'
+import { getDurationInMilliseconds } from '../../time-utils.js'
+import type { PikkuWire, SerializedError } from '../../types/core.types.js'
+import type { QueueService } from '../queue/queue.types.js'
 import type {
   PikkuWorkflowWire,
   StepState,
   WorkflowRun,
+  WorkflowRunWire,
   WorkflowStatus,
   WorkflowServiceConfig,
   WorkflowStepOptions,
 } from './workflow.types.js'
-import { executeGraphStep, runWorkflowGraph } from './graph/graph-runner.js'
-import { WorkflowService } from '../../services/workflow-service.js'
-import { PikkuError } from '../../errors/error-handler.js'
+import {
+  continueGraph,
+  executeGraphStep,
+  runWorkflowGraph,
+  runFromMeta,
+} from './graph/graph-runner.js'
+import type { WorkflowService } from '../../services/workflow-service.js'
+import { PikkuError, addError } from '../../errors/error-handler.js'
+import { RPCNotFoundError } from '../rpc/rpc-runner.js'
 
 /**
  * Exception thrown when workflow needs to pause for async step
@@ -47,6 +52,19 @@ export class WorkflowCancelledException extends Error {
   }
 }
 
+/**
+ * Exception thrown when workflow is suspended
+ */
+export class WorkflowSuspendedException extends Error {
+  constructor(
+    public readonly runId: string,
+    public readonly reason: string
+  ) {
+    super(reason || 'Workflow suspended')
+    this.name = 'WorkflowSuspendedException'
+  }
+}
+
 /**
  * Error class for workflow not found
  */
@@ -55,15 +73,20 @@ export class WorkflowNotFoundError extends PikkuError {
     super(`Workflow not found: ${name}`)
   }
 }
+addError(WorkflowNotFoundError, {
+  status: 404,
+  message: 'Workflow not found.',
+})
 
-/**
- * Error class for workflow not found
- */
-export class WorkflowRunNotFound extends PikkuError {
+export class WorkflowRunNotFoundError extends PikkuError {
   constructor(runId: string) {
     super(`Workflow run not found: ${runId}`)
   }
 }
+addError(WorkflowRunNotFoundError, {
+  status: 404,
+  message: 'Workflow run not found.',
+})
 
 export class WorkflowServiceNotInitialized extends Error {}
 export class WorkflowStepNameNotString extends Error {
@@ -72,15 +95,19 @@ export class WorkflowStepNameNotString extends Error {
   }
 }
 
+const WORKFLOW_END_STATES: ReadonlySet<string> = new Set([
+  'completed',
+  'failed',
+  'cancelled',
+  'suspended',
+])
+
 /**
  * Abstract workflow state service
  * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
  * Combines orchestration and step execution
  */
 export abstract class PikkuWorkflowService implements WorkflowService {
-  private config: WorkflowServiceConfig | undefined
-  private singletonServices: CoreSingletonServices | undefined
-  private createWireServices: CreateWireServices | undefined
   private inlineRuns = new Set<string>()
 
   constructor() {}
@@ -106,34 +133,20 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     this.inlineRuns.delete(runId)
   }
 
-  public setServices(
-    singletonServices: CoreSingletonServices,
-    createWireServices: CreateWireServices,
-    { workflow }: CoreConfig
-  ) {
-    this.singletonServices = singletonServices
-    this.createWireServices = createWireServices
-    this.config = {
-      retries: workflow?.retries ?? 0,
-      retryDelay: workflow?.retryDelay ?? 0,
-      orchestratorQueueName:
-        workflow?.orchestratorQueueName ?? 'pikku-workflow-orchestrator',
-      stepWorkerQueueName:
-        workflow?.stepWorkerQueueName ?? 'pikku-workflow-step-worker',
-      sleeperRPCName: workflow?.sleeperRPCName ?? 'pikkuWorkflowSleeper',
+  public async registerWorkflowVersions(): Promise<void> {
+    const allMeta = pikkuState(null, 'workflows', 'meta')
+    for (const [name, meta] of Object.entries(allMeta)) {
+      if (!meta.graphHash) continue
+      await this.upsertWorkflowVersion(name, meta.graphHash, meta, meta.source)
     }
   }
 
-  /**
-   * Create a new workflow run
-   * @param name - Workflow name
-   * @param input - Input data for the workflow
-   * @returns Run ID
-   */
   abstract createRun(
     workflowName: string,
     input: any,
-    inline?: boolean
+    inline: boolean,
+    graphHash: string,
+    wire: WorkflowRunWire
   ): Promise<string>
 
   /**
@@ -270,6 +283,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
    */
   abstract getCompletedGraphState(runId: string): Promise<{
     completedNodeIds: string[]
+    failedNodeIds: string[]
     branchKeys: Record<string, string>
   }>
 
@@ -321,6 +335,18 @@ export abstract class PikkuWorkflowService implements WorkflowService {
    */
   abstract getRunState(runId: string): Promise<Record<string, unknown>>
 
+  abstract upsertWorkflowVersion(
+    name: string,
+    graphHash: string,
+    graph: any,
+    source: string
+  ): Promise<void>
+
+  abstract getWorkflowVersion(
+    name: string,
+    graphHash: string
+  ): Promise<{ graph: any; source: string } | null>
+
   // ============================================================================
   // Workflow Lifecycle Methods
   // ============================================================================
@@ -334,6 +360,21 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     await queueService.add(this.getConfig().orchestratorQueueName, { runId })
   }
 
+  public async queueStepWorker(
+    runId: string,
+    stepName: string,
+    rpcName: string,
+    data: any
+  ): Promise<void> {
+    const queueService = this.verifyQueueService()
+    await queueService.add(this.getConfig().stepWorkerQueueName, {
+      runId,
+      stepName,
+      rpcName,
+      data,
+    })
+  }
+
   /**
    * Execute a workflow sleep step completion
    * Sets the step result to null and resumes the workflow
@@ -373,6 +414,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
   public async startWorkflow<I>(
     name: string,
     input: I,
+    wire: WorkflowRunWire,
     rpcService: any,
     options?: { inline?: boolean; startNode?: string }
   ): Promise<{ runId: string }> {
@@ -386,14 +428,16 @@ export abstract class PikkuWorkflowService implements WorkflowService {
 
     // Check if this is a graph workflow (source === 'graph')
     if (workflowMeta.source === 'graph') {
-      // Graph workflows use the graph scheduler
+      const shouldInline =
+        options?.inline || !getSingletonServices()?.queueService
       return runWorkflowGraph(
         this,
         name,
         input,
         rpcService,
-        options?.inline,
-        options?.startNode
+        shouldInline,
+        options?.startNode,
+        wire
       )
     }
 
@@ -405,36 +449,90 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       throw new WorkflowNotFoundError(name)
     }
 
-    // Create workflow run in state
-    const runId = await this.createRun(name, input, options?.inline)
+    if (!workflowMeta.graphHash) {
+      throw new Error(`Missing workflow graphHash for '${name}'`)
+    }
+
+    const runId = await this.createRun(
+      name,
+      input,
+      options?.inline ?? false,
+      workflowMeta.graphHash,
+      wire
+    )
 
-    // Register inline run for fast lookup
     if (options?.inline) {
       this.inlineRuns.add(runId)
     }
 
-    try {
-      // If inline mode or no queue service, execute directly
-      // Otherwise, use remote execution (queue-based)
-      if (options?.inline || !this.singletonServices?.queueService) {
-        await this.runWorkflowJob(runId, rpcService)
-      } else {
-        await this.resumeWorkflow(runId)
-      }
+    if (options?.inline || !getSingletonServices()?.queueService) {
+      this.runWorkflowJob(runId, rpcService)
+        .catch(() => {})
+        .finally(() => {
+          if (options?.inline) {
+            this.inlineRuns.delete(runId)
+          }
+        })
+    } else {
+      await this.resumeWorkflow(runId)
+    }
 
-      return { runId }
-    } finally {
-      // Clean up inline tracking
-      if (options?.inline) {
-        this.inlineRuns.delete(runId)
+    return { runId }
+  }
+
+  public async runToCompletion<I>(
+    name: string,
+    input: I,
+    rpcService: any,
+    options?: { pollIntervalMs?: number; wire?: WorkflowRunWire }
+  ): Promise<any> {
+    const pollInterval = options?.pollIntervalMs ?? 1000
+    const { runId } = await this.startWorkflow(
+      name,
+      input,
+      options?.wire ?? { type: 'internal' },
+      rpcService,
+      { inline: true }
+    )
+    while (true) {
+      const run = await this.getRun(runId)
+      if (!run) {
+        throw new WorkflowRunNotFoundError(runId)
       }
+      if (WORKFLOW_END_STATES.has(run.status)) {
+        if (run.status === 'failed') {
+          throw new Error(run.error?.message || 'Workflow failed')
+        }
+        if (run.status === 'cancelled') {
+          throw new Error('Workflow was cancelled')
+        }
+        return run.output
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval))
     }
   }
 
   public async runWorkflowJob(runId: string, rpcService: any): Promise<void> {
     const run = await this.getRun(runId)
     if (!run) {
-      throw new WorkflowRunNotFound(runId)
+      throw new WorkflowRunNotFoundError(runId)
+    }
+
+    const meta = pikkuState(null, 'workflows', 'meta')
+    const workflowMeta = meta[run.workflow]
+
+    if (
+      run.graphHash &&
+      workflowMeta?.graphHash &&
+      run.graphHash !== workflowMeta.graphHash
+    ) {
+      await this.runVersionMismatchFallback(run, workflowMeta, rpcService)
+      return
+    }
+
+    if (workflowMeta?.source === 'graph') {
+      await continueGraph(this, runId, run.workflow)
+      return
     }
 
     const registrations = pikkuState(null, 'workflows', 'registrations')
@@ -444,9 +542,6 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     }
 
     await this.withRunLock(runId, async () => {
-      const meta = pikkuState(null, 'workflows', 'meta')
-      const workflowMeta = meta[run.workflow]
-
       const workflowWire = this.createWorkflowWire(
         run.workflow,
         runId,
@@ -457,11 +552,11 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         const result = await runPikkuFunc(
           'workflow',
           workflowMeta.name,
-          workflowMeta.pikkuFuncName,
+          workflowMeta.pikkuFuncId,
           {
-            singletonServices: this.singletonServices!,
+            singletonServices: getSingletonServices()!,
             wire,
-            createWireServices: this.createWireServices,
+            createWireServices: getCreateWireServices(),
             data: () => run.input,
           }
         )
@@ -469,13 +564,10 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         await this.updateRunStatus(runId, 'completed', result)
       } catch (error: any) {
         if (error instanceof WorkflowAsyncException) {
-          // Normal - workflow paused for step execution
           throw error
         }
 
-        // Check if it's a WorkflowCancelledException
         if (error instanceof WorkflowCancelledException) {
-          // Workflow was cancelled - update status and rethrow
           await this.updateRunStatus(runId, 'cancelled', undefined, {
             message: error.message || 'Workflow cancelled',
             stack: '',
@@ -484,6 +576,15 @@ export abstract class PikkuWorkflowService implements WorkflowService {
           throw error
         }
 
+        if (error instanceof WorkflowSuspendedException) {
+          await this.updateRunStatus(runId, 'suspended', undefined, {
+            message: error.message || 'Workflow suspended',
+            stack: '',
+            code: 'WORKFLOW_SUSPENDED',
+          })
+          throw error
+        }
+
         await this.updateRunStatus(runId, 'failed', undefined, {
           message: error.message,
           stack: error.stack,
@@ -495,6 +596,35 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     })
   }
 
+  private async runVersionMismatchFallback(
+    run: WorkflowRun,
+    currentMeta: { source: string },
+    rpcService: any
+  ): Promise<void> {
+    const source = currentMeta.source
+
+    if (source === 'complex') {
+      await this.updateRunStatus(run.id, 'failed', undefined, {
+        message: `Workflow '${run.workflow}' definition changed. Complex workflows with inline steps cannot be migrated.`,
+        stack: '',
+        code: 'VERSION_CONFLICT',
+      })
+      return
+    }
+
+    const version = await this.getWorkflowVersion(run.workflow, run.graphHash!)
+    if (!version) {
+      await this.updateRunStatus(run.id, 'failed', undefined, {
+        message: `Workflow '${run.workflow}' version '${run.graphHash}' not found. Cannot resume with changed definition.`,
+        stack: '',
+        code: 'VERSION_NOT_FOUND',
+      })
+      return
+    }
+
+    await runFromMeta(this, run.id, version.graph, rpcService)
+  }
+
   /**
    * Execute a single workflow step (called by worker)
    * Handles idempotency, RPC execution, result storage, retry logic, and orchestrator triggering
@@ -527,24 +657,23 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         stepState = await this.createRetryAttempt(stepState.stepId, 'running')
       }
 
-      if (stepState.status !== 'pending') {
-        // Mark step as running (pending or failed status)
+      if (stepState.status === 'pending') {
+        // Mark pending step as running before execution
         await this.setStepRunning(stepState.stepId)
       }
 
       try {
         let result: any
 
-        // Check if this is a graph node step (step name starts with 'node:')
-        if (stepName.startsWith('node:')) {
-          // Get the graph name from the workflow run
-          const run = await this.getRun(runId)
-          if (!run) {
-            throw new Error(`Workflow run not found: ${runId}`)
-          }
-          const graphName = run.workflow
+        const run = await this.getRun(runId)
+        if (!run) {
+          throw new Error(`Workflow run not found: ${runId}`)
+        }
+
+        const meta = pikkuState(null, 'workflows', 'meta')
+        const workflowMeta = meta[run.workflow]
 
-          // Execute as graph step with graph wire context
+        if (workflowMeta?.nodes && stepName in workflowMeta.nodes) {
           result = await executeGraphStep(
             this,
             rpcService,
@@ -553,10 +682,9 @@ export abstract class PikkuWorkflowService implements WorkflowService {
             stepName,
             rpcName,
             data,
-            graphName
+            run.workflow
           )
         } else {
-          // Execute RPC with workflow step context (regular workflow)
           result = await rpcService.rpcWithWire(rpcName, data, {
             workflowStep: {
               runId,
@@ -572,6 +700,15 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         // Resume orchestrator to continue workflow
         await this.resumeWorkflow(runId)
       } catch (error: any) {
+        if (error instanceof RPCNotFoundError) {
+          await this.setStepError(stepState.stepId, error)
+          await this.updateRunStatus(runId, 'suspended', undefined, {
+            message: `RPC '${rpcName}' not found. Deploy the missing function and resume.`,
+            code: 'RPC_NOT_FOUND',
+          })
+          return
+        }
+
         // Store error and mark failed
         await this.setStepError(stepState.stepId, error)
 
@@ -603,7 +740,8 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     } catch (error: any) {
       if (
         error.name === 'WorkflowAsyncException' ||
-        error.name === 'WorkflowCancelledException'
+        error.name === 'WorkflowCancelledException' ||
+        error.name === 'WorkflowSuspendedException'
       ) {
         return
       }
@@ -619,13 +757,13 @@ export abstract class PikkuWorkflowService implements WorkflowService {
   }
 
   private verifyQueueService(): QueueService {
-    if (!this.singletonServices?.queueService) {
+    if (!getSingletonServices()?.queueService) {
       throw new Error(
         'QueueService not configured. Remote workflows require a queue service.'
       )
     }
 
-    return this.singletonServices!.queueService
+    return getSingletonServices()!.queueService!
   }
 
   private async rpcStep(
@@ -678,12 +816,12 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     await this.setStepScheduled(stepState.stepId)
 
     // Enqueue step worker (unless inline mode)
-    if (!this.isInline(runId) && this.singletonServices!.queueService) {
+    if (!this.isInline(runId) && getSingletonServices()!.queueService) {
       // Map step retry options to queue job options
       const retries = stepOptions?.retries ?? 0
       const retryDelay = stepOptions?.retryDelay
 
-      await this.singletonServices!.queueService.add(
+      await getSingletonServices()!.queueService!.add(
         this.getConfig().stepWorkerQueueName,
         {
           runId,
@@ -724,6 +862,14 @@ export abstract class PikkuWorkflowService implements WorkflowService {
           await this.setStepResult(currentStepState.stepId, result)
           return result
         } catch (error: any) {
+          if (error instanceof RPCNotFoundError) {
+            await this.updateRunStatus(runId, 'suspended', undefined, {
+              message: `RPC '${rpcName}' not found. Deploy the missing function and resume.`,
+              code: 'RPC_NOT_FOUND',
+            })
+            throw error
+          }
+
           // Record the error (marks step as failed)
           await this.setStepError(currentStepState.stepId, error)
 
@@ -766,8 +912,8 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       stepState = await this.insertStepState(
         runId,
         stepName,
-        null, // No RPC for inline steps
-        null, // No data for inline steps
+        null,
+        null,
         stepOptions
       )
     }
@@ -852,13 +998,9 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       stepState = await this.getStepState(runId, stepName)
     } catch {
       // Step doesn't exist - create it (sleep step, no RPC)
-      stepState = await this.insertStepState(
-        runId,
-        stepName,
-        null, // No RPC for sleep steps
-        { duration }, // Store duration as data
-        undefined // No retry options for sleep
-      )
+      stepState = await this.insertStepState(runId, stepName, null, {
+        duration,
+      })
     }
 
     if (stepState.status === 'succeeded') {
@@ -875,9 +1017,9 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     await this.setStepScheduled(stepState.stepId)
 
     // Check if inline mode or no scheduler service
-    if (!this.isInline(runId) && this.singletonServices!.schedulerService) {
+    if (!this.isInline(runId) && getSingletonServices()!.schedulerService) {
       // Remote mode - schedule sleep via scheduler service
-      await this.singletonServices!.schedulerService.scheduleRPC(
+      await getSingletonServices()!.schedulerService!.scheduleRPC(
         duration,
         this.getConfig().sleeperRPCName,
         {
@@ -897,13 +1039,63 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     }
   }
 
+  private getSuspendStepName(reason: string): string {
+    if (!reason) {
+      return '__workflow_suspend'
+    }
+    return '__workflow_suspend'
+  }
+
+  private async suspendStep(runId: string, reason: string): Promise<void> {
+    const stepName = this.getSuspendStepName(reason)
+    await this.withStepLock(runId, stepName, async () => {
+      let stepState: StepState
+      try {
+        stepState = await this.getStepState(runId, stepName)
+      } catch {
+        stepState = await this.insertStepState(
+          runId,
+          stepName,
+          'pikkuWorkflowSuspend',
+          {
+            reason,
+          }
+        )
+      }
+      if (!stepState.stepId) {
+        stepState = await this.insertStepState(
+          runId,
+          stepName,
+          'pikkuWorkflowSuspend',
+          {
+            reason,
+          }
+        )
+      }
+
+      if (stepState.status === 'succeeded') {
+        return
+      }
+
+      if (stepState.status === 'pending') {
+        await this.setStepRunning(stepState.stepId)
+      }
+
+      await this.setStepResult(stepState.stepId, {
+        reason,
+        suspendedAt: new Date().toISOString(),
+      })
+      throw new WorkflowSuspendedException(runId, reason)
+    })
+  }
+
   private createWorkflowWire(
-    workflowName: string,
+    name: string,
     runId: string,
     rpcService: any
   ): PikkuWorkflowWire {
     const workflowWire: PikkuWorkflowWire = {
-      workflowName,
+      name,
       runId,
       getRun: async () => (await this.getRun(runId)) as WorkflowRun,
 
@@ -943,6 +1135,10 @@ export abstract class PikkuWorkflowService implements WorkflowService {
           getDurationInMilliseconds(duration)
         )
       },
+
+      suspend: async (reason: string) => {
+        await this.suspendStep(runId, reason || 'Workflow suspended')
+      },
     }
     return workflowWire
   }
@@ -953,10 +1149,17 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     }
   }
 
-  private getConfig() {
-    if (!this.singletonServices || !this.config) {
-      throw new WorkflowServiceNotInitialized()
+  private getConfig(): WorkflowServiceConfig {
+    const singletonServices = getSingletonServices()
+    const workflow = singletonServices.config?.workflow
+    return {
+      retries: workflow?.retries ?? 0,
+      retryDelay: workflow?.retryDelay ?? 0,
+      orchestratorQueueName:
+        workflow?.orchestratorQueueName ?? 'pikku-workflow-orchestrator',
+      stepWorkerQueueName:
+        workflow?.stepWorkerQueueName ?? 'pikku-workflow-step-worker',
+      sleeperRPCName: workflow?.sleeperRPCName ?? 'pikkuWorkflowSleeper',
     }
-    return this.config
   }
 }