@pikku/core 0.12.51 → 0.12.52

package/CHANGELOG.md

@@ -1,3 +1,62 @@
+## 0.12.52
+
+### Patch Changes
+
+- 61c9ce9: Add `actor.converse(...)` — actor agents for user journeys (#850)
+
+  An actor can now hold a dynamic, LLM-driven conversation with a target Pikku AI
+  agent in its own persona:
+
+  ```ts
+  const verdict = await actors.pm.converse({
+    agent: 'todoBot',
+    task: 'Get a todo created for the launch',
+    evaluate: 'A todo about the launch now exists',
+  })
+  // verdict: { passed, reasoning, transcript }
+  // then assert deterministically as the same actor:
+  const todos = await actors.pm.invoke('listTodos', {})
+  ```
+
+  The actor drives the target over the real transport (the agent's own
+  `agentRun` / `agentApprove` HTTP routes, signed in as the actor), plays the
+  persona from its `pikku.config.json` config, answers the agent's tool-approval
+  requests in-persona (`approvals: 'in-persona' | 'always' | 'never'`), and
+  returns its verdict on whether the task was met. Deterministic checks stay the
+  caller's job — they already hold the actor.
+
+  The conversation engine is transport-agnostic (persona LLM + injected target
+  driver); the persona's own turns run in-process via the configured
+  `aiAgentRunner` (`model` from the call or the actors-service default).
+
+  `agent` is typed against the generated agent-name union (`keyof AgentMap`), so
+  it's author-time checked and autocompleted in a typed project.
+
+- f1f39f8: Bound the actor-flow approval loop (#850)
+
+  `converseWithTarget` now caps suspend→approve rounds within a single target turn
+  (default 16, override via `maxApprovalRounds`). A cooperative target completes
+  after a handful of rounds; a buggy or uncooperative one — e.g. re-requesting a
+  tool the persona keeps denying — previously could spin the inner loop forever
+  without ever spending a `maxTurns` credit. Exceeding the cap now throws instead
+  of hanging.
+
+- c45e98d: Run user flows from the console, actors and all (#850)
+
+  Starting a `user-flow` workflow without explicit run actors (as the console's
+  Run button does) now auto-builds HTTP actors from `USER_FLOW_ACTOR_SECRET` and
+  `API_URL`: each actor signs in via the actor auth plugin — which mints the
+  `actor: true` user row on first sign-in — and drives its steps over HTTP as
+  that persona. When the secret or API base URL isn't configured the run simply
+  proceeds without actors (with a warning) instead of failing.
+
+  The workflow-detail view also gains the shared console header: the workflow
+  selector and the "complex workflow" note now live in the header bar, the right
+  details panel hides when it has nothing to show, and step nodes display their
+  DSL labels (e.g. `Double ${item}`).
+
+- 472a349: Rename the userflow concept to scenario (#862). `pikkuUserFlow` becomes `pikkuScenario`, `pikku userflow run/list` becomes `pikku scenario run/list`, the workflow meta flag `userFlow` becomes `scenario`, actor types are now `ScenarioActor`/`ScenarioActors`/`ScenarioActorConfig` (`createHttpScenarioActors`), pikku.config.json's `userFlows` key becomes `scenarios`, the generated actors file is `pikku-scenario-actors.gen.ts` (`createScenarioActors`), the actor sign-in secret env var is `SCENARIO_ACTOR_SECRET`, and the console's User Flows view is now Scenarios.
+
 ## 0.12.51
 
 ### Patch Changes

package/dist/services/http-scenario-actors.d.ts

@@ -0,0 +1,67 @@
+import type { ScenarioActor, ScenarioActorConfig, ScenarioActors } from './scenario-actors-service.js';
+import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.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 declare class HttpScenarioActor implements ScenarioActor {
+    readonly name: string;
+    private actorConfig;
+    private config;
+    private cookie;
+    private origin;
+    constructor(name: string, actorConfig: ScenarioActorConfig, config: HttpScenarioActorsConfig);
+    get email(): string;
+    invoke(rpcName: string, data: unknown): Promise<unknown>;
+    converse(options: ConverseOptions): Promise<ActorFlowVerdict>;
+    /** Start/continue the target agent's run over HTTP as this actor. */
+    private agentRun;
+    /** Answer the target agent's pending approvals over HTTP and continue. */
+    private agentApprove;
+    /**
+     * 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 postAgent;
+    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 createHttpScenarioActors(config: HttpScenarioActorsConfig): ScenarioActors;

package/dist/services/http-scenario-actors.js

@@ -0,0 +1,193 @@
+import { runConversation } from '../wirings/actor-flow/run-conversation.js';
+import { getSingletonServices } from '../pikku-state.js';
+import { AIProviderNotConfiguredError } from '../errors/errors.js';
+/**
+ * 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 {
+    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 converse(options) {
+        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. */
+    async agentRun(agentName, message, threadId, resourceId) {
+        const raw = await this.postAgent(`agent/${agentName}`, {
+            message,
+            threadId,
+            resourceId,
+        });
+        return normalizeAgentReply(raw);
+    }
+    /** Answer the target agent's pending approvals over HTTP and continue. */
+    async agentApprove(agentName, runId, decisions) {
+        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.
+     */
+    async postAgent(subPath, body) {
+        const rpcPath = this.config.rpcPath ?? '/rpc';
+        const url = `${this.config.apiUrl}${rpcPath}/${subPath}`;
+        const send = (cookie) => 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;
+    }
+    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(`[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;
+    }
+    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(`[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) {
+    const r = (raw ?? {});
+    const pending = Array.isArray(r.pendingApprovals)
+        ? r.pendingApprovals.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) {
+    const actors = {};
+    for (const [name, actorConfig] of Object.entries(config.actors)) {
+        actors[name] = new HttpScenarioActor(name, actorConfig, config);
+    }
+    return actors;
+}

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

@@ -1,4 +1,5 @@
 import type { UserFlowActor, UserFlowActorConfig, UserFlowActors } from './user-flow-actors-service.js';
+import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
 export interface HttpUserFlowActorsConfig {
     /**
      * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
@@ -18,6 +19,12 @@ export interface HttpUserFlowActorsConfig {
     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
@@ -36,6 +43,19 @@ export declare class HttpUserFlowActor implements UserFlowActor {
     constructor(name: string, actorConfig: UserFlowActorConfig, config: HttpUserFlowActorsConfig);
     get email(): string;
     invoke(rpcName: string, data: unknown): Promise<unknown>;
+    converse(options: ConverseOptions): Promise<ActorFlowVerdict>;
+    /** Start/continue the target agent's run over HTTP as this actor. */
+    private agentRun;
+    /** Answer the target agent's pending approvals over HTTP and continue. */
+    private agentApprove;
+    /**
+     * 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 postAgent;
     private postRpc;
     private readRpcResponse;
     private login;

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

@@ -1,3 +1,6 @@
+import { runConversation } from '../wirings/actor-flow/run-conversation.js';
+import { getSingletonServices } from '../pikku-state.js';
+import { AIProviderNotConfiguredError } from '../errors/errors.js';
 /**
  * Default HTTP-backed actor. Signs in lazily on first invoke via the Better
  * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
@@ -31,6 +34,83 @@ export class HttpUserFlowActor {
         }
         return this.readRpcResponse(rpcName, res);
     }
+    async converse(options) {
+        const { aiAgentRunner } = getSingletonServices();
+        if (!aiAgentRunner) {
+            throw new AIProviderNotConfiguredError();
+        }
+        const model = options.model ?? this.config.model;
+        if (!model) {
+            throw new Error(`[user-flow] 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. */
+    async agentRun(agentName, message, threadId, resourceId) {
+        const raw = await this.postAgent(`agent/${agentName}`, {
+            message,
+            threadId,
+            resourceId,
+        });
+        return normalizeAgentReply(raw);
+    }
+    /** Answer the target agent's pending approvals over HTTP and continue. */
+    async agentApprove(agentName, runId, decisions) {
+        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.
+     */
+    async postAgent(subPath, body) {
+        const rpcPath = this.config.rpcPath ?? '/rpc';
+        const url = `${this.config.apiUrl}${rpcPath}/${subPath}`;
+        const send = (cookie) => 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(`[user-flow] 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;
+    }
     async postRpc(rpcName, data, cookie) {
         const rpcPath = this.config.rpcPath ?? '/rpc';
         return fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
@@ -80,6 +160,26 @@ export class HttpUserFlowActor {
         return cookie;
     }
 }
+/** Normalize an agentRun/agentApprove HTTP response into a TargetAgentReply. */
+function normalizeAgentReply(raw) {
+    const r = (raw ?? {});
+    const pending = Array.isArray(r.pendingApprovals)
+        ? r.pendingApprovals.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.

package/dist/services/index.d.ts

@@ -18,8 +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 { ScenarioActor, ScenarioActorConfig, ScenarioActors, } from './scenario-actors-service.js';
+export { HttpScenarioActor, createHttpScenarioActors, type HttpScenarioActorsConfig, } from './http-scenario-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,7 +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 { HttpScenarioActor, createHttpScenarioActors, } from './http-scenario-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,7 +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 { ScenarioActorConfig } from './scenario-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';
@@ -141,7 +141,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>;
@@ -173,7 +173,7 @@ export declare class LocalMetaService implements MetaService {
     private gatewayMetaCache;
     private rpcMetaCache;
     private workflowMetaCache;
-    private userFlowActorsMetaCache;
+    private scenarioActorsMetaCache;
     private triggerMetaCache;
     private triggerSourceMetaCache;
     private functionsMetaCache;
@@ -200,7 +200,7 @@ export declare class LocalMetaService implements 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>;

package/dist/services/meta-service.js

@@ -15,7 +15,7 @@ export class LocalMetaService {
     gatewayMetaCache = null;
     rpcMetaCache = null;
     workflowMetaCache = null;
-    userFlowActorsMetaCache = null;
+    scenarioActorsMetaCache = null;
     triggerMetaCache = null;
     triggerSourceMetaCache = null;
     functionsMetaCache = null;
@@ -64,7 +64,7 @@ export class LocalMetaService {
         this.gatewayMetaCache = null;
         this.rpcMetaCache = null;
         this.workflowMetaCache = null;
-        this.userFlowActorsMetaCache = null;
+        this.scenarioActorsMetaCache = null;
         this.triggerMetaCache = null;
         this.triggerSourceMetaCache = null;
         this.functionsMetaCache = null;
@@ -203,12 +203,12 @@ 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 getScenarioActorsMeta() {
+        if (this.scenarioActorsMetaCache)
+            return this.scenarioActorsMetaCache;
+        const content = await this.readFile('workflow/scenario-actors.gen.json');
+        this.scenarioActorsMetaCache = content ? JSON.parse(content) : {};
+        return this.scenarioActorsMetaCache;
     }
     async getTriggerMeta() {
         if (this.triggerMetaCache)

package/dist/services/scenario-actors-service.d.ts

@@ -0,0 +1,39 @@
+import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
+/**
+ * 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 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>;
+}
+/**
+ * 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 ScenarioActorConfig {
+    email: string;
+    name?: string;
+    jobTitle?: string;
+    personality?: string;
+}
+/** The injected `actors` service: actor name → actor. */
+export type ScenarioActors = Record<string, ScenarioActor>;

package/dist/services/scenario-actors-service.js

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

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

@@ -1,3 +1,4 @@
+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
  * workflow steps can run as. Passed to `workflow.do(step, rpc, data, { actor })`
@@ -6,13 +7,22 @@
  * 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 UserFlowActor<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>;
 }
 /**
  * Display/config metadata for an actor (from pikku.config.json). The email