@pikku/core 0.12.47 → 0.12.50

package/src/services/http-user-flow-actors.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer, type Server } from 'node:http'
+
+import { createHttpUserFlowActors } from './http-user-flow-actors.js'
+
+// Minimal target app: actor sign-in endpoint + exposed RPC endpoint, session
+// via cookie. Mirrors the Better Auth actor plugin's contract.
+const startTarget = async () => {
+  let logins = 0
+  let expireNext = false
+  const server: Server = createServer((req, res) => {
+    const chunks: Buffer[] = []
+    req.on('data', (c) => chunks.push(c))
+    req.on('end', () => {
+      const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) : {}
+      if (req.url === '/api/auth/sign-in/actor') {
+        if (body.secret !== 'impersonation-secret') {
+          res.writeHead(401).end(JSON.stringify({ message: 'bad actor secret' }))
+          return
+        }
+        logins++
+        res.setHeader('set-cookie', [
+          `session=s${logins}; Path=/; HttpOnly`,
+          `csrf=c${logins}; Path=/`,
+        ])
+        res.writeHead(200).end(JSON.stringify({ ok: true, email: body.email }))
+        return
+      }
+      if (req.url?.startsWith('/api/rpc/')) {
+        const cookie = req.headers.cookie ?? ''
+        if (!cookie.includes('session=') || expireNext) {
+          expireNext = false
+          res.writeHead(401).end()
+          return
+        }
+        res.writeHead(200, { 'content-type': 'application/json' }).end(
+          JSON.stringify({
+            rpcName: req.url.slice('/api/rpc/'.length),
+            echoed: body.data,
+            cookie,
+          })
+        )
+        return
+      }
+      res.writeHead(404).end()
+    })
+  })
+  await new Promise<void>((resolve) => server.listen(0, resolve))
+  const { port } = server.address() as { port: number }
+  return {
+    server,
+    apiUrl: `http://127.0.0.1:${port}/api`,
+    loginCount: () => logins,
+    expireSession: () => {
+      expireNext = true
+    },
+  }
+}
+
+describe('HttpUserFlowActor', async () => {
+  const target = await startTarget()
+  after(() => target.server.close())
+
+  const makeActors = (secret = 'impersonation-secret') =>
+    createHttpUserFlowActors({
+      apiUrl: target.apiUrl,
+      secret,
+      actors: {
+        customer: { email: 'customer@actors.local', jobTitle: 'Buyer' },
+        manager: { email: 'manager@actors.local' },
+      },
+    })
+
+  test('builds one lazy actor per config entry', () => {
+    const actors = makeActors()
+    assert.deepEqual(Object.keys(actors).sort(), ['customer', 'manager'])
+    assert.equal(actors.customer!.name, 'customer')
+    assert.equal(target.loginCount(), 0, 'no login until first invoke')
+  })
+
+  test('logs in lazily once and replays the session cookie on RPCs', async () => {
+    const actors = makeActors()
+
+    const first = (await actors.customer!.invoke('createTodo', { title: 'x' })) as any
+    const second = (await actors.customer!.invoke('listTodos', {})) as any
+
+    assert.equal(first.rpcName, 'createTodo')
+    assert.deepEqual(first.echoed, { title: 'x' })
+    assert.match(first.cookie, /session=s1/)
+    assert.match(first.cookie, /csrf=c1/)
+    assert.match(second.cookie, /session=s1/, 'session is cached, not re-minted')
+    assert.equal(target.loginCount(), 1)
+  })
+
+  test('re-logs-in once when the session expires mid-run', async () => {
+    const actors = makeActors()
+    await actors.manager!.invoke('ping', {})
+    const loginsBefore = target.loginCount()
+
+    target.expireSession()
+    const result = (await actors.manager!.invoke('ping', {})) as any
+
+    assert.equal(target.loginCount(), loginsBefore + 1, 'one re-login')
+    assert.match(result.cookie, new RegExp(`session=s${loginsBefore + 1}`))
+  })
+
+  test('a wrong impersonation secret surfaces status and body', async () => {
+    const actors = makeActors('wrong-secret')
+    await assert.rejects(
+      actors.customer!.invoke('ping', {}),
+      /actor sign-in failed for 'customer' \(401\).*bad actor secret/
+    )
+  })
+})

package/src/services/http-user-flow-actors.ts

@@ -0,0 +1,132 @@
+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 class HttpUserFlowActor implements UserFlowActor {
+  private cookie: string | null = null
+  private origin: string
+
+  constructor(
+    readonly name: string,
+    private actorConfig: UserFlowActorConfig,
+    private config: HttpUserFlowActorsConfig
+  ) {
+    this.origin = new URL(config.apiUrl).origin
+  }
+
+  get email(): string {
+    return this.actorConfig.email
+  }
+
+  async invoke(rpcName: string, data: unknown): Promise<unknown> {
+    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)
+  }
+
+  private async postRpc(rpcName: string, data: unknown, cookie: string) {
+    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 }),
+    })
+  }
+
+  private async readRpcResponse(rpcName: string, res: Response) {
+    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
+  }
+
+  private async login(): Promise<string> {
+    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: HttpUserFlowActorsConfig
+): UserFlowActors {
+  const actors: UserFlowActors = {}
+  for (const [name, actorConfig] of Object.entries(config.actors)) {
+    actors[name] = new HttpUserFlowActor(name, actorConfig, config)
+  }
+  return actors
+}

package/src/services/index.ts

@@ -36,6 +36,16 @@ export type {
   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,

package/src/services/meta-service.ts

@@ -12,6 +12,7 @@ import type {
   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,
@@ -170,6 +171,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>
@@ -208,6 +210,8 @@ export class LocalMetaService implements MetaService {
   private gatewayMetaCache: GatewaysMeta | null = null
   private rpcMetaCache: RPCMetaRecord | null = null
   private workflowMetaCache: WorkflowsMeta | null = null
+  private userFlowActorsMetaCache: Record<string, UserFlowActorConfig> | null =
+    null
   private triggerMetaCache: TriggerMeta | null = null
   private triggerSourceMetaCache: TriggerSourceMeta | null = null
   private functionsMetaCache: FunctionsMeta | null = null
@@ -258,6 +262,7 @@ export class LocalMetaService implements MetaService {
     this.gatewayMetaCache = null
     this.rpcMetaCache = null
     this.workflowMetaCache = null
+    this.userFlowActorsMetaCache = null
     this.triggerMetaCache = null
     this.triggerSourceMetaCache = null
     this.functionsMetaCache = null
@@ -424,6 +429,14 @@ export class LocalMetaService implements MetaService {
     }
   }
 
+  async getUserFlowActorsMeta(): Promise<Record<string, UserFlowActorConfig>> {
+    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(): Promise<TriggerMeta> {
     if (this.triggerMetaCache) return this.triggerMetaCache
 

package/src/services/user-flow-actors-service.ts

@@ -0,0 +1,31 @@
+/**
+ * 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/src/types/core.types.ts

@@ -29,6 +29,7 @@ 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'
@@ -243,6 +244,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
 }
 
 /**
@@ -336,6 +339,8 @@ export type PikkuWire<
   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/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -4,6 +4,7 @@
  */
 
 import type { WorkflowRun } from '../workflow.types.js'
+import type { UserFlowActor } from '../../../services/user-flow-actors-service.js'
 
 /**
  * Workflow step options
@@ -15,9 +16,27 @@ 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
   // Future: timeout, failFast, priority
 }
 
+/**
+ * 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
  */
@@ -90,6 +109,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
 }
 
 /**
@@ -346,6 +369,18 @@ export interface PikkuWorkflowWire {
   /** 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
 

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)