@pikku/inspector 0.12.31 → 0.12.34

package/src/error-codes.ts

@@ -21,6 +21,7 @@ export enum ErrorCode {
   MISSING_QUEUE_NAME = 'PKU384',
   MISSING_CHANNEL_NAME = 'PKU400',
   CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = 'PKU672',
+  USER_FLOW_HAS_SERVICES = 'PKU673',
   DYNAMIC_STEP_NAME = 'PKU529',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
   INVALID_DSL_WORKFLOW = 'PKU641',

package/src/utils/workflow/dsl/extract-dsl-workflow.ts

@@ -21,6 +21,8 @@ import type {
 } from '@pikku/core/workflow'
 import {
   isWorkflowDoCall,
+  isWorkflowExpectEventuallyCall,
+  extractActorFromOptions,
   isWorkflowSleepCall,
   isWorkflowSuspendCall,
   isThrowCancelException,
@@ -553,10 +555,15 @@ function extractRpcStep(
     const inputs =
       args.length >= 3 ? extractInputSources(args[2], context) : undefined
 
-    // Extract options from fourth argument
+    // do(step, rpc, data, options?) vs expectEventually(step, rpc, data, predicate, options?)
+    const expectEventually = isWorkflowExpectEventuallyCall(call)
+    const optionsIndex = expectEventually ? 4 : 3
+    const optionsArg =
+      args.length > optionsIndex ? args[optionsIndex] : undefined
+
     const options =
-      args.length >= 4 && ts.isObjectLiteralExpression(args[3])
-        ? extractStepOptions(args[3], context)
+      optionsArg && ts.isObjectLiteralExpression(optionsArg)
+        ? extractStepOptions(optionsArg, context)
         : undefined
 
     return {
@@ -566,6 +573,8 @@ function extractRpcStep(
       outputVar,
       inputs,
       options,
+      actor: extractActorFromOptions(optionsArg),
+      expectEventually: expectEventually || undefined,
     }
   } catch (error) {
     context.errors.push({

package/src/utils/workflow/dsl/patterns.ts

@@ -5,7 +5,8 @@ import * as ts from 'typescript'
  */
 
 /**
- * Check if a call expression is workflow.do()
+ * Check if a call expression is workflow.do() or workflow.expectEventually()
+ * (both are RPC steps; expectEventually is the polling variant used by user flows)
  */
 export function isWorkflowDoCall(
   node: ts.CallExpression,
@@ -17,12 +18,57 @@ export function isWorkflowDoCall(
 
   const propAccess = node.expression
   return (
-    propAccess.name.text === 'do' &&
+    (propAccess.name.text === 'do' ||
+      propAccess.name.text === 'expectEventually') &&
     ts.isIdentifier(propAccess.expression) &&
     propAccess.expression.text === 'workflow'
   )
 }
 
+/**
+ * Check if a call expression is workflow.expectEventually()
+ */
+export function isWorkflowExpectEventuallyCall(
+  node: ts.CallExpression
+): boolean {
+  return (
+    ts.isPropertyAccessExpression(node.expression) &&
+    node.expression.name.text === 'expectEventually' &&
+    ts.isIdentifier(node.expression.expression) &&
+    node.expression.expression.text === 'workflow'
+  )
+}
+
+/**
+ * Extract the actor NAME from a step options object literal:
+ * `{ actor: actors.x }` → 'x' (also `actors['x']`). Undefined when absent
+ * or not statically resolvable.
+ */
+export function extractActorFromOptions(
+  optionsArg: ts.Expression | undefined
+): string | undefined {
+  if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg)) return
+  for (const prop of optionsArg.properties) {
+    if (
+      ts.isPropertyAssignment(prop) &&
+      ts.isIdentifier(prop.name) &&
+      prop.name.text === 'actor'
+    ) {
+      const init = prop.initializer
+      if (ts.isPropertyAccessExpression(init)) {
+        return init.name.text
+      }
+      if (
+        ts.isElementAccessExpression(init) &&
+        ts.isStringLiteral(init.argumentExpression)
+      ) {
+        return init.argumentExpression.text
+      }
+    }
+  }
+  return
+}
+
 /**
  * Check if a call expression is workflow.sleep()
  */

package/src/utils/workflow/graph/convert-dsl-to-graph.ts

@@ -93,6 +93,12 @@ function convertStepToNode(
         rpcName: step.rpcName,
         next: nextNodeId,
       }
+      if (step.actor) {
+        node.actor = step.actor
+      }
+      if (step.expectEventually) {
+        node.expectEventually = true
+      }
       if (step.inputs) {
         if (step.inputs === 'passthrough') {
           // Entire data is passed through - store as reference to trigger
@@ -389,17 +395,24 @@ export function convertDslToGraph(
 
   const entryNodeIds = nodes.length > 0 ? [nodes[0].nodeId] : []
 
-  // Determine source type based on dsl flag:
+  // Determine source type:
+  // - userFlow: complex workflow whose steps run as actors (user flow)
   // - dsl === true: pure DSL workflow, can be serialized
   // - dsl === false: complex workflow with inline steps, not serializable
-  const source = meta.dsl === false ? 'complex' : 'dsl'
+  const source = meta.userFlow
+    ? 'user-flow'
+    : meta.dsl === false
+      ? 'complex'
+      : 'dsl'
 
   return {
     name: workflowName,
     pikkuFuncId: meta.pikkuFuncId,
     source,
+    title: meta.title,
     description: meta.description,
     tags: meta.tags,
+    actors: meta.actors,
     context: meta.context,
     nodes: nodesRecord,
     entryNodeIds,

package/src/utils/workflow/graph/workflow-graph.types.ts

@@ -142,6 +142,10 @@ export interface FunctionNode extends BaseNode {
   outputVar?: string
   /** Hash of nodeId + RPC input/output schemas for version detection */
   stepHash?: string
+  /** User-flow actor name this step runs as (workflow.do {actor: actors.x}) */
+  actor?: string
+  /** True for workflow.expectEventually polling steps (user flows) */
+  expectEventually?: boolean
 }
 
 /**
@@ -177,8 +181,9 @@ export const isFlowNode = (node: SerializedGraphNode): node is FlowNode =>
  * - 'dsl': Pure DSL workflow (pikkuWorkflowFunc) - can be round-tripped to code
  * - 'complex': Complex workflow (pikkuWorkflowComplexFunc) - contains inline steps, not serializable
  * - 'graph': Graph-based workflow (pikkuWorkflowGraph)
+ * - 'user-flow': User flow (pikkuUserFlow) - complex workflow whose steps run as actors
  */
-export type WorkflowSourceType = 'dsl' | 'complex' | 'graph'
+export type WorkflowSourceType = 'dsl' | 'complex' | 'graph' | 'user-flow'
 
 /**
  * Serialized workflow graph - the canonical JSON format
@@ -190,10 +195,14 @@ export interface SerializedWorkflowGraph {
   pikkuFuncId: string
   /** Source type: 'dsl' for pikkuWorkflowFunc, 'graph' for pikkuWorkflowGraph */
   source: WorkflowSourceType
+  /** Optional short display name */
+  title?: string
   /** Optional description */
   description?: string
   /** Tags for organization */
   tags?: string[]
+  /** Actor names a user flow's steps run as */
+  actors?: string[]
   /** If true, workflow always executes inline without queues */
   inline?: boolean
   /** Workflow context/state variables (from Zod schema) */