@pikku/core 0.11.2 → 0.12.1

package/src/wirings/workflow/workflow-helpers.test.ts

@@ -0,0 +1,129 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import {
+  workflow,
+  workflowStart,
+  workflowStatus,
+  graphStart,
+} from './workflow-helpers.js'
+
+describe('workflow helpers', () => {
+  describe('workflow', () => {
+    test('should return an object with func', () => {
+      const wf = workflow('myWorkflow')
+      assert.strictEqual(typeof wf.func, 'function')
+    })
+
+    test('func should call workflowService.runToCompletion', async () => {
+      const wf = workflow('myWorkflow', { pollIntervalMs: 500 })
+      let calledWith: any
+      const services = {
+        workflowService: {
+          runToCompletion: async (...args: any[]) => {
+            calledWith = args
+            return { result: 'done' }
+          },
+        },
+      }
+      const result = await wf.func(services, { input: 1 }, { rpc: {} })
+      assert.strictEqual(calledWith[0], 'myWorkflow')
+      assert.deepStrictEqual(calledWith[1], { input: 1 })
+      assert.deepStrictEqual(result, { result: 'done' })
+    })
+  })
+
+  describe('workflowStart', () => {
+    test('should return an object with func', () => {
+      const wfs = workflowStart('myWorkflow')
+      assert.strictEqual(typeof wfs.func, 'function')
+    })
+
+    test('func should call rpc.startWorkflow', async () => {
+      const wfs = workflowStart('myWorkflow')
+      let calledWith: any
+      const rpc = {
+        startWorkflow: async (...args: any[]) => {
+          calledWith = args
+          return { runId: 'run-1' }
+        },
+      }
+      const result = await wfs.func({}, { input: 1 }, { rpc })
+      assert.strictEqual(calledWith[0], 'myWorkflow')
+      assert.deepStrictEqual(calledWith[1], { input: 1 })
+      assert.deepStrictEqual(result, { runId: 'run-1' })
+    })
+  })
+
+  describe('workflowStatus', () => {
+    test('should return an object with func', () => {
+      const wfst = workflowStatus('myWorkflow')
+      assert.strictEqual(typeof wfst.func, 'function')
+    })
+
+    test('func should return run status', async () => {
+      const wfst = workflowStatus('myWorkflow')
+      const services = {
+        workflowService: {
+          getRun: async (runId: string) => ({
+            id: runId,
+            status: 'completed',
+            output: { data: 'ok' },
+          }),
+        },
+      }
+      const result = await wfst.func(services, { runId: 'run-1' })
+      assert.strictEqual(result.id, 'run-1')
+      assert.strictEqual(result.status, 'completed')
+      assert.deepStrictEqual(result.output, { data: 'ok' })
+    })
+
+    test('func should throw WorkflowRunNotFoundError for missing run', async () => {
+      const wfst = workflowStatus('myWorkflow')
+      const services = {
+        workflowService: { getRun: async () => null },
+      }
+      await assert.rejects(
+        () => wfst.func(services, { runId: 'non-existent' }),
+        (err: any) => err.message.includes('non-existent')
+      )
+    })
+
+    test('func should include error message when run has error', async () => {
+      const wfst = workflowStatus('myWorkflow')
+      const services = {
+        workflowService: {
+          getRun: async () => ({
+            id: 'run-2',
+            status: 'failed',
+            error: { message: 'step failed', name: 'Error' },
+          }),
+        },
+      }
+      const result = await wfst.func(services, { runId: 'run-2' })
+      assert.strictEqual(result.status, 'failed')
+      assert.deepStrictEqual(result.error, { message: 'step failed' })
+    })
+  })
+
+  describe('graphStart', () => {
+    test('should return an object with func', () => {
+      const gs = graphStart('myGraph', 'startNode')
+      assert.strictEqual(typeof gs.func, 'function')
+    })
+
+    test('func should call rpc.startWorkflow with startNode', async () => {
+      const gs = graphStart('myGraph', 'nodeA')
+      let calledWith: any
+      const rpc = {
+        startWorkflow: async (...args: any[]) => {
+          calledWith = args
+          return { runId: 'run-3' }
+        },
+      }
+      const result = await gs.func({}, { input: 1 }, { rpc })
+      assert.strictEqual(calledWith[0], 'myGraph')
+      assert.deepStrictEqual(calledWith[2], { startNode: 'nodeA' })
+      assert.deepStrictEqual(result, { runId: 'run-3' })
+    })
+  })
+})

package/src/wirings/workflow/workflow-helpers.ts

@@ -0,0 +1,79 @@
+import { WorkflowRunNotFoundError } from './pikku-workflow-service.js'
+
+export 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> } {
+  return {
+    func: async (services: any, data: any, { rpc }: any) => {
+      return services.workflowService.runToCompletion(
+        workflowName,
+        data,
+        rpc,
+        options
+      )
+    },
+  }
+}
+
+export function workflowStart<
+  TWorkflowMap extends Record<string, { input: any; output: any }>,
+>(
+  workflowName: string & keyof TWorkflowMap
+): {
+  func: (services: any, data: any, wire: any) => Promise<{ runId: string }>
+} {
+  return {
+    func: async (_services: any, data: any, { rpc }: any) => {
+      return rpc.startWorkflow(workflowName, data)
+    },
+  }
+}
+
+export 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 }
+  }>
+} {
+  return {
+    func: async (services: any, data: { runId: string }) => {
+      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<
+  TGraphsMap extends Record<string, Record<string, any>>,
+>(
+  graphName: string & keyof TGraphsMap,
+  startNode: string
+): {
+  func: (services: any, data: any, wire: any) => Promise<{ runId: string }>
+} {
+  return {
+    func: async (_services: any, data: any, { rpc }: any) => {
+      return rpc.startWorkflow(graphName, data, { startNode })
+    },
+  }
+}

package/src/wirings/workflow/workflow.types.ts

@@ -1,5 +1,5 @@
-import { SerializedError, CommonWireMeta } from '../../types/core.types.js'
-import { CorePikkuFunctionConfig } from '../../function/functions.types.js'
+import type { SerializedError, CommonWireMeta } from '../../types/core.types.js'
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 
 // Re-export WorkflowService from services module
 export type { WorkflowService } from '../../services/workflow-service.js'
@@ -10,6 +10,7 @@ export type {
   WorkflowWireDoRPC,
   WorkflowWireDoInline,
   WorkflowWireSleep,
+  WorkflowWireSuspend,
   InputSource,
   OutputBinding,
   RpcStepMeta,
@@ -35,6 +36,12 @@ export type {
 
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js'
 
+export interface WorkflowRunWire {
+  type: string
+  id?: string
+  parentRunId?: string
+}
+
 export interface WorkflowServiceConfig {
   retries: number
   retryDelay: number
@@ -43,94 +50,15 @@ export interface WorkflowServiceConfig {
   sleeperRPCName: string
 }
 
-/**
- * HTTP wire configuration for workflows
- */
-export interface WorkflowHTTPWire {
-  route: string
-  method: 'get' | 'post' | 'put' | 'patch' | 'delete'
-  startNode: string
-}
-
-/**
- * Channel wire configuration for workflows
- */
-export interface WorkflowChannelWire {
-  name: string
-  onConnect?: string
-  onDisconnect?: string
-  onMessage?: string
-}
-
-/**
- * Queue wire configuration for workflows
- */
-export interface WorkflowQueueWire {
-  name: string
-  startNode: string
-}
-
-/**
- * CLI wire configuration for workflows
- */
-export interface WorkflowCliWire {
-  command: string
-  startNode: string
-}
-
-/**
- * MCP wire configurations for workflows
- */
-export interface WorkflowMcpWires {
-  tool?: Array<{ name: string; startNode: string }>
-  prompt?: Array<{ name: string; startNode: string }>
-  resource?: Array<{ uri: string; startNode: string }>
-}
-
-/**
- * Schedule wire configuration for workflows
- */
-export interface WorkflowScheduleWire {
-  cron?: string
-  interval?: string
-  startNode: string
-}
-
-/**
- * Trigger wire configuration for workflows
- */
-export interface WorkflowTriggerWire {
-  name: string
-  startNode: string
-}
-
-/**
- * Wire configuration for workflows
- * Defines how a workflow can be triggered
- */
-export interface WorkflowWires {
-  /** API entry point - node ID for startWorkflow() calls */
-  api?: string
-  /** HTTP triggers */
-  http?: WorkflowHTTPWire[]
-  /** Channel triggers */
-  channel?: WorkflowChannelWire[]
-  /** Queue triggers */
-  queue?: WorkflowQueueWire[]
-  /** CLI triggers */
-  cli?: WorkflowCliWire[]
-  /** MCP triggers (tool, prompt, resource) */
-  mcp?: WorkflowMcpWires
-  /** Schedule triggers */
-  schedule?: WorkflowScheduleWire[]
-  /** Named trigger wires */
-  trigger?: WorkflowTriggerWire[]
-}
-
 /**
  * Workflow run status
  */
-export type WorkflowStatus = 'running' | 'completed' | 'failed' | 'cancelled'
+export type WorkflowStatus =
+  | 'running'
+  | 'suspended'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
 
 /**
  * Workflow step status
@@ -141,6 +69,7 @@ export type StepStatus =
   | 'scheduled'
   | 'succeeded'
   | 'failed'
+  | 'suspended'
 
 /**
  * Workflow run representation
@@ -160,6 +89,10 @@ export interface WorkflowRun {
   error?: SerializedError
   /** If true, workflow executes inline without queues */
   inline?: boolean
+  /** Graph hash of the workflow definition at run creation time */
+  graphHash?: string
+  /** Wire origin info (how this run was started) */
+  wire: WorkflowRunWire
   /** Creation timestamp */
   createdAt: Date
   /** Last update timestamp */
@@ -198,6 +131,28 @@ export interface StepState {
   failedAt?: Date
 }
 
+export interface WorkflowRunService {
+  listRuns(options?: {
+    workflowName?: string
+    status?: string
+    limit?: number
+    offset?: number
+  }): Promise<WorkflowRun[]>
+  getRun(id: string): Promise<WorkflowRun | null>
+  getRunSteps(
+    runId: string
+  ): Promise<
+    Array<StepState & { stepName: string; rpcName?: string; data?: any }>
+  >
+  getRunHistory(runId: string): Promise<Array<StepState & { stepName: string }>>
+  getDistinctWorkflowNames(): Promise<string[]>
+  getWorkflowVersion(
+    name: string,
+    graphHash: string
+  ): Promise<{ graph: any; source: string } | null>
+  deleteRun(id: string): Promise<boolean>
+}
+
 /**
  * Core workflow definition
  */
@@ -255,7 +210,7 @@ export type WorkflowContext = Record<string, ContextVariable>
 export type WorkflowsMeta = Record<
   string,
   CommonWireMeta & {
-    workflowName: string
+    name: string
     steps: WorkflowStepMeta[]
     context?: WorkflowContext
     dsl?: boolean
@@ -271,19 +226,19 @@ export interface WorkflowRuntimeMeta {
   /** Workflow name (used as key in registrations) */
   name: string
   /** Pikku function name (for execution) */
-  pikkuFuncName: string
+  pikkuFuncId: string
   /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph' */
-  source?: 'dsl' | 'complex' | 'graph'
+  source: 'dsl' | 'complex' | 'graph'
   /** Optional description */
   description?: string
   /** Tags for organization */
   tags?: string[]
-  /** Wires - how the workflow is triggered */
-  wires?: WorkflowWires
   /** Serialized nodes */
   nodes?: Record<string, any>
   /** Entry node IDs for graph workflows (computed at build time) */
   entryNodeIds?: string[]
+  /** Hash of graph topology (nodes, edges, input mappings) */
+  graphHash?: string
 }
 
 /**