@pikku/core 0.12.141 → 0.12.142

package/dist/services/virtual-user-sign-in.d.ts

@@ -0,0 +1,52 @@
+import type { ResolvedVirtualUser } from './virtual-users-service.js';
+import type { ScenarioCookieJar } from './scenario-cookie-jar.js';
+/**
+ * How a virtual user obtains a session on the target. Both implementations end
+ * in the app's one virtual user sign-in handler; they differ in how they get
+ * there. See docs/virtual-user-sign-in.md.
+ */
+export interface VirtualUserSignIn {
+    /**
+     * Establish a session in `jar`. Throws on failure with a message naming the
+     * virtual user, since a run that continues unauthenticated fails later and
+     * somewhere less informative.
+     */
+    login(jar: ScenarioCookieJar, virtualUser: ResolvedVirtualUser): Promise<void>;
+}
+/**
+ * The auth mount a configured sign-in path sits under, or `undefined` when it
+ * names nothing recognisable.
+ *
+ * better-auth serves sign-in and `get-session` from one prefix, so an app that
+ * mounts it at `/api/auth` moves both together and says so once through
+ * `signInPath`. Reading `get-session` from a hardcoded `/auth` on such an app
+ * 404s, and a 404 reads as "this stage does not report roles", which silently
+ * turns off the check that tells a permissions finding from seed drift.
+ */
+export declare const authMount: (signInPath?: string) => string | undefined;
+/** Signs one statement naming `virtualUser`, for an audience the signer knows. */
+export type VirtualUserStatementMint = (virtualUser: ResolvedVirtualUser) => string | Promise<string>;
+export interface StatementSignInOptions {
+    apiUrl: string;
+    /** Default `/auth/sign-in/virtual-user`. */
+    signInPath?: string;
+    mint: VirtualUserStatementMint;
+}
+/**
+ * Sign in from outside the app by presenting a signed statement.
+ *
+ * A fresh statement is minted per login, because each is single-use: the re-login
+ * after a 401 must not replay the first.
+ */
+export declare const statementSignIn: ({ apiUrl, signInPath, mint, }: StatementSignInOptions) => VirtualUserSignIn;
+/** The part of an auth instance an in-process sign-in needs. */
+export interface InProcessAuth {
+    api: Record<string, any>;
+}
+/**
+ * Sign in from inside the app, with no credential: the code asking is the app.
+ *
+ * Calls the server-only endpoint through `auth.api`, which the HTTP router
+ * never serves, and takes the session cookie from the response.
+ */
+export declare const inProcessSignIn: (auth: InProcessAuth) => VirtualUserSignIn;

package/dist/services/virtual-user-sign-in.js

@@ -0,0 +1,80 @@
+import { PikkuError } from '../errors/error-handler.js';
+import { VIRTUAL_USER_IN_PROCESS_ENDPOINT } from './virtual-user-statement.js';
+/**
+ * A sign-in the target refused. `PikkuError`, not `Error`, so the CLI prints
+ * this message alone: a rejected statement or a virtual user the stage has never
+ * seen is something to go and fix, and a stack trace through the fetch internals
+ * only buries the status and the body that say which one it is.
+ */
+const failed = async (what, virtualUserId, res) => {
+    const body = (await res.text().catch(() => '')).slice(0, 300);
+    return new PikkuError(`[scenario] ${what} failed for '${virtualUserId}' (${res.status}): ${body}`);
+};
+/**
+ * The auth mount a configured sign-in path sits under, or `undefined` when it
+ * names nothing recognisable.
+ *
+ * better-auth serves sign-in and `get-session` from one prefix, so an app that
+ * mounts it at `/api/auth` moves both together and says so once through
+ * `signInPath`. Reading `get-session` from a hardcoded `/auth` on such an app
+ * 404s, and a 404 reads as "this stage does not report roles", which silently
+ * turns off the check that tells a permissions finding from seed drift.
+ */
+export const authMount = (signInPath) => {
+    const mount = signInPath ? signInPath.lastIndexOf('/sign-in/') : -1;
+    return !signInPath || mount === -1 ? undefined : signInPath.slice(0, mount);
+};
+/**
+ * Sign in from outside the app by presenting a signed statement.
+ *
+ * A fresh statement is minted per login, because each is single-use: the re-login
+ * after a 401 must not replay the first.
+ */
+export const statementSignIn = ({ apiUrl, signInPath = '/auth/sign-in/virtual-user', mint, }) => ({
+    async login(jar, virtualUser) {
+        const res = await jar.fetch(`${apiUrl}${signInPath}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ statement: await mint(virtualUser) }),
+        });
+        if (res.status === 404) {
+            throw new PikkuError(`[scenario] ${apiUrl}${signInPath} does not exist, so '${virtualUser.id}' cannot sign in. ` +
+                `The target has no VIRTUAL_USER_VERIFY_KEY set, or does not serve virtual user sign-in at all (production never does).`);
+        }
+        if (!res.ok) {
+            throw await failed('virtual user sign-in', virtualUser.id, res);
+        }
+        // What proves a session was established is this response setting a cookie,
+        // not the jar being non-empty: the target may have set one earlier.
+        if (res.headers.getSetCookie().length === 0) {
+            throw new PikkuError(`[scenario] virtual user sign-in for '${virtualUser.id}' returned no session cookie`);
+        }
+    },
+});
+/**
+ * Sign in from inside the app, with no credential: the code asking is the app.
+ *
+ * Calls the server-only endpoint through `auth.api`, which the HTTP router
+ * never serves, and takes the session cookie from the response.
+ */
+export const inProcessSignIn = (auth) => ({
+    async login(jar, virtualUser) {
+        const endpoint = auth.api[VIRTUAL_USER_IN_PROCESS_ENDPOINT];
+        if (typeof endpoint !== 'function') {
+            throw new PikkuError(`[scenario] '${virtualUser.id}' cannot sign in: the app's auth has no virtual user sign-in. ` +
+                `Add the pikkuVirtualUser plugin from @pikku/better-auth, and note it is only registered under pikku dev or the stage opt-in.`);
+        }
+        const res = await endpoint({
+            body: { email: virtualUser.email, name: virtualUser.name },
+            asResponse: true,
+        });
+        if (!res.ok) {
+            throw await failed('virtual user sign-in', virtualUser.id, res);
+        }
+        const cookies = res.headers.getSetCookie();
+        if (cookies.length === 0) {
+            throw new PikkuError(`[scenario] virtual user sign-in for '${virtualUser.id}' returned no session cookie`);
+        }
+        jar.absorb(cookies);
+    },
+});

package/dist/services/virtual-user-statement.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The signed statement an external caller presents to sign a virtual user in.
+ *
+ * An EdDSA (Ed25519) JWT: `sub` is the virtual user id, `aud` the app's
+ * audience, `exp` a few minutes out and `jti` a one-time id. The app can only
+ * verify one, against a public key; whoever deploys holds the private key.
+ */
+export declare const VIRTUAL_USER_STATEMENT_ALGORITHM = "EdDSA";
+/** How long a statement lives when its signer does not say. */
+export declare const VIRTUAL_USER_STATEMENT_TTL_SECONDS = 180;
+/** The longest a verifier accepts, whatever `exp` claims. */
+export declare const VIRTUAL_USER_STATEMENT_MAX_TTL_SECONDS = 300;
+/** The variable a stage carries its PUBLIC key in. Not `PIKKU_`/`PIKKUSTUDIO_`: a stage rejects those. */
+export declare const VIRTUAL_USER_VERIFY_KEY_VARIABLE = "VIRTUAL_USER_VERIFY_KEY";
+/** The variable whoever deploys holds the PRIVATE key in. Never set on a stage. */
+export declare const VIRTUAL_USER_SIGNING_KEY_VARIABLE = "VIRTUAL_USER_SIGNING_KEY";
+/** The key a run reaches the in-process sign-in under, on `auth.api`. */
+export declare const VIRTUAL_USER_IN_PROCESS_ENDPOINT = "signInVirtualUserInternal";
+export interface VirtualUserStatementVerifier {
+    /**
+     * Resolves to the virtual user the statement names. Throws
+     * {@link VirtualUserStatementError} for anything that is not a fresh,
+     * unreplayed statement for `audience` signed by the private half of the key.
+     */
+    verify(statement: string, audience: string): Promise<{
+        virtualUserId: string;
+    }>;
+}
+export declare class VirtualUserStatementError extends Error {
+    constructor(message: string);
+}

package/dist/services/virtual-user-statement.js

@@ -0,0 +1,24 @@
+/**
+ * The signed statement an external caller presents to sign a virtual user in.
+ *
+ * An EdDSA (Ed25519) JWT: `sub` is the virtual user id, `aud` the app's
+ * audience, `exp` a few minutes out and `jti` a one-time id. The app can only
+ * verify one, against a public key; whoever deploys holds the private key.
+ */
+export const VIRTUAL_USER_STATEMENT_ALGORITHM = 'EdDSA';
+/** How long a statement lives when its signer does not say. */
+export const VIRTUAL_USER_STATEMENT_TTL_SECONDS = 180;
+/** The longest a verifier accepts, whatever `exp` claims. */
+export const VIRTUAL_USER_STATEMENT_MAX_TTL_SECONDS = 300;
+/** The variable a stage carries its PUBLIC key in. Not `PIKKU_`/`PIKKUSTUDIO_`: a stage rejects those. */
+export const VIRTUAL_USER_VERIFY_KEY_VARIABLE = 'VIRTUAL_USER_VERIFY_KEY';
+/** The variable whoever deploys holds the PRIVATE key in. Never set on a stage. */
+export const VIRTUAL_USER_SIGNING_KEY_VARIABLE = 'VIRTUAL_USER_SIGNING_KEY';
+/** The key a run reaches the in-process sign-in under, on `auth.api`. */
+export const VIRTUAL_USER_IN_PROCESS_ENDPOINT = 'signInVirtualUserInternal';
+export class VirtualUserStatementError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VirtualUserStatementError';
+    }
+}

package/dist/services/{personas-service.d.ts → virtual-users-service.d.ts}

@@ -1,5 +1,5 @@
-import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
-import type { PersonaMeta } from '../wirings/persona/persona.types.js';
+import type { ConverseOptions, ConversationVerdict } from '../wirings/virtual-user/conversation/conversation.types.js';
+import type { VirtualUserMeta } from '../wirings/virtual-user/virtual-user-declaration.types.js';
 /**
  * What the transport answered, for a step that treats the status as data.
  *
@@ -30,8 +30,8 @@ export interface ScenarioHttpResponse<T = unknown> {
  * Drain a response into the shape a step can carry: the parsed body (an empty
  * one counting as no body at all) alongside the text it was parsed from.
  *
- * `invokeRaw` returns this, and a step that has to reach past a persona — a
- * route with no RPC, an identity no persona can hold — reaches for this rather
+ * `invokeRaw` returns this, and a step that has to reach past a virtual user — a
+ * route with no RPC, an identity no virtual user can hold — reaches for this rather
  * than writing the same record by hand.
  *
  * @example snippet: scenarioPolling
@@ -55,7 +55,7 @@ export interface ScenarioJsonRequest {
 /**
  * POST JSON somewhere and report what came back, without throwing on a 4xx/5xx.
  *
- * Every scenario that reaches past a persona was writing this by hand — the same
+ * Every scenario that reaches past a virtual user was writing this by hand — the same
  * `content-type`, the same `JSON.stringify`, the same drain — and the copies had
  * drifted: some returned `res.json()`, which loses the status and throws
  * outright when the target answers an empty body or an HTML error page. A
@@ -68,36 +68,38 @@ export declare const postScenarioJson: <T = unknown>(url: string, { body, header
 /** Per-call transport options. */
 export interface ScenarioInvokeOptions {
     /**
-     * Headers to send alongside the persona's own session. This is how a step
-     * expresses an identity no declared persona can — an impersonation header, or
+     * Headers to send alongside the virtual user's own session. This is how a step
+     * expresses an identity no declared virtual user can — an impersonation header, or
      * one of the header-shim principals a credential scenario invents.
      */
     headers?: Record<string, string>;
 }
 /**
- * The RPC surface a persona can reach, as name → input/output. A project binds
+ * The RPC surface a virtual user can reach, as name → input/output. A project binds
  * its generated exposed RPC map here; the default leaves every name open, which
- * is what a persona built by hand (or by a third-party driver) gets.
+ * is what a virtual user built by hand (or by a third-party driver) gets.
  */
 export type ScenarioRpcMap = Record<string, {
     input: any;
     output: any;
 }>;
 /**
- * The persona a step's `actor` slot carries, for a project whose personas are
- * known. No declared personas keeps the open type rather than collapsing to
+ * The virtual user a step's `virtualUser` slot carries, for a project whose virtual users are
+ * known. No declared virtual users keeps the open type rather than collapsing to
  * `never` — a project may still build one itself.
  */
-export type ScenarioPersonaOf<TPersonas> = [keyof TPersonas] extends [never] ? ScenarioPersona : TPersonas[keyof TPersonas];
+export type ScenarioVirtualUserOf<TVirtualUsers> = [
+    keyof TVirtualUsers
+] extends [never] ? ScenarioVirtualUser : TVirtualUsers[keyof TVirtualUsers];
 /**
  * A declared person, signed in and acting over the real transport.
  *
- * The runtime half of `definePersonas()`: sign-in materialises a user row
- * flagged `actor: true`, and everything a step or a virtual user does goes
+ * The runtime half of `defineVirtualUsers()`: sign-in materialises a user row
+ * flagged `virtualUser: true`, and everything a step or a virtual user does goes
  * through here.
  */
-export interface ScenarioPersona<TAgentName extends string = string, TRpcMap extends ScenarioRpcMap = ScenarioRpcMap> {
-    /** The id it was declared under — what a step's `actor` slot names. */
+export interface ScenarioVirtualUser<TAgentName extends string = string, TRpcMap extends ScenarioRpcMap = ScenarioRpcMap> {
+    /** The id it was declared under — what a step's `virtualUser` slot names. */
     readonly name: string;
     /** Their address, computed from the id. Flows use it for invites/lookups. */
     readonly email: string;
@@ -110,7 +112,7 @@ export interface ScenarioPersona<TAgentName extends string = string, TRpcMap ext
      */
     invokeRaw<TName extends keyof TRpcMap & string>(rpcName: TName, data: TRpcMap[TName]['input'], options?: ScenarioInvokeOptions): Promise<ScenarioHttpResponse>;
     /** Converse with a Pikku AI agent in character and return its verdict. */
-    converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>;
+    converse(options: ConverseOptions<TAgentName>): Promise<ConversationVerdict>;
     /**
      * The roles this person actually holds on the stage, read back after signing
      * in — what a run compares against the declaration before its first step.
@@ -123,16 +125,16 @@ export interface ScenarioPersona<TAgentName extends string = string, TRpcMap ext
     sessionRoles(): Promise<string[] | null>;
 }
 /**
- * A declared persona with its address filled in — what codegen writes and what
+ * A declared virtual user with its address filled in — what codegen writes and what
  * a seed, a scenario run and a virtual-user run all read.
  *
- * The address is not declared. It is derived from the persona's id and the
- * project's persona domain, so two people can never accidentally share one and
+ * The address is not declared. It is derived from the virtual user's id and the
+ * project's virtual user domain, so two people can never accidentally share one and
  * sign in as the same user row — which would silently collapse exactly the
  * isolation scenarios a second person exists for.
  */
-export type ResolvedPersona = PersonaMeta & {
+export type ResolvedVirtualUser = VirtualUserMeta & {
     email: string;
 };
-/** The injected `personas` service: persona id → persona. */
-export type ScenarioPersonas = Record<string, ScenarioPersona>;
+/** The injected `virtualUsers` service: virtual user id → virtual user. */
+export type ScenarioVirtualUsers = Record<string, ScenarioVirtualUser>;

package/dist/services/{personas-service.js → virtual-users-service.js}

@@ -2,8 +2,8 @@
  * Drain a response into the shape a step can carry: the parsed body (an empty
  * one counting as no body at all) alongside the text it was parsed from.
  *
- * `invokeRaw` returns this, and a step that has to reach past a persona — a
- * route with no RPC, an identity no persona can hold — reaches for this rather
+ * `invokeRaw` returns this, and a step that has to reach past a virtual user — a
+ * route with no RPC, an identity no virtual user can hold — reaches for this rather
  * than writing the same record by hand.
  *
  * @example snippet: scenarioPolling
@@ -28,7 +28,7 @@ const parseJsonBody = (text) => {
 /**
  * POST JSON somewhere and report what came back, without throwing on a 4xx/5xx.
  *
- * Every scenario that reaches past a persona was writing this by hand — the same
+ * Every scenario that reaches past a virtual user was writing this by hand — the same
  * `content-type`, the same `JSON.stringify`, the same drain — and the copies had
  * drifted: some returned `res.json()`, which loses the status and throws
  * outright when the target answers an empty body or an HTML error page. A

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

@@ -25,7 +25,7 @@ import type { SchedulerService } from '../services/scheduler-service.js';
 import type { DeploymentService } from '../services/deployment-service.js';
 import type { AgentStorageService } from '../services/agent-storage-service.js';
 import type { ContentService } from '../services/content-service.js';
-import type { ScenarioPersonaOf, ScenarioPersonas } from '../services/personas-service.js';
+import type { ScenarioVirtualUserOf, ScenarioVirtualUsers } from '../services/virtual-users-service.js';
 import type { AgentRunnerService } from '../services/agent-runner-service.js';
 import type { AIEmbeddingService } from '../services/ai-embedding-service.js';
 import type { AgentRunStateService } from '../services/agent-run-state-service.js';
@@ -89,8 +89,8 @@ export interface CoreUserSession {
     userId?: string;
     /** The tenant the session is acting inside, when the project has more than one. */
     orgId?: string;
-    /** True when the session belongs to a synthetic scenario actor — lets audits/analytics address synthetic traffic */
-    actor?: boolean;
+    /** True when the session belongs to a synthetic scenario virtual user — lets audits/analytics address synthetic traffic */
+    virtualUser?: boolean;
     /**
      * Scopes granted to this session, checked against a function's `scopes`.
      * Populated by whoever builds the session — core reads them, never fetches.
@@ -150,7 +150,7 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
      */
     virtualUserRunStore?: VirtualUserRunStore;
     /**
-     * Each persona's cadence, for apps that want their virtual users to keep
+     * Each virtual user's cadence, for apps that want their virtual users to keep
      * going without being asked. Separate from the run store on purpose: wiring
      * nothing is how an app says it only wants the runs it starts itself.
      */
@@ -214,7 +214,7 @@ export type GetCredential<TCredentials = Record<string, unknown>> = string exten
     <K extends keyof TCredentials & string>(name: K): TCredentials[K] | null | Promise<TCredentials[K] | null>;
     <T = unknown>(name: string): T | null | Promise<T | null>;
 };
-export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>, TypedActors extends ScenarioPersonas = ScenarioPersonas, TypedCredentials = Record<string, unknown>> = {
+export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>, TScenarioVirtualUsers extends ScenarioVirtualUsers = ScenarioVirtualUsers, TypedCredentials = Record<string, unknown>> = {
     /** Always present — lazily initialised on first access for every function invocation */
     rpc: TypedRPC;
     /** Get a single credential by name — lazy-loads from CredentialService on first call, sync thereafter */
@@ -241,17 +241,17 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     cli: PikkuCLI<TypedRPC['remote']>;
     workflow: TypedWorkflow;
     scenario: TypedScenario;
-    actors: TypedActors;
+    virtualUsers: TScenarioVirtualUsers;
     /**
-     * The persona this step runs as, injected by the runner.
+     * The virtual user this step runs as, injected by the runner.
      *
      * Required on a `browser` binding, which cannot be provisioned without one,
-     * and on any binding whose step declares `actor: true`. A step that declares
-     * neither has no `actor` on its wire at all rather than an optional one —
+     * and on any binding whose step declares `virtualUser: true`. A step that declares
+     * neither has no `virtualUser` on its wire at all rather than an optional one —
      * a pure assertion has nobody to be, and `attemptsSignIn` deliberately posts
-     * credentials instead of reusing an actor's session.
+     * credentials instead of reusing a virtual user's session.
      */
-    actor: ScenarioPersonaOf<TypedActors>;
+    virtualUser: ScenarioVirtualUserOf<TScenarioVirtualUsers>;
     /** Present on every scenario step invocation */
     scenarioStep: PikkuScenarioStepWire;
     /** Present only when the runner provisioned a browser for this step */

package/dist/wirings/role/define-system-role.d.ts

@@ -3,7 +3,7 @@ import type { CoreSystemRoles } from './role.types.js';
  * No-op function for declaring system roles.
  * This exists purely for TypeScript type checking and will be tree-shaken.
  * The CLI extracts metadata via AST parsing and generates a `SystemRoleName`
- * union, so a persona naming an undeclared role fails the build.
+ * union, so a virtual user naming an undeclared role fails the build.
  *
  * A system role is a role that ships with the product: the console may grant
  * it, but cannot rename, re-scope or delete it. Roles an admin composes in the

package/dist/wirings/role/define-system-role.js

@@ -2,7 +2,7 @@
  * No-op function for declaring system roles.
  * This exists purely for TypeScript type checking and will be tree-shaken.
  * The CLI extracts metadata via AST parsing and generates a `SystemRoleName`
- * union, so a persona naming an undeclared role fails the build.
+ * union, so a virtual user naming an undeclared role fails the build.
  *
  * A system role is a role that ships with the product: the console may grant
  * it, but cannot rename, re-scope or delete it. Roles an admin composes in the

package/dist/wirings/{actor-flow/actor-flow.types.d.ts → virtual-user/conversation/conversation.types.d.ts}

@@ -1,15 +1,15 @@
-export type ActorFlowApprovalPolicy = 'in-persona' | 'always' | 'never';
+export type ConversationApprovalPolicy = 'in-virtual-user' | 'always' | 'never';
 export interface ConverseOptions<TAgentName extends string = string> {
     agent: TAgentName;
-    /** What the actor is trying to get the agent to accomplish. */
+    /** What the virtual user is trying to get the agent to accomplish. */
     task: string;
-    /** Natural-language success criterion the actor judges the conversation against. */
+    /** Natural-language success criterion the virtual user judges the conversation against. */
     evaluate: string;
-    approvals?: ActorFlowApprovalPolicy;
+    approvals?: ConversationApprovalPolicy;
     model?: string;
     maxTurns?: number;
 }
-export interface ActorFlowVerdict {
+export interface ConversationVerdict {
     passed: boolean;
     reasoning: string;
     transcript: string[];

package/dist/wirings/virtual-user/conversation/index.d.ts

@@ -0,0 +1,2 @@
+export type { ConversationVerdict, ConverseOptions, TargetAgentDriver, } from './conversation.types.js';
+export { runConversation, type RunConversationParams, type VirtualUserLLM, } from './run-conversation.js';

package/dist/wirings/virtual-user/conversation/run-conversation.d.ts

@@ -0,0 +1,36 @@
+import type { ConversationApprovalPolicy, ConversationVerdict, TargetAgentDriver } from './conversation.types.js';
+import type { ResolvedVirtualUser } from '../../../services/virtual-users-service.js';
+import type { AgentRunnerParams, AgentStepResult } from '../../../services/agent-runner-service.js';
+/** The LLM call the virtual user uses for its own turns/decisions/evaluation. */
+export type VirtualUserLLM = (params: AgentRunnerParams) => Promise<AgentStepResult>;
+export interface RunConversationParams {
+    /** The person being played — name, job title, personality. */
+    virtualUser: ResolvedVirtualUser;
+    /** The id they were declared under (for transcript labelling). */
+    virtualUserId: string;
+    /** What the virtual user is trying to get the target agent to accomplish. */
+    task: string;
+    /** Natural-language success criterion the virtual user evaluates at the end. */
+    evaluate: string;
+    /** How the virtual user answers the target agent's tool-approval requests. */
+    approvals?: ConversationApprovalPolicy;
+    /** Model the virtual user uses for its own turns/decisions. */
+    model: string;
+    /** Hard cap on conversation turns. Default 12. */
+    maxTurns?: number;
+    /** Hard cap on tool-approval rounds within a single target turn. Default 16. */
+    maxApprovalRounds?: number;
+    /** Transport that drives the target agent (HTTP in production). */
+    target: TargetAgentDriver;
+    /** The virtual user's own LLM. */
+    llm: VirtualUserLLM;
+    /** Display name of the target agent (transcript labelling). */
+    agentName: string;
+}
+/**
+ * Run a conversation: an LLM-driven virtual user holds a real multi-turn exchange
+ * with a target agent (driven via the injected transport), answers the target's
+ * tool-approval requests in-virtual-user, then evaluates whether the task was met.
+ * Deterministic checks are the caller's responsibility.
+ */
+export declare function runConversation(params: RunConversationParams): Promise<ConversationVerdict>;

package/dist/wirings/{actor-flow → virtual-user/conversation}/run-conversation.js

@@ -1,5 +1,5 @@
-/** One turn the actor takes: the message to send and whether it's finished. */
-const ACTOR_TURN_SCHEMA = {
+/** One turn the virtual user takes: the message to send and whether it's finished. */
+const VIRTUAL_USER_TURN_SCHEMA = {
     type: 'object',
     properties: {
         message: { type: 'string' },
@@ -7,7 +7,7 @@ const ACTOR_TURN_SCHEMA = {
     },
     required: ['message', 'done'],
 };
-/** The actor's approve/deny decision for each pending tool request. */
+/** The virtual user's approve/deny decision for each pending tool request. */
 const APPROVAL_DECISION_SCHEMA = {
     type: 'object',
     properties: {
@@ -26,7 +26,7 @@ const APPROVAL_DECISION_SCHEMA = {
     },
     required: ['decisions'],
 };
-/** The actor's final verdict on whether the task was accomplished. */
+/** The virtual user's final verdict on whether the task was accomplished. */
 const EVALUATION_SCHEMA = {
     type: 'object',
     properties: {
@@ -60,25 +60,25 @@ function readObject(result) {
     }
     return null;
 }
-function actorInstructions(persona, task) {
+function virtualUserConversationInstructions(virtualUser, task) {
     return [
         `You are role-playing a real user interacting with an AI assistant. Stay in character at all times — you are the user, not the assistant.`,
-        `Your name is ${persona.name}.`,
-        persona.jobTitle ? `Your role: ${persona.jobTitle}.` : '',
-        persona.personality
-            ? `Your personality and communication style: ${persona.personality}. Match this tone, vocabulary, and level of detail exactly.`
+        `Your name is ${virtualUser.name}.`,
+        virtualUser.jobTitle ? `Your role: ${virtualUser.jobTitle}.` : '',
+        virtualUser.personality
+            ? `Your personality and communication style: ${virtualUser.personality}. Match this tone, vocabulary, and level of detail exactly.`
             : '',
         `Your goal in this conversation: ${task}.`,
         `Send one message at a time. Set "done" to true only once your goal is clearly accomplished, or clearly impossible.`,
-        // knowledge: decisions/internals/the-actor-prompt-says-json-because-of-json-object-mode.md
+        // knowledge: decisions/internals/the-virtual-user-prompt-says-json-because-of-json-object-mode.md
         `Reply with json matching the schema you are given, and nothing else.`,
     ]
         .filter(Boolean)
         .join('\n');
 }
-/** Route the target agent's pending tool approvals through the actor. */
+/** Route the target agent's pending tool approvals through the virtual user. */
 async function decideApprovals(params, instructions, pending) {
-    const policy = params.approvals ?? 'in-persona';
+    const policy = params.approvals ?? 'in-virtual-user';
     if (policy === 'always') {
         return pending.map((p) => ({ toolCallId: p.toolCallId, approved: true }));
     }
@@ -90,7 +90,7 @@ async function decideApprovals(params, instructions, pending) {
         .join('\n');
     const result = await params.llm({
         model: params.model,
-        instructions: `${instructions}\nThe assistant is asking permission to run tools on your behalf. Decide whether YOU, as this actor, would allow each one.`,
+        instructions: `${instructions}\nThe assistant is asking permission to run tools on your behalf. Decide whether YOU, as this virtual user, would allow each one.`,
         messages: [
             msg('user', `The assistant wants to run these tools:\n${summary}\nApprove or deny each toolCallId.`),
         ],
@@ -106,7 +106,7 @@ async function decideApprovals(params, instructions, pending) {
         return { toolCallId: p.toolCallId, approved: match?.approved ?? false };
     });
 }
-/** Drive the target to a non-suspended reply, routing approvals to the actor. */
+/** Drive the target to a non-suspended reply, routing approvals to the virtual user. */
 async function converseWithTarget(params, instructions, message) {
     const maxRounds = params.maxApprovalRounds ?? DEFAULT_MAX_APPROVAL_ROUNDS;
     let reply = await params.target.run(message);
@@ -124,40 +124,40 @@ async function converseWithTarget(params, instructions, message) {
     return reply;
 }
 /**
- * Run a conversation: an LLM-driven actor holds a real multi-turn exchange
+ * Run a conversation: an LLM-driven virtual user holds a real multi-turn exchange
  * with a target agent (driven via the injected transport), answers the target's
- * tool-approval requests in-persona, then evaluates whether the task was met.
+ * tool-approval requests in-virtual-user, then evaluates whether the task was met.
  * Deterministic checks are the caller's responsibility.
  */
 export async function runConversation(params) {
     const maxTurns = params.maxTurns ?? DEFAULT_MAX_TURNS;
-    const instructions = actorInstructions(params.persona, params.task);
-    // Seed a kickoff so the very first actor turn has a non-empty message list
-    // (providers reject an empty prompt). It's an instruction TO the actor, so
+    const instructions = virtualUserConversationInstructions(params.virtualUser, params.task);
+    // Seed a kickoff so the very first virtual user turn has a non-empty message list
+    // (providers reject an empty prompt). It's an instruction TO the virtual user, so
     // it never appears in the transcript.
-    const actorMessages = [
+    const virtualUserMessages = [
         msg('user', 'Begin the conversation now — send your first message to the assistant to work towards your goal.'),
     ];
     const transcript = [];
     for (let turn = 0; turn < maxTurns; turn++) {
-        const actorResult = await params.llm({
+        const virtualUserResult = await params.llm({
             model: params.model,
             instructions,
-            messages: actorMessages,
+            messages: virtualUserMessages,
             tools: [],
             maxSteps: 1,
             toolChoice: 'none',
-            outputSchema: ACTOR_TURN_SCHEMA,
+            outputSchema: VIRTUAL_USER_TURN_SCHEMA,
         });
-        const turnData = readObject(actorResult);
-        const actorMessage = turnData?.message?.trim();
-        if (!actorMessage) {
+        const turnData = readObject(virtualUserResult);
+        const virtualUserMessage = turnData?.message?.trim();
+        if (!virtualUserMessage) {
             break;
         }
-        actorMessages.push(msg('assistant', actorMessage));
-        transcript.push(`${params.persona.name}: ${actorMessage}`);
-        const reply = await converseWithTarget(params, instructions, actorMessage);
-        actorMessages.push(msg('user', reply.text ?? ''));
+        virtualUserMessages.push(msg('assistant', virtualUserMessage));
+        transcript.push(`${params.virtualUser.name}: ${virtualUserMessage}`);
+        const reply = await converseWithTarget(params, instructions, virtualUserMessage);
+        virtualUserMessages.push(msg('user', reply.text ?? ''));
         transcript.push(`${params.agentName}: ${reply.text ?? ''}`);
         if (turnData?.done) {
             break;

package/dist/wirings/virtual-user/define-virtual-users.d.ts

@@ -0,0 +1,32 @@
+import type { CoreVirtualUsers } from './virtual-user-declaration.types.js';
+/**
+ * No-op function for declaring virtual users.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `VirtualUserId` union
+ * and a `virtual-users.gen.json` the console and `pikku virtual-user run` read off disk —
+ * describing, listing or running one never has to load the app.
+ *
+ * Declaring is not running: a virtual user that exists only to be acted upon
+ * (the account an admin bans, the colleague a document is shared with) is
+ * seeded and never run.
+ *
+ * Exactly one `defineVirtualUsers(...)` is allowed per codebase, so there is one
+ * place to read the cast from and one place to add to. A second call — even in
+ * the same file — fails the build.
+ *
+ * @example
+ * ```typescript
+ * defineVirtualUsers({
+ *   susan: {
+ *     name: 'Susan',
+ *     jobTitle: 'Buys for a small café',
+ *     roles: ['buyer'],
+ *     personality: 'Hunts cheap deals. Tries three coupon codes before giving up.',
+ *     goals: ['Get the weekly order in under five minutes'],
+ *     disposition: 'careless',
+ *     account: {},
+ *   },
+ * })
+ * ```
+ */
+export declare const defineVirtualUsers: (_config: CoreVirtualUsers) => void;