@pikku/core 0.12.139 → 0.12.142

package/dist/wirings/http/http-runner.js

@@ -164,6 +164,10 @@ const executeRoute = async (services, matchedRoute, http, options) => {
                 await originalClose();
             };
         }
+        response.onClose?.(() => {
+            channel.state = 'closed';
+            singletonServices.eventHub?.onChannelClosed(channelId);
+        });
     }
     const wire = {
         traceId: requestId,

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

@@ -185,6 +185,7 @@ export interface PikkuHTTPResponse<Out = unknown> {
     send?(data: string | ArrayBuffer | ArrayBufferView): this;
     redirect(location: string, status?: number): this;
     close?: () => void;
+    onClose?: (callback: () => void) => void;
     setMode?: (mode: 'stream') => void;
     flushHeaders?: () => void;
 }

package/dist/wirings/http/pikku-fetch-http-response.d.ts

@@ -14,6 +14,7 @@ export declare class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
     send(data: any): this;
     redirect(location: string, status?: number): this;
     close(): this;
+    onClose(callback: () => void): void;
     toResponse(args?: Record<string, any>): Response;
     private createStream;
 }

package/dist/wirings/http/pikku-fetch-http-response.js

@@ -8,6 +8,7 @@ export class PikkuFetchHTTPResponse {
     #send = null;
     #close = null;
     #cancelStream = null;
+    #onClose = [];
     setMode(mode) {
         this.#responseMode = 'stream';
         if (mode === 'stream') {
@@ -95,6 +96,15 @@ export class PikkuFetchHTTPResponse {
         }
         return this;
     }
+    onClose(callback) {
+        this.#onClose.push(callback);
+    }
+    #closed() {
+        const callbacks = this.#onClose;
+        this.#onClose = [];
+        for (const callback of callbacks)
+            callback();
+    }
     toResponse(args) {
         const cookieHeader = Array.from(this.#cookies.entries()).map(([name, { value, flags }]) => stringifySetCookie({ name, value, ...flags }, flags));
         cookieHeader.forEach((cookie) => this.#headers.append('Set-Cookie', cookie));
@@ -119,9 +129,11 @@ export class PikkuFetchHTTPResponse {
                         return;
                     closed = true;
                     controller.close();
+                    this.#closed();
                 };
                 this.#cancelStream = () => {
                     closed = true;
+                    this.#closed();
                 };
                 this.#send = send;
                 this.#close = close;

package/dist/wirings/http/web-request.js

@@ -1,3 +1,4 @@
+import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
 export function toWebRequest(req, baseUrl) {
     const proto = req.header('x-forwarded-proto') ?? 'http';
     const host = req.header('x-forwarded-host') ?? req.header('host') ?? 'localhost';
@@ -120,6 +121,12 @@ export async function applyWebResponse(res, webResponse) {
     if (setCookieValues.length > 0) {
         res.header('Set-Cookie', setCookieValues);
     }
+    if (webResponse.body &&
+        res instanceof PikkuFetchHTTPResponse &&
+        webResponse.headers.get('content-type')?.startsWith('text/event-stream')) {
+        res.send(webResponse.body);
+        return;
+    }
     const body = await readBody(webResponse);
     if (body !== null) {
         if (res.send) {

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;

package/dist/wirings/{persona/define-personas.js → virtual-user/define-virtual-users.js}

@@ -1,21 +1,21 @@
 /**
- * No-op function for declaring personas.
+ * 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 `PersonaId` union
- * and a `personas.gen.json` the console and `pikku persona run` read off disk —
+ * 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.
  *
- * `definePersonas` rather than `defineVirtualUsers` because declaring is not
- * running: a persona that exists only to be acted upon (the account an admin
- * bans, the colleague a document is shared with) is seeded and never run.
+ * 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 `definePersonas(...)` is allowed per codebase, so there is one
+ * 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
- * definePersonas({
+ * defineVirtualUsers({
  *   susan: {
  *     name: 'Susan',
  *     jobTitle: 'Buys for a small café',
@@ -28,4 +28,4 @@
  * })
  * ```
  */
-export const definePersonas = (_config) => { };
+export const defineVirtualUsers = (_config) => { };

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

@@ -1,7 +1,7 @@
 /**
  * Virtual user module exports.
  *
- * A virtual user is an LLM playing a persona that signs into a *running* stage
+ * A virtual user is an LLM that signs into a *running* stage
  * and works its API in character — non-deterministically, with a budget, and
  * with oracles watching what comes back. It is not a test runner: nothing here
  * asserts an expected outcome, because the point is the outcomes nobody thought
@@ -9,24 +9,47 @@
  *
  * Everything it needs is derived from what a pikku project already generates —
  * the function meta becomes the catalogue, the scenario meta becomes the
- * intents, the declared personas become the identities — so adopting it is
+ * intents, the declared virtual users become the identities — so adopting it is
  * configuration rather than authoring.
  *
  * The engine is transport-agnostic: the virtual user drives an
- * {@link VirtualUserTarget}, which in production is an `HttpPersona`
+ * {@link VirtualUserTarget}, which in production is an `HttpVirtualUser`
  * signed in as a real user against staging or production.
  */
 export type { ApiCatalogueEntry, IntentRecord, IntentSource, StepRecord, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTarget, } from './virtual-user.types.js';
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
 export { runVirtualUser, type RunVirtualUserParams, } from './run-virtual-user.js';
-export { personaScopes, prepareVirtualUserRun, type VirtualUserPreparation, } from './prepare-virtual-user-run.js';
+export { virtualUserScopes, prepareVirtualUserRun, type VirtualUserPreparation, } from './prepare-virtual-user-run.js';
 export type { VirtualUserRunOutcome, VirtualUserRunRecord, VirtualUserRunStart, VirtualUserRunStore, } from './virtual-user-run-store.js';
 export type { VirtualUserScheduleInput, VirtualUserScheduleRecord, VirtualUserScheduleStore, } from './virtual-user-schedule-store.js';
 export { DEFAULT_MAX_INTERVAL_MS, DEFAULT_MIN_INTERVAL_MS, isDue, nextRunAt, STALE_RUN_AFTER_MS, tickVirtualUserSchedules, type VirtualUserTickParams, type VirtualUserTickResult, } from './virtual-user-schedule.js';
 export { DISPOSITIONS, dispositionProfile, type DispositionProfile, type VirtualUserTuning, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { type AgentReachability, type ReachableAgent, } from './virtual-user-agents.js';
-export { IntentStack, intentsForPersona } from './virtual-user-intents.js';
+export { IntentStack, intentsForVirtualUser } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, type SchemaMap, } from './virtual-user-derive.js';
-export { personaVirtualUserTarget, type PersonaTargetOptions, } from './virtual-user-target.js';
-export { executeVirtualUserRun, logVirtualUserTick, requireVirtualUserRunStore, requireVirtualUserScheduleStore, runnablePersona, serializeVirtualUserRun, serializeVirtualUserSchedule, serializeVirtualUserSteps, signInPathFor, startVirtualUserRun, VIRTUAL_USER_VARIABLES, virtualUserScheduleRunInput, writeVirtualUserSchedule, type ExecuteVirtualUserRunParams, type ScaffoldPersonas, type StartedVirtualUserRun, type StartVirtualUserRunParams, type WriteVirtualUserScheduleParams, } from './virtual-user-scaffold.js';
+export { virtualUserTarget, type VirtualUserTargetOptions, } from './virtual-user-target.js';
+export { executeVirtualUserRun, logVirtualUserTick, requireVirtualUserRunStore, requireVirtualUserScheduleStore, runnableVirtualUser, serializeVirtualUserRun, serializeVirtualUserSchedule, serializeVirtualUserSteps, startVirtualUserRun, VIRTUAL_USER_VARIABLES, virtualUserScheduleRunInput, writeVirtualUserSchedule, type ExecuteVirtualUserRunParams, type ScaffoldVirtualUsers, type StartedVirtualUserRun, type StartVirtualUserRunParams, type WriteVirtualUserScheduleParams, } from './virtual-user-scaffold.js';
+export { defineVirtualUsers } from './define-virtual-users.js';
+export { isRunnableVirtualUser, roleMismatchMessage, runnableVirtualUsers, validateAndBuildVirtualUsersMeta, verifyVirtualUserRoles, } from './validate-virtual-users.js';
+export type { RoleVerification } from './validate-virtual-users.js';
+export { virtualUserEnvironmentErrors, virtualUserEnvironmentRefusal, } from './virtual-user-environments.js';
+export type { VirtualUserEnvironment, VirtualUserEnvironmentSubject, } from './virtual-user-environments.js';
+export { virtualUserEmail, virtualUserEmails } from './virtual-user-email.js';
+export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './virtual-user-app-scopes.js';
+export type { MailboxAllowlist, VirtualUserMailbox, ReceivedEmail, } from './virtual-user-mailbox.js';
+export type { CoreVirtualUser, CoreVirtualUsers, VirtualUserAccountMeta, VirtualUserDefinitions, VirtualUserMeta, VirtualUsersMeta, } from './virtual-user-declaration.types.js';
+/**
+ * Signing in as a virtual user and talking to a stage over HTTP.
+ *
+ * Deliberately reached through this entry point rather than `@pikku/core/services`.
+ * `HttpVirtualUser` pulls in the conversation runner and, through it, the
+ * agent runner — none of which a production server has any use for. Exporting it
+ * from the services barrel put that chain in the module graph of every app that
+ * imports services, which only a bundler could remove and an unbundled Node or
+ * Lambda deploy would load outright.
+ */
+export { HttpVirtualUser, createHttpVirtualUsers, type HttpVirtualUsersConfig, } from '../../services/http-virtual-users.js';
+export { statementSignIn, inProcessSignIn, authMount, type VirtualUserSignIn, type VirtualUserStatementMint, type StatementSignInOptions, type InProcessAuth, } from '../../services/virtual-user-sign-in.js';
+export { createCookieJar, type ScenarioCookieJar, } from '../../services/scenario-cookie-jar.js';
+export { postScenarioJson, readScenarioHttpResponse, } from '../../services/virtual-users-service.js';

package/dist/wirings/virtual-user/index.js

@@ -1,10 +1,29 @@
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
 export { runVirtualUser, } from './run-virtual-user.js';
-export { personaScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
+export { virtualUserScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
 export { DEFAULT_MAX_INTERVAL_MS, DEFAULT_MIN_INTERVAL_MS, isDue, nextRunAt, STALE_RUN_AFTER_MS, tickVirtualUserSchedules, } from './virtual-user-schedule.js';
 export { DISPOSITIONS, dispositionProfile, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
-export { IntentStack, intentsForPersona } from './virtual-user-intents.js';
+export { IntentStack, intentsForVirtualUser } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, } from './virtual-user-derive.js';
-export { personaVirtualUserTarget, } from './virtual-user-target.js';
-export { executeVirtualUserRun, logVirtualUserTick, requireVirtualUserRunStore, requireVirtualUserScheduleStore, runnablePersona, serializeVirtualUserRun, serializeVirtualUserSchedule, serializeVirtualUserSteps, signInPathFor, startVirtualUserRun, VIRTUAL_USER_VARIABLES, virtualUserScheduleRunInput, writeVirtualUserSchedule, } from './virtual-user-scaffold.js';
+export { virtualUserTarget, } from './virtual-user-target.js';
+export { executeVirtualUserRun, logVirtualUserTick, requireVirtualUserRunStore, requireVirtualUserScheduleStore, runnableVirtualUser, serializeVirtualUserRun, serializeVirtualUserSchedule, serializeVirtualUserSteps, startVirtualUserRun, VIRTUAL_USER_VARIABLES, virtualUserScheduleRunInput, writeVirtualUserSchedule, } from './virtual-user-scaffold.js';
+export { defineVirtualUsers } from './define-virtual-users.js';
+export { isRunnableVirtualUser, roleMismatchMessage, runnableVirtualUsers, validateAndBuildVirtualUsersMeta, verifyVirtualUserRoles, } from './validate-virtual-users.js';
+export { virtualUserEnvironmentErrors, virtualUserEnvironmentRefusal, } from './virtual-user-environments.js';
+export { virtualUserEmail, virtualUserEmails } from './virtual-user-email.js';
+export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './virtual-user-app-scopes.js';
+/**
+ * Signing in as a virtual user and talking to a stage over HTTP.
+ *
+ * Deliberately reached through this entry point rather than `@pikku/core/services`.
+ * `HttpVirtualUser` pulls in the conversation runner and, through it, the
+ * agent runner — none of which a production server has any use for. Exporting it
+ * from the services barrel put that chain in the module graph of every app that
+ * imports services, which only a bundler could remove and an unbundled Node or
+ * Lambda deploy would load outright.
+ */
+export { HttpVirtualUser, createHttpVirtualUsers, } from '../../services/http-virtual-users.js';
+export { statementSignIn, inProcessSignIn, authMount, } from '../../services/virtual-user-sign-in.js';
+export { createCookieJar, } from '../../services/scenario-cookie-jar.js';
+export { postScenarioJson, readScenarioHttpResponse, } from '../../services/virtual-users-service.js';

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

@@ -5,19 +5,19 @@ import { type SchemaMap } from './virtual-user-derive.js';
 import { type AgentReachability, type ReachableAgent } from './virtual-user-agents.js';
 import type { ApiCatalogueEntry, IntentSource } from './virtual-user.types.js';
 /**
- * The scopes a persona holds, resolved through its roles.
+ * The scopes a virtual user holds, resolved through its roles.
  *
- * Roles are the only thing a persona declares; scopes are what a function
+ * Roles are the only thing a virtual user declares; scopes are what a function
  * checks. Narrowing a virtual user's catalogue needs the second, so the
  * expansion happens once, here, against the same `defineSystemRole` definitions
  * the seed grants from.
  */
-export declare const personaScopes: (persona: {
+export declare const virtualUserScopes: (virtualUser: {
     roles?: readonly string[];
 }, roleScopes: Record<string, readonly string[]>) => string[];
 /** Everything a run needs that is derived rather than decided. */
 export interface VirtualUserPreparation {
-    /** Every RPC the app exposes, narrowed to what this persona can reach. */
+    /** Every RPC the app exposes, narrowed to what this virtual user can reach. */
     catalogue: ApiCatalogueEntry[];
     intents: IntentSource[];
     scopes: string[];
@@ -27,18 +27,18 @@ export interface VirtualUserPreparation {
  * Derive what a virtual user needs from what the project already generates.
  *
  * Shared because there are two callers with the same problem and different
- * sources for it: `pikku persona run` reads the inspector state at build time,
+ * sources for it: `pikku virtual-user run` reads the inspector state at build time,
  * and the scaffolded `runVirtualUser` RPC reads `metaService` at runtime. They
- * must agree — a persona whose catalogue is narrower over RPC than on the CLI
+ * must agree — a virtual user whose catalogue is narrower over RPC than on the CLI
  * finds different things from the same seed, which is exactly the property a
  * seed exists to give.
  *
  * Nothing here is authored for the virtual user's benefit: the function meta is
  * the catalogue, the scenario meta is the intents, and the role definitions are
- * what turn a persona's declared roles into the scopes a function checks.
+ * what turn a virtual user's declared roles into the scopes a function checks.
  */
 export declare const prepareVirtualUserRun: (input: {
-    persona: {
+    virtualUser: {
         roles?: readonly string[];
     };
     functionsMeta: FunctionsMeta;

package/dist/wirings/virtual-user/prepare-virtual-user-run.js

@@ -2,16 +2,16 @@ import { flattenSystemRoleDefinitions } from '../role/validate-role-definitions.
 import { deriveCatalogue, deriveIntents, } from './virtual-user-derive.js';
 import { reachableAgents, } from './virtual-user-agents.js';
 /**
- * The scopes a persona holds, resolved through its roles.
+ * The scopes a virtual user holds, resolved through its roles.
  *
- * Roles are the only thing a persona declares; scopes are what a function
+ * Roles are the only thing a virtual user declares; scopes are what a function
  * checks. Narrowing a virtual user's catalogue needs the second, so the
  * expansion happens once, here, against the same `defineSystemRole` definitions
  * the seed grants from.
  */
-export const personaScopes = (persona, roleScopes) => {
+export const virtualUserScopes = (virtualUser, roleScopes) => {
     const scopes = new Set();
-    for (const role of persona.roles ?? []) {
+    for (const role of virtualUser.roles ?? []) {
         for (const scope of roleScopes[role] ?? []) {
             scopes.add(scope);
         }
@@ -22,15 +22,15 @@ export const personaScopes = (persona, roleScopes) => {
  * Derive what a virtual user needs from what the project already generates.
  *
  * Shared because there are two callers with the same problem and different
- * sources for it: `pikku persona run` reads the inspector state at build time,
+ * sources for it: `pikku virtual-user run` reads the inspector state at build time,
  * and the scaffolded `runVirtualUser` RPC reads `metaService` at runtime. They
- * must agree — a persona whose catalogue is narrower over RPC than on the CLI
+ * must agree — a virtual user whose catalogue is narrower over RPC than on the CLI
  * finds different things from the same seed, which is exactly the property a
  * seed exists to give.
  *
  * Nothing here is authored for the virtual user's benefit: the function meta is
  * the catalogue, the scenario meta is the intents, and the role definitions are
- * what turn a persona's declared roles into the scopes a function checks.
+ * what turn a virtual user's declared roles into the scopes a function checks.
  */
 export const prepareVirtualUserRun = (input) => {
     const catalogue = deriveCatalogue(input.functionsMeta, input.schemas ?? {});
@@ -40,10 +40,10 @@ export const prepareVirtualUserRun = (input) => {
     for (const role of flattenSystemRoleDefinitions(Array.isArray(declared) ? declared : Object.values(declared))) {
         roleScopes[role.name] = role.scopes;
     }
-    const scopes = personaScopes(input.persona, roleScopes);
+    const scopes = virtualUserScopes(input.virtualUser, roleScopes);
     // Gated by the same scopes as the RPCs, because an agent is reached rather
     // than declared: `CoreAgent.scopes` is checked against the session, so a
-    // persona finds the specialists its roles unlock and no others.
+    // virtual user finds the specialists its roles unlock and no others.
     const agents = reachableAgents(input.agentsMeta ?? {}, scopes);
     return { catalogue, intents, scopes, agents };
 };

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

@@ -1,5 +1,5 @@
-import type { ResolvedPersona } from '../../services/personas-service.js';
-import type { ActorLLM } from '../actor-flow/run-conversation.js';
+import type { ResolvedVirtualUser } from '../../services/virtual-users-service.js';
+import type { VirtualUserLLM } from './conversation/run-conversation.js';
 import { type VirtualUserTuning } from './virtual-user-dispositions.js';
 import type { ApiCatalogueEntry, IntentSource, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTally, VirtualUserTarget } from './virtual-user.types.js';
 /** What an app-specific oracle is shown about one call. */
@@ -15,9 +15,9 @@ export interface VirtualUserCallContext {
 }
 export interface RunVirtualUserParams {
     /** The person being run — name, job title, personality, goals. */
-    persona: ResolvedPersona;
+    virtualUser: ResolvedVirtualUser;
     /** The id they were declared under, as the intent sources refer to them. */
-    personaId: string;
+    virtualUserId: string;
     /** How it behaves. Default `realistic`. */
     disposition?: VirtualUserDisposition;
     /** Per-user overrides for that disposition's dials. */
@@ -31,7 +31,7 @@ export interface RunVirtualUserParams {
     /** The transport it acts through. */
     target: VirtualUserTarget;
     /** The user's own LLM. */
-    llm: ActorLLM;
+    llm: VirtualUserLLM;
     model: string;
     budget?: VirtualUserBudget;
     /**
@@ -60,7 +60,7 @@ export interface RunVirtualUserParams {
     /** Ids and slugs remembered from an earlier run, for a `stale` user. */
     memory?: Record<string, string>;
     /**
-     * The scopes this persona actually holds, resolved from its roles at sign-in.
+     * The scopes this virtual user actually holds, resolved from its roles at sign-in.
      *
      * Used two ways: to narrow a large catalogue to what it is entitled to reach,
      * and as an oracle — a call whose scopes it does not hold that nonetheless