@pikku/core 0.12.139 → 0.12.142

package/CHANGELOG.md

@@ -1,3 +1,50 @@
+## 0.12.142
+
+### Patch Changes
+
+- fdcc821: Fabric is gone from the open toolchain. The previous names are removed with no aliases.
+
+  The CLI group is `pikku cloud …` and the export is `@pikku/cli/cloud`. The project link is the `cloud` key of `pikku.config.json` (`cloud.projectId`), the CLI keeps its local state in `~/.pikkustudio` (run `pikku cloud login` again), and the project config file is `pikkustudio.config.json`.
+
+  Every environment variable drops the `FABRIC_` prefix for `PIKKUSTUDIO_` with the same suffix: `PIKKUSTUDIO_API_URL`, `PIKKUSTUDIO_PROJECT_ID`, `PIKKUSTUDIO_TOKEN`, `PIKKUSTUDIO_OPERATOR_TOKEN`, `PIKKUSTUDIO_AUTH_PUBLIC_KEY`, `PIKKUSTUDIO_STAGE_ID` and the rest. Rename them wherever you set them.
+
+  Wire ids: the operator sign-in route is `/sign-in/cloud`, the plugin and mode literal is `'cloud'`, the Better Auth plugin is `pikkuCloud`, its session field is `pikkustudioadmin`, and the signature header is `x-cloud-sig`. The cloud API calls are `getCloudLogs`, `getCloudLogsByStageKind`, `cloudCliProjects`, `cloudCliDeployments`, `providedByCloud` and `recordCloudAnalyticsEvents`. Addon packages are `@pikkustudio/*`, scaffolded files live under `scaffold/cloud` and `__cloud_*__`, and the API hosts are the `pikkustudio.app` and `pikkustudio.dev` domains.
+
+  `pikku skills install --fabric` is `--cloud`, the install group is `cloud`, and the skills are `pikku-cloud`, `pikku-cloud-debug`, `pikku-admin-to-cloud` and `pikku-blueprint-to-cloud`.
+
+  The stale analytics forwarder copies are removed from the online-shop example and the starter template.
+
+  The sealed-box salt stays `pikkufabric/sealed-box/v1`: it is a cryptographic constant that already-sealed secrets depend on.
+
+- 33b102d: Virtual users now have one name everywhere. The id column of `virtual_user_run` and `virtual_user_schedule` is `virtual_user_id` (a migration renames it in place), the CLI group is `pikku virtual-user …`, and the declarations and imports live under `@pikku/core/virtual-user`. The previous names are removed with no aliases.
+
+  The default virtual user email domain is now `virtualuser.invalid`: apps that rely on the default domain get new accounts at the next provisioning (`pikku virtual-user sync`, deploy, or `pikku dev` start), and the old rows stay unused.
+
+  The sign-in surface carries the same name. The route is `/sign-in/virtual-user`, the environment variables are `PIKKU_ALLOW_VIRTUAL_USER_SIGN_IN` and the `PIKKU_DEV_VIRTUAL_USER_SIGN_IN` / `VITE_*` equivalents, the Better Auth plugin is `pikkuVirtualUser`, the scenario step option and wire member are `virtualUser` and `virtualUsers`, and the Better Auth user flag column is `virtual_user`. Rename the environment variables wherever you set them, and add a migration that renames the flag column on the `user` table. Nothing is aliased.
+
+  The conversation runner is now `@pikku/core/virtual-user/conversation`, replacing the old `-flow` subpath. Update the import; the old subpath is gone.
+
+- 6a25c70: Virtual users no longer run against production. Starting a run, and enabling a schedule, is refused with a 403 in a production environment for every disposition, including `accountable`, which was the one disposition production used to accept. Turning a schedule off or editing a disabled one is still allowed, so a leftover schedule can be stopped.
+- a084c3b: Virtual users sign themselves in. A scheduled run signs in from inside the app through a server-only Better Auth endpoint, then drives the app over HTTP with the cookie. Outside callers (`pikku dev`, `pikku scenario run`, `pikku virtual-user run` and `rpc`, `pikku pages screenshot --as`, the Playwright provider) present one signed, short-lived, single-use EdDSA statement, which the app checks against `VIRTUAL_USER_VERIFY_KEY`; `pikku dev` generates the key pair, and a deployed stage's deployer holds `VIRTUAL_USER_SIGNING_KEY`. `@pikku/jose` gains `JoseVirtualUserStatementVerifier` and `@pikku/better-auth` takes `verifyKey`. Removed with no aliases: the operator token and `OperatorSignIn`, derived per-virtual-user secrets, `SCENARIO_VIRTUAL_USER_SECRET`, `PIKKU_VIRTUAL_USER_SECRETS`, `pikku virtual-user secret`, and `wireVirtualUserSignIn`. In production neither sign-in endpoint is registered.
+
+  The scenario cookie jar moved to `services` and `createCookieJar` is exported from `@pikku/core/virtual-user`, which removes the wire-to-wire import cycles; `VirtualUserSignIn.headers` is now optional.
+
+  Migration for apps: pass `verifyKey: await variables.get('VIRTUAL_USER_VERIFY_KEY')` to `pikkuVirtualUser` instead of `secret`, declare that variable as optional, delete any `SCENARIO_VIRTUAL_USER_SECRET` secret and any `wireVirtualUserSignIn` call, and stop passing `secret` or `operator` to `createHttpVirtualUsers`. A stage that must run scenarios still opts in with `PIKKU_ALLOW_VIRTUAL_USER_SIGN_IN`.
+
+## 0.12.141
+
+### Patch Changes
+
+- b04e444: Fix CLI commands that come from an addon package. Auth and permissions set on such a command are now merged into the addon's own function instead of replacing it, and the command's input is shaped by the addon's own schema (for example a comma list becomes an array). The inspector now also resolves `...refCLI('addon:contract')`, spreads and `defineCLICommands` identifiers inside a command's `subcommands`.
+- d3d8a98: Graceful shutdown ignores repeat signals. A second SIGTERM or SIGINT arriving while `beforeStop` and the service teardown are still running no longer falls through to the default handler and kills the process mid-cleanup. `@pikku/core/lifecycle` is a new entry point holding `onShutdownSignals`, `stopSingletonServices` and `pikkuServerLifecycle` (the latter two stay re-exported from `utils`), which the server runtimes now share.
+- 658da50: `SecretService` gains an optional `setEncryptedSecret(key, sealed)` for stores that hold a sealing key, so a browser can seal a secret and the caller's process never sees the plaintext.
+
+## 0.12.140
+
+### Patch Changes
+
+- f396538: Event-stream responses pass through `applyWebResponse` without being read, so an SSE route can proxy another stream. HTTP responses gain `onClose`, which `executeRoute` uses to tell an SSE route's event hub when the client leaves. `pikku all` wires the console's `/meta/stream` route to `console:streamMetaChanges`.
+
 ## 0.12.139
 
 ### Patch Changes

package/dist/errors/errors.d.ts

@@ -118,7 +118,7 @@ export declare class AIProviderAuthError extends PikkuError {
  *
  * System roles ship with the product: the console may show and grant them, but
  * renaming, re-scoping or deleting one would let a UI action silently change
- * what a declared persona means, and what every scenario written against that
+ * what a declared virtual user means, and what every scenario written against that
  * role is actually testing.
  * @group Error
  */

package/dist/errors/errors.js

@@ -314,7 +314,7 @@ addError(AIProviderAuthError, {
  *
  * System roles ship with the product: the console may show and grant them, but
  * renaming, re-scoping or deleting one would let a UI action silently change
- * what a declared persona means, and what every scenario written against that
+ * what a declared virtual user means, and what every scenario written against that
  * role is actually testing.
  * @group Error
  */

package/dist/function/function-meta.types.d.ts

@@ -80,17 +80,17 @@ export type FunctionRuntimeMeta = {
      */
     scenarioStepSurfaces?: ScenarioSurface[];
     /**
-     * Scenario steps only: this step runs as a persona, so every call site must
-     * pass one and the runner injects it as `wire.actor`.
+     * Scenario steps only: this step runs as a virtual user, so every call site must
+     * pass one and the runner injects it as `wire.virtualUser`.
      *
-     * Declared by `actor: true`, or implied by a `browser` binding — a window is
+     * Declared by `virtualUser: true`, or implied by a `browser` binding — a window is
      * opened as somebody. Absent on a step with nobody to be: an assertion over
      * what an earlier step returned, or one posting credentials precisely because
-     * it must not reuse an actor's session.
+     * it must not reuse a virtual user's session.
      */
-    scenarioStepRequiresActor?: boolean;
+    scenarioStepRequiresVirtualUser?: boolean;
     /**
-     * Scenario steps only: who acts. Absent means `persona` — the ordinary step,
+     * Scenario steps only: who acts. Absent means `virtualUser` — the ordinary step,
      * and the only kind that existed before the other two.
      *
      * A `platform` or `addon` step is the app or a third-party system acting, and

package/dist/function/functions.types.d.ts

@@ -111,8 +111,8 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
      * and report how much of the flow each surface actually covers.
      */
     surfaces?: ScenarioSurface[];
-    /** Scenario steps only, and set by the definer rather than by hand: this step needs a persona, so the runner injects `wire.actor`. */
-    requiresActor?: boolean;
+    /** Scenario steps only, and set by the definer rather than by hand: this step needs a virtual user, so the runner injects `wire.virtualUser`. */
+    requiresVirtualUser?: boolean;
     /**
      * Records every call in the audit log. `transactional` durability writes the
      * entry in the same transaction as the work, so the two cannot disagree;

package/dist/lifecycle.d.ts

@@ -0,0 +1,6 @@
+import type { CoreSingletonServices, ServerLifecycle } from './types/core.types.js';
+/** Stops addon package services first, then the parent singleton services. */
+export declare const stopSingletonServices: () => Promise<void>;
+/** Wrap server lifecycle hooks so the inspector can discover them. */
+export declare const pikkuServerLifecycle: <SS extends CoreSingletonServices = CoreSingletonServices>(lifecycle: ServerLifecycle<SS>) => ServerLifecycle<SS>;
+export declare const onShutdownSignals: (run: (signal: NodeJS.Signals) => void | Promise<void>, signals?: NodeJS.Signals[]) => (() => void);

package/dist/lifecycle.js

@@ -0,0 +1,58 @@
+import { getSingletonServices, getAllPackageStates } from './pikku-state.js';
+const stopService = async (logger, name, service) => {
+    const stop = service?.stop;
+    if (stop) {
+        logger.info(`Stopping singleton service: ${name}`);
+        try {
+            await stop.call(service);
+        }
+        catch (e) {
+            logger.error(`Error stopping service ${name}:`, e);
+        }
+    }
+};
+/** Stops addon package services first, then the parent singleton services. */
+export const stopSingletonServices = async () => {
+    const singletonServices = getSingletonServices();
+    const logger = singletonServices.logger;
+    const stateMap = getAllPackageStates();
+    if (stateMap.size > 0) {
+        for (const [packageName, packageState] of stateMap) {
+            if (packageName === '__main__')
+                continue;
+            const packageServices = packageState.package?.singletonServices;
+            if (packageServices) {
+                logger.info(`Stopping singleton services for package: ${packageName}`);
+                for (const [name, service] of Object.entries(packageServices)) {
+                    await stopService(logger, `${packageName}/${name}`, service);
+                }
+                packageState.package.singletonServices = null;
+            }
+        }
+    }
+    for (const [name, service] of Object.entries(singletonServices)) {
+        await stopService(logger, name, service);
+    }
+};
+/** Wrap server lifecycle hooks so the inspector can discover them. */
+export const pikkuServerLifecycle = (lifecycle) => lifecycle;
+export const onShutdownSignals = (run, signals = ['SIGINT', 'SIGTERM']) => {
+    const proc = typeof process !== 'undefined' ? process : undefined;
+    if (!proc?.on)
+        return () => { };
+    let stopping = false;
+    const handlers = signals.map((signal) => {
+        const handler = () => {
+            if (stopping)
+                return;
+            stopping = true;
+            void run(signal);
+        };
+        proc.on(signal, handler);
+        return [signal, handler];
+    });
+    return () => {
+        for (const [signal, handler] of handlers)
+            proc.off(signal, handler);
+    };
+};

package/dist/services/audit-service.d.ts

@@ -13,10 +13,10 @@ export type ResolvedAuditConfig = {
 /**
  * Who an event happened under.
  *
- * A user, not an "actor": in pikku an actor is a synthetic person a scenario
- * drives, flagged `actor` on the user row, and the overwhelming majority of
- * audited events are caused by ordinary customers. Naming this `actor` made the
- * synthetic case unsayable — `actor.actor === true` — and implied every
+ * A user, not an "virtualUser": in pikku a virtual user is a synthetic person a scenario
+ * drives, flagged `virtualUser` on the user row, and the overwhelming majority of
+ * audited events are caused by ordinary customers. Naming this `virtualUser` made the
+ * synthetic case unsayable — `virtualUser.virtualUser === true` — and implied every
  * recorded action was a test.
  *
  * `pikkuUserId` is the identity pikku resolves for every wire, so it is the one

package/dist/services/feature-flag-service.d.ts

@@ -88,10 +88,10 @@ export interface FeatureFlagStore extends FeatureFlagSource {
      * every flag to render a board would grow with the wrong number.
      */
     listOverrides(key: string): Promise<FlagOverrideRow[]>;
-    setEnabled(key: string, enabled: boolean, actor?: string, note?: string): Promise<void>;
+    setEnabled(key: string, enabled: boolean, virtualUser?: string, note?: string): Promise<void>;
     /** `percent` is 0–100, or null to remove the rollout constraint. */
-    setRollout(key: string, percent: number | null, actor?: string): Promise<void>;
-    setOverride(key: string, subject: FlagSubject, enabled: boolean, actor?: string): Promise<void>;
+    setRollout(key: string, percent: number | null, virtualUser?: string): Promise<void>;
+    setOverride(key: string, subject: FlagSubject, enabled: boolean, virtualUser?: string): Promise<void>;
     clearOverride(key: string, subject: FlagSubject): Promise<void>;
     /** Flags in the store with no declaration left in code; powers `pikku flags audit`. */
     findStaleFlags(): Promise<string[]>;

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

@@ -1,7 +1,7 @@
-import type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, ScenarioInvokeOptions, ScenarioHttpResponse } from './personas-service.js';
-import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
-import { type ActorSecretResolver, type OperatorSignInOptions } from './persona-sign-in.js';
-export interface HttpPersonasConfig {
+import type { ScenarioVirtualUser, ResolvedVirtualUser, ScenarioVirtualUsers, ScenarioInvokeOptions, ScenarioHttpResponse } from './virtual-users-service.js';
+import type { ConverseOptions, ConversationVerdict } from '../wirings/virtual-user/conversation/conversation.types.js';
+import { type VirtualUserSignIn } from './virtual-user-sign-in.js';
+export interface HttpVirtualUsersConfig {
     /**
      * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
      * `https://app.example.com/api` or `http://localhost:4000/api`. Sign-in is
@@ -10,39 +10,21 @@ export interface HttpPersonasConfig {
      */
     apiUrl: string;
     /**
-     * The ROOT actor secret, from which each persona's own credential is derived
-     * and bound to their address. Sign-in only ever works for user rows flagged
-     * `actor: true`, and a derived credential only ever works for the one address
-     * it was derived for.
-     *
-     * Pass an {@link ActorSecretResolver} instead to drive personas whose
-     * credentials were minted elsewhere — a caller entitled to one persona then
-     * never holds the root.
-     *
-     * The local-development credential. A deployed stage has none, and passes
-     * {@link HttpPersonasConfig.operator} instead.
-     */
-    secret?: string | ActorSecretResolver;
-    /**
-     * Fabric operator credentials, for signing personas into a DEPLOYED stage.
-     *
-     * Mutually exclusive with {@link HttpPersonasConfig.secret}: the operator
-     * path acts as the persona through an admin session rather than logging in as
-     * them, so no test credential has to exist on the target at all.
+     * How each virtual user obtains a session: {@link inProcessSignIn} from inside
+     * the app, {@link statementSignIn} from outside it.
      */
-    operator?: OperatorSignInOptions;
-    /** Persona id → the declaration with its address filled in. */
-    personas: Record<string, ResolvedPersona>;
+    signIn: VirtualUserSignIn;
+    /** Virtual user id → the declaration with its address filled in. */
+    virtualUsers: Record<string, ResolvedVirtualUser>;
     /**
-     * Sign-in path under apiUrl, for whichever of the two paths is in use — an
-     * app that mounts auth under `/api` moves both. Default: the actor plugin's
-     * `/auth/sign-in/actor`, or `/auth/sign-in/fabric` for an operator.
-     * {@link OperatorSignInOptions.signInPath} overrides it.
+     * The sign-in path, when the app mounts auth somewhere other than `/auth`.
+     * Only the mount is used here, to find `get-session`; signing in itself is
+     * the job of {@link HttpVirtualUsersConfig.signIn}.
      */
     signInPath?: string;
     /**
      * Where the session (and its roles) is read back. Defaults to `get-session`
-     * under the same auth mount as {@link HttpPersonasConfig.signInPath}, so an
+     * under the same auth mount as {@link HttpVirtualUsersConfig.signInPath}, so an
      * app that moved auth under `/api` moves this with it and does not have to
      * say so twice.
      */
@@ -57,28 +39,24 @@ export interface HttpPersonasConfig {
      * on scopes that column is a projection rather than the model — it exists so
      * better-auth's own admin endpoints have something to read, is written by
      * whatever keeps it in step, and is absent entirely from an app that declares
-     * no such field. A persona verified against it is verified against a copy.
+     * no such field. A virtual user verified against it is verified against a copy.
      */
     rolesRpc?: string | false;
     /**
-     * Default model a persona thinks with when `converse(...)` is called without
+     * Default model a virtual user thinks with when `converse(...)` is called without
      * an explicit `model`. Its own turns/approvals/evaluation run in-process via
      * the configured `agentRunner`.
      */
     model?: string;
 }
 /**
- * Default HTTP-backed persona. Signs in lazily on first invoke, holds the
+ * Default HTTP-backed virtual user. Signs in lazily on first invoke, holds the
  * session cookies for its lifetime, and re-logs-in once on a 401 mid-run (long
  * health-check runs can outlive a session).
- *
- * How it signs in depends on the target, and the two ways are not
- * interchangeable — see {@link ActorSignIn} for local development and
- * {@link OperatorSignIn} for a deployed stage.
  */
-export declare class HttpPersona implements ScenarioPersona {
+export declare class HttpVirtualUser implements ScenarioVirtualUser {
     readonly name: string;
-    private persona;
+    private virtualUser;
     private config;
     private jar;
     /**
@@ -89,15 +67,15 @@ export declare class HttpPersona implements ScenarioPersona {
      */
     private signedIn;
     private signIn;
-    constructor(name: string, persona: ResolvedPersona, config: HttpPersonasConfig);
+    constructor(name: string, virtualUser: ResolvedVirtualUser, config: HttpVirtualUsersConfig);
     get email(): string;
     invoke(rpcName: string, data: unknown): Promise<unknown>;
     invokeRaw(rpcName: string, data: unknown, options?: ScenarioInvokeOptions): Promise<ScenarioHttpResponse>;
-    converse(options: ConverseOptions): Promise<ActorFlowVerdict>;
+    converse(options: ConverseOptions): Promise<ConversationVerdict>;
     /**
      * The roles the stage says this session holds.
      *
-     * {@link HttpPersonasConfig.rolesRpc} first, then better-auth's
+     * {@link HttpVirtualUsersConfig.rolesRpc} first, then better-auth's
      * `get-session` — where its admin plugin puts `role` on the user, as a
      * comma-separated list. A target that answers neither returns `null` rather
      * than an empty list, because "this stage does not report roles" and "this
@@ -112,7 +90,7 @@ export declare class HttpPersona implements ScenarioPersona {
     private rolesFromRpc;
     private rolesFromSession;
     /**
-     * Start/continue the target agent's run over HTTP as this persona.
+     * Start/continue the target agent's run over HTTP as this virtual user.
      *
      * The SSE route, not the plain one. `POST /rpc/agent/:name` buffers the whole
      * run before it sends a single byte, so a run longer than the client's
@@ -134,7 +112,7 @@ export declare class HttpPersona implements ScenarioPersona {
     private login;
 }
 /**
- * Build the injected `personas` service from the declared personas: id → lazy
- * HTTP persona. Wire the result as the `personas` singleton service.
+ * Build the injected `virtualUsers` service from the declared virtual users: id → lazy
+ * HTTP virtual user. Wire the result as the `virtualUsers` singleton service.
  */
-export declare function createHttpPersonas(config: HttpPersonasConfig): ScenarioPersonas;
+export declare function createHttpVirtualUsers(config: HttpVirtualUsersConfig): ScenarioVirtualUsers;

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

@@ -1,21 +1,17 @@
-import { readScenarioHttpResponse } from './personas-service.js';
-import { runConversation } from '../wirings/actor-flow/run-conversation.js';
-import { createCookieJar, } from '../wirings/workflow/scenario-cookie-jar.js';
-import { ActorSignIn, OperatorSignIn, authMount, } from './persona-sign-in.js';
+import { readScenarioHttpResponse } from './virtual-users-service.js';
+import { runConversation } from '../wirings/virtual-user/conversation/run-conversation.js';
+import { createCookieJar, } from './scenario-cookie-jar.js';
+import { authMount } from './virtual-user-sign-in.js';
 import { getSingletonServices } from '../pikku-state.js';
 import { AIProviderNotConfiguredError } from '../errors/errors.js';
 /**
- * Default HTTP-backed persona. Signs in lazily on first invoke, holds the
+ * Default HTTP-backed virtual user. Signs in lazily on first invoke, holds the
  * session cookies for its lifetime, and re-logs-in once on a 401 mid-run (long
  * health-check runs can outlive a session).
- *
- * How it signs in depends on the target, and the two ways are not
- * interchangeable — see {@link ActorSignIn} for local development and
- * {@link OperatorSignIn} for a deployed stage.
  */
-export class HttpPersona {
+export class HttpVirtualUser {
     name;
-    persona;
+    virtualUser;
     config;
     jar;
     /**
@@ -26,29 +22,15 @@ export class HttpPersona {
      */
     signedIn = false;
     signIn;
-    constructor(name, persona, config) {
+    constructor(name, virtualUser, config) {
         this.name = name;
-        this.persona = persona;
+        this.virtualUser = virtualUser;
         this.config = config;
         this.jar = createCookieJar(config.apiUrl);
-        if (config.operator) {
-            this.signIn = new OperatorSignIn(config.apiUrl, {
-                ...config.operator,
-                signInPath: config.operator.signInPath ??
-                    (authMount(config.signInPath)
-                        ? `${authMount(config.signInPath)}/sign-in/fabric`
-                        : undefined),
-            });
-        }
-        else if (config.secret) {
-            this.signIn = new ActorSignIn(config.apiUrl, config.secret, config.signInPath ?? '/auth/sign-in/actor');
-        }
-        else {
-            throw new Error(`[scenario] persona '${name}' has no way to sign in — set 'secret' for a dev target or 'operator' for a deployed one`);
-        }
+        this.signIn = config.signIn;
     }
     get email() {
-        return this.persona.email;
+        return this.virtualUser.email;
     }
     async invoke(rpcName, data) {
         const res = await this.invokeRaw(rpcName, data);
@@ -78,20 +60,20 @@ export class HttpPersona {
         // Signed in here rather than left to postAgent's 401 retry, which a public
         // agent route never triggers. An unowned thread is minted under a fresh
         // anonymous id per request, so turn one succeeds and turn two is refused as
-        // somebody else's — and a persona is a real account with real credentials,
+        // somebody else's — and a virtual user is a real account with real credentials,
         // so there is no case where conversing as nobody is the intent.
         if (!this.signedIn) {
             await this.login();
         }
         const model = options.model ?? this.config.model;
         if (!model) {
-            throw new Error(`[scenario] persona '${this.name}' converse needs a model — pass options.model or set 'model' on the personas service`);
+            throw new Error(`[scenario] virtual user '${this.name}' converse needs a model — pass options.model or set 'model' on the virtual users service`);
         }
         const threadId = globalThis.crypto.randomUUID();
-        const resourceId = `persona:${this.name}`;
+        const resourceId = `virtualUser:${this.name}`;
         return runConversation({
-            persona: this.persona,
-            personaId: this.name,
+            virtualUser: this.virtualUser,
+            virtualUserId: this.name,
             agentName: options.agent,
             task: options.task,
             evaluate: options.evaluate,
@@ -108,7 +90,7 @@ export class HttpPersona {
     /**
      * The roles the stage says this session holds.
      *
-     * {@link HttpPersonasConfig.rolesRpc} first, then better-auth's
+     * {@link HttpVirtualUsersConfig.rolesRpc} first, then better-auth's
      * `get-session` — where its admin plugin puts `role` on the user, as a
      * comma-separated list. A target that answers neither returns `null` rather
      * than an empty list, because "this stage does not report roles" and "this
@@ -148,11 +130,9 @@ export class HttpPersona {
         return roles.filter((name) => typeof name === 'string');
     }
     async rolesFromSession() {
-        const mount = authMount(this.config.operator?.signInPath ?? this.config.signInPath);
+        const mount = authMount(this.config.signInPath);
         const sessionPath = this.config.sessionPath ?? `${mount ?? '/auth'}/get-session`;
-        const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`, {
-            headers: this.signIn.headers(),
-        });
+        const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`);
         if (!res.ok) {
             return null;
         }
@@ -183,7 +163,7 @@ export class HttpPersona {
         return user ? [] : null;
     }
     /**
-     * Start/continue the target agent's run over HTTP as this persona.
+     * Start/continue the target agent's run over HTTP as this virtual user.
      *
      * The SSE route, not the plain one. `POST /rpc/agent/:name` buffers the whole
      * run before it sends a single byte, so a run longer than the client's
@@ -216,10 +196,7 @@ export class HttpPersona {
         const url = `${this.config.apiUrl}${rpcPath}/${subPath}`;
         const send = () => this.jar.fetch(url, {
             method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                ...this.signIn.headers(),
-            },
+            headers: { 'content-type': 'application/json' },
             body: JSON.stringify(body),
         });
         let res = await send();
@@ -247,7 +224,6 @@ export class HttpPersona {
             method: 'POST',
             headers: {
                 'content-type': 'application/json',
-                ...this.signIn.headers(),
                 ...extraHeaders,
             },
             body: JSON.stringify({ data }),
@@ -259,7 +235,7 @@ export class HttpPersona {
         this.signedIn = false;
     }
     async login() {
-        await this.signIn.login(this.jar, this.persona);
+        await this.signIn.login(this.jar, this.virtualUser);
         this.signedIn = true;
     }
 }
@@ -358,13 +334,13 @@ function normalizeAgentReply(raw) {
     };
 }
 /**
- * Build the injected `personas` service from the declared personas: id → lazy
- * HTTP persona. Wire the result as the `personas` singleton service.
+ * Build the injected `virtualUsers` service from the declared virtual users: id → lazy
+ * HTTP virtual user. Wire the result as the `virtualUsers` singleton service.
  */
-export function createHttpPersonas(config) {
-    const personas = {};
-    for (const [id, persona] of Object.entries(config.personas)) {
-        personas[id] = new HttpPersona(id, persona, config);
+export function createHttpVirtualUsers(config) {
+    const virtualUsers = {};
+    for (const [id, virtualUser] of Object.entries(config.virtualUsers)) {
+        virtualUsers[id] = new HttpVirtualUser(id, virtualUser, config);
     }
-    return personas;
+    return virtualUsers;
 }

package/dist/services/index.d.ts

@@ -23,12 +23,12 @@ export { InMemoryLeaseService } from './in-memory-lease-service.js';
 export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
 export type { ContentService, ContentVisibility, GetDownloadURLArgs, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
-export type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, } from './personas-service.js';
+export type { ScenarioVirtualUser, ResolvedVirtualUser, ScenarioVirtualUsers, } from './virtual-users-service.js';
 export type { JWTService } from './jwt-service.js';
 export type { EmailAttachment, EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
 export { renderEmail, type EmailAssets, type EmailTemplateAssets, type EmailTemplateHashes, type RenderEmailRequest, type RenderedEmailResult, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts, type WebhookJobData, type WebhookServiceConfig, } from './webhook-service.js';
-export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from './persona-actor-secret.js';
+export { VIRTUAL_USER_IN_PROCESS_ENDPOINT, VIRTUAL_USER_STATEMENT_ALGORITHM, VIRTUAL_USER_STATEMENT_MAX_TTL_SECONDS, VIRTUAL_USER_STATEMENT_TTL_SECONDS, VIRTUAL_USER_SIGNING_KEY_VARIABLE, VIRTUAL_USER_VERIFY_KEY_VARIABLE, VirtualUserStatementError, type VirtualUserStatementVerifier, } from './virtual-user-statement.js';
 export type { Logger } from './logger.js';
 export type { SecretService, SecretValues } from './secret-service.js';
 export type { VariablesService } from './variables-service.js';

package/dist/services/index.js

@@ -24,7 +24,7 @@ export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-servic
 export { LocalGatewayService } from './local-gateway-service.js';
 export { renderEmail, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
-export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from './persona-actor-secret.js';
+export { VIRTUAL_USER_IN_PROCESS_ENDPOINT, VIRTUAL_USER_STATEMENT_ALGORITHM, VIRTUAL_USER_STATEMENT_MAX_TTL_SECONDS, VIRTUAL_USER_STATEMENT_TTL_SECONDS, VIRTUAL_USER_SIGNING_KEY_VARIABLE, VIRTUAL_USER_VERIFY_KEY_VARIABLE, VirtualUserStatementError, } from './virtual-user-statement.js';
 export { SchedulerService } from './scheduler-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';
 export { NoopAuditService, createInvocationAudit } from './audit-service.js';

package/dist/services/meta-service.d.ts

@@ -7,7 +7,7 @@ import type { CLIMeta } from '../wirings/cli/cli.types.js';
 import type { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
 import type { WorkflowsMeta } from '../wirings/workflow/workflow.types.js';
 import type { FeaturesMeta } from '../wirings/workflow/scenario.types.js';
-import type { ResolvedPersona } from './personas-service.js';
+import type { ResolvedVirtualUser } from './virtual-users-service.js';
 import type { SystemRoleDefinitionsMeta } from '../wirings/role/role.types.js';
 import type { FeatureFlagDefinitionsMeta } from '../wirings/flag/flag.types.js';
 import type { ScopeDefinitionsMeta } from '../wirings/scope/scope.types.js';
@@ -147,12 +147,12 @@ export interface MetaService {
     getGatewayMeta(): Promise<GatewaysMeta>;
     getRpcMeta(): Promise<RPCMetaRecord>;
     getWorkflowMeta(): Promise<WorkflowsMeta>;
-    getPersonasMeta(): Promise<Record<string, ResolvedPersona>>;
+    getVirtualUsersMeta(): Promise<Record<string, ResolvedVirtualUser>>;
     /**
      * The roles declared with `defineSystemRole`, keyed by name.
      *
-     * A persona declares roles; a function checks scopes. Anything showing what a
-     * persona can reach — the console's persona page, a run's catalogue — needs
+     * A virtual user declares roles; a function checks scopes. Anything showing what a
+     * virtual user can reach — the console's virtual user page, a run's catalogue — needs
      * this to get from one to the other, and needs it to be the same expansion the
      * seed granted from rather than a second one.
      */
@@ -206,7 +206,7 @@ export declare class LocalMetaService implements MetaService {
     private gatewayMetaCache;
     private rpcMetaCache;
     private workflowMetaCache;
-    private personasMetaCache;
+    private virtualUsersMetaCache;
     private systemRolesMetaCache;
     private scopesMetaCache;
     private featureFlagsMetaCache;
@@ -244,7 +244,7 @@ export declare class LocalMetaService implements MetaService {
     getRpcMeta(): Promise<RPCMetaRecord>;
     private readWorkflowMetaDir;
     getWorkflowMeta(): Promise<WorkflowsMeta>;
-    getPersonasMeta(): Promise<Record<string, ResolvedPersona>>;
+    getVirtualUsersMeta(): Promise<Record<string, ResolvedVirtualUser>>;
     getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
     getScopesMeta(): Promise<ScopeDefinitionsMeta>;
     getFeatureFlagsMeta(): Promise<FeatureFlagDefinitionsMeta>;

package/dist/services/meta-service.js

@@ -14,7 +14,7 @@ export class LocalMetaService {
     gatewayMetaCache = null;
     rpcMetaCache = null;
     workflowMetaCache = null;
-    personasMetaCache = null;
+    virtualUsersMetaCache = null;
     systemRolesMetaCache = null;
     scopesMetaCache = null;
     featureFlagsMetaCache = null;
@@ -114,7 +114,7 @@ export class LocalMetaService {
         this.gatewayMetaCache = null;
         this.rpcMetaCache = null;
         this.workflowMetaCache = null;
-        this.personasMetaCache = null;
+        this.virtualUsersMetaCache = null;
         this.systemRolesMetaCache = null;
         this.scopesMetaCache = null;
         this.featureFlagsMetaCache = null;
@@ -265,12 +265,12 @@ export class LocalMetaService {
             return this.workflowMetaCache;
         }
     }
-    async getPersonasMeta() {
-        if (this.personasMetaCache)
-            return this.personasMetaCache;
-        const content = await this.readFile('workflow/personas.gen.json');
-        this.personasMetaCache = content ? JSON.parse(content) : {};
-        return this.personasMetaCache;
+    async getVirtualUsersMeta() {
+        if (this.virtualUsersMetaCache)
+            return this.virtualUsersMetaCache;
+        const content = await this.readFile('workflow/virtual-users.gen.json');
+        this.virtualUsersMetaCache = content ? JSON.parse(content) : {};
+        return this.virtualUsersMetaCache;
     }
     async getSystemRolesMeta() {
         if (this.systemRolesMetaCache)

package/dist/{wirings/workflow → services}/scenario-cookie-jar.d.ts

@@ -1,6 +1,8 @@
 export interface ScenarioCookieJar {
     fetch: typeof fetch;
     clear(): void;
+    /** Take in raw `Set-Cookie` values from a response this jar did not fetch. */
+    absorb(setCookies: readonly string[]): void;
     readonly empty: boolean;
 }
 /**