@pikku/core 0.12.69 → 0.12.70

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

@@ -875,3 +875,58 @@ describe('pikku-workflow-service approval', () => {
     cleanup()
   })
 })
+
+describe('pikku-workflow-service run identity on failure', () => {
+  // A failing inline run throws before startWorkflow can return `{ runId }`,
+  // so a caller that wants to read the run back — its steps, which one failed,
+  // what it was called with — has nothing to read it by. `onRunCreated` fires
+  // as soon as the run exists, which is the only moment guaranteed to happen
+  // whether the run goes on to pass, fail, or suspend.
+  const runFailing = async (name: string) => {
+    resetPikkuState()
+    const ws = new InMemoryWorkflowService()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: { error() {}, info() {}, warn() {}, debug() {} },
+    } as any)
+
+    const metaState = pikkuState(null, 'workflows', 'meta')
+    metaState[name] = {
+      name,
+      pikkuFuncId: name,
+      source: 'scenario',
+      graphHash: `${name}-hash`,
+    } as any
+    pikkuState(null, 'function', 'meta')[name] = {
+      name,
+      sessionless: true,
+      permissions: [],
+    } as any
+
+    addWorkflow(name, {
+      func: async () => {
+        throw new Error('the scenario blew up')
+      },
+    } as any)
+
+    const created: string[] = []
+    let error: any
+    try {
+      await ws.startWorkflow(name, {}, {} as any, {}, {
+        onRunCreated: (runId: string) => created.push(runId),
+      } as any)
+    } catch (e: any) {
+      error = e
+    }
+    return { ws, created, error }
+  }
+
+  test('reports the run id of a run that fails inline', async () => {
+    const { ws, created, error } = await runFailing('onRunCreatedFailing')
+
+    assert.equal(error?.message, 'the scenario blew up')
+    assert.equal(created.length, 1, 'the run existed, so its id must be known')
+    const run = await ws.getRun(created[0]!)
+    assert.equal(run?.status, 'failed')
+    assert.equal(run?.error?.message, 'the scenario blew up')
+  })
+})

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

@@ -11,7 +11,6 @@ import {
   pikkuState,
 } from '../../pikku-state.js'
 import { getDurationInMilliseconds } from '../../time-utils.js'
-import { createHttpScenarioActors } from '../../services/http-scenario-actors.js'
 
 const resolveWorkflowMeta = (
   name: string
@@ -46,10 +45,10 @@ const toKebab = (s: string) =>
   s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
 import type { PikkuWire, SerializedError } from '../../types/core.types.js'
 import type { QueueService } from '../queue/queue.types.js'
-import { runScheduledTask } from '../scheduler/scheduler-runner.js'
 import type {
   ApprovalOutcome,
-  PikkuScenarioWire,
+  CoreWorkflow,
+  PikkuWorkflowWire,
   StepState,
   StepStatus,
   WorkflowApprovalOptions,
@@ -63,9 +62,6 @@ import type {
   WorkflowQueueOptions,
   WorkflowServiceConfig,
   WorkflowStepOptions,
-  WorkflowExpectEventuallyOptions,
-  WorkflowExpectErrorOptions,
-  WorkflowExpectServiceOptions,
 } from './workflow.types.js'
 import {
   continueGraph,
@@ -246,6 +242,101 @@ const WORKFLOW_END_STATES: ReadonlySet<string> = new Set([
   'suspended',
 ])
 
+/**
+ * Everything an extension needs to run something of its own around a run's
+ * function: the registration it was resolved from, the run itself (so `input`
+ * is the same object the function is called with), and the wire it is given.
+ */
+export interface RunLifecycleContext {
+  runId: string
+  run: WorkflowRun
+  workflowMeta: any
+  workflow: CoreWorkflow
+  wire: PikkuWire
+  packageName: string | null
+}
+
+/**
+ * The slice of the run engine an extension is allowed to drive, handed to it at
+ * construction. It exists so that recording a durable step stays available to
+ * an extension without `inlineStep` and friends becoming public API on every
+ * workflow service a production app instantiates.
+ */
+export interface WorkflowRunEngine {
+  inlineStep(
+    runId: string,
+    logicalStepName: string,
+    fn: Function,
+    stepOptions?: WorkflowStepOptions,
+    data?: any,
+    funcName?: string
+  ): Promise<any>
+  updateRunStatus(
+    runId: string,
+    status: WorkflowStatus,
+    output?: any,
+    error?: SerializedError
+  ): Promise<void>
+  onChildWorkflowFailed(run: WorkflowRun, error: unknown): Promise<void>
+  verifyStepName(stepName: unknown): void
+}
+
+/**
+ * A capability layered onto a run without being a workflow service itself.
+ *
+ * The engine names nothing about what an extension is for: a bundler drops an
+ * unused *module* but never an unused class member, so the alternative — a
+ * subclass carrying the capability — puts it in every server built on Pikku
+ * whether or not the app ever uses it. Scenarios are the one implementation
+ * today (`PikkuScenarioService` in `@pikku/core/scenario`).
+ */
+export interface WorkflowRunExtension {
+  /** Per-run state resolved once the run has an id. */
+  attachRunContext(
+    runId: string,
+    workflowMeta: any,
+    options?: Record<string, any>
+  ): Promise<void>
+  /** Release whatever `attachRunContext` stored. */
+  detachRunContext(runId: string): void
+  /** Contribute extra members to the wire a run's function is invoked with. */
+  decorateRunWire(
+    wire: PikkuWire,
+    context: {
+      runId: string
+      workflowMeta: any
+      workflowWire: PikkuWorkflowWire
+    }
+  ): void
+  /** Contribute extra members to the workflow wire itself, in place. */
+  decorateWorkflowWire(
+    workflowWire: PikkuWorkflowWire,
+    context: {
+      name: string
+      runId: string
+      rpcService: any
+      addonNamespace?: string | null
+    }
+  ): void
+  /**
+   * Called immediately before the run's function, inside the run lock. Throwing
+   * skips the function and fails the run.
+   */
+  onBeforeRunFunc(context: RunLifecycleContext): Promise<void>
+  /**
+   * Called once the run reaches a terminal state, in a `finally`, so it runs
+   * whether the function passed or threw. `interrupted` means the run suspended
+   * or went async and is still mid-flight. Throwing here propagates, replacing
+   * a pending failure, so an extension that must not mask one handles that
+   * itself.
+   */
+  onAfterRunFunc(
+    context: RunLifecycleContext,
+    outcome: 'completed' | 'failed' | 'interrupted',
+    failure: unknown
+  ): Promise<void>
+}
+
 /**
  * Abstract workflow state service
  * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
@@ -253,9 +344,7 @@ 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, ScenarioActors>()
+  private runExtension?: WorkflowRunExtension
 
   protected get logger() {
     return getSingletonServices()?.logger
@@ -631,7 +720,10 @@ export abstract class PikkuWorkflowService implements WorkflowService {
    * Creates pending step in both workflow_step and workflow_step_history
    * @param runId - Run ID
    * @param stepName - Step cache key
-   * @param rpcName - RPC function name
+   * @param rpcName - The name this step was dispatched by: an RPC for a
+   *   `workflow.do` step, a step function for a scenario step, null for a
+   *   closure. Nothing dispatches off this value — it is recorded so a reader
+   *   can join a step back to the function that ran it.
    * @param data - Step input data
    * @param stepOptions - Step options (retries, retryDelay)
    * @returns Step state with generated stepId
@@ -1162,37 +1254,28 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     return true
   }
 
-  /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
-  private async resolveScenarioActors(): Promise<ScenarioActors | undefined> {
-    const services = getSingletonServices()
-    const variables = services?.variables
-    const metaService = services?.metaService
-    if (!variables || !metaService) {
-      return undefined
-    }
-    const secret = await variables.get('SCENARIO_ACTOR_SECRET')
-    const apiUrl = await variables.get('API_URL')
-    if (!secret || !apiUrl) {
-      services?.logger?.warn(
-        'A scenario was started without actors but SCENARIO_ACTOR_SECRET / API_URL is not configured — running without actors.'
-      )
-      return undefined
-    }
-    const actorsConfig = await metaService.getScenarioActorsMeta()
-    if (!actorsConfig || Object.keys(actorsConfig).length === 0) {
-      return undefined
+  /**
+   * Install the one extension a run may have, built from a handle onto the run
+   * engine so that `inlineStep` and friends stay protected rather than becoming
+   * public API. Returns the extension, so the caller keeps a typed reference to
+   * whatever it just built.
+   */
+  public setRunExtension<T extends WorkflowRunExtension>(
+    create: (engine: WorkflowRunEngine) => T
+  ): T {
+    const engine: WorkflowRunEngine = {
+      inlineStep: this.inlineStep.bind(this),
+      updateRunStatus: this.updateRunStatus.bind(this),
+      onChildWorkflowFailed: this.onChildWorkflowFailed.bind(this),
+      verifyStepName: this.verifyStepName.bind(this),
     }
-    const signInPath =
-      (await variables.get('SCENARIO_SIGN_IN_PATH')) ??
-      '/api/auth/sign-in/actor'
-    const rpcPath = (await variables.get('SCENARIO_RPC_PATH')) ?? '/rpc'
-    return createHttpScenarioActors({
-      apiUrl,
-      secret,
-      actors: actorsConfig,
-      signInPath,
-      rpcPath,
-    })
+    const extension = create(engine)
+    this.runExtension = extension
+    return extension
+  }
+
+  public getRunExtension(): WorkflowRunExtension | undefined {
+    return this.runExtension
   }
 
   /**
@@ -1200,13 +1283,21 @@ export abstract class PikkuWorkflowService implements WorkflowService {
    * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
    * @param options.inline - If true, execute workflow directly without queue service
    * @param options.startNode - Starting node ID for graph workflows (from wire config)
+   * @param options.onRunCreated - Called with the run id the moment the run exists.
+   * An inline run that fails throws instead of returning, so this is the only
+   * way a caller can still read that run back — its steps, and which one failed.
    */
   public async startWorkflow<I>(
     name: string,
     input: I,
     wire: WorkflowRunWire,
     rpcService: any,
-    options?: { inline?: boolean; startNode?: string; actors?: ScenarioActors }
+    options?: {
+      inline?: boolean
+      startNode?: string
+      actors?: ScenarioActors
+      onRunCreated?: (runId: string) => void
+    }
   ): Promise<{ runId: string }> {
     // Resolve workflow from static meta (root or addon namespace), then dynamic DB
     const resolved = resolveWorkflowMeta(name)
@@ -1270,14 +1361,9 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       }
     )
 
-    const actors =
-      options?.actors ??
-      (workflowMeta.source === 'scenario'
-        ? await this.resolveScenarioActors()
-        : undefined)
-    if (actors) {
-      this.runActors.set(runId, actors)
-    }
+    options?.onRunCreated?.(runId)
+
+    await this.runExtension?.attachRunContext(runId, workflowMeta, options)
 
     if (shouldInline) {
       this.inlineRuns.add(runId)
@@ -1314,7 +1400,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         }
       } finally {
         this.inlineRuns.delete(runId)
-        this.runActors.delete(runId)
+        this.runExtension?.detachRunContext(runId)
       }
     } else {
       await this.resumeWorkflow(runId)
@@ -1485,15 +1571,33 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       workflowWire.pikkuUserId = run.wire?.pikkuUserId
       const wire: PikkuWire = {
         workflow: workflowWire,
-        scenario:
-          workflowMeta?.source === 'scenario' ? workflowWire : undefined,
         pikkuUserId: run.wire?.pikkuUserId,
         session: rpcService?.wire?.session,
         rpc: rpcService?.wire?.rpc,
-        // User-flow actors registered for this run (see startWorkflow options)
-        actors: this.runActors.get(runId),
       }
+      this.runExtension?.decorateRunWire(wire, {
+        runId,
+        workflowMeta,
+        workflowWire,
+      })
+
+      const lifecycle: RunLifecycleContext = {
+        runId,
+        run,
+        workflowMeta,
+        workflow,
+        wire,
+        packageName: pkgName,
+      }
+
+      // `interrupted` means the run has not reached a terminal state — it is
+      // suspended or waiting — so teardown would run while the run is still
+      // mid-flight.
+      let outcome: 'completed' | 'failed' | 'interrupted' = 'completed'
+      let failure: any
       try {
+        await this.runExtension?.onBeforeRunFunc(lifecycle)
+
         const result = await runPikkuFunc(
           'workflow',
           workflowMeta.name,
@@ -1510,11 +1614,15 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         await this.updateRunStatus(runId, 'completed', result)
         await this.onChildWorkflowCompleted(run, result)
       } catch (error: any) {
+        failure = error
+
         if (error instanceof WorkflowAsyncException) {
+          outcome = 'interrupted'
           throw error
         }
 
         if (error instanceof WorkflowCancelledException) {
+          outcome = 'failed'
           await this.updateRunStatus(runId, 'cancelled', undefined, {
             message: error.message || 'Workflow cancelled',
             stack: '',
@@ -1525,6 +1633,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         }
 
         if (error instanceof WorkflowSuspendedException) {
+          outcome = 'interrupted'
           await this.updateRunStatus(runId, 'suspended', undefined, {
             message: error.message || 'Workflow suspended',
             stack: '',
@@ -1533,6 +1642,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
           throw error
         }
 
+        outcome = 'failed'
         await this.updateRunStatus(runId, 'failed', undefined, {
           message: error.message,
           stack: error.stack,
@@ -1541,6 +1651,8 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         await this.onChildWorkflowFailed(run, error)
 
         throw error
+      } finally {
+        await this.runExtension?.onAfterRunFunc(lifecycle, outcome, failure)
       }
     })
   }
@@ -1559,7 +1671,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     await this.resumeWorkflow(parentRunId)
   }
 
-  private async onChildWorkflowFailed(
+  protected async onChildWorkflowFailed(
     childRun: WorkflowRun,
     error: Error
   ): Promise<void> {
@@ -2088,11 +2200,25 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     )
   }
 
-  private async inlineStep(
+  protected async inlineStep(
     runId: string,
     logicalStepName: string,
     fn: Function,
-    stepOptions?: WorkflowStepOptions
+    stepOptions?: WorkflowStepOptions,
+    /**
+     * The input this step was called with, recorded on the run so a reporter can
+     * name the values under test. A closure step has none; a scenario step does.
+     */
+    data: any = null,
+    /**
+     * The name this step was dispatched by, for the kinds of inline step that
+     * have one. A closure step has no name; a scenario step is a step RPC, so
+     * it records the step function that ran — which is the only way to join a
+     * step back to its declaration when its durable name was built at runtime
+     * (a step called in a loop reaches the run as `sees @pikku/addon-todos`,
+     * declared as `sees ${packageName}`).
+     */
+    rpcName: string | null = null
   ): Promise<any> {
     const fromStepName = this.lastStepName(runId)
     const stepName = this.nextStepKey(runId, logicalStepName)
@@ -2101,12 +2227,12 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     try {
       stepState = await this.getStepState(runId, stepName)
     } catch {
-      // Step doesn't exist - create it (inline, no RPC)
+      // Step doesn't exist - create it (inline, so never dispatched)
       stepState = await this.insertStepState(
         runId,
         stepName,
-        null,
-        null,
+        rpcName,
+        data,
         stepOptions,
         fromStepName
       )
@@ -2494,8 +2620,8 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     runId: string,
     rpcService: any,
     addonNamespace?: string | null
-  ): PikkuScenarioWire {
-    const workflowWire: PikkuScenarioWire = {
+  ): PikkuWorkflowWire {
+    const workflowWire: PikkuWorkflowWire = {
       name,
       runId,
       getRun: async () => (await this.getRun(runId)) as WorkflowRun,
@@ -2531,146 +2657,6 @@ 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
-        )
-      },
-
-      expectError: async (
-        stepName: string,
-        rpcName: string,
-        data: any,
-        options?: WorkflowExpectErrorOptions
-      ) => {
-        this.verifyStepName(stepName)
-        const resolvedRpcName =
-          addonNamespace && !rpcName.includes(':')
-            ? `${addonNamespace}:${rpcName}`
-            : rpcName
-        return await this.inlineStep(
-          runId,
-          stepName,
-          async () => {
-            let result: any
-            try {
-              result = options?.actor
-                ? await options.actor.invoke(resolvedRpcName, data)
-                : await rpcService.rpcWithWire(resolvedRpcName, data, {})
-            } catch (e: any) {
-              const message = e?.message ?? String(e)
-              if (options?.matches) {
-                const matched =
-                  typeof options.matches === 'string'
-                    ? message.includes(options.matches)
-                    : options.matches.test(message)
-                if (!matched) {
-                  throw new Error(
-                    `[workflow] expectError '${stepName}' ('${resolvedRpcName}') threw, but the message did not match ${options.matches}: ${message}`
-                  )
-                }
-              }
-              return message
-            }
-            throw new Error(
-              `[workflow] expectError '${stepName}' ('${resolvedRpcName}') expected an error but the call succeeded: ${JSON.stringify(result)?.slice(0, 300)}`
-            )
-          },
-          options
-        )
-      },
-
-      expectService: async (
-        stepName: string,
-        serviceMethod: string,
-        options?: WorkflowExpectServiceOptions
-      ) => {
-        this.verifyStepName(stepName)
-        const [service, method] = serviceMethod.split('.')
-        if (!service || !method) {
-          throw new Error(
-            `[workflow] expectService '${stepName}' needs 'service.method', got '${serviceMethod}'`
-          )
-        }
-        await this.inlineStep(
-          runId,
-          stepName,
-          async () => {
-            const rpcName = 'pikkuScenarioGetStubCalls'
-            const calls: Array<{
-              service: string
-              method: string
-              args: unknown[]
-            }> = options?.actor
-              ? await options.actor.invoke(rpcName, { service })
-              : await rpcService.rpcWithWire(rpcName, { service }, {})
-            const matching = (calls ?? []).filter(
-              (c) =>
-                c.service === service &&
-                c.method === method &&
-                (options?.calledWith === undefined ||
-                  JSON.stringify(c.args?.[0]) ===
-                    JSON.stringify(options.calledWith))
-            )
-            const expected = options?.times
-            const ok =
-              expected === undefined
-                ? matching.length > 0
-                : matching.length === expected
-            if (!ok) {
-              const seen =
-                (calls ?? [])
-                  .map(
-                    (c) =>
-                      `${c.service}.${c.method}(${JSON.stringify(c.args?.[0])?.slice(0, 120) ?? ''})`
-                  )
-                  .join('\n  ') || '(none)'
-              throw new Error(
-                `[workflow] expectService '${stepName}' expected ${expected ?? 'at least one'} call(s) to '${serviceMethod}'` +
-                  `${options?.calledWith !== undefined ? ` with ${JSON.stringify(options.calledWith)}` : ''}, found ${matching.length}. Recorded:\n  ${seen}`
-              )
-            }
-          },
-          options
-        )
-      },
-
       // Implement workflow.sleep()
       sleep: async (stepName: string, duration: string | number) => {
         this.verifyStepName(stepName)
@@ -2689,16 +2675,18 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       approval: (async (reason: string, options: WorkflowApprovalOptions) => {
         this.verifyStepName(reason)
         return await this.approvalStep(runId, reason, options)
-      }) as PikkuScenarioWire['approval'],
-
-      runScheduledTask: async (taskName: string) => {
-        await runScheduledTask({ name: taskName })
-      },
+      }) as PikkuWorkflowWire['approval'],
     }
+    this.runExtension?.decorateWorkflowWire(workflowWire, {
+      name,
+      runId,
+      rpcService,
+      addonNamespace,
+    })
     return workflowWire
   }
 
-  private verifyStepName(stepName: string) {
+  protected verifyStepName(stepName: string) {
     if (typeof stepName !== 'string') {
       throw new WorkflowStepNameNotString(stepName)
     }