@pikku/core 0.12.50 → 0.12.52

package/src/services/http-scenario-actors-converse.test.ts

@@ -0,0 +1,222 @@
+import { describe, test, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer, type Server } from 'node:http'
+
+import { createHttpScenarioActors } from './http-scenario-actors.js'
+import { pikkuState, resetPikkuState } from '../pikku-state.js'
+import type { AIAgentStepResult } from './ai-agent-runner-service.js'
+
+/**
+ * Minimal target app exposing the agent HTTP surface: actor sign-in, the agent
+ * run route (suspends once for approval, then completes), and the batch approve
+ * route (records the decisions). `authRequired` toggles whether the agent
+ * routes reject unauthenticated calls with 401 (to exercise lazy sign-in).
+ */
+const startAgentTarget = async () => {
+  let agentRuns = 0
+  let logins = 0
+  let authRequired = false
+  let approvalsSeen: unknown[] = []
+  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())
+        : {}
+      const json = (obj: unknown) =>
+        res
+          .writeHead(200, { 'content-type': 'application/json' })
+          .end(JSON.stringify(obj))
+
+      if (req.url === '/api/auth/sign-in/actor') {
+        logins++
+        res.setHeader('set-cookie', ['session=s1; Path=/; HttpOnly'])
+        json({ ok: true })
+        return
+      }
+
+      const isAgentRoute = req.url?.startsWith('/api/rpc/agent/')
+      if (
+        isAgentRoute &&
+        authRequired &&
+        !(req.headers.cookie ?? '').includes('session=')
+      ) {
+        res.writeHead(401).end()
+        return
+      }
+
+      if (req.url === '/api/rpc/agent/todoBot/approve') {
+        approvalsSeen.push(body.approvals)
+        json({ runId: body.runId, text: 'Created it.', status: 'completed' })
+        return
+      }
+      if (req.url === '/api/rpc/agent/todoBot') {
+        agentRuns++
+        if (agentRuns === 1) {
+          json({
+            runId: 'run-1',
+            text: 'Let me do that.',
+            status: 'suspended',
+            pendingApprovals: [
+              {
+                toolCallId: 'tc1',
+                toolName: 'createTodo',
+                args: { title: 'x' },
+              },
+            ],
+          })
+          return
+        }
+        json({
+          runId: `run-${agentRuns}`,
+          text: 'All set.',
+          status: 'completed',
+        })
+        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,
+    approvalsSeen: () => approvalsSeen,
+    reset: (opts?: { authRequired?: boolean }) => {
+      agentRuns = 0
+      logins = 0
+      approvalsSeen = []
+      authRequired = opts?.authRequired ?? false
+    },
+  }
+}
+
+/** Persona LLM scripted by the outputSchema it's asked for. */
+const scriptedRunner = () => {
+  let turn = 0
+  const turns = [
+    { message: 'please make a todo', done: false },
+    { message: 'thanks', done: true },
+  ]
+  return {
+    run: async (params: {
+      outputSchema?: unknown
+    }): Promise<AIAgentStepResult> => {
+      const props =
+        (params.outputSchema as { properties?: Record<string, unknown> })
+          ?.properties ?? {}
+      const object =
+        'message' in props
+          ? (turns[turn++] ?? turns[turns.length - 1])
+          : 'decisions' in props
+            ? { decisions: [{ toolCallId: 'tc1', approved: true }] }
+            : { passed: true, reasoning: 'a todo was created' }
+      return {
+        text: '',
+        object,
+        toolCalls: [],
+        toolResults: [],
+        usage: { inputTokens: 0, outputTokens: 0 },
+        finishReason: 'stop',
+      }
+    },
+  }
+}
+
+const wireRunner = () => {
+  resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+    aiAgentRunner: scriptedRunner(),
+  } as any)
+}
+
+describe('HttpScenarioActor.converse', async () => {
+  const target = await startAgentTarget()
+  after(() => {
+    target.server.close()
+    resetPikkuState()
+  })
+
+  test('converses over HTTP, approves in-persona, returns a verdict', async () => {
+    wireRunner()
+    target.reset()
+
+    const actors = createHttpScenarioActors({
+      apiUrl: target.apiUrl,
+      secret: 'impersonation-secret',
+      model: 'test/test-model',
+      actors: {
+        pm: { email: 'pm@actors.local', name: 'Priya', personality: 'concise' },
+      },
+    })
+
+    const verdict = await actors.pm!.converse({
+      agent: 'todoBot',
+      task: 'Get a todo created for the launch',
+      evaluate: 'A todo about the launch now exists',
+    })
+
+    assert.equal(verdict.passed, true)
+    assert.match(verdict.reasoning, /todo/i)
+    // The target's approval was answered in-persona (approved) over HTTP.
+    assert.deepEqual(target.approvalsSeen(), [
+      [{ toolCallId: 'tc1', approved: true }],
+    ])
+    // No-auth agent → converse never signs in (lazy login).
+    assert.equal(target.loginCount(), 0)
+  })
+
+  test('signs in lazily and retries once when an agent route returns 401', async () => {
+    wireRunner()
+    target.reset({ authRequired: true })
+
+    const actors = createHttpScenarioActors({
+      apiUrl: target.apiUrl,
+      secret: 'impersonation-secret',
+      model: 'test/test-model',
+      actors: { pm: { email: 'pm@actors.local' } },
+    })
+
+    const verdict = await actors.pm!.converse({
+      agent: 'todoBot',
+      task: 'make a todo',
+      evaluate: 'a todo exists',
+    })
+
+    assert.equal(verdict.passed, true)
+    // 401 on the first (unauthenticated) call → one sign-in, then cached.
+    assert.equal(target.loginCount(), 1)
+  })
+
+  test('throws when no AI provider is configured', async () => {
+    resetPikkuState()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+    } as any)
+
+    const actors = createHttpScenarioActors({
+      apiUrl: target.apiUrl,
+      secret: 'impersonation-secret',
+      model: 'test/test-model',
+      actors: { pm: { email: 'pm@actors.local' } },
+    })
+
+    await assert.rejects(
+      actors.pm!.converse({ agent: 'todoBot', task: 't', evaluate: 'e' })
+    )
+  })
+})

package/src/services/{http-user-flow-actors.test.ts → http-scenario-actors.test.ts}

@@ -2,7 +2,7 @@ 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'
+import { createHttpScenarioActors } from './http-scenario-actors.js'
 
 // Minimal target app: actor sign-in endpoint + exposed RPC endpoint, session
 // via cookie. Mirrors the Better Auth actor plugin's contract.
@@ -13,10 +13,14 @@ const startTarget = async () => {
     const chunks: Buffer[] = []
     req.on('data', (c) => chunks.push(c))
     req.on('end', () => {
-      const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) : {}
+      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' }))
+          res
+            .writeHead(401)
+            .end(JSON.stringify({ message: 'bad actor secret' }))
           return
         }
         logins++
@@ -58,12 +62,12 @@ const startTarget = async () => {
   }
 }
 
-describe('HttpUserFlowActor', async () => {
+describe('HttpScenarioActor', async () => {
   const target = await startTarget()
   after(() => target.server.close())
 
   const makeActors = (secret = 'impersonation-secret') =>
-    createHttpUserFlowActors({
+    createHttpScenarioActors({
       apiUrl: target.apiUrl,
       secret,
       actors: {
@@ -82,14 +86,20 @@ describe('HttpUserFlowActor', async () => {
   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 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.match(
+      second.cookie,
+      /session=s1/,
+      'session is cached, not re-minted'
+    )
     assert.equal(target.loginCount(), 1)
   })
 

package/src/services/http-scenario-actors.ts

@@ -0,0 +1,269 @@
+import type {
+  ScenarioActor,
+  ScenarioActorConfig,
+  ScenarioActors,
+} from './scenario-actors-service.js'
+import type {
+  ConverseOptions,
+  ActorFlowVerdict,
+  TargetAgentReply,
+} from '../wirings/actor-flow/actor-flow.types.js'
+import { runConversation } from '../wirings/actor-flow/run-conversation.js'
+import { getSingletonServices } from '../pikku-state.js'
+import { AIProviderNotConfiguredError } from '../errors/errors.js'
+
+export interface HttpScenarioActorsConfig {
+  /**
+   * 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, ScenarioActorConfig>
+  /** 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 model the persona uses when `actor.converse(...)` is called without
+   * an explicit `model`. The persona's own turns/approvals/evaluation run
+   * in-process via the configured `aiAgentRunner`.
+   */
+  model?: 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 HttpScenarioActor implements ScenarioActor {
+  private cookie: string | null = null
+  private origin: string
+
+  constructor(
+    readonly name: string,
+    private actorConfig: ScenarioActorConfig,
+    private config: HttpScenarioActorsConfig
+  ) {
+    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)
+  }
+
+  async converse(options: ConverseOptions): Promise<ActorFlowVerdict> {
+    const { aiAgentRunner } = getSingletonServices()
+    if (!aiAgentRunner) {
+      throw new AIProviderNotConfiguredError()
+    }
+    const model = options.model ?? this.config.model
+    if (!model) {
+      throw new Error(
+        `[scenario] actor '${this.name}' converse needs a model — pass options.model or set 'model' on the actors service`
+      )
+    }
+    const threadId = globalThis.crypto.randomUUID()
+    const resourceId = `actor:${this.name}`
+
+    return runConversation({
+      persona: this.actorConfig,
+      personaName: this.actorConfig.name ?? this.name,
+      agentName: options.agent,
+      task: options.task,
+      evaluate: options.evaluate,
+      approvals: options.approvals,
+      model,
+      maxTurns: options.maxTurns,
+      llm: (params) => aiAgentRunner.run(params),
+      target: {
+        run: (message) =>
+          this.agentRun(options.agent, message, threadId, resourceId),
+        approve: (runId, decisions) =>
+          this.agentApprove(options.agent, runId, decisions),
+      },
+    })
+  }
+
+  /** Start/continue the target agent's run over HTTP as this actor. */
+  private async agentRun(
+    agentName: string,
+    message: string,
+    threadId: string,
+    resourceId: string
+  ): Promise<TargetAgentReply> {
+    const raw = await this.postAgent(`agent/${agentName}`, {
+      message,
+      threadId,
+      resourceId,
+    })
+    return normalizeAgentReply(raw)
+  }
+
+  /** Answer the target agent's pending approvals over HTTP and continue. */
+  private async agentApprove(
+    agentName: string,
+    runId: string,
+    decisions: { toolCallId: string; approved: boolean }[]
+  ): Promise<TargetAgentReply> {
+    const raw = await this.postAgent(`agent/${agentName}/approve`, {
+      runId,
+      approvals: decisions,
+    })
+    return normalizeAgentReply(raw)
+  }
+
+  /**
+   * POST an agent HTTP route (raw body, not RPC-wrapped). Signs in lazily: the
+   * first call goes out with whatever cookie we hold (none, for a no-auth
+   * agent), and only a 401 triggers `login()` + one retry. This lets an actor
+   * converse with a no-auth agent without any sign-in wiring, while still
+   * authenticating against agents that require a session.
+   */
+  private async postAgent(subPath: string, body: unknown): Promise<unknown> {
+    const rpcPath = this.config.rpcPath ?? '/rpc'
+    const url = `${this.config.apiUrl}${rpcPath}/${subPath}`
+    const send = (cookie: string | null) =>
+      fetch(url, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          origin: this.origin,
+          ...(cookie ? { cookie } : {}),
+        },
+        body: JSON.stringify(body),
+      })
+
+    let res = await send(this.cookie)
+    if (res.status === 401) {
+      this.cookie = null
+      res = await send(await this.login())
+    }
+    if (!res.ok) {
+      const text = (await res.text().catch(() => '')).slice(0, 300)
+      throw new Error(
+        `[scenario] agent call '${subPath}' as '${this.name}' returned ${res.status}: ${text}`
+      )
+    }
+    if (res.status === 204) return undefined
+    const text = await res.text()
+    return text ? JSON.parse(text) : undefined
+  }
+
+  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(
+        `[scenario] '${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(
+        `[scenario] 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(
+        `[scenario] actor sign-in for '${this.name}' returned no session cookie`
+      )
+    }
+    this.cookie = cookie
+    return cookie
+  }
+}
+
+/** Normalize an agentRun/agentApprove HTTP response into a TargetAgentReply. */
+function normalizeAgentReply(raw: unknown): TargetAgentReply {
+  const r = (raw ?? {}) as Record<string, unknown>
+  const pending = Array.isArray(r.pendingApprovals)
+    ? (r.pendingApprovals as Array<Record<string, unknown>>).map((p) => ({
+        toolCallId: String(p.toolCallId),
+        toolName: String(p.toolName),
+        args: p.args,
+        reason: typeof p.reason === 'string' ? p.reason : undefined,
+      }))
+    : undefined
+  return {
+    text: typeof r.text === 'string' ? r.text : '',
+    runId: typeof r.runId === 'string' ? r.runId : '',
+    status:
+      r.status === 'completed' || r.status === 'suspended'
+        ? r.status
+        : undefined,
+    pendingApprovals: pending,
+  }
+}
+
+/**
+ * Build the injected `actors` service from the config registry: actor name →
+ * lazy HTTP actor. Wire the result as the `actors` singleton service.
+ */
+export function createHttpScenarioActors(
+  config: HttpScenarioActorsConfig
+): ScenarioActors {
+  const actors: ScenarioActors = {}
+  for (const [name, actorConfig] of Object.entries(config.actors)) {
+    actors[name] = new HttpScenarioActor(name, actorConfig, config)
+  }
+  return actors
+}

package/src/services/index.ts

@@ -37,15 +37,15 @@ export type {
   CopyFileArgs,
 } from './content-service.js'
 export type {
-  UserFlowActor,
-  UserFlowActorConfig,
-  UserFlowActors,
-} from './user-flow-actors-service.js'
+  ScenarioActor,
+  ScenarioActorConfig,
+  ScenarioActors,
+} from './scenario-actors-service.js'
 export {
-  HttpUserFlowActor,
-  createHttpUserFlowActors,
-  type HttpUserFlowActorsConfig,
-} from './http-user-flow-actors.js'
+  HttpScenarioActor,
+  createHttpScenarioActors,
+  type HttpScenarioActorsConfig,
+} from './http-scenario-actors.js'
 export type { JWTService } from './jwt-service.js'
 export type {
   EmailService,

package/src/services/meta-service.ts

@@ -12,7 +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 { ScenarioActorConfig } from './scenario-actors-service.js'
 import type {
   TriggerMeta,
   TriggerSourceMeta,
@@ -171,7 +171,7 @@ export interface MetaService {
   getGatewayMeta(): Promise<GatewaysMeta>
   getRpcMeta(): Promise<RPCMetaRecord>
   getWorkflowMeta(): Promise<WorkflowsMeta>
-  getUserFlowActorsMeta(): Promise<Record<string, UserFlowActorConfig>>
+  getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>>
   getTriggerMeta(): Promise<TriggerMeta>
   getTriggerSourceMeta(): Promise<TriggerSourceMeta>
   getFunctionsMeta(): Promise<FunctionsMeta>
@@ -210,7 +210,7 @@ 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 =
+  private scenarioActorsMetaCache: Record<string, ScenarioActorConfig> | null =
     null
   private triggerMetaCache: TriggerMeta | null = null
   private triggerSourceMetaCache: TriggerSourceMeta | null = null
@@ -262,7 +262,7 @@ export class LocalMetaService implements MetaService {
     this.gatewayMetaCache = null
     this.rpcMetaCache = null
     this.workflowMetaCache = null
-    this.userFlowActorsMetaCache = null
+    this.scenarioActorsMetaCache = null
     this.triggerMetaCache = null
     this.triggerSourceMetaCache = null
     this.functionsMetaCache = null
@@ -429,12 +429,12 @@ export class LocalMetaService implements MetaService {
     }
   }
 
-  async getUserFlowActorsMeta(): Promise<Record<string, UserFlowActorConfig>> {
-    if (this.userFlowActorsMetaCache) return this.userFlowActorsMetaCache
+  async getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>> {
+    if (this.scenarioActorsMetaCache) return this.scenarioActorsMetaCache
 
-    const content = await this.readFile('workflow/user-flow-actors.gen.json')
-    this.userFlowActorsMetaCache = content ? JSON.parse(content) : {}
-    return this.userFlowActorsMetaCache!
+    const content = await this.readFile('workflow/scenario-actors.gen.json')
+    this.scenarioActorsMetaCache = content ? JSON.parse(content) : {}
+    return this.scenarioActorsMetaCache!
   }
 
   async getTriggerMeta(): Promise<TriggerMeta> {

package/src/services/{user-flow-actors-service.ts → scenario-actors-service.ts}

@@ -1,18 +1,32 @@
+import type {
+  ConverseOptions,
+  ActorFlowVerdict,
+} from '../wirings/actor-flow/actor-flow.types.js'
+
 /**
- * A user-flow actor: a synthetic user (a normal user row flagged `actor`) that
+ * A scenario 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 {
+export interface ScenarioActor<TAgentName extends string = string> {
   /** 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>
+  /**
+   * Hold a dynamic conversation with a target Pikku AI agent, in THIS actor's
+   * persona (personality/jobTitle). Drives the target over the real transport
+   * as the signed-in actor, answers its tool-approval requests in-persona, and
+   * returns the actor's verdict on whether the task was met. Deterministic
+   * checks are the caller's job — use `invoke` afterwards. In a typed project
+   * `agent` is constrained to the generated union of agent names.
+   */
+  converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>
 }
 
 /**
@@ -20,7 +34,7 @@ export interface UserFlowActor {
  * 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 {
+export interface ScenarioActorConfig {
   email: string
   name?: string
   jobTitle?: string
@@ -28,4 +42,4 @@ export interface UserFlowActorConfig {
 }
 
 /** The injected `actors` service: actor name → actor. */
-export type UserFlowActors = Record<string, UserFlowActor>
+export type ScenarioActors = Record<string, ScenarioActor>