@pikku/core 0.12.141 → 0.12.143

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;
 }
 /**

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

@@ -7,7 +7,24 @@
 export const createCookieJar = (apiUrl) => {
     const jar = new Map();
     const origin = new URL(apiUrl).origin;
+    const absorb = (setCookies) => {
+        for (const raw of setCookies) {
+            const [pair] = raw.split(';');
+            const separator = pair.indexOf('=');
+            if (separator > 0) {
+                const name = pair.slice(0, separator);
+                const value = pair.slice(separator + 1);
+                if (value) {
+                    jar.set(name, value);
+                }
+                else {
+                    jar.delete(name);
+                }
+            }
+        }
+    };
     return {
+        absorb,
         fetch: async (input, init) => {
             const headers = new Headers(init?.headers);
             headers.set('origin', origin);
@@ -26,20 +43,7 @@ export const createCookieJar = (apiUrl) => {
                 headers.set('cookie', [caller, ...held].filter(Boolean).join('; '));
             }
             const response = await fetch(input, { ...init, headers });
-            for (const raw of response.headers.getSetCookie()) {
-                const [pair] = raw.split(';');
-                const separator = pair.indexOf('=');
-                if (separator > 0) {
-                    const name = pair.slice(0, separator);
-                    const value = pair.slice(separator + 1);
-                    if (value) {
-                        jar.set(name, value);
-                    }
-                    else {
-                        jar.delete(name);
-                    }
-                }
-            }
+            absorb(response.headers.getSetCookie());
             return response;
         },
         clear: () => jar.clear(),

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

@@ -1,4 +1,5 @@
 import type { CoreUserSession } from '../types/core.types.js';
+import type { ScheduledTaskRuns } from '../wirings/scheduler/scheduler.types.js';
 export interface ScheduledTaskSummary {
     taskId: string;
     rpcName: string;
@@ -17,6 +18,8 @@ export declare abstract class SchedulerService {
     abstract getTask(taskId: string): Promise<ScheduledTaskInfo | null>;
     abstract getAllTasks(): Promise<ScheduledTaskSummary[]>;
     abstract close(): Promise<void>;
+    /** Per wired cron task. Empty when this scheduler keeps no run history. */
+    getTaskRuns(): Promise<Record<string, ScheduledTaskRuns>>;
     start(): Promise<void>;
     stop(): Promise<void>;
 }

package/dist/services/scheduler-service.js

@@ -1,4 +1,8 @@
 export class SchedulerService {
+    /** Per wired cron task. Empty when this scheduler keeps no run history. */
+    async getTaskRuns() {
+        return {};
+    }
     async start() { }
     async stop() { }
 }

package/dist/services/system-role-guard.d.ts

@@ -5,7 +5,7 @@ import type { Role } from './scope-service.js';
  *
  * Shared rather than left to each implementation because the rule is a
  * contract, not a policy: a store that lets the console delete `buyer` makes
- * every persona and scenario written against `buyer` silently stop testing
+ * every virtual user and scenario written against `buyer` silently stop testing
  * what it claims to, and nothing fails at the point of the mistake. Two
  * implementations disagreeing about that would be worse than either rule.
  *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/wirings/queue/index.d.ts

@@ -1,4 +1,4 @@
-export type { ConfigValidationResult, CoreQueueWorker, GroupConcurrencyConfig, JobGroup, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueJob, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
+export type { ConfigValidationResult, CoreQueueWorker, GroupConcurrencyConfig, JobGroup, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueInspection, QueueJob, QueueJobCounts, QueueJobRecord, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
 export { wireQueueWorker, runQueueJob, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
 export type { QueueIdentityBinding } from './queue-identity.js';
 export { SignedQueueService } from './signed-queue-service.js';

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

@@ -94,8 +94,29 @@ export interface JobOptions {
     /** Counts against the worker's {@link PikkuWorkerConfig.groupConcurrency}. */
     group?: JobGroup;
 }
+export type QueueJobCounts = Record<QueueJobStatus, number>;
+export type QueueJobRecord = {
+    jobId: string;
+    status: QueueJobStatus;
+    attemptsMade: number;
+    maxAttempts: number;
+    createdAt: Date;
+    processedAt: Date | null;
+    finishedAt: Date | null;
+    durationMs: number | null;
+    error: string | null;
+};
+export type QueueInspection = {
+    counts: QueueJobCounts;
+    /** Newest first. */
+    recent: QueueJobRecord[];
+};
 export interface QueueService {
     readonly supportsResults: boolean;
+    /** Live counts and recent jobs for one queue. Absent on a queue service that cannot inspect its backlog. */
+    inspect?(queueName: string, opts?: {
+        limit?: number;
+    }): Promise<QueueInspection>;
     add<T>(queueName: string, data: Safe<T>, options?: JobOptions): Promise<string>;
     getJob<T, R>(queueName: string, jobId: string): Promise<QueueJob<T, R> | null>;
 }

package/dist/wirings/queue/signed-queue-service.d.ts

@@ -1,7 +1,7 @@
 import type { Safe } from '../../classification/secret-value.js';
 import type { Logger } from '../../services/logger.js';
 import type { SecretService } from '../../services/secret-service.js';
-import type { JobOptions, QueueJob, QueueService } from './queue.types.js';
+import type { JobOptions, QueueInspection, QueueJob, QueueService } from './queue.types.js';
 /**
  * Wraps any {@link QueueService} so `JobOptions.pikkuUserId` leaves the process
  * as a signed claim that `runQueueJob` can verify.
@@ -14,4 +14,7 @@ export declare class SignedQueueService implements QueueService {
     get supportsResults(): boolean;
     add<T>(queueName: string, data: Safe<T>, options?: JobOptions): Promise<string>;
     getJob<T, R>(queueName: string, jobId: string): Promise<QueueJob<T, R> | null>;
+    get inspect(): ((queueName: string, opts?: {
+        limit?: number;
+    }) => Promise<QueueInspection>) | undefined;
 }

package/dist/wirings/queue/signed-queue-service.js

@@ -39,4 +39,7 @@ export class SignedQueueService {
     async getJob(queueName, jobId) {
         return this.queueService.getJob(queueName, jobId);
     }
+    get inspect() {
+        return this.queueService.inspect?.bind(this.queueService);
+    }
 }

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