@pikku/core 0.11.2 → 0.12.0

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 { 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,6 +71,12 @@ 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.)
@@ -92,6 +117,14 @@ export class PikkuWorkflowService {
             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 +136,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 +169,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 +178,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 || !this.singletonServices?.queueService;
+            return runWorkflowGraph(this, name, input, rpcService, shouldInline, options?.startNode, wire);
         }
         // DSL workflow - check registration exists
         const registrations = pikkuState(null, 'workflows', 'registrations');
@@ -145,34 +187,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 || !this.singletonServices?.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,12 +251,10 @@ 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, {
+                const result = await runPikkuFunc('workflow', workflowMeta.name, workflowMeta.pikkuFuncId, {
                     singletonServices: this.singletonServices,
                     wire,
                     createWireServices: this.createWireServices,
@@ -195,12 +264,9 @@ export class PikkuWorkflowService {
             }
             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 +274,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 +291,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 +334,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 +364,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 +396,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, {
@@ -385,6 +486,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 +521,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 +594,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
@@ -520,9 +625,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 +681,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;
     }

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 });
+        },
+    };
+}

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

@@ -1,23 +1 @@
-import { PikkuWire, CreateWireServices, CoreSingletonServices, CoreServices, CoreUserSession } from '../../types/core.types.js';
-import { HTTPWiringMeta } from '../http/http.types.js';
-/**
- * Result of finding a workflow by HTTP wire
- */
-export interface WorkflowHttpMatch {
-    workflowName: string;
-    startNode?: string;
-}
-/**
- * Find workflow name by matching route and method against workflow wires
- */
-export declare const findWorkflowByHttpWire: (route: string, method: string) => WorkflowHttpMatch | undefined;
-/**
- * Start a workflow triggered by an HTTP wire
- * The workflow is responsible for handling the HTTP response
- */
-export declare const startWorkflowByHttpWire: (singletonServices: CoreSingletonServices, createWireServices: CreateWireServices<CoreSingletonServices, CoreServices<CoreSingletonServices>, CoreUserSession> | undefined, matchedRoute: {
-    matchedPath: any;
-    params: any;
-    route: any;
-    meta: HTTPWiringMeta;
-}, wire: PikkuWire) => Promise<void>;
+export {};

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

@@ -1,66 +1 @@
-import { pikkuState } from '../../pikku-state.js';
-import { NotFoundError } from '../../errors/errors.js';
-import { ContextAwareRPCService } from '../rpc/rpc-runner.js';
-/**
- * Find workflow name by matching route and method against workflow wires
- */
-export const findWorkflowByHttpWire = (route, method) => {
-    const wirings = pikkuState(null, 'workflows', 'wirings');
-    const graphWirings = pikkuState(null, 'workflows', 'graphWirings');
-    // Check DSL workflow wirings
-    for (const [, wiring] of wirings) {
-        const httpWires = wiring.wires?.http;
-        if (httpWires) {
-            const matchedWire = httpWires.find((w) => w.route === route && w.method === method);
-            if (matchedWire) {
-                const meta = pikkuState(null, 'workflows', 'meta');
-                for (const [name, workflowMeta] of Object.entries(meta)) {
-                    if (workflowMeta.source !== 'graph') {
-                        const registrations = pikkuState(null, 'workflows', 'registrations');
-                        if (registrations.has(name)) {
-                            return { workflowName: name, startNode: matchedWire.startNode };
-                        }
-                    }
-                }
-            }
-        }
-    }
-    // Check graph workflow wirings
-    for (const [, wiring] of graphWirings) {
-        const httpWires = wiring.wires?.http;
-        if (httpWires) {
-            const matchedWire = httpWires.find((w) => w.route === route && w.method === method);
-            if (matchedWire) {
-                const meta = pikkuState(null, 'workflows', 'meta');
-                for (const [name, workflowMeta] of Object.entries(meta)) {
-                    if (workflowMeta.source === 'graph') {
-                        return { workflowName: name, startNode: matchedWire.startNode };
-                    }
-                }
-            }
-        }
-    }
-    return undefined;
-};
-/**
- * Start a workflow triggered by an HTTP wire
- * The workflow is responsible for handling the HTTP response
- */
-export const startWorkflowByHttpWire = async (singletonServices, createWireServices, matchedRoute, wire) => {
-    const { meta } = matchedRoute;
-    const match = findWorkflowByHttpWire(meta.route, meta.method);
-    if (!match) {
-        throw new NotFoundError(`No workflow found for route ${meta.method.toUpperCase()} ${meta.route}`);
-    }
-    const workflowService = singletonServices.workflowService;
-    if (!workflowService) {
-        throw new Error('WorkflowService not available');
-    }
-    const data = await wire.http.request.data();
-    const wireServices = createWireServices?.(singletonServices, wire);
-    const rpcService = new ContextAwareRPCService({ ...singletonServices, ...wireServices }, wire, {});
-    await workflowService.startWorkflow(match.workflowName, data, rpcService, {
-        inline: true,
-        startNode: match.startNode,
-    });
-};
+export {};