@pikku/core 0.12.47 → 0.12.50

package/CHANGELOG.md

@@ -1,3 +1,55 @@
+## 0.12.50
+
+### Patch Changes
+
+- 35a9bab: UserFlowActor exposes the actor's `email` so flows can use it for
+  invites/lookups instead of hardcoding the config value.
+- 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.
+
+## 0.12.49
+
+### 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).
+
+## 0.12.48
+
+### Patch Changes
+
+- 5f2c566: Better Auth actor plugin for user flows: `actor({ secret })` adds an `actor`
+  boolean column on `user` and a `POST /sign-in/actor` endpoint (`{ email,
+secret }`, constant-time compare). Actor rows are auto-created on first
+  sign-in; a real (non-actor) user can never be impersonated with the secret.
+  The flag propagates into the pikku core session (`CoreUserSession.actor`) via
+  both `betterAuthSession` and `betterAuthStatelessSession`, so audits and
+  analytics can address synthetic traffic.
+- 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.
+
 ## 0.12.47
 
 ### Patch Changes

package/dist/services/http-user-flow-actors.d.ts

@@ -0,0 +1,47 @@
+import type { UserFlowActor, UserFlowActorConfig, UserFlowActors } from './user-flow-actors-service.js';
+export interface HttpUserFlowActorsConfig {
+    /**
+     * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
+     * `https://app.example.com/api` or `http://localhost:4000/api`. Actor
+     * sign-in is reached at `${apiUrl}${signInPath}` and exposed RPCs at
+     * `${apiUrl}${rpcPath}/:rpcName`.
+     */
+    apiUrl: string;
+    /**
+     * The actor impersonation secret. Sign-in only ever works for user rows
+     * flagged `actor: true` — knowing the secret never impersonates real users.
+     */
+    secret: string;
+    /** Actor name → config (usually from pikku.config.json's actor registry). */
+    actors: Record<string, UserFlowActorConfig>;
+    /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
+    signInPath?: string;
+    /** Exposed-RPC path prefix under apiUrl. Default `/rpc`. */
+    rpcPath?: string;
+}
+/**
+ * Default HTTP-backed actor. Signs in lazily on first invoke via the Better
+ * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
+ * the plugin upserts the actor-flagged user row and mints a session whose
+ * `actor` flag flows into audits/analytics). Holds the session cookies for
+ * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
+ * outlive a session).
+ */
+export declare class HttpUserFlowActor implements UserFlowActor {
+    readonly name: string;
+    private actorConfig;
+    private config;
+    private cookie;
+    private origin;
+    constructor(name: string, actorConfig: UserFlowActorConfig, config: HttpUserFlowActorsConfig);
+    get email(): string;
+    invoke(rpcName: string, data: unknown): Promise<unknown>;
+    private postRpc;
+    private readRpcResponse;
+    private login;
+}
+/**
+ * Build the injected `actors` service from the config registry: actor name →
+ * lazy HTTP actor. Wire the result as the `actors` singleton service.
+ */
+export declare function createHttpUserFlowActors(config: HttpUserFlowActorsConfig): UserFlowActors;

package/dist/services/http-user-flow-actors.js

@@ -0,0 +1,93 @@
+/**
+ * Default HTTP-backed actor. Signs in lazily on first invoke via the Better
+ * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
+ * the plugin upserts the actor-flagged user row and mints a session whose
+ * `actor` flag flows into audits/analytics). Holds the session cookies for
+ * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
+ * outlive a session).
+ */
+export class HttpUserFlowActor {
+    name;
+    actorConfig;
+    config;
+    cookie = null;
+    origin;
+    constructor(name, actorConfig, config) {
+        this.name = name;
+        this.actorConfig = actorConfig;
+        this.config = config;
+        this.origin = new URL(config.apiUrl).origin;
+    }
+    get email() {
+        return this.actorConfig.email;
+    }
+    async invoke(rpcName, data) {
+        const cookie = this.cookie ?? (await this.login());
+        const res = await this.postRpc(rpcName, data, cookie);
+        if (res.status === 401) {
+            // Session expired mid-run — re-login once and retry.
+            this.cookie = null;
+            return this.readRpcResponse(rpcName, await this.postRpc(rpcName, data, await this.login()));
+        }
+        return this.readRpcResponse(rpcName, res);
+    }
+    async postRpc(rpcName, data, cookie) {
+        const rpcPath = this.config.rpcPath ?? '/rpc';
+        return fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                origin: this.origin,
+                cookie,
+            },
+            body: JSON.stringify({ data }),
+        });
+    }
+    async readRpcResponse(rpcName, res) {
+        if (!res.ok) {
+            const body = (await res.text().catch(() => '')).slice(0, 300);
+            throw new Error(`[user-flow] '${rpcName}' as '${this.name}' returned ${res.status}: ${body}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        return text ? JSON.parse(text) : undefined;
+    }
+    async login() {
+        const signInPath = this.config.signInPath ?? '/auth/sign-in/actor';
+        const res = await fetch(`${this.config.apiUrl}${signInPath}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', origin: this.origin },
+            body: JSON.stringify({
+                email: this.actorConfig.email,
+                name: this.actorConfig.name ?? this.name,
+                secret: this.config.secret,
+            }),
+        });
+        if (!res.ok) {
+            const body = (await res.text().catch(() => '')).slice(0, 300);
+            throw new Error(`[user-flow] actor sign-in failed for '${this.name}' (${res.status}): ${body}`);
+        }
+        const setCookies = res.headers.getSetCookie?.() ?? [];
+        const cookie = setCookies
+            .map((c) => c.split(';')[0])
+            .filter(Boolean)
+            .join('; ');
+        if (!cookie) {
+            throw new Error(`[user-flow] actor sign-in for '${this.name}' returned no session cookie`);
+        }
+        this.cookie = cookie;
+        return cookie;
+    }
+}
+/**
+ * Build the injected `actors` service from the config registry: actor name →
+ * lazy HTTP actor. Wire the result as the `actors` singleton service.
+ */
+export function createHttpUserFlowActors(config) {
+    const actors = {};
+    for (const [name, actorConfig] of Object.entries(config.actors)) {
+        actors[name] = new HttpUserFlowActor(name, actorConfig, config);
+    }
+    return actors;
+}

package/dist/services/index.d.ts

@@ -18,6 +18,8 @@ export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
 export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
+export type { UserFlowActor, UserFlowActorConfig, UserFlowActors, } from './user-flow-actors-service.js';
+export { HttpUserFlowActor, createHttpUserFlowActors, type HttpUserFlowActorsConfig, } from './http-user-flow-actors.js';
 export type { JWTService } from './jwt-service.js';
 export type { EmailService, EmailTemplateReference, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
 export type { Logger } from './logger.js';

package/dist/services/index.js

@@ -17,6 +17,7 @@ export { InMemoryQueueService } from './in-memory-queue-service.js';
 export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
+export { HttpUserFlowActor, createHttpUserFlowActors, } from './http-user-flow-actors.js';
 export { TypedCredentialService } from './typed-credential-service.js';
 export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';

package/dist/services/meta-service.d.ts

@@ -6,6 +6,7 @@ import type { QueueWorkersMeta } from '../wirings/queue/queue.types.js';
 import type { CLIMeta } from '../wirings/cli/cli.types.js';
 import type { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
 import type { WorkflowsMeta } from '../wirings/workflow/workflow.types.js';
+import type { UserFlowActorConfig } from './user-flow-actors-service.js';
 import type { TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
 import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
 import type { CredentialDefinitionsMeta } from '../wirings/credential/credential.types.js';
@@ -140,6 +141,7 @@ export interface MetaService {
     getGatewayMeta(): Promise<GatewaysMeta>;
     getRpcMeta(): Promise<RPCMetaRecord>;
     getWorkflowMeta(): Promise<WorkflowsMeta>;
+    getUserFlowActorsMeta(): Promise<Record<string, UserFlowActorConfig>>;
     getTriggerMeta(): Promise<TriggerMeta>;
     getTriggerSourceMeta(): Promise<TriggerSourceMeta>;
     getFunctionsMeta(): Promise<FunctionsMeta>;
@@ -171,6 +173,7 @@ export declare class LocalMetaService implements MetaService {
     private gatewayMetaCache;
     private rpcMetaCache;
     private workflowMetaCache;
+    private userFlowActorsMetaCache;
     private triggerMetaCache;
     private triggerSourceMetaCache;
     private functionsMetaCache;
@@ -197,6 +200,7 @@ export declare class LocalMetaService implements MetaService {
     getGatewayMeta(): Promise<GatewaysMeta>;
     getRpcMeta(): Promise<RPCMetaRecord>;
     getWorkflowMeta(): Promise<WorkflowsMeta>;
+    getUserFlowActorsMeta(): Promise<Record<string, UserFlowActorConfig>>;
     getTriggerMeta(): Promise<TriggerMeta>;
     getTriggerSourceMeta(): Promise<TriggerSourceMeta>;
     getFunctionsMeta(): Promise<FunctionsMeta>;

package/dist/services/meta-service.js

@@ -15,6 +15,7 @@ export class LocalMetaService {
     gatewayMetaCache = null;
     rpcMetaCache = null;
     workflowMetaCache = null;
+    userFlowActorsMetaCache = null;
     triggerMetaCache = null;
     triggerSourceMetaCache = null;
     functionsMetaCache = null;
@@ -63,6 +64,7 @@ export class LocalMetaService {
         this.gatewayMetaCache = null;
         this.rpcMetaCache = null;
         this.workflowMetaCache = null;
+        this.userFlowActorsMetaCache = null;
         this.triggerMetaCache = null;
         this.triggerSourceMetaCache = null;
         this.functionsMetaCache = null;
@@ -201,6 +203,13 @@ export class LocalMetaService {
             return this.workflowMetaCache;
         }
     }
+    async getUserFlowActorsMeta() {
+        if (this.userFlowActorsMetaCache)
+            return this.userFlowActorsMetaCache;
+        const content = await this.readFile('workflow/user-flow-actors.gen.json');
+        this.userFlowActorsMetaCache = content ? JSON.parse(content) : {};
+        return this.userFlowActorsMetaCache;
+    }
     async getTriggerMeta() {
         if (this.triggerMetaCache)
             return this.triggerMetaCache;

package/dist/services/user-flow-actors-service.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A user-flow actor: a synthetic user (a normal user row flagged `actor`) that
+ * workflow steps can run as. Passed to `workflow.do(step, rpc, data, { actor })`
+ * — the step then goes through the actor's authenticated client over the REAL
+ * transport (auth middleware, permissions, serialization all exercised),
+ * never through internal dispatch. Login is lazy: the first `invoke` signs the
+ * actor in and the session is cached for the actor's lifetime.
+ */
+export interface UserFlowActor {
+    /** Stable actor name (the key in pikku.config.json's actor registry). */
+    readonly name: string;
+    /** The actor's user email — flows use it for invites/lookups. */
+    readonly email: string;
+    /** Invoke an exposed RPC as this actor over the real transport. */
+    invoke(rpcName: string, data: unknown): Promise<unknown>;
+}
+/**
+ * Display/config metadata for an actor (from pikku.config.json). The email
+ * identifies the actor's user row; personality/jobTitle exist for the console
+ * screen and for agent-driven flows (the agent plays the persona).
+ */
+export interface UserFlowActorConfig {
+    email: string;
+    name?: string;
+    jobTitle?: string;
+    personality?: string;
+}
+/** The injected `actors` service: actor name → actor. */
+export type UserFlowActors = Record<string, UserFlowActor>;

package/dist/services/user-flow-actors-service.js

@@ -0,0 +1 @@
+export {};

package/dist/types/core.types.d.ts

@@ -19,6 +19,7 @@ import type { SchedulerService } from '../services/scheduler-service.js';
 import type { DeploymentService } from '../services/deployment-service.js';
 import type { AIStorageService } from '../services/ai-storage-service.js';
 import type { ContentService } from '../services/content-service.js';
+import type { UserFlowActors } from '../services/user-flow-actors-service.js';
 import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js';
 import type { AIRunStateService } from '../services/ai-run-state-service.js';
 import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js';
@@ -185,6 +186,8 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
 export interface CoreUserSession {
     userId?: string;
     orgId?: string;
+    /** True when the session belongs to a synthetic user-flow actor — lets audits/analytics address synthetic traffic */
+    actor?: boolean;
 }
 /**
  * Interface for core singleton services provided by Pikku.
@@ -263,6 +266,8 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     queue: PikkuQueue;
     cli: PikkuCLI;
     workflow: TypedWorkflow;
+    /** User-flow actor registry (user-flow runs only) — pass into workflow.do as `{ actor: actors.x }` */
+    actors: UserFlowActors;
     workflowStep: WorkflowStepWire;
     graph: PikkuGraphWire;
     trigger: PikkuTrigger<TriggerOutput>;

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -3,6 +3,7 @@
  * These types define the step-based workflow format extracted by the inspector
  */
 import type { WorkflowRun } from '../workflow.types.js';
+import type { UserFlowActor } from '../../../services/user-flow-actors-service.js';
 /**
  * Workflow step options
  */
@@ -13,6 +14,23 @@ export interface WorkflowStepOptions {
     retries?: number;
     /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
     retryDelay?: string | number;
+    /**
+     * Run this step as an actor (user flows). The RPC is sent through the
+     * actor's authenticated client over the REAL transport — never dispatched
+     * internally — so auth middleware and permissions are exercised end-to-end.
+     * The step is recorded durably like any RPC step.
+     */
+    actor?: UserFlowActor;
+}
+/**
+ * Options for workflow.expectEventually() — a durable polling step used by
+ * user flows to await async effects (a notification landing, a job finishing).
+ */
+export interface WorkflowExpectEventuallyOptions extends WorkflowStepOptions {
+    /** Give up after this long (e.g. '30s'). Default '30s'. */
+    within?: string | number;
+    /** Poll interval (e.g. '1s'). Default '1s'. */
+    interval?: string | number;
 }
 /**
  * Type signature for workflow.do() RPC form - used by inspector
@@ -92,6 +110,10 @@ export interface RpcStepMeta {
     inputs?: Record<string, InputSource> | 'passthrough';
     /** Step options */
     options?: WorkflowStepOptions;
+    /** User-flow actor name this step runs as ({ actor: actors.x }) */
+    actor?: string;
+    /** True for workflow.expectEventually polling steps */
+    expectEventually?: boolean;
 }
 /**
  * Simple condition expression (leaf node)
@@ -317,6 +339,11 @@ export interface PikkuWorkflowWire {
     getRun: () => Promise<WorkflowRun>;
     /** Execute a workflow step (overloaded - RPC or inline form) */
     do: WorkflowWireDoRPC & WorkflowWireDoInline;
+    /**
+     * Durable polling step (user flows): invoke `rpcName` (as an actor when
+     * `options.as` is set) until `predicate` passes or `options.within` elapses.
+     */
+    expectEventually: <TOutput = any, TInput = any>(stepName: string, rpcName: string, data: TInput, predicate: (output: TOutput) => boolean, options?: WorkflowExpectEventuallyOptions) => Promise<TOutput>;
     /** Sleep for a duration */
     sleep: WorkflowWireSleep;
     /** Suspend workflow until explicitly resumed */

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,6 +1,7 @@
 import type { SerializedError } from '../../types/core.types.js';
 import type { PikkuWorkflowWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
+import type { UserFlowActors } from '../../services/user-flow-actors-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
 import type { JobOptions } from '../queue/queue.types.js';
@@ -81,6 +82,7 @@ export declare class WorkflowStepNameNotString extends Error {
  */
 export declare abstract class PikkuWorkflowService implements WorkflowService {
     private inlineRuns;
+    private runActors;
     protected get logger(): import("../../services/logger.js").Logger;
     protected mirror?: WorkflowRunMirror;
     constructor(options?: {
@@ -373,6 +375,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: any, options?: {
         inline?: boolean;
         startNode?: string;
+        actors?: UserFlowActors;
     }): Promise<{
         runId: string;
     }>;

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -160,6 +160,9 @@ const WORKFLOW_END_STATES = new Set([
  */
 export class PikkuWorkflowService {
     inlineRuns = new Set();
+    // User-flow actors per run: live authenticated clients (cookie jars) are
+    // process-local by nature, so they ride this map, never the persisted wire.
+    runActors = new Map();
     get logger() {
         return getSingletonServices()?.logger;
     }
@@ -638,6 +641,9 @@ export class PikkuWorkflowService {
             deterministic: workflowMeta.deterministic,
             plannedSteps: workflowMeta.plannedSteps,
         });
+        if (options?.actors) {
+            this.runActors.set(runId, options.actors);
+        }
         if (shouldInline) {
             this.inlineRuns.add(runId);
             try {
@@ -670,6 +676,7 @@ export class PikkuWorkflowService {
             }
             finally {
                 this.inlineRuns.delete(runId);
+                this.runActors.delete(runId);
             }
         }
         else {
@@ -795,8 +802,10 @@ export class PikkuWorkflowService {
             const wire = {
                 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('workflow', workflowMeta.name, workflowMeta.pikkuFuncId, {
@@ -1101,6 +1110,7 @@ export class PikkuWorkflowService {
         const resolvedStepOptions = {
             retries: stepOptions?.retries ?? DEFAULT_STEP_RETRIES,
             retryDelay: stepOptions?.retryDelay,
+            actor: stepOptions?.actor,
         };
         // Check if step already exists
         let stepState;
@@ -1136,7 +1146,11 @@ export class PikkuWorkflowService {
         // 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);
@@ -1146,6 +1160,12 @@ export class PikkuWorkflowService {
         const retries = resolvedStepOptions.retries ?? this.getConfig().retries;
         const retryDelay = resolvedStepOptions.retryDelay;
         return this.runInlineRetryLoop(stepState, 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) {
@@ -1339,6 +1359,34 @@ export class PikkuWorkflowService {
                     return await this.inlineStep(runId, stepName, rpcNameOrFn, dataOrOptions);
                 }
             },
+            // 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, rpcName, data, predicate, options) => {
+                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;
+                    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, duration) => {
                 this.verifyStepName(stepName);

package/dist/wirings/workflow/workflow.types.d.ts

@@ -1,7 +1,7 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;
@@ -236,6 +236,10 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     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[];
 }>;
 /**
  * Unified workflow runtime meta (used by runtime to execute workflows)
@@ -247,12 +251,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) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.47",
+  "version": "0.12.50",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",