@pikku/core 0.11.2 → 0.12.1

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -1,8 +1,9 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
-import { pikkuState } from '../../pikku-state.js';
+import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
-import { executeGraphStep, runWorkflowGraph } from './graph/graph-runner.js';
-import { PikkuError } from '../../errors/error-handler.js';
+import { continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.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
  */
@@ -29,6 +30,19 @@ export class WorkflowCancelledException extends Error {
         this.name = 'WorkflowCancelledException';
     }
 }
+/**
+ * Exception thrown when workflow is suspended
+ */
+export class WorkflowSuspendedException extends Error {
+    runId;
+    reason;
+    constructor(runId, reason) {
+        super(reason || 'Workflow suspended');
+        this.runId = runId;
+        this.reason = reason;
+        this.name = 'WorkflowSuspendedException';
+    }
+}
 /**
  * Error class for workflow not found
  */
@@ -37,14 +51,19 @@ export class WorkflowNotFoundError extends PikkuError {
         super(`Workflow not found: ${name}`);
     }
 }
-/**
- * Error class for workflow not found
- */
-export class WorkflowRunNotFound extends PikkuError {
+addError(WorkflowNotFoundError, {
+    status: 404,
+    message: 'Workflow not found.',
+});
+export class WorkflowRunNotFoundError extends PikkuError {
     constructor(runId) {
         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 {
@@ -52,15 +71,18 @@ export class WorkflowStepNameNotString extends Error {
         super(`Workflow step name must be a string. Received: ${typeof stepName}`);
     }
 }
+const WORKFLOW_END_STATES = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+    'suspended',
+]);
 /**
  * Abstract workflow state service
  * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
  * Combines orchestration and step execution
  */
 export class PikkuWorkflowService {
-    config;
-    singletonServices;
-    createWireServices;
     inlineRuns = new Set();
     constructor() { }
     /**
@@ -81,16 +103,13 @@ export class PikkuWorkflowService {
     unregisterInlineRun(runId) {
         this.inlineRuns.delete(runId);
     }
-    setServices(singletonServices, createWireServices, { workflow }) {
-        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',
-        };
+    async registerWorkflowVersions() {
+        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);
+        }
     }
     // ============================================================================
     // Workflow Lifecycle Methods
@@ -103,6 +122,15 @@ export class PikkuWorkflowService {
         const queueService = this.verifyQueueService();
         await queueService.add(this.getConfig().orchestratorQueueName, { runId });
     }
+    async queueStepWorker(runId, stepName, rpcName, data) {
+        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
@@ -127,7 +155,7 @@ export class PikkuWorkflowService {
      * @param options.inline - If true, execute workflow directly without queue service
      * @param options.startNode - Starting node ID for graph workflows (from wire config)
      */
-    async startWorkflow(name, input, rpcService, options) {
+    async startWorkflow(name, input, wire, rpcService, options) {
         // Check meta to determine workflow type
         const meta = pikkuState(null, 'workflows', 'meta');
         const workflowMeta = meta[name];
@@ -136,8 +164,8 @@ export class PikkuWorkflowService {
         }
         // Check if this is a graph workflow (source === 'graph')
         if (workflowMeta.source === 'graph') {
-            // Graph workflows use the graph scheduler
-            return runWorkflowGraph(this, name, input, rpcService, options?.inline, options?.startNode);
+            const shouldInline = options?.inline || !getSingletonServices()?.queueService;
+            return runWorkflowGraph(this, name, input, rpcService, shouldInline, options?.startNode, wire);
         }
         // DSL workflow - check registration exists
         const registrations = pikkuState(null, 'workflows', 'registrations');
@@ -145,34 +173,63 @@ export class PikkuWorkflowService {
         if (!workflow) {
             throw new WorkflowNotFoundError(name);
         }
-        // Create workflow run in state
-        const runId = await this.createRun(name, input, options?.inline);
-        // Register inline run for fast lookup
+        if (!workflowMeta.graphHash) {
+            throw new Error(`Missing workflow graphHash for '${name}'`);
+        }
+        const runId = await this.createRun(name, input, options?.inline ?? false, workflowMeta.graphHash, wire);
         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);
-            }
-            return { runId };
+        if (options?.inline || !getSingletonServices()?.queueService) {
+            this.runWorkflowJob(runId, rpcService)
+                .catch(() => { })
+                .finally(() => {
+                if (options?.inline) {
+                    this.inlineRuns.delete(runId);
+                }
+            });
+        }
+        else {
+            await this.resumeWorkflow(runId);
         }
-        finally {
-            // Clean up inline tracking
-            if (options?.inline) {
-                this.inlineRuns.delete(runId);
+        return { runId };
+    }
+    async runToCompletion(name, input, rpcService, options) {
+        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));
         }
     }
     async runWorkflowJob(runId, rpcService) {
         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');
         const workflow = registrations.get(run.workflow);
@@ -180,27 +237,22 @@ export class PikkuWorkflowService {
             throw new WorkflowNotFoundError(run.workflow);
         }
         await this.withRunLock(runId, async () => {
-            const meta = pikkuState(null, 'workflows', 'meta');
-            const workflowMeta = meta[run.workflow];
             const workflowWire = this.createWorkflowWire(run.workflow, runId, rpcService);
             const wire = { workflow: workflowWire };
             try {
-                const result = await runPikkuFunc('workflow', workflowMeta.name, workflowMeta.pikkuFuncName, {
-                    singletonServices: this.singletonServices,
+                const result = await runPikkuFunc('workflow', workflowMeta.name, workflowMeta.pikkuFuncId, {
+                    singletonServices: getSingletonServices(),
                     wire,
-                    createWireServices: this.createWireServices,
+                    createWireServices: getCreateWireServices(),
                     data: () => run.input,
                 });
                 await this.updateRunStatus(runId, 'completed', result);
             }
             catch (error) {
                 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: '',
@@ -208,6 +260,14 @@ export class PikkuWorkflowService {
                     });
                     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,
@@ -217,6 +277,27 @@ export class PikkuWorkflowService {
             }
         });
     }
+    async runVersionMismatchFallback(run, currentMeta, rpcService) {
+        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
@@ -239,25 +320,22 @@ export class PikkuWorkflowService {
             if (stepState.status === 'failed') {
                 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;
-                // 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;
-                    // Execute as graph step with graph wire context
-                    result = await executeGraphStep(this, rpcService, runId, stepState.stepId, stepName, rpcName, data, graphName);
+                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];
+                if (workflowMeta?.nodes && stepName in workflowMeta.nodes) {
+                    result = await executeGraphStep(this, rpcService, runId, stepState.stepId, stepName, rpcName, data, run.workflow);
                 }
                 else {
-                    // Execute RPC with workflow step context (regular workflow)
                     result = await rpcService.rpcWithWire(rpcName, data, {
                         workflowStep: {
                             runId,
@@ -272,6 +350,14 @@ export class PikkuWorkflowService {
                 await this.resumeWorkflow(runId);
             }
             catch (error) {
+                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);
                 const maxAttempts = (stepState.retries ?? 0) + 1;
@@ -296,7 +382,8 @@ export class PikkuWorkflowService {
         }
         catch (error) {
             if (error.name === 'WorkflowAsyncException' ||
-                error.name === 'WorkflowCancelledException') {
+                error.name === 'WorkflowCancelledException' ||
+                error.name === 'WorkflowSuspendedException') {
                 return;
             }
             await this.updateRunStatus(runId, 'failed', undefined, {
@@ -308,10 +395,10 @@ export class PikkuWorkflowService {
         }
     }
     verifyQueueService() {
-        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;
     }
     async rpcStep(runId, stepName, rpcName, data, rpcService, stepOptions) {
         // Check if step already exists
@@ -344,11 +431,11 @@ export class PikkuWorkflowService {
         // Step is pending - schedule it
         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(this.getConfig().stepWorkerQueueName, {
+            await getSingletonServices().queueService.add(this.getConfig().stepWorkerQueueName, {
                 runId,
                 stepName,
                 rpcName,
@@ -385,6 +472,13 @@ export class PikkuWorkflowService {
                     return result;
                 }
                 catch (error) {
+                    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);
                     // Check if we should retry
@@ -413,9 +507,7 @@ export class PikkuWorkflowService {
         }
         catch {
             // Step doesn't exist - create it (inline, no RPC)
-            stepState = await this.insertStepState(runId, stepName, null, // No RPC for inline steps
-            null, // No data for inline steps
-            stepOptions);
+            stepState = await this.insertStepState(runId, stepName, null, null, stepOptions);
         }
         if (stepState.status === 'succeeded') {
             // Return cached result
@@ -488,10 +580,9 @@ export class PikkuWorkflowService {
         }
         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') {
             // Sleep already completed, return immediately
@@ -504,9 +595,9 @@ export class PikkuWorkflowService {
         // Step is pending - schedule it
         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(duration, this.getConfig().sleeperRPCName, {
+            await getSingletonServices().schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, {
                 runId,
                 stepId: stepState.stepId,
             });
@@ -520,9 +611,45 @@ export class PikkuWorkflowService {
             return;
         }
     }
-    createWorkflowWire(workflowName, runId, rpcService) {
+    getSuspendStepName(reason) {
+        if (!reason) {
+            return '__workflow_suspend';
+        }
+        return '__workflow_suspend';
+    }
+    async suspendStep(runId, reason) {
+        const stepName = this.getSuspendStepName(reason);
+        await this.withStepLock(runId, stepName, async () => {
+            let 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);
+        });
+    }
+    createWorkflowWire(name, runId, rpcService) {
         const workflowWire = {
-            workflowName,
+            name,
             runId,
             getRun: async () => (await this.getRun(runId)),
             // Implement workflow.do() - RPC form
@@ -540,6 +667,9 @@ export class PikkuWorkflowService {
                 this.verifyStepName(stepName);
                 await this.sleepStep(runId, stepName, getDurationInMilliseconds(duration));
             },
+            suspend: async (reason) => {
+                await this.suspendStep(runId, reason || 'Workflow suspended');
+            },
         };
         return workflowWire;
     }
@@ -549,9 +679,14 @@ export class PikkuWorkflowService {
         }
     }
     getConfig() {
-        if (!this.singletonServices || !this.config) {
-            throw new WorkflowServiceNotInitialized();
-        }
-        return this.config;
+        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',
+        };
     }
 }

package/dist/wirings/workflow/workflow-helpers.d.ts

@@ -0,0 +1,36 @@
+export declare function workflow<TWorkflowMap extends Record<string, {
+    input: any;
+    output: any;
+}>>(workflowName: string & keyof TWorkflowMap, options?: {
+    pollIntervalMs?: number;
+}): {
+    func: (services: any, data: any, wire: any) => Promise<any>;
+};
+export declare function workflowStart<TWorkflowMap extends Record<string, {
+    input: any;
+    output: any;
+}>>(workflowName: string & keyof TWorkflowMap): {
+    func: (services: any, data: any, wire: any) => Promise<{
+        runId: string;
+    }>;
+};
+export declare function workflowStatus<TWorkflowMap extends Record<string, {
+    input: any;
+    output: any;
+}>>(_workflowName: string & keyof TWorkflowMap): {
+    func: (services: any, data: {
+        runId: string;
+    }) => Promise<{
+        id: string;
+        status: 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled';
+        output?: any;
+        error?: {
+            message?: string;
+        };
+    }>;
+};
+export declare function graphStart<TGraphsMap extends Record<string, Record<string, any>>>(graphName: string & keyof TGraphsMap, startNode: string): {
+    func: (services: any, data: any, wire: any) => Promise<{
+        runId: string;
+    }>;
+};

package/dist/wirings/workflow/workflow-helpers.js

@@ -0,0 +1,38 @@
+import { WorkflowRunNotFoundError } from './pikku-workflow-service.js';
+export function workflow(workflowName, options) {
+    return {
+        func: async (services, data, { rpc }) => {
+            return services.workflowService.runToCompletion(workflowName, data, rpc, options);
+        },
+    };
+}
+export function workflowStart(workflowName) {
+    return {
+        func: async (_services, data, { rpc }) => {
+            return rpc.startWorkflow(workflowName, data);
+        },
+    };
+}
+export function workflowStatus(_workflowName) {
+    return {
+        func: async (services, data) => {
+            const run = await services.workflowService.getRun(data.runId);
+            if (!run) {
+                throw new WorkflowRunNotFoundError(data.runId);
+            }
+            return {
+                id: run.id,
+                status: run.status,
+                output: run.output,
+                error: run.error ? { message: run.error.message } : undefined,
+            };
+        },
+    };
+}
+export function graphStart(graphName, startNode) {
+    return {
+        func: async (_services, data, { rpc }) => {
+            return rpc.startWorkflow(graphName, data, { startNode });
+        },
+    };
+}