@pikku/inspector 0.12.31 → 0.12.34

package/CHANGELOG.md

@@ -1,3 +1,55 @@
+## 0.12.34
+
+### Patch Changes
+
+- 92bd643: User flows in the console: workflow graph extraction now captures
+  `workflow.expectEventually` steps and per-step actor names (`{ actor:
+actors.x }`), workflow meta carries `actors`/`title` into the serialized
+  graph, the CLI emits `user-flow-actors.gen.json` for the new
+  `MetaService.getUserFlowActorsMeta()`, and the console Workflows page gains a
+  Workflows / User Flows / Personas toggle. Also fixes complex-workflow graphs
+  being clobbered by a duplicate basic-extraction pass after successful DSL
+  extraction.
+- Updated dependencies [35a9bab]
+- Updated dependencies [92bd643]
+  - @pikku/core@0.12.50
+
+## 0.12.33
+
+### Patch Changes
+
+- 4c17f7e: user flows: actors move onto the workflow wire + `pikku userflow` command
+  - Actors are no longer a singleton service: `startWorkflow(..., { actors })`
+    registers them per run and they arrive on the wire —
+    `func: async ({ logger }, input, { workflow, actors })`.
+  - Inspector enforces user flows are pure remote stories (PKU673): a
+    pikkuUserFlow func may only destructure `logger`/`config` from services.
+  - New `pikku userflow run <environment> [--flows a,b] [--tags x,y]` runs flows
+    against `userFlows.environments` from pikku.config.json (secret from
+    USER_FLOW_ACTOR_SECRET env), refusing internal (non-actor) steps so runs
+    against staging/production never touch local services; non-zero exit on
+    failure. `pikku userflow list` prints names, descriptions and tags.
+  - Workflow meta now carries `title` (parity with HTTP routes/functions).
+
+- Updated dependencies [4c17f7e]
+  - @pikku/core@0.12.49
+
+## 0.12.32
+
+### Patch Changes
+
+- 8dfddc3: pikkuUserFlow: user flows as workflows. A complex workflow whose steps can run
+  as actors over the real transport — `workflow.do(step, rpc, data, { actor:
+actors.yasser })` — plus `workflow.expectEventually(...)` for polling async
+  effects. Actor steps never queue and never dispatch internally, so auth
+  middleware/permissions are exercised end-to-end; flows double as e2e tests and
+  staged/production health checks. Ships UserFlowActor types +
+  createHttpUserFlowActors (lazy sign-in via `/auth/sign-in/actor` with a
+  server-held secret), inspector source `'user-flow'`, and a console badge.
+- Updated dependencies [5f2c566]
+- Updated dependencies [8dfddc3]
+  - @pikku/core@0.12.48
+
 ## 0.12.31
 
 ### Patch Changes

package/dist/add/add-functions.js

@@ -250,9 +250,11 @@ export const addFunctions = (logger, node, checker, state, options) => {
     if (!ts.isIdentifier(expression)) {
         return;
     }
-    // Match identifiers that contain both "pikku" and "func" (case insensitive)
+    // Match identifiers that contain both "pikku" and "func" (case insensitive),
+    // plus pikkuUserFlow (a workflow wrapper without "func" in its name)
     const pikkuFuncPattern = /pikku.*func/i;
-    if (!pikkuFuncPattern.test(expression.text)) {
+    if (!pikkuFuncPattern.test(expression.text) &&
+        expression.text !== 'pikkuUserFlow') {
         return;
     }
     // only handle calls like pikkuFunc(...)

package/dist/add/add-workflow.d.ts

@@ -5,7 +5,7 @@ import type { WorkflowStepMeta } from '@pikku/core/workflow';
  */
 export declare function collectInvokedRPCs(steps: WorkflowStepMeta[], rpcs: Set<string>): void;
 /**
- * Inspector for pikkuWorkflowFunc() and pikkuWorkflowComplexFunc() calls
- * Detects workflow registration and extracts metadata
+ * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
+ * pikkuUserFlow() calls. Detects workflow registration and extracts metadata.
  */
 export declare const addWorkflow: AddWiring;

package/dist/add/add-workflow.js

@@ -5,7 +5,7 @@ import { ErrorCode } from '../error-codes.js';
 import { extractStringLiteral, isStringLike, isFunctionLike, extractDescription, extractDuration, } from '../utils/extract-node-value.js';
 import { getCommonWireMetaData, getPropertyValue, } from '../utils/get-property-value.js';
 import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js';
-import { getSourceText } from '../utils/workflow/dsl/patterns.js';
+import { getSourceText, extractActorFromOptions, } from '../utils/workflow/dsl/patterns.js';
 /**
  * Extract a workflow step's display name without letting a non-static name
  * (e.g. a function call) abort the scan. The step name is cosmetic, so a
@@ -86,14 +86,18 @@ export function collectInvokedRPCs(steps, rpcs) {
     }
 }
 /**
- * Scan for workflow.do(), workflow.sleep(), and workflow.cancel() calls to extract workflow steps
+ * Scan for workflow.do(), workflow.expectEventually(), workflow.sleep(), and
+ * workflow.cancel() calls to extract workflow steps
  */
 function getWorkflowInvocations(node, checker, state, workflowName, steps) {
     // Look for property access expressions: workflow.do or workflow.sleep
     if (ts.isPropertyAccessExpression(node)) {
         const { name } = node;
         // Check if this is accessing 'do' or 'sleep' property
-        if (name.text === 'do' || name.text === 'sleep' || name.text === 'cancel') {
+        if (name.text === 'do' ||
+            name.text === 'sleep' ||
+            name.text === 'cancel' ||
+            name.text === 'expectEventually') {
             // Check if the parent is a call expression
             const parent = node.parent;
             if (ts.isCallExpression(parent) && parent.expression === node) {
@@ -113,6 +117,7 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
                             type: 'rpc',
                             stepName,
                             rpcName,
+                            actor: extractActorFromOptions(optionsArg),
                         });
                         state.rpc.invokedFunctions.add(rpcName);
                     }
@@ -125,6 +130,21 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
                         });
                     }
                 }
+                else if (name.text === 'expectEventually' && args.length >= 4) {
+                    // workflow.expectEventually(stepName, rpcName, data, predicate, options?)
+                    const stepName = extractStepName(args[0], checker);
+                    if (isStringLike(args[1], checker)) {
+                        const rpcName = extractStringLiteral(args[1], checker);
+                        steps.push({
+                            type: 'rpc',
+                            stepName,
+                            rpcName,
+                            expectEventually: true,
+                            actor: extractActorFromOptions(args.length >= 5 ? args[4] : undefined),
+                        });
+                        state.rpc.invokedFunctions.add(rpcName);
+                    }
+                }
                 else if (name.text === 'sleep' && args.length >= 2) {
                     // workflow.sleep(stepName, duration)
                     const stepNameArg = args[0];
@@ -156,8 +176,8 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
     });
 }
 /**
- * Inspector for pikkuWorkflowFunc() and pikkuWorkflowComplexFunc() calls
- * Detects workflow registration and extracts metadata
+ * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
+ * pikkuUserFlow() calls. Detects workflow registration and extracts metadata.
  */
 export const addWorkflow = (logger, node, checker, state) => {
     if (!ts.isCallExpression(node)) {
@@ -176,6 +196,11 @@ export const addWorkflow = (logger, node, checker, state) => {
     else if (expression.text === 'pikkuWorkflowComplexFunc') {
         wrapperType = 'complex';
     }
+    else if (expression.text === 'pikkuUserFlow') {
+        // A user flow is a complex workflow whose steps run as actors over the
+        // real transport — same extraction rules as complex, distinct meta.
+        wrapperType = 'user-flow';
+    }
     else {
         return;
     }
@@ -193,6 +218,7 @@ export const addWorkflow = (logger, node, checker, state) => {
     const { funcNode, resolvedFunc } = extractFunctionNode(firstArg, checker);
     // Extract metadata if using object form
     let tags;
+    let title;
     let summary;
     let description;
     let errors;
@@ -202,6 +228,7 @@ export const addWorkflow = (logger, node, checker, state) => {
         if (metadata.disabled)
             return;
         tags = metadata.tags;
+        title = metadata.title;
         summary = metadata.summary;
         description = metadata.description;
         errors = metadata.errors;
@@ -230,7 +257,7 @@ export const addWorkflow = (logger, node, checker, state) => {
     // Try DSL workflow extraction first
     // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
     const result = extractDSLWorkflow(node, checker, {
-        allowInline: wrapperType === 'complex',
+        allowInline: wrapperType !== 'dsl',
     });
     if (result.status === 'ok' && result.steps) {
         // Extraction succeeded
@@ -275,24 +302,51 @@ export const addWorkflow = (logger, node, checker, state) => {
     // For pikkuWorkflowComplexFunc, also run basic extraction so RPCs in
     // patterns the DSL extractor doesn't handle (array+push, nested Promise.all
     // with identifier args, etc.) are still registered as invoked functions.
-    if (wrapperType === 'complex') {
-        getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps);
+    // When DSL extraction already produced steps this pass is registration-only:
+    // appending to `steps` would duplicate nodes and clobber the graph.
+    if (wrapperType !== 'dsl') {
+        const sink = steps.length > 0 ? [] : steps;
+        getWorkflowInvocations(resolvedFunc, checker, state, workflowName, sink);
     }
+    // Actor names the flow's steps run as (user flows) — powers the console
+    // personas view and the User Flow graph badges.
+    const actorNames = [
+        ...new Set(steps
+            .map((s) => ('actor' in s ? s.actor : undefined))
+            .filter((a) => typeof a === 'string')),
+    ];
     state.workflows.meta[workflowName] = {
         pikkuFuncId,
         name: workflowName,
         steps,
         context,
         dsl,
+        title,
         summary,
         description,
         errors,
         tags,
         expose,
+        userFlow: wrapperType === 'user-flow' ? true : undefined,
+        actors: actorNames.length > 0 ? actorNames : undefined,
     };
+    // User flows are pure stories of remote RPCs (same rule as client-side CLI
+    // renderers): the func may only destructure logger/config — everything else
+    // must go through actor steps so the flow runs against the TARGET
+    // environment, never local services.
+    const funcMeta = state.functions.meta[pikkuFuncId];
+    if (wrapperType === 'user-flow' && funcMeta?.services) {
+        const disallowed = funcMeta.services.services.filter((svc) => svc !== 'logger' && svc !== 'config');
+        if (disallowed.length > 0) {
+            logger.critical(ErrorCode.USER_FLOW_HAS_SERVICES, `User flow '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
+                `User flows may only use 'logger'/'config' — drive everything else through ` +
+                `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
+                `runs against the target environment.`);
+            return;
+        }
+    }
     // Workflow functions require platform services that aren't visible
     // through parameter destructuring (they're accessed via workflow.do/sleep)
-    const funcMeta = state.functions.meta[pikkuFuncId];
     if (funcMeta?.services) {
         for (const svc of [
             'workflowService',

package/dist/error-codes.d.ts

@@ -19,6 +19,7 @@ export declare 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/dist/error-codes.js

@@ -21,6 +21,7 @@ export var ErrorCode;
     ErrorCode["MISSING_QUEUE_NAME"] = "PKU384";
     ErrorCode["MISSING_CHANNEL_NAME"] = "PKU400";
     ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
+    ErrorCode["USER_FLOW_HAS_SERVICES"] = "PKU673";
     ErrorCode["DYNAMIC_STEP_NAME"] = "PKU529";
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { isWorkflowDoCall, isWorkflowSleepCall, isWorkflowSuspendCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
+import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
 import { validateNoDisallowedPatterns, validateAwaitedCalls, formatValidationErrors, } from './validation.js';
 import { extractStringLiteral, extractNumberLiteral, } from '../../extract-node-value.js';
 /**
@@ -386,9 +386,12 @@ function extractRpcStep(call, context, outputVar) {
         const rpcName = extractStringLiteral(args[1], context.checker);
         // Extract inputs from third argument
         const inputs = args.length >= 3 ? extractInputSources(args[2], context) : undefined;
-        // Extract options from fourth argument
-        const options = args.length >= 4 && ts.isObjectLiteralExpression(args[3])
-            ? extractStepOptions(args[3], context)
+        // 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 = optionsArg && ts.isObjectLiteralExpression(optionsArg)
+            ? extractStepOptions(optionsArg, context)
             : undefined;
         return {
             type: 'rpc',
@@ -397,6 +400,8 @@ function extractRpcStep(call, context, outputVar) {
             outputVar,
             inputs,
             options,
+            actor: extractActorFromOptions(optionsArg),
+            expectEventually: expectEventually || undefined,
         };
     }
     catch (error) {

package/dist/utils/workflow/dsl/patterns.d.ts

@@ -3,9 +3,20 @@ import * as ts from 'typescript';
  * Pattern detection helpers for DSL workflow extraction
  */
 /**
- * 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 declare function isWorkflowDoCall(node: ts.CallExpression, checker: ts.TypeChecker): boolean;
+/**
+ * Check if a call expression is workflow.expectEventually()
+ */
+export declare function isWorkflowExpectEventuallyCall(node: ts.CallExpression): boolean;
+/**
+ * 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 declare function extractActorFromOptions(optionsArg: ts.Expression | undefined): string | undefined;
 /**
  * Check if a call expression is workflow.sleep()
  */

package/dist/utils/workflow/dsl/patterns.js

@@ -3,17 +3,52 @@ import * as ts from 'typescript';
  * Pattern detection helpers for DSL workflow extraction
  */
 /**
- * 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, checker) {
     if (!ts.isPropertyAccessExpression(node.expression)) {
         return false;
     }
     const propAccess = node.expression;
-    return (propAccess.name.text === 'do' &&
+    return ((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) {
+    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) {
+    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/dist/utils/workflow/graph/convert-dsl-to-graph.js

@@ -58,6 +58,12 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
                 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
@@ -291,16 +297,23 @@ export function convertDslToGraph(workflowName, meta) {
         nodesRecord[node.nodeId] = node;
     }
     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/dist/utils/workflow/graph/workflow-graph.types.d.ts

@@ -96,6 +96,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;
 }
 /**
  * Flow node - control flow only, no RPC call
@@ -123,8 +127,9 @@ export declare 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
  */
@@ -135,10 +140,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) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.31",
+  "version": "0.12.34",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.45",
+    "@pikku/core": "^0.12.50",
     "openapi-types": "^12.1.3",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "2.9.1-next.16",

package/src/add/add-functions.ts

@@ -357,9 +357,13 @@ export const addFunctions: AddWiring = (
     return
   }
 
-  // Match identifiers that contain both "pikku" and "func" (case insensitive)
+  // Match identifiers that contain both "pikku" and "func" (case insensitive),
+  // plus pikkuUserFlow (a workflow wrapper without "func" in its name)
   const pikkuFuncPattern = /pikku.*func/i
-  if (!pikkuFuncPattern.test(expression.text)) {
+  if (
+    !pikkuFuncPattern.test(expression.text) &&
+    expression.text !== 'pikkuUserFlow'
+  ) {
     return
   }
 

package/src/add/add-workflow.ts

@@ -16,7 +16,10 @@ import {
   getPropertyValue,
 } from '../utils/get-property-value.js'
 import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js'
-import { getSourceText } from '../utils/workflow/dsl/patterns.js'
+import {
+  getSourceText,
+  extractActorFromOptions,
+} from '../utils/workflow/dsl/patterns.js'
 
 /**
  * Extract a workflow step's display name without letting a non-static name
@@ -86,7 +89,8 @@ export function collectInvokedRPCs(
 }
 
 /**
- * Scan for workflow.do(), workflow.sleep(), and workflow.cancel() calls to extract workflow steps
+ * Scan for workflow.do(), workflow.expectEventually(), workflow.sleep(), and
+ * workflow.cancel() calls to extract workflow steps
  */
 function getWorkflowInvocations(
   node: ts.Node,
@@ -100,7 +104,12 @@ function getWorkflowInvocations(
     const { name } = node
 
     // Check if this is accessing 'do' or 'sleep' property
-    if (name.text === 'do' || name.text === 'sleep' || name.text === 'cancel') {
+    if (
+      name.text === 'do' ||
+      name.text === 'sleep' ||
+      name.text === 'cancel' ||
+      name.text === 'expectEventually'
+    ) {
       // Check if the parent is a call expression
       const parent = node.parent
       if (ts.isCallExpression(parent) && parent.expression === node) {
@@ -125,6 +134,7 @@ function getWorkflowInvocations(
               type: 'rpc',
               stepName,
               rpcName,
+              actor: extractActorFromOptions(optionsArg),
             })
             state.rpc.invokedFunctions.add(rpcName)
           } else if (isFunctionLike(secondArg)) {
@@ -135,6 +145,20 @@ function getWorkflowInvocations(
               description: description || '<dynamic>',
             })
           }
+        } else if (name.text === 'expectEventually' && args.length >= 4) {
+          // workflow.expectEventually(stepName, rpcName, data, predicate, options?)
+          const stepName = extractStepName(args[0], checker)
+          if (isStringLike(args[1], checker)) {
+            const rpcName = extractStringLiteral(args[1], checker)
+            steps.push({
+              type: 'rpc',
+              stepName,
+              rpcName,
+              expectEventually: true,
+              actor: extractActorFromOptions(args.length >= 5 ? args[4] : undefined),
+            })
+            state.rpc.invokedFunctions.add(rpcName)
+          }
         } else if (name.text === 'sleep' && args.length >= 2) {
           // workflow.sleep(stepName, duration)
           const stepNameArg = args[0]
@@ -169,8 +193,8 @@ function getWorkflowInvocations(
 }
 
 /**
- * Inspector for pikkuWorkflowFunc() and pikkuWorkflowComplexFunc() calls
- * Detects workflow registration and extracts metadata
+ * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
+ * pikkuUserFlow() calls. Detects workflow registration and extracts metadata.
  */
 export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   if (!ts.isCallExpression(node)) {
@@ -185,11 +209,15 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     return
   }
 
-  let wrapperType: 'dsl' | 'complex' | null = null
+  let wrapperType: 'dsl' | 'complex' | 'user-flow' | null = null
   if (expression.text === 'pikkuWorkflowFunc') {
     wrapperType = 'dsl'
   } else if (expression.text === 'pikkuWorkflowComplexFunc') {
     wrapperType = 'complex'
+  } else if (expression.text === 'pikkuUserFlow') {
+    // A user flow is a complex workflow whose steps run as actors over the
+    // real transport — same extraction rules as complex, distinct meta.
+    wrapperType = 'user-flow'
   } else {
     return
   }
@@ -220,6 +248,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
 
   // Extract metadata if using object form
   let tags: string[] | undefined
+  let title: string | undefined
   let summary: string | undefined
   let description: string | undefined
   let errors: string[] | undefined
@@ -235,6 +264,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     )
     if (metadata.disabled) return
     tags = metadata.tags
+    title = metadata.title
     summary = metadata.summary
     description = metadata.description
     errors = metadata.errors
@@ -277,7 +307,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   // Try DSL workflow extraction first
   // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
   const result = extractDSLWorkflow(node, checker, {
-    allowInline: wrapperType === 'complex',
+    allowInline: wrapperType !== 'dsl',
   })
 
   if (result.status === 'ok' && result.steps) {
@@ -331,26 +361,62 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   // For pikkuWorkflowComplexFunc, also run basic extraction so RPCs in
   // patterns the DSL extractor doesn't handle (array+push, nested Promise.all
   // with identifier args, etc.) are still registered as invoked functions.
-  if (wrapperType === 'complex') {
-    getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
+  // When DSL extraction already produced steps this pass is registration-only:
+  // appending to `steps` would duplicate nodes and clobber the graph.
+  if (wrapperType !== 'dsl') {
+    const sink: WorkflowStepMeta[] = steps.length > 0 ? [] : steps
+    getWorkflowInvocations(resolvedFunc, checker, state, workflowName, sink)
   }
 
+  // Actor names the flow's steps run as (user flows) — powers the console
+  // personas view and the User Flow graph badges.
+  const actorNames = [
+    ...new Set(
+      steps
+        .map((s) => ('actor' in s ? s.actor : undefined))
+        .filter((a): a is string => typeof a === 'string')
+    ),
+  ]
+
   state.workflows.meta[workflowName] = {
     pikkuFuncId,
     name: workflowName,
     steps,
     context,
     dsl,
+    title,
     summary,
     description,
     errors,
     tags,
     expose,
+    userFlow: wrapperType === 'user-flow' ? true : undefined,
+    actors: actorNames.length > 0 ? actorNames : undefined,
+  }
+
+  // User flows are pure stories of remote RPCs (same rule as client-side CLI
+  // renderers): the func may only destructure logger/config — everything else
+  // must go through actor steps so the flow runs against the TARGET
+  // environment, never local services.
+  const funcMeta = state.functions.meta[pikkuFuncId]
+  if (wrapperType === 'user-flow' && funcMeta?.services) {
+    const disallowed = funcMeta.services.services.filter(
+      (svc) => svc !== 'logger' && svc !== 'config'
+    )
+    if (disallowed.length > 0) {
+      logger.critical(
+        ErrorCode.USER_FLOW_HAS_SERVICES,
+        `User flow '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
+          `User flows may only use 'logger'/'config' — drive everything else through ` +
+          `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
+          `runs against the target environment.`
+      )
+      return
+    }
   }
 
   // Workflow functions require platform services that aren't visible
   // through parameter destructuring (they're accessed via workflow.do/sleep)
-  const funcMeta = state.functions.meta[pikkuFuncId]
   if (funcMeta?.services) {
     for (const svc of [
       'workflowService',