@pikku/core 0.12.139 → 0.12.142

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

@@ -1,9 +1,9 @@
+import { inProcessSignIn, } from '../../services/virtual-user-sign-in.js';
 import { readEnvVariable } from '../../env.js';
 import { BadRequestError, ForbiddenError } from '../../errors/errors.js';
 import { prepareVirtualUserRun } from './prepare-virtual-user-run.js';
 import { runVirtualUser as runVirtualUserEngine } from './run-virtual-user.js';
-import { personaVirtualUserTarget } from './virtual-user-target.js';
-import { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
+import { virtualUserTarget } from './virtual-user-target.js';
 /**
  * The variables a scaffolded run reads.
  *
@@ -18,55 +18,28 @@ export const VIRTUAL_USER_VARIABLES = {
      * somewhere it only assumed was itself.
      */
     apiUrl: 'VIRTUAL_USER_API_URL',
-    secret: 'SCENARIO_ACTOR_SECRET',
     model: 'VIRTUAL_USER_MODEL',
     /**
-     * The same two variables a scenario run reads, because a virtual user signs
-     * in and calls through exactly the doors a scenario does. An app that mounts
-     * auth somewhere other than the root — `/api/auth` is the common one — has no
-     * other way to say so, and without them the run signs in against a 404 and
-     * spends its whole budget thinking about why nothing works.
+     * Where the app serves its exposed RPCs, as a scenario run reads it. An app
+     * that mounts them somewhere other than `/rpc` has no other way to say so.
      */
-    signInPath: 'SCENARIO_SIGN_IN_PATH',
     rpcPath: 'SCENARIO_RPC_PATH',
-    /**
-     * The deployed way in. A Fabric operator token is asymmetric — a stage can
-     * verify one and can never mint one — so unlike the actor secret it is safe
-     * for a run against a real environment. Read from the environment only as the
-     * fallback for a run nobody handed a token to, which is what a schedule is.
-     */
-    operatorToken: 'FABRIC_OPERATOR_TOKEN',
-};
-/**
- * Which door under the auth mount, given the credential in hand.
- *
- * Both are better-auth plugins mounted side by side, so `SCENARIO_SIGN_IN_PATH`
- * names the mount and the last segment is ours to pick — an app that moved auth
- * to `/api/auth` says so once and both paths follow. A path that names neither
- * plugin is left alone, since it was configured deliberately.
- */
-export const signInPathFor = (configured, plugin) => {
-    if (!configured) {
-        return undefined;
-    }
-    const mount = configured.replace(/\/sign-in\/(actor|fabric)$/, '');
-    return mount === configured ? configured : `${mount}/sign-in/${plugin}`;
 };
 /**
- * The declared persona behind an id, refused unless it is one a run may be.
+ * The declared virtual user behind an id, refused unless it is one a run may be.
  *
- * An acted-upon persona has no session of its own, and running one would race
+ * An acted-upon virtual user has no session of its own, and running one would race
  * whatever scenario acts on it.
  */
-export const runnablePersona = (personas, personaId) => {
-    const persona = personas[personaId];
-    if (!persona) {
-        throw new BadRequestError(`Unknown persona "${personaId}" — declare it with definePersonas()`);
+export const runnableVirtualUser = (virtualUsers, virtualUserId) => {
+    const virtualUser = virtualUsers[virtualUserId];
+    if (!virtualUser) {
+        throw new BadRequestError(`Unknown virtual user "${virtualUserId}" — declare it with defineVirtualUsers()`);
     }
-    if (!persona.runnable) {
-        throw new BadRequestError(`Persona "${personaId}" is declared as acted upon, never run`);
+    if (!virtualUser.runnable) {
+        throw new BadRequestError(`VirtualUser "${virtualUserId}" is declared as acted upon, never run`);
     }
-    return persona;
+    return virtualUser;
 };
 const MISSING_RUN_STORE = 'No virtualUserRunStore is wired — a run has nowhere to be recorded. ' +
     'Wire KyselyVirtualUserRunStore from @pikku/kysely, or your own implementation of VirtualUserRunStore.';
@@ -94,7 +67,7 @@ export const requireVirtualUserScheduleStore = (store) => {
  * `NODE_ENV=production` there too — keying on it refuses every disposition on
  * the one environment they exist to be used on. `PIKKU_ENV` names which of the
  * configured environments this is, which is the question actually being asked,
- * and it is the same signal `personaEnvironmentRefusal` already checks at
+ * and it is the same signal `virtualUserEnvironmentRefusal` already checks at
  * sign-in.
  *
  * Unresolved is treated as production: an environment nobody can name is one
@@ -108,12 +81,11 @@ const isProductionRun = (config, environments, environment) => {
     }
     return environment ? Boolean(environments[environment]?.production) : true;
 };
-// Every disposition other than this one exists to find out what the product
-// does wrong, which is not a thing to do to real customers' data.
-const refuseInProduction = (personaId, disposition, config, environments, environment) => {
-    if (disposition !== PRODUCTION_DISPOSITION &&
-        isProductionRun(config, environments, environment)) {
-        throw new ForbiddenError(`Only the '${PRODUCTION_DISPOSITION}' disposition may run against production; "${personaId}" is ${disposition}`);
+// A virtual user is a probe, and probing is not a thing to do to real
+// customers' data, whatever the disposition.
+const refuseInProduction = (virtualUserId, config, environments, environment) => {
+    if (isProductionRun(config, environments, environment)) {
+        throw new ForbiddenError(`Virtual users do not run against production; "${virtualUserId}" cannot run here`);
     }
 };
 /**
@@ -123,15 +95,13 @@ const refuseInProduction = (personaId, disposition, config, environments, enviro
  * scheduled tick have in common. The dispatch that follows is typed off the
  * app's RPC map, so it stays in the generated wiring.
  */
-export const startVirtualUserRun = async ({ store, personas, config, environments, environment = readEnvVariable('PIKKU_ENV'), persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }) => {
+export const startVirtualUserRun = async ({ store, virtualUsers, config, environments, environment = readEnvVariable('PIKKU_ENV'), virtualUserId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }) => {
     const runStore = requireVirtualUserRunStore(store);
-    const persona = runnablePersona(personas, personaId);
+    const virtualUser = runnableVirtualUser(virtualUsers, virtualUserId);
     const disposition = (requested ??
-        persona.disposition ??
+        virtualUser.disposition ??
         'realistic');
-    // Checked against the effective disposition, so an override cannot smuggle
-    // one in.
-    refuseInProduction(personaId, disposition, config, environments, environment);
+    refuseInProduction(virtualUserId, config, environments, environment);
     // Seeded here rather than inside the engine so the record carries the seed
     // even if the run dies before returning — an unreproducible crash costs the
     // most.
@@ -139,7 +109,7 @@ export const startVirtualUserRun = async ({ store, personas, config, environment
     const resolvedGoals = goals ?? [];
     const resolvedMemory = memory ?? {};
     const runId = await runStore.start({
-        persona: persona.id,
+        virtualUserId: virtualUser.id,
         disposition,
         seed,
         goals: resolvedGoals,
@@ -148,7 +118,7 @@ export const startVirtualUserRun = async ({ store, personas, config, environment
     });
     return {
         runId,
-        persona: persona.id,
+        virtualUserId: virtualUser.id,
         disposition,
         seed,
         goals: resolvedGoals,
@@ -164,7 +134,7 @@ export const startVirtualUserRun = async ({ store, personas, config, environment
  */
 export const serializeVirtualUserRun = (run) => ({
     runId: run.runId,
-    persona: run.persona,
+    virtualUserId: run.virtualUserId,
     disposition: run.disposition,
     seed: run.seed,
     status: run.status,
@@ -212,10 +182,10 @@ export const serializeVirtualUserSteps = (steps) => steps.map((step) => ({
  * takes; the engine's own duration also accepts `'30m'`, which nothing on this
  * side ever writes.
  */
-export const serializeVirtualUserSchedule = (schedule, personas) => {
-    const persona = personas[schedule.persona];
+export const serializeVirtualUserSchedule = (schedule, virtualUsers) => {
+    const virtualUser = virtualUsers[schedule.virtualUserId];
     return {
-        persona: schedule.persona,
+        virtualUserId: schedule.virtualUserId,
         enabled: schedule.enabled,
         disposition: schedule.disposition,
         goals: schedule.goals,
@@ -234,36 +204,36 @@ export const serializeVirtualUserSchedule = (schedule, personas) => {
         lastRunId: schedule.lastRunId,
         lastRunAt: schedule.lastRunAt ? schedule.lastRunAt.toISOString() : null,
         declared: {
-            disposition: (persona?.disposition ??
+            disposition: (virtualUser?.disposition ??
                 'realistic'),
-            goals: persona?.goals ?? [],
+            goals: virtualUser?.goals ?? [],
         },
     };
 };
 /**
- * Writes a persona's cadence.
+ * Writes a virtual user's cadence.
  *
  * Applies the same rules `startVirtualUserRun` enforces, at the point the row is
- * written rather than every hour afterwards: an acted-upon persona has no
- * session, and an enabled cadence whose disposition production refuses, so
- * either is a tick that can only ever fail to start, with nobody watching.
+ * written rather than every hour afterwards: an acted-upon virtual user has no
+ * session, and production refuses every run, so either is a tick that can only
+ * ever fail to start, with nobody watching.
  *
- * The disposition checked is the one the row will hold, since a field left out
- * keeps what it had: enabling a row saved earlier as adversarial is refused
- * just as saving one would be.
+ * Whether the row is enabled is the one thing checked, since a field left out
+ * keeps what it had: enabling a row saved earlier is refused just as saving a
+ * new one would be.
  */
-export const writeVirtualUserSchedule = async ({ store, personas, persona, enabled, disposition, goals, budget, minIntervalMs, maxIntervalMs, nextRunAt, config, environments, environment = readEnvVariable('PIKKU_ENV'), }) => {
+export const writeVirtualUserSchedule = async ({ store, virtualUsers, virtualUserId, enabled, disposition, goals, budget, minIntervalMs, maxIntervalMs, nextRunAt, config, environments, environment = readEnvVariable('PIKKU_ENV'), }) => {
     const scheduleStore = requireVirtualUserScheduleStore(store);
-    const declared = runnablePersona(personas, persona);
+    const declared = runnableVirtualUser(virtualUsers, virtualUserId);
     const current = enabled === undefined || disposition === undefined
-        ? await scheduleStore.get(persona)
+        ? await scheduleStore.get(virtualUserId)
         : null;
     const created = disposition === undefined && !current ? declared.disposition : undefined;
     if (enabled ?? current?.enabled) {
-        refuseInProduction(persona, disposition ?? current?.disposition ?? created ?? 'realistic', config, environments, environment);
+        refuseInProduction(virtualUserId, config, environments, environment);
     }
     return scheduleStore.set({
-        persona,
+        virtualUserId,
         enabled,
         disposition: (disposition ?? created),
         goals,
@@ -283,7 +253,7 @@ export const writeVirtualUserSchedule = async ({ store, personas, persona, enabl
 };
 /** What a due schedule asks `runVirtualUser` for. */
 export const virtualUserScheduleRunInput = (schedule) => ({
-    persona: schedule.persona,
+    virtualUserId: schedule.virtualUserId,
     disposition: schedule.disposition,
     goals: schedule.goals,
     budget: schedule.budget
@@ -300,28 +270,28 @@ export const virtualUserScheduleRunInput = (schedule) => ({
  * What a tick did.
  *
  * Logged rather than returned: the caller is a cron, and a run this started is
- * otherwise the only trace that a persona is still out there working.
+ * otherwise the only trace that a virtual user is still out there working.
  */
 export const logVirtualUserTick = (logger, result) => {
-    for (const { persona, runId } of result.dispatched) {
-        logger.info(`Virtual user ${persona} started run ${runId} on schedule`);
+    for (const { virtualUserId, runId } of result.dispatched) {
+        logger.info(`Virtual user ${virtualUserId} started run ${runId} on schedule`);
     }
     for (const runId of result.reaped) {
-        logger.warn(`Virtual user run ${runId} was abandoned — marked failed so its persona can run again`);
+        logger.warn(`Virtual user run ${runId} was abandoned — marked failed so its virtual user can run again`);
     }
-    for (const { persona, reason } of result.skipped) {
-        logger.info(`Virtual user ${persona} skipped this tick: ${reason}`);
+    for (const { virtualUserId, reason } of result.skipped) {
+        logger.info(`Virtual user ${virtualUserId} skipped this tick: ${reason}`);
     }
 };
 /**
  * The run itself.
  *
  * Everything it needs is derived through `metaService` and the generated
- * personas — the same public surface any consumer has. Nothing reaches into
+ * virtual users — the same public surface any consumer has. Nothing reaches into
  * pikku's internals, because an app could not, and a feature built on what only
  * the framework can see would not be this feature.
  */
-export const executeVirtualUserRun = async ({ runStore, metaService, agentRunner, variables, logger, personas, createPersonas, runId, persona: personaId, disposition, goals, memory, seed, budget, operatorToken, }) => {
+export const executeVirtualUserRun = async ({ runStore, metaService, agentRunner, variables, logger, virtualUsers, createVirtualUsers, runId, virtualUserId, disposition, goals, memory, seed, budget, auth, }) => {
     const store = requireVirtualUserRunStore(runStore);
     try {
         if (!metaService) {
@@ -332,20 +302,11 @@ export const executeVirtualUserRun = async ({ runStore, metaService, agentRunner
         }
         const apiUrl = await variables.get(VIRTUAL_USER_VARIABLES.apiUrl);
         if (!apiUrl) {
-            throw new Error(`${VIRTUAL_USER_VARIABLES.apiUrl} is not set — a virtual user has no address to sign in at.`);
+            throw new Error(`${VIRTUAL_USER_VARIABLES.apiUrl} is not set, so the virtual user has no address to drive. ` +
+                `Set it to the URL this app is reached at, including any HTTP prefix (for example https://my-app.example.com/api). \`pikku dev\` sets it for you.`);
         }
-        // An operator token wins wherever one is available: it is asymmetric, and
-        // it does not need the target to hold a shared secret at all. The actor
-        // secret is the local-only fallback, because only `pikku dev` serves the
-        // endpoint that accepts it.
-        const token = operatorToken ??
-            (await variables.get(VIRTUAL_USER_VARIABLES.operatorToken));
-        const secret = token
-            ? undefined
-            : await variables.get(VIRTUAL_USER_VARIABLES.secret);
-        if (!token && !secret) {
-            throw new Error(`Neither an operator token nor ${VIRTUAL_USER_VARIABLES.secret} is available — there is nobody for the virtual user to be. ` +
-                `Hand a Fabric operator token in with the run against a deployed stage, or export ${VIRTUAL_USER_VARIABLES.secret} against a local \`pikku dev\` target.`);
+        if (!auth) {
+            throw new Error('The app has no auth service, so the virtual user has no way to sign in. Register better-auth (with the pikkuVirtualUser plugin) as the auth singleton service.');
         }
         const model = await variables.get(VIRTUAL_USER_VARIABLES.model);
         if (!model) {
@@ -358,40 +319,31 @@ export const executeVirtualUserRun = async ({ runStore, metaService, agentRunner
             ...new Set(Object.values(functionsMeta).flatMap((meta) => [meta.inputSchemaName, meta.outputSchemaName].filter((name) => !!name))),
         ];
         const schemas = (await metaService.getSchemas(schemaNames));
-        const persona = personas[personaId];
-        if (!persona) {
-            throw new Error(`Persona "${personaId}" is no longer declared`);
+        const virtualUser = virtualUsers[virtualUserId];
+        if (!virtualUser) {
+            throw new Error(`VirtualUser "${virtualUserId}" is no longer declared`);
         }
         const { catalogue, intents, agents } = prepareVirtualUserRun({
-            persona,
+            virtualUser,
             functionsMeta,
             schemas,
             workflowsMeta: await metaService.getWorkflowMeta(),
             systemRoles: await metaService.getSystemRolesMeta(),
             agentsMeta: await metaService.getAgentsMeta(),
         });
-        const configuredSignInPath = (await variables.get(VIRTUAL_USER_VARIABLES.signInPath)) ?? undefined;
-        const signedIn = createPersonas({
+        const signedIn = createVirtualUsers({
             apiUrl,
-            ...(token
-                ? {
-                    operator: {
-                        token,
-                        signInPath: signInPathFor(configuredSignInPath, 'fabric'),
-                    },
-                }
-                : { secret }),
+            signIn: inProcessSignIn(auth),
             model,
-            signInPath: signInPathFor(configuredSignInPath, 'actor'),
             rpcPath: (await variables.get(VIRTUAL_USER_VARIABLES.rpcPath)) ?? undefined,
         });
-        const target = signedIn[personaId];
+        const target = signedIn[virtualUserId];
         if (!target) {
-            throw new Error(`Persona "${personaId}" cannot sign in`);
+            throw new Error(`VirtualUser "${virtualUserId}" cannot sign in`);
         }
         const result = await runVirtualUserEngine({
-            persona,
-            personaId,
+            virtualUser,
+            virtualUserId,
             disposition: disposition,
             catalogue,
             intents,
@@ -399,11 +351,11 @@ export const executeVirtualUserRun = async ({ runStore, metaService, agentRunner
             memory,
             seed,
             agents,
-            target: personaVirtualUserTarget(target, {
+            target: virtualUserTarget(target, {
                 model,
                 agents: agents.map((agent) => agent.name),
             }),
-            // `AgentRunnerService.run` IS the engine's `ActorLLM` — same params, same
+            // `AgentRunnerService.run` IS the engine's `VirtualUserLLM` — same params, same
             // result — so a virtual user thinks through the same runner every agent in
             // the app does, provider quirks and all.
             llm: (params) => agentRunner.run(params),
@@ -429,7 +381,7 @@ export const executeVirtualUserRun = async ({ runStore, metaService, agentRunner
         // record is the only place that distinction survives — leaving it at
         // 'running' forever is what `fail` exists to prevent.
         const message = error instanceof Error ? error.message : String(error);
-        logger.error(`Virtual user run ${runId} (${personaId}) failed: ${message}`);
+        logger.error(`Virtual user run ${runId} (${virtualUserId}) failed: ${message}`);
         await store.fail(runId, message);
         throw error;
     }

package/dist/wirings/virtual-user/virtual-user-schedule-store.d.ts

@@ -1,20 +1,20 @@
 import type { VirtualUserBudget, VirtualUserDisposition } from './virtual-user.types.js';
 /**
- * One persona's standing instruction to keep using the app.
+ * One virtual user's standing instruction to keep using the app.
  *
  * A virtual user that runs once tells you about one afternoon. What an app
- * actually wants to know is what a persona hits over a fortnight, and that is
+ * actually wants to know is what a virtual user hits over a fortnight, and that is
  * a cadence, not a longer run — a budget already caps how far a single run
  * goes, and raising it only buys a more tired user.
  *
  * The row is the schedule. There is deliberately no timer, interval or
  * in-memory loop anywhere near it: a process that holds the next run in its own
- * heap forgets it on the next deploy, and a persona silently stops. Something
+ * heap forgets it on the next deploy, and a virtual user silently stops. Something
  * outside asks which rows are due; the answer survives restarts because it is
  * written down.
  */
 export interface VirtualUserScheduleRecord {
-    persona: string;
+    virtualUserId: string;
     /**
      * Off by default. A schedule that ran the moment it was written would start
      * spending an app's model budget as a side effect of a migration.
@@ -24,20 +24,20 @@ export interface VirtualUserScheduleRecord {
     goals: string[];
     budget: VirtualUserBudget | null;
     /**
-     * The gap to the next run is drawn between these, not fixed. A persona that
+     * The gap to the next run is drawn between these, not fixed. A virtual user that
      * appears at exactly 09:00 every day exercises one cache state and one cron
      * neighbourhood; a real one does not keep an appointment.
      */
     minIntervalMs: number;
     maxIntervalMs: number;
-    /** When this persona is next allowed to run. The whole schedule, in one field. */
+    /** When this virtual user is next allowed to run. The whole schedule, in one field. */
     nextRunAt: Date;
     lastRunId: string | null;
     lastRunAt: Date | null;
 }
 /** A partial write — anything left out keeps whatever the row already had. */
 export interface VirtualUserScheduleInput {
-    persona: string;
+    virtualUserId: string;
     enabled?: boolean;
     disposition?: VirtualUserDisposition;
     goals?: readonly string[];
@@ -57,33 +57,33 @@ export interface VirtualUserScheduleInput {
  * smaller permission than deciding they should keep going.
  */
 export interface VirtualUserScheduleStore {
-    /** Creates or updates one persona's cadence. Returns the row as it now stands. */
+    /** Creates or updates one virtual user's cadence. Returns the row as it now stands. */
     set(schedule: VirtualUserScheduleInput): Promise<VirtualUserScheduleRecord>;
-    get(persona: string): Promise<VirtualUserScheduleRecord | null>;
+    get(virtualUserId: string): Promise<VirtualUserScheduleRecord | null>;
     list(): Promise<VirtualUserScheduleRecord[]>;
     /** Enabled rows whose `nextRunAt` has passed. */
     due(now: Date): Promise<VirtualUserScheduleRecord[]>;
     /**
-     * Pushes the persona's next run out, and records which run this was.
+     * Pushes the virtual user's next run out, and records which run this was.
      *
      * Called *before* the run is dispatched, so a tick that dies halfway does not
      * leave a row due and get re-dispatched by the next one. The cost is that a
      * dispatch which throws waits a full interval rather than retrying, which is
-     * the right way round: a persona that is failing to start should not be
+     * the right way round: a virtual user that is failing to start should not be
      * retried every minute for a week.
      *
      * `from` is the `nextRunAt` the caller read, and the write must match it to
-     * land — the claim is how a tick wins the persona, not just how it records
+     * land — the claim is how a tick wins the virtual user, not just how it records
      * winning. Two processes on the same cron read the same due row, and without
      * the compare-and-set both would dispatch: the same user acting twice over,
      * at twice the budget, producing findings neither run can reproduce. The
-     * loser is told `false` and leaves the persona to whoever got there first.
+     * loser is told `false` and leaves the virtual user to whoever got there first.
      */
-    claim(persona: string, claim: {
+    claim(virtualUserId: string, claim: {
         from: Date;
         nextRunAt: Date;
         runId: string | null;
         at: Date;
     }): Promise<boolean>;
-    remove(persona: string): Promise<void>;
+    remove(virtualUserId: string): Promise<void>;
 }

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

@@ -6,7 +6,7 @@ import type { VirtualUserScheduleRecord, VirtualUserScheduleStore } from './virt
  *
  * A run holds no process across a restart — see {@link VirtualUserRunRecord} —
  * so a deploy mid-run strands the record, and a stranded record would block its
- * persona's schedule for good. Twice the longest duration budget anyone sets in
+ * virtual user's schedule for good. Twice the longest duration budget anyone sets in
  * practice, because the failure this guards against is cheap to recover from
  * and expensive to trigger early: reaping a run that was still working loses
  * its findings.
@@ -25,7 +25,7 @@ export declare const DEFAULT_MAX_INTERVAL_MS: number;
 /** Whether a row is the tick's business, for stores that cannot ask in a query. */
 export declare const isDue: (schedule: VirtualUserScheduleRecord, now: Date) => boolean;
 /**
- * When this persona should next appear, drawn from its own interval.
+ * When this virtual user should next appear, drawn from its own interval.
  *
  * Uniform between the two bounds. Reversed bounds are read as a range rather
  * than rejected, because a schedule is configuration and a swapped pair is a
@@ -35,11 +35,11 @@ export declare const nextRunAt: (schedule: Pick<VirtualUserScheduleRecord, 'minI
 export type VirtualUserSkipReason = 'in-flight' | 'dispatch-failed' | 'claimed-elsewhere';
 export interface VirtualUserTickResult {
     dispatched: {
-        persona: string;
+        virtualUserId: string;
         runId: string;
     }[];
     skipped: {
-        persona: string;
+        virtualUserId: string;
         reason: VirtualUserSkipReason;
     }[];
     /** Runs found stranded at `running` and marked failed. */
@@ -55,14 +55,14 @@ export interface VirtualUserTickParams {
     staleAfterMs?: number;
 }
 /**
- * Acts on whichever personas are due, once.
+ * Acts on whichever virtual users are due, once.
  *
  * The whole cadence lives in this one call, so what schedules it is the host's
  * choice — a cron wiring, a platform scheduler, or a person clicking a button.
  * Pikku does not start a timer on an app's behalf; a scaffold that did would
  * begin spending model budget the moment a project ran `pikku all`.
  *
- * A persona is skipped, not queued, while its previous run is still going. Two
+ * A virtual user is skipped, not queued, while its previous run is still going. Two
  * copies of the same user acting at once is not a heavier test, it is a
  * different one, and every finding it produces is unreproducible. Two ticks
  * running at once are held to the same rule by the claim, which only lands for

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

@@ -4,7 +4,7 @@
  *
  * A run holds no process across a restart — see {@link VirtualUserRunRecord} —
  * so a deploy mid-run strands the record, and a stranded record would block its
- * persona's schedule for good. Twice the longest duration budget anyone sets in
+ * virtual user's schedule for good. Twice the longest duration budget anyone sets in
  * practice, because the failure this guards against is cheap to recover from
  * and expensive to trigger early: reaping a run that was still working loses
  * its findings.
@@ -23,7 +23,7 @@ export const DEFAULT_MAX_INTERVAL_MS = 24 * 60 * 60 * 1000;
 /** Whether a row is the tick's business, for stores that cannot ask in a query. */
 export const isDue = (schedule, now) => schedule.enabled && schedule.nextRunAt.getTime() <= now.getTime();
 /**
- * When this persona should next appear, drawn from its own interval.
+ * When this virtual user should next appear, drawn from its own interval.
  *
  * Uniform between the two bounds. Reversed bounds are read as a range rather
  * than rejected, because a schedule is configuration and a swapped pair is a
@@ -35,14 +35,14 @@ export const nextRunAt = (schedule, now, random) => {
     return new Date(now.getTime() + low + random() * (high - low));
 };
 /**
- * Acts on whichever personas are due, once.
+ * Acts on whichever virtual users are due, once.
  *
  * The whole cadence lives in this one call, so what schedules it is the host's
  * choice — a cron wiring, a platform scheduler, or a person clicking a button.
  * Pikku does not start a timer on an app's behalf; a scaffold that did would
  * begin spending model budget the moment a project ran `pikku all`.
  *
- * A persona is skipped, not queued, while its previous run is still going. Two
+ * A virtual user is skipped, not queued, while its previous run is still going. Two
  * copies of the same user acting at once is not a heavier test, it is a
  * different one, and every finding it produces is unreproducible. Two ticks
  * running at once are held to the same rule by the claim, which only lands for
@@ -55,17 +55,17 @@ export const tickVirtualUserSchedules = async ({ schedules, runs, dispatch, now
         reaped: [],
     };
     for (const schedule of await schedules.due(now)) {
-        const [latest] = await runs.list({ persona: schedule.persona, limit: 1 });
+        const [latest] = await runs.list({ virtualUserId: schedule.virtualUserId, limit: 1 });
         if (latest?.status === 'running') {
             if (now.getTime() - latest.createdAt.getTime() < staleAfterMs) {
-                result.skipped.push({ persona: schedule.persona, reason: 'in-flight' });
+                result.skipped.push({ virtualUserId: schedule.virtualUserId, reason: 'in-flight' });
                 continue;
             }
             await runs.fail(latest.runId, `Abandoned: still running ${Math.round((now.getTime() - latest.createdAt.getTime()) / 60000)}m after it started, which is longer than any budget allows.`);
             result.reaped.push(latest.runId);
         }
         const due = nextRunAt(schedule, now, random);
-        const acquired = await schedules.claim(schedule.persona, {
+        const acquired = await schedules.claim(schedule.virtualUserId, {
             from: schedule.nextRunAt,
             nextRunAt: due,
             runId: null,
@@ -73,7 +73,7 @@ export const tickVirtualUserSchedules = async ({ schedules, runs, dispatch, now
         });
         if (!acquired) {
             result.skipped.push({
-                persona: schedule.persona,
+                virtualUserId: schedule.virtualUserId,
                 reason: 'claimed-elsewhere',
             });
             continue;
@@ -84,18 +84,18 @@ export const tickVirtualUserSchedules = async ({ schedules, runs, dispatch, now
         }
         catch {
             result.skipped.push({
-                persona: schedule.persona,
+                virtualUserId: schedule.virtualUserId,
                 reason: 'dispatch-failed',
             });
             continue;
         }
-        await schedules.claim(schedule.persona, {
+        await schedules.claim(schedule.virtualUserId, {
             from: due,
             nextRunAt: due,
             runId,
             at: now,
         });
-        result.dispatched.push({ persona: schedule.persona, runId });
+        result.dispatched.push({ virtualUserId: schedule.virtualUserId, runId });
     }
     return result;
 };

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

@@ -1,15 +1,15 @@
-import type { ScenarioPersona } from '../../services/personas-service.js';
+import type { ScenarioVirtualUser } from '../../services/virtual-users-service.js';
 import type { VirtualUserTarget } from './virtual-user.types.js';
-export interface PersonaTargetOptions {
-    /** Model the persona uses for its side of a conversation with an agent. */
+export interface VirtualUserTargetOptions {
+    /** Model the virtual user uses for its side of a conversation with an agent. */
     model?: string;
     /** Agents this user may talk to. Omit to leave `talkTo` unavailable. */
     agents?: readonly string[];
 }
 /**
- * Drive a virtual user through a signed-in persona.
+ * Drive a virtual user's run through its signed-in session.
  *
- * This is the only place the engine meets the network. A persona already signs
+ * This is the only place the engine meets the network. A virtual user already signs
  * in as a real user over the app's own auth, keeps its cookies, re-logs-in when
  * a session expires mid-run and reports a status as data rather than throwing —
  * everything a user imitating a user needs, and none of it worth building twice.
@@ -18,4 +18,4 @@ export interface PersonaTargetOptions {
  * error, it is the system saying no, which is information it should be allowed
  * to act on.
  */
-export declare const personaVirtualUserTarget: (persona: ScenarioPersona, { model, agents }?: PersonaTargetOptions) => VirtualUserTarget;
+export declare const virtualUserTarget: (virtualUser: ScenarioVirtualUser, { model, agents }?: VirtualUserTargetOptions) => VirtualUserTarget;

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

@@ -1,7 +1,7 @@
 /**
- * Drive a virtual user through a signed-in persona.
+ * Drive a virtual user's run through its signed-in session.
  *
- * This is the only place the engine meets the network. A persona already signs
+ * This is the only place the engine meets the network. A virtual user already signs
  * in as a real user over the app's own auth, keeps its cookies, re-logs-in when
  * a session expires mid-run and reports a status as data rather than throwing —
  * everything a user imitating a user needs, and none of it worth building twice.
@@ -10,8 +10,8 @@
  * error, it is the system saying no, which is information it should be allowed
  * to act on.
  */
-export const personaVirtualUserTarget = (persona, { model, agents } = {}) => ({
-    call: (rpcName, args) => persona.invokeRaw(rpcName, args),
+export const virtualUserTarget = (virtualUser, { model, agents } = {}) => ({
+    call: (rpcName, args) => virtualUser.invokeRaw(rpcName, args),
     talkTo: agents?.length
         ? async (agent, task) => {
             if (!agents.includes(agent)) {
@@ -21,7 +21,7 @@ export const personaVirtualUserTarget = (persona, { model, agents } = {}) => ({
                     transcript: [],
                 };
             }
-            return persona.converse({
+            return virtualUser.converse({
                 agent,
                 task,
                 // A user asking for something judges the answer by whether they got