@pikku/core 0.12.139 → 0.12.142

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/scoped-secret-service.d.ts

@@ -8,6 +8,7 @@ export declare class ScopedSecretService implements SecretService {
     getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     hasSecret(key: string): Promise<boolean>;
     setSecret(_key: string, _value: unknown): Promise<void>;
+    setEncryptedSecret(_key: string, _sealed: string): Promise<void>;
     deleteSecret(_key: string): Promise<void>;
     getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
 }

package/dist/services/scoped-secret-service.js

@@ -21,6 +21,9 @@ export class ScopedSecretService {
     async setSecret(_key, _value) {
         throw new Error('setSecret is not allowed in scoped secret service');
     }
+    async setEncryptedSecret(_key, _sealed) {
+        throw new Error('setEncryptedSecret is not allowed in scoped secret service');
+    }
     async deleteSecret(_key) {
         throw new Error('deleteSecret is not allowed in scoped secret service');
     }

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

@@ -13,6 +13,12 @@ export interface SecretService {
     /** Answers for any key, including a disallowed one — it must not throw. */
     hasSecret(key: string): Promise<boolean>;
     setSecret(key: string, value: unknown): Promise<void>;
+    /**
+     * Stores a value sealed to this service's public key, so the plaintext never
+     * reaches the caller's process. `sealed` is the serialized envelope, opaque
+     * here. Optional: only stores that hold a sealing key implement it.
+     */
+    setEncryptedSecret?(key: string, sealed: string): Promise<void>;
     deleteSecret(key: string): Promise<void>;
     /**
      * Missing keys are omitted rather than throwing, hence `Partial<T>`: callers

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/typed-secret-service.d.ts

@@ -41,6 +41,7 @@ export declare class TypedSecretService<TMap = Record<string, unknown>> implemen
     getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     hasSecret(key: string): Promise<boolean>;
     setSecret<K extends string>(key: K, value: K extends keyof TMap ? TMap[K] : unknown): Promise<void>;
+    setEncryptedSecret(key: string, sealed: string): Promise<void>;
     deleteSecret(key: string): Promise<void>;
     getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
     getAllStatus(): Promise<CredentialStatus[]>;

package/dist/services/typed-secret-service.js

@@ -33,6 +33,13 @@ export class TypedSecretService {
         await this.secrets.setSecret(key, value);
         this.cache.delete(key);
     }
+    async setEncryptedSecret(key, sealed) {
+        if (!this.secrets.setEncryptedSecret) {
+            throw new Error('This secret service does not accept sealed secrets');
+        }
+        await this.secrets.setEncryptedSecret(key, sealed);
+        this.cache.delete(key);
+    }
     async deleteSecret(key) {
         await this.secrets.deleteSecret(key);
         this.cache.delete(key);

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/testing/service-tests/secret-service-tests.js

@@ -48,6 +48,15 @@ export const defineSecretServiceTests = (name, secretService) => {
             await service.deleteSecret('to-delete');
             assert.strictEqual(await service.hasSecret('to-delete'), false);
         });
+        test('setEncryptedSecret stores a sealed value without opening it', async (t) => {
+            const service = await factory({ key: kek });
+            if (!service.setEncryptedSecret) {
+                t.skip('store does not accept sealed secrets');
+                return;
+            }
+            await service.setEncryptedSecret('sealed-key', 'opaque-envelope');
+            assert.strictEqual(await service.hasSecret('sealed-key'), true);
+        });
         test('rotateKEK re-wraps all secrets', async () => {
             const newKEK = 'new-key-encryption-key-rotated!';
             const oldService = await factory({ key: kek });

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/utils.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from './services/logger.js';
-import type { CoreSingletonServices, ServerLifecycle, WireServices } from './types/core.types.js';
+import type { WireServices } from './types/core.types.js';
 export declare const closeWireServices: (logger: Logger, wireServices: WireServices) => Promise<void>;
 export declare const createWeakUID: () => string;
 export declare const isSerializable: (data: any) => boolean;
@@ -12,10 +12,7 @@ export declare const getTagGroups: <T>(tagGroups: Record<string, T>, tag: string
  */
 export declare const parseJson: <T = any>(input: string | Uint8Array) => T;
 export declare const freezeDedupe: <T>(arr?: readonly T[] | T[] | undefined) => readonly T[];
-/** 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 { stopSingletonServices, pikkuServerLifecycle } from './lifecycle.js';
 export type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
 export type JSONPrimitive = string | number | boolean | null | undefined;
 export type JSONValue = JSONPrimitive | JSONValue[] | {

package/dist/utils.js

@@ -1,4 +1,3 @@
-import { getSingletonServices, getAllPackageStates } from './pikku-state.js';
 import { BadRequestError } from './errors/errors.js';
 export const closeWireServices = async (logger, wireServices) => {
     await Promise.all(Object.values(wireServices).map(async (service) => {
@@ -77,42 +76,6 @@ export const freezeDedupe = (arr) => {
     }
     return Object.freeze(out);
 };
-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 { stopSingletonServices, pikkuServerLifecycle } from './lifecycle.js';
 export { getDurationInMilliseconds, getRelativeTimeOffset, getRelativeTimeOffsetFromNow, parseDurationString, } from './time-utils.js';
 export { formatVersionedId, isVersionedId, parseVersionedId, } from './version.js';

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

@@ -95,11 +95,26 @@ function registerCLICommands(commands, path = [], inheritedOptions = {}, program
         const unwrapped = unwrapFunc(command);
         const commandAuth = typeof command === 'object' ? command.auth : undefined;
         const commandPermissions = typeof command === 'object' ? command.permissions : undefined;
-        addFunction(funcName, {
-            ...unwrapped,
-            auth: commandAuth ?? unwrapped.auth,
-            permissions: commandPermissions ?? unwrapped.permissions,
-        }, currentMeta?.packageName);
+        if (currentMeta?.packageName && !funcName.includes(':')) {
+            if (commandAuth !== undefined || commandPermissions !== undefined) {
+                const registered = pikkuState(currentMeta.packageName, 'function', 'functions');
+                const existing = registered.get(funcName);
+                if (existing) {
+                    registered.set(funcName, {
+                        ...existing,
+                        auth: commandAuth ?? existing.auth,
+                        permissions: commandPermissions ?? existing.permissions,
+                    });
+                }
+            }
+        }
+        if (!currentMeta?.packageName || funcName.includes(':')) {
+            addFunction(funcName, {
+                ...unwrapped,
+                auth: commandAuth ?? unwrapped.auth,
+                permissions: commandPermissions ?? unwrapped.permissions,
+            }, currentMeta?.packageName);
+        }
         if (typeof command === 'object' && command.render) {
             if (programs[program]) {
                 programs[program].renderers[commandId] = command.render;
@@ -110,11 +125,11 @@ function registerCLICommands(commands, path = [], inheritedOptions = {}, program
         }
     }
 }
-function pluckCLIData(mergedData, funcName, availableOptions) {
-    const funcMeta = pikkuState(null, 'function', 'meta')[funcName];
+function pluckCLIData(mergedData, funcName, availableOptions, packageName) {
+    const funcMeta = pikkuState(packageName ?? null, 'function', 'meta')[funcName];
     const schemaName = funcMeta?.inputSchemaName;
     const schema = schemaName
-        ? pikkuState(funcMeta?.packageName ?? null, 'misc', 'schemas').get(schemaName)
+        ? pikkuState(packageName ?? funcMeta?.packageName ?? null, 'misc', 'schemas').get(schemaName)
         : null;
     if (schema && schema.properties) {
         const result = {};
@@ -172,7 +187,7 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
     }
     const commandId = commandPath.join('.');
     const availableOptions = programData?.commandOptions?.[commandId] || {};
-    const pluckedData = () => pluckCLIData(data, funcName, availableOptions);
+    const pluckedData = () => pluckCLIData(data, funcName, availableOptions, currentCommand.packageName);
     const renderer = programData?.renderers[commandId] || programData?.defaultRenderer;
     let cliState;
     const channel = {