@pikku/core 0.12.46 → 0.12.49

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

@@ -58,6 +58,7 @@ import type {
   WorkflowVersionStatus,
   WorkflowServiceConfig,
   WorkflowStepOptions,
+  WorkflowExpectEventuallyOptions,
 } from './workflow.types.js'
 import {
   continueGraph,
@@ -66,6 +67,7 @@ import {
   runFromMeta,
 } from './graph/graph-runner.js'
 import type { WorkflowService } from '../../services/workflow-service.js'
+import type { UserFlowActors } from '../../services/user-flow-actors-service.js'
 import {
   PikkuError,
   addError,
@@ -218,6 +220,9 @@ const WORKFLOW_END_STATES: ReadonlySet<string> = new Set([
  */
 export abstract class PikkuWorkflowService implements WorkflowService {
   private inlineRuns = new Set<string>()
+  // User-flow actors per run: live authenticated clients (cookie jars) are
+  // process-local by nature, so they ride this map, never the persisted wire.
+  private runActors = new Map<string, UserFlowActors>()
 
   protected get logger() {
     return getSingletonServices()?.logger
@@ -1071,7 +1076,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     input: I,
     wire: WorkflowRunWire,
     rpcService: any,
-    options?: { inline?: boolean; startNode?: string }
+    options?: { inline?: boolean; startNode?: string; actors?: UserFlowActors }
   ): Promise<{ runId: string }> {
     // Resolve workflow from static meta (root or addon namespace), then dynamic DB
     const resolved = resolveWorkflowMeta(name)
@@ -1135,6 +1140,10 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       }
     )
 
+    if (options?.actors) {
+      this.runActors.set(runId, options.actors)
+    }
+
     if (shouldInline) {
       this.inlineRuns.add(runId)
       try {
@@ -1170,6 +1179,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         }
       } finally {
         this.inlineRuns.delete(runId)
+        this.runActors.delete(runId)
       }
     } else {
       await this.resumeWorkflow(runId)
@@ -1341,8 +1351,10 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       const wire: PikkuWire = {
         workflow: workflowWire,
         pikkuUserId: run.wire?.pikkuUserId,
-        session: rpcService.wire?.session,
-        rpc: rpcService.wire?.rpc,
+        session: rpcService?.wire?.session,
+        rpc: rpcService?.wire?.rpc,
+        // User-flow actors registered for this run (see startWorkflow options)
+        actors: this.runActors.get(runId),
       }
       try {
         const result = await runPikkuFunc(
@@ -1760,6 +1772,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     const resolvedStepOptions: WorkflowStepOptions = {
       retries: stepOptions?.retries ?? DEFAULT_STEP_RETRIES,
       retryDelay: stepOptions?.retryDelay,
+      actor: stepOptions?.actor,
     }
     // Check if step already exists
     let stepState: StepState
@@ -1807,14 +1820,18 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     // so the orchestrator's next replay re-dispatches it. Marking `scheduled`
     // first would strand the step (replay sees `scheduled`, pauses, never
     // re-enqueues the job that was never created).
-    const dispatched = await this.dispatchStep(
-      runId,
-      stepName,
-      rpcName,
-      data,
-      resolvedStepOptions,
-      fromStepName
-    )
+    // Actor steps never queue: they are outbound HTTP calls made by the
+    // runner itself, and the actor's session lives on this process.
+    const dispatched = resolvedStepOptions.actor
+      ? false
+      : await this.dispatchStep(
+          runId,
+          stepName,
+          rpcName,
+          data,
+          resolvedStepOptions,
+          fromStepName
+        )
     if (dispatched) {
       await this.setStepScheduled(stepState.stepId)
       throw new WorkflowAsyncException(runId, stepName)
@@ -1830,6 +1847,12 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       retries,
       retryDelay,
       async (currentStepState) => {
+        // Actor step: send through the actor's authenticated client over the
+        // REAL transport. Never falls back to internal dispatch — that would
+        // bypass auth and fake a green health check.
+        if (resolvedStepOptions.actor) {
+          return resolvedStepOptions.actor.invoke(rpcName, data)
+        }
         // Check if the name refers to a workflow
         const workflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName]
         if (workflowMeta) {
@@ -2119,6 +2142,48 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         }
       },
 
+      // Durable polling step: invoke an RPC (as an actor when options.as is
+      // set) until the predicate passes or `within` elapses. The whole poll is
+      // ONE recorded step, so replay returns the cached outcome.
+      expectEventually: async (
+        stepName: string,
+        rpcName: string,
+        data: any,
+        predicate: (output: any) => boolean,
+        options?: WorkflowExpectEventuallyOptions
+      ) => {
+        this.verifyStepName(stepName)
+        const resolvedRpcName =
+          addonNamespace && !rpcName.includes(':')
+            ? `${addonNamespace}:${rpcName}`
+            : rpcName
+        const within = getDurationInMilliseconds(options?.within ?? '30s')
+        const interval = getDurationInMilliseconds(options?.interval ?? '1s')
+        return await this.inlineStep(
+          runId,
+          stepName,
+          async () => {
+            const deadline = Date.now() + within
+            let last: any
+            while (true) {
+              last = options?.actor
+                ? await options.actor.invoke(resolvedRpcName, data)
+                : await rpcService.rpcWithWire(resolvedRpcName, data, {})
+              if (predicate(last)) return last
+              if (Date.now() + interval > deadline) {
+                throw new Error(
+                  `[workflow] expectEventually '${stepName}' ('${resolvedRpcName}'` +
+                    `${options?.actor ? ` as '${options.actor.name}'` : ''}) did not pass within ${within}ms; ` +
+                    `last result: ${JSON.stringify(last)?.slice(0, 300)}`
+                )
+              }
+              await new Promise((resolve) => setTimeout(resolve, interval))
+            }
+          },
+          options
+        )
+      },
+
       // Implement workflow.sleep()
       sleep: async (stepName: string, duration: string | number) => {
         this.verifyStepName(stepName)

package/src/wirings/workflow/user-flow-step.test.ts

@@ -0,0 +1,192 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import type { UserFlowActor } from '../../services/user-flow-actors-service.js'
+
+const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+const fakeActor = (
+  name: string,
+  handler: (rpcName: string, data: unknown) => Promise<unknown>
+): UserFlowActor & { calls: Array<{ rpcName: string; data: unknown }> } => {
+  const calls: Array<{ rpcName: string; data: unknown }> = []
+  return {
+    name,
+    calls,
+    invoke: async (rpcName: string, data: unknown) => {
+      calls.push({ rpcName, data })
+      return handler(rpcName, data)
+    },
+  }
+}
+
+const setup = async (
+  ws: InMemoryWorkflowService,
+  services: Record<string, unknown> = {}
+) => {
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: noopLogger,
+    ...services,
+  } as any)
+  const runId = await ws.createRun('userFlowTest', {}, true, 'hash', {
+    type: 'test',
+  } as any)
+  ws.registerInlineRun(runId)
+  return runId
+}
+
+describe('user-flow actor steps (workflow.do with `actor`)', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('routes through the actor over the real transport, never internal rpc', async () => {
+    const ws = new InMemoryWorkflowService()
+    const customer = fakeActor('customer', async () => ({ todoId: 't1' }))
+    let internalCalls = 0
+
+    const runId = await setup(ws)
+    const rpc = {
+      rpcWithWire: async () => {
+        internalCalls++
+        return {}
+      },
+    }
+
+    const wire = ws.createWorkflowWire('userFlowTest', runId, rpc)
+    const result = await wire.do(
+      'customer creates todo',
+      'createTodo',
+      { title: 'x' },
+      { actor: customer }
+    )
+
+    assert.deepEqual(result, { todoId: 't1' })
+    assert.deepEqual(customer.calls, [
+      { rpcName: 'createTodo', data: { title: 'x' } },
+    ])
+    assert.equal(internalCalls, 0, 'actor steps must NOT dispatch internally')
+  })
+
+  test('step is recorded durably and replay returns the cached result without re-invoking', async () => {
+    const ws = new InMemoryWorkflowService()
+    let invocations = 0
+    const yasser = fakeActor('yasser', async () => ({ n: ++invocations }))
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('userFlowTest', runId, {})
+
+    const first = await wire.do('step', 'someRpc', {}, { actor: yasser })
+    assert.deepEqual(first, { n: 1 })
+
+    // Simulate replay: reset per-run ordinals so the same logical step name
+    // resolves to the same durable step key.
+    ;(ws as any).resetStepOrdinals(runId)
+    const replayWire = ws.createWorkflowWire('userFlowTest', runId, {})
+    const replayed = await replayWire.do('step', 'someRpc', {}, { actor: yasser })
+
+    assert.deepEqual(replayed, { n: 1 }, 'replay must return the cached result')
+    assert.equal(invocations, 1, 'the actor must not be re-invoked on replay')
+  })
+
+  test('actor steps never queue, even when the function is queue-eligible', async () => {
+    const ws = new InMemoryWorkflowService()
+    let queued = 0
+    const customer = fakeActor('customer', async () => ({}))
+    const runId = await setup(ws, {
+      queueService: {
+        add: async () => {
+          queued++
+        },
+      },
+    })
+    // Function meta says this RPC would normally dispatch via the queue.
+    pikkuState(null, 'function', 'meta').queuedRpc = {
+      pikkuFuncId: 'queuedRpc',
+      workflowQueued: true,
+    } as any
+
+    const wire = ws.createWorkflowWire('userFlowTest', runId, {})
+    await wire.do('step', 'queuedRpc', {}, { actor: customer })
+
+    assert.equal(queued, 0, 'actor steps are outbound HTTP — never queued')
+    assert.equal(customer.calls.length, 1)
+  })
+
+  test('actor step failure surfaces the actor error and fails after retries', async () => {
+    const ws = new InMemoryWorkflowService()
+    const broken = fakeActor('broken', async () => {
+      throw new Error("[user-flow] 'createTodo' as 'broken' returned 403: nope")
+    })
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('userFlowTest', runId, {})
+
+    await assert.rejects(
+      wire.do('step', 'createTodo', {}, { actor: broken, retries: 2 }),
+      /returned 403/
+    )
+    assert.equal(broken.calls.length, 2, 'retries bounds total attempts')
+  })
+})
+
+describe('workflow.expectEventually', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('polls as the actor until the predicate passes', async () => {
+    const ws = new InMemoryWorkflowService()
+    let polls = 0
+    const sarah = fakeActor('sarah', async () => ({
+      notifications: ++polls >= 3 ? ['ping'] : [],
+    }))
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('userFlowTest', runId, {})
+
+    const result = await wire.expectEventually(
+      'sarah sees the notification',
+      'getNotifications',
+      {},
+      (out: any) => out.notifications.length > 0,
+      { actor: sarah, within: 2_000, interval: 5 }
+    )
+
+    assert.deepEqual(result, { notifications: ['ping'] })
+    assert.equal(polls, 3)
+  })
+
+  test('fails with the last result when the deadline passes', async () => {
+    const ws = new InMemoryWorkflowService()
+    const sarah = fakeActor('sarah', async () => ({ notifications: [] }))
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('userFlowTest', runId, {})
+
+    await assert.rejects(
+      wire.expectEventually(
+        'never arrives',
+        'getNotifications',
+        {},
+        (out: any) => out.notifications.length > 0,
+        { actor: sarah, within: 30, interval: 5, retries: 0 }
+      ),
+      /did not pass within 30ms.*notifications/
+    )
+  })
+
+  test('polls internally (rpcWithWire) when no actor is given', async () => {
+    const ws = new InMemoryWorkflowService()
+    let polls = 0
+    const runId = await setup(ws)
+    const rpc = {
+      rpcWithWire: async () => ({ ready: ++polls >= 2 }),
+    }
+    const wire = ws.createWorkflowWire('userFlowTest', runId, rpc)
+
+    const result = await wire.expectEventually(
+      'job finishes',
+      'getJob',
+      {},
+      (out: any) => out.ready,
+      { within: 2_000, interval: 5 }
+    )
+    assert.deepEqual(result, { ready: true })
+    assert.equal(polls, 2)
+  })
+})

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

@@ -7,6 +7,7 @@ export type { WorkflowService } from '../../services/workflow-service.js'
 // Re-export DSL types from dsl module
 export type {
   WorkflowStepOptions,
+  WorkflowExpectEventuallyOptions,
   WorkflowWireDoRPC,
   WorkflowWireDoInline,
   WorkflowWireSleep,
@@ -324,6 +325,10 @@ export type WorkflowsMeta = Record<
     context?: WorkflowContext
     dsl?: boolean
     expose?: boolean
+    /** True for pikkuUserFlow workflows (complex + actor steps). */
+    userFlow?: boolean
+    /** Actor names a user flow declares (personas it runs steps as). */
+    actors?: string[]
   }
 >
 
@@ -337,12 +342,14 @@ export interface WorkflowRuntimeMeta {
   name: string
   /** Pikku function name (for execution) */
   pikkuFuncId: string
-  /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph' */
-  source: 'dsl' | 'complex' | 'graph' | 'dynamic-workflow'
+  /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph', 'user-flow' (complex + actor steps) */
+  source: 'dsl' | 'complex' | 'graph' | 'dynamic-workflow' | 'user-flow'
   /** Optional description */
   description?: string
   /** Tags for organization */
   tags?: string[]
+  /** Actor names a user flow declares (personas it runs steps as). */
+  actors?: string[]
   /** Serialized nodes */
   nodes?: Record<string, any>
   /** Entry node IDs for graph workflows (computed at build time) */