@pikku/core 0.12.89 → 0.12.91

package/CHANGELOG.md

@@ -1,3 +1,184 @@
+## 0.12.91
+
+### Patch Changes
+
+- 09aff02: Let personas run against a deployed stage.
+
+  A persona could only ever sign in through the actor plugin, which is
+  passwordless and therefore a local-development mechanism — so the scenario
+  suite had no way to reach staging or production, including the parts of it
+  that never assert anything about a logged-in user.
+
+  `HttpPersonasConfig` now takes `operator` as an alternative to `secret`. Given
+  Fabric operator credentials, a persona signs in at `/auth/sign-in/fabric` and
+  acts as its account through the `x-pikku-impersonate-user-id` header, which is
+  gated on the umbrella `admin` scope rather than `user.role`. Nothing on the
+  deployed side holds a test credential: the stage verifies operator tokens and
+  cannot mint them.
+
+  Provisioning stays opt-in (`createMissing`), so pointing a run at a live
+  environment never quietly writes user rows into it.
+
+## 0.12.90
+
+### Patch Changes
+
+- 3c0012c: Gate console agent-thread reads and deletes on thread ownership, claim MongoDB workflow steps atomically, and reach the deployment fallback from `rpcWithWire`
+
+  `getAgentThreadMessages` and `deleteAgentThread` in the console addon took a
+  caller-supplied `threadId` straight to storage, while their siblings
+  `getAgentThreads` and `getAgentThreadRuns` already filtered to what the session
+  owns. Both now carry an `isThreadOwner` permission: an admin reaches any thread,
+  everyone else only their own, and a missing thread is refused rather than 404'd
+  so it is indistinguishable from someone else's.
+
+  `MongoDBWorkflowService` claimed a step by reading its status and then writing
+  it, under a `withStepLock` that is a pass-through — so two dispatches racing for
+  the same step could both proceed and run a side-effecting step twice. The claim
+  is now a single status-guarded update, atomic on one document.
+
+  `rpcWithWire` threw `RPCNotFoundError` for any unresolved namespaced call
+  instead of falling through to the deployment service, so a namespaced RPC that
+  `rpc()` would have dispatched remotely failed when called with an explicit wire.
+
+- 05e47cf: fix(personas): sign a persona in before it converses, not after a 401
+
+  `HttpPersona.converse` left authentication to `postAgent`'s 401-retry, which
+  only fires on a route that refuses an anonymous caller. An agent route wired
+  without `auth: true` never refuses one: turn one is accepted and the thread is
+  minted under a fresh anonymous id, turn two arrives under a different anonymous
+  id, and the persona is told the thread belongs to somebody else — intermittently,
+  because it depends on which turn the retry happened to run on.
+
+  The persona now logs in before the first turn if it has not already. A persona
+  is a declared account with real credentials in every case, so there was never a
+  run where conversing as nobody was what was wanted; the sign-in is the same one
+  `call` has always done, just no longer conditional on the server pushing back.
+
+- cfd364a: Remove the last `@pikku/core/ecosystem` references and guard against new ones
+
+  `@pikku/kysely`'s workflow-service test still imported `StepState` from
+  `@pikku/core/ecosystem/workflow`, a subpath that no longer exists in
+  `@pikku/core`'s `exports`. Nothing caught it: the import is type-only, so tsx
+  erases it before it can fail at runtime, and the package tsconfig excludes
+  `**/*.test.ts`, so `yarn tsc` never saw it either. It now imports from
+  `@pikku/core/workflow`.
+
+  A new guard test in `@pikku/core` scans the repository for the dead specifier
+  and fails if one comes back, so the next stale import is a red test rather than
+  a silent `any`.
+
+- 05e47cf: fix(virtual-user): offer agents under the name the server can resolve
+
+  `reachableAgents` named each offered agent `agent.name ?? id`, where `id` is the
+  key the agent is registered under and `agent.name` is the display label from its
+  config. Those are the same string only by coincidence. `addAgent` stores the
+  export's own name and `resolveAgent` looks the call up by it, so an agent
+  exported as `adminAgent` and declaring `name: 'admin-agent'` was advertised to a
+  virtual user as `admin-agent` — a name nothing has ever registered. The persona
+  took the offer on its first turn, the stage answered
+  `500 AI agent not found: admin-agent`, and the run died there. Every fixture in
+  the tests happened to use one string for both, so nothing caught it.
+
+  The offered name is now always the registration key. `AgentReachability.name` is
+  gone rather than ignored, so there is no longer a display label sitting in the
+  shape inviting the same mistake.
+
+- 05e47cf: feat(virtual-user): keep the transcript a run already produced
+
+  The engine returns `intents` and `steps` on every run — what the user set out
+  to do, and every turn it took getting there — and `VirtualUserRunOutcome` kept
+  neither. The record held counts and findings, so the one question anybody
+  actually asks of a completed run ("what did it _do_?") had no answer anywhere,
+  even though the answer had been computed and thrown away a moment earlier.
+
+  `VirtualUserRunOutcome` now carries both, and `VirtualUserRunStore` gains a
+  `steps(runId, options?)` read. Intents ride on the run record: there are a
+  handful of them and every read of the run wants them. Steps get their own
+  `virtualUserRunStep` table, because a run at a 500-step budget carries more
+  transcript than every other column together and `list()` would pay for it on
+  every row.
+
+  Three things the kysely store had to get right, all of them driver differences
+  rather than design:
+
+  - steps are inserted in chunks of 50, because a bare sqlite driver binds at
+    most 999 variables per statement and ten columns times a 500-step budget is
+    five thousand — an un-chunked insert fails on long runs, which are the
+    interesting ones;
+  - `ok` is stored as 0 or 1, since a bare driver cannot bind a boolean at all
+    and `SerializePlugin` is not installed everywhere;
+  - `response` is stored JSON-encoded, because a truncated API response usually
+    starts with a brace and `SerializePlugin` would otherwise read it back as an
+    object rather than the string the engine saw.
+
+  Completing a run that does not exist no longer writes steps: there is no
+  foreign key to refuse them and nothing would ever read or reap them.
+
+  **This adds a table to the `virtualUser` schema**, and the runtime creates
+  nothing: a database that already has `virtualUserRun` gets the store's own
+  refusal at startup until `pikku db generate` writes the migration and
+  `pikku db migrate` applies it. Landing it now costs nothing, because
+  `scaffold.virtualUser` is not yet switched on anywhere.
+
+- 05e47cf: feat(virtual-user): put each persona on its own clock
+
+  A budget says where one run stops. Nothing said how often a persona should use
+  the application, so in practice each one ran whenever somebody remembered — and
+  what actually tells you about a product is the same user coming back over a
+  fortnight.
+
+  Each persona now gets a row rather than a bigger budget. `virtualUserSchedule`
+  holds `enabled`, the disposition and goals to run with, an interval **range**,
+  and `nextRunAt`. `tickVirtualUserSchedules` acts on whichever rows are due:
+
+  ```ts
+  wireScheduler({
+    name: 'virtualUsers',
+    schedule: '0 * * * *',
+    func: tickVirtualUserSchedules,
+  })
+  ```
+
+  The tick is generated and wired by nobody, deliberately. A scaffolded
+  `wireScheduler` would start spending an application's model budget the moment
+  somebody ran `pikku all`, on a host that may not run schedulers at all. Tick
+  resolution bounds how late a due persona is, never how often it runs.
+
+  Three things it does that are easy to leave out:
+
+  - The next due time is written **before** the run is dispatched, so a tick that
+    dies halfway cannot hand the same persona to the next one. A dispatch that
+    throws waits a full interval instead of retrying every minute for a week.
+    That write is a compare-and-set against the `nextRunAt` the tick read, so it
+    is also how a tick _wins_ the persona: two processes on the same cron see the
+    same due row, and only the one whose claim lands dispatches.
+  - A persona whose previous run is still `running` is skipped, not queued. Two
+    copies of the same user acting at once is a different test, and its findings
+    do not reproduce.
+  - A run still `running` after two hours is failed. Without that, one restart
+    mid-run blocks that persona's schedule permanently — which is where the
+    stranded-record cost of not using a queue finally gets paid.
+
+  Reschedule-on-completion was the other candidate and is worse in exactly one
+  way, fatally: a crash between finishing and scheduling ends the persona forever,
+  and the evidence is an absence.
+
+  New: `VirtualUserScheduleStore` in core (with the tick, `isDue` and `nextRunAt`
+  as pure functions), `KyselyVirtualUserScheduleStore` and its own schema —
+  its own rather than a third table in `virtualUserSchema`, and owned by its own
+  store, so a project that records runs and never wants them unattended carries no
+  cadence table. `scaffold.virtualUser` gains `setVirtualUserSchedule`,
+  `listVirtualUserSchedules` and the tick, behind a new `virtualUser:schedule`
+  scope: starting a run spends money once with a caller watching, while writing a
+  schedule spends it repeatedly with nobody there.
+
+  The console's Virtual Users screen gains a **Run now** button beside a persona's
+  run history, gated on `pikku:console:virtualUsers:run`. It dispatches the
+  project's own `runVirtualUser` rather than starting a run itself, so a run the
+  application would refuse — an acted-upon persona, a non-accountable disposition
+  in production — is still refused.
+
 ## 0.12.89
 
 ### Patch Changes

package/dist/services/http-personas.d.ts

@@ -1,5 +1,6 @@
 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 OperatorSignInOptions } from './persona-sign-in.js';
 export interface HttpPersonasConfig {
     /**
      * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
@@ -11,8 +12,19 @@ export interface HttpPersonasConfig {
     /**
      * The impersonation secret. Sign-in only ever works for user rows flagged
      * `actor: true` — knowing the secret never impersonates real users.
+     *
+     * The local-development credential. A deployed stage has none, and passes
+     * {@link HttpPersonasConfig.operator} instead.
+     */
+    secret?: string;
+    /**
+     * 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.
      */
-    secret: string;
+    operator?: OperatorSignInOptions;
     /** Persona id → the declaration with its address filled in. */
     personas: Record<string, ResolvedPersona>;
     /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
@@ -29,12 +41,13 @@ export interface HttpPersonasConfig {
     model?: string;
 }
 /**
- * Default HTTP-backed persona. Signs in lazily on first invoke via the Better
- * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
- * the plugin upserts the actor-flagged user row and mints a session whose
- * `actor` flag flows into audits/analytics). Holds the session cookies for
- * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
- * outlive a session).
+ * Default HTTP-backed persona. 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 {
     readonly name: string;
@@ -48,6 +61,7 @@ export declare class HttpPersona implements ScenarioPersona {
      * established.
      */
     private signedIn;
+    private signIn;
     constructor(name: string, persona: ResolvedPersona, config: HttpPersonasConfig);
     get email(): string;
     invoke(rpcName: string, data: unknown): Promise<unknown>;

package/dist/services/http-personas.js

@@ -1,15 +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, } from './persona-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 via the Better
- * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
- * the plugin upserts the actor-flagged user row and mints a session whose
- * `actor` flag flows into audits/analytics). Holds the session cookies for
- * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
- * outlive a session).
+ * Default HTTP-backed persona. 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 {
     name;
@@ -23,11 +25,21 @@ export class HttpPersona {
      * established.
      */
     signedIn = false;
+    signIn;
     constructor(name, persona, config) {
         this.name = name;
         this.persona = persona;
         this.config = config;
         this.jar = createCookieJar(config.apiUrl);
+        if (config.operator) {
+            this.signIn = new OperatorSignIn(config.apiUrl, config.operator);
+        }
+        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`);
+        }
     }
     get email() {
         return this.persona.email;
@@ -57,6 +69,14 @@ export class HttpPersona {
         if (!agentRunner) {
             throw new AIProviderNotConfiguredError();
         }
+        // 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,
+        // 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`);
@@ -93,7 +113,9 @@ export class HttpPersona {
             await this.login();
         }
         const sessionPath = this.config.sessionPath ?? '/auth/get-session';
-        const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`);
+        const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`, {
+            headers: this.signIn.headers(),
+        });
         if (!res.ok) {
             return null;
         }
@@ -146,7 +168,10 @@ export class HttpPersona {
         const url = `${this.config.apiUrl}${rpcPath}/${subPath}`;
         const send = () => this.jar.fetch(url, {
             method: 'POST',
-            headers: { 'content-type': 'application/json' },
+            headers: {
+                'content-type': 'application/json',
+                ...this.signIn.headers(),
+            },
             body: JSON.stringify(body),
         });
         let res = await send();
@@ -168,7 +193,11 @@ export class HttpPersona {
         const rpcPath = this.config.rpcPath ?? '/rpc';
         return this.jar.fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
             method: 'POST',
-            headers: { 'content-type': 'application/json', ...extraHeaders },
+            headers: {
+                'content-type': 'application/json',
+                ...this.signIn.headers(),
+                ...extraHeaders,
+            },
             body: JSON.stringify({ data }),
         });
     }
@@ -178,25 +207,7 @@ export class HttpPersona {
         this.signedIn = false;
     }
     async login() {
-        const signInPath = this.config.signInPath ?? '/auth/sign-in/actor';
-        const res = await this.jar.fetch(`${this.config.apiUrl}${signInPath}`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-                email: this.persona.email,
-                name: this.persona.name,
-                secret: this.config.secret,
-            }),
-        });
-        if (!res.ok) {
-            const body = (await res.text().catch(() => '')).slice(0, 300);
-            throw new Error(`[scenario] persona sign-in failed for '${this.name}' (${res.status}): ${body}`);
-        }
-        // 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 Error(`[scenario] persona sign-in for '${this.name}' returned no session cookie`);
-        }
+        await this.signIn.login(this.jar, this.persona);
         this.signedIn = true;
     }
 }

package/dist/services/persona-sign-in.d.ts

@@ -0,0 +1,107 @@
+import type { ResolvedPersona } from './personas-service.js';
+import type { ScenarioCookieJar } from '../wirings/workflow/scenario-cookie-jar.js';
+/**
+ * The header `resolveImpersonatedSession` reads the target user id from.
+ *
+ * A wire value rather than a shared import: the reader lives in
+ * `@pikku/services-better-auth`, which depends on core, so core cannot import
+ * it back. The two agree by protocol, the way an HTTP header always does.
+ */
+export declare const IMPERSONATE_USER_ID_HEADER = "x-pikku-impersonate-user-id";
+/**
+ * How a persona obtains a session on the target, and what every later request
+ * needs to carry to keep acting as them.
+ *
+ * Two answers exist because the two environments have opposite trust models,
+ * not because one is a fallback for the other. See {@link ActorSignIn} and
+ * {@link OperatorSignIn}.
+ */
+export interface PersonaSignIn {
+    /**
+     * Establish a session in `jar`. Throws on failure with a message naming the
+     * persona, since a run that continues unauthenticated fails later and
+     * somewhere less informative.
+     */
+    login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
+    /** Headers every request after `login` must carry. */
+    headers(): Record<string, string>;
+}
+/**
+ * Sign a persona in through the Better Auth actor plugin — the local-development
+ * path.
+ *
+ * `POST /auth/sign-in/actor` upserts an `actor: true` row and mints a session
+ * for it. Passwordless by design and refused for any row not carrying that flag,
+ * so the secret can never reach a real user's account; the plugin still declines
+ * to serve the endpoint at all outside `pikku dev`.
+ */
+export declare class ActorSignIn implements PersonaSignIn {
+    private readonly apiUrl;
+    private readonly secret;
+    private readonly signInPath;
+    constructor(apiUrl: string, secret: string, signInPath: string);
+    login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
+    headers(): Record<string, string>;
+}
+export interface OperatorSignInOptions {
+    /**
+     * The short-lived RS256 operator token, or a function that mints one. Prefer
+     * the function: tokens expire, and a long run re-logs-in after a 401.
+     */
+    token: string | (() => string | Promise<string>);
+    /**
+     * Create the persona's user row when the target has no account for that
+     * address.
+     *
+     * Off by default, which is the whole point of the deployed path: a persona is
+     * meant to be a real account somebody provisioned, and a test run that
+     * silently writes users into a live database is a side effect nobody asked
+     * for. Turn it on for throwaway stages.
+     */
+    createMissing?: boolean;
+    /** Admin endpoint prefix under apiUrl. Default `/auth/admin`. */
+    adminPath?: string;
+    /** Fabric operator sign-in path under apiUrl. Default `/auth/sign-in/fabric`. */
+    signInPath?: string;
+}
+/** What an operator handshake yields: the session, and who to act as. */
+export interface OperatorSessionResult {
+    /** `Set-Cookie` values the operator sign-in returned. */
+    setCookies: string[];
+    /** The target's own id for the persona, for the impersonation header. */
+    userId: string;
+}
+/**
+ * Establish a Fabric operator session against `apiUrl` and resolve the target's
+ * own id for `persona`, which is what the impersonation header names.
+ *
+ * Takes the fetch to use rather than making one, because the two callers need
+ * the cookies to land in different places: an HTTP persona keeps them in its
+ * jar, a browser run plants them on a Playwright context. Both need the same
+ * handshake, and it is the kind of sequence that quietly diverges once it is
+ * written twice.
+ */
+export declare const establishOperatorSession: (fetchImpl: typeof fetch, apiUrl: string, persona: ResolvedPersona, options: OperatorSignInOptions, extraHeaders?: Record<string, string>) => Promise<OperatorSessionResult>;
+/**
+ * Sign a persona in on a DEPLOYED stage, by having a Fabric operator act as
+ * them — the path that needs no test credential to exist anywhere.
+ *
+ * `POST /auth/sign-in/fabric` verifies an RS256 token against the stage's
+ * `FABRIC_AUTH_PUBLIC_KEY` and mints a session for a synthetic operator row
+ * granted the umbrella `admin` scope. Impersonation is then a header on each
+ * request rather than a second session, and its gate is that scope — not
+ * `user.role`, which is why this works without touching the app's roles.
+ *
+ * Asymmetric throughout: the stage can verify an operator token and never mint
+ * one, so nothing in a deployed environment is worth stealing. That is the
+ * property the actor secret cannot have, and the reason these are two classes
+ * instead of one with a flag.
+ */
+export declare class OperatorSignIn implements PersonaSignIn {
+    private readonly apiUrl;
+    private readonly options;
+    private userId;
+    constructor(apiUrl: string, options: OperatorSignInOptions);
+    login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
+    headers(): Record<string, string>;
+}

package/dist/services/persona-sign-in.js

@@ -0,0 +1,179 @@
+/**
+ * The header `resolveImpersonatedSession` reads the target user id from.
+ *
+ * A wire value rather than a shared import: the reader lives in
+ * `@pikku/services-better-auth`, which depends on core, so core cannot import
+ * it back. The two agree by protocol, the way an HTTP header always does.
+ */
+export const IMPERSONATE_USER_ID_HEADER = 'x-pikku-impersonate-user-id';
+const failed = async (what, personaId, res) => {
+    const body = (await res.text().catch(() => '')).slice(0, 300);
+    return new Error(`[scenario] ${what} failed for '${personaId}' (${res.status}): ${body}`);
+};
+/**
+ * Sign a persona in through the Better Auth actor plugin — the local-development
+ * path.
+ *
+ * `POST /auth/sign-in/actor` upserts an `actor: true` row and mints a session
+ * for it. Passwordless by design and refused for any row not carrying that flag,
+ * so the secret can never reach a real user's account; the plugin still declines
+ * to serve the endpoint at all outside `pikku dev`.
+ */
+export class ActorSignIn {
+    apiUrl;
+    secret;
+    signInPath;
+    constructor(apiUrl, secret, signInPath) {
+        this.apiUrl = apiUrl;
+        this.secret = secret;
+        this.signInPath = signInPath;
+    }
+    async login(jar, persona) {
+        const res = await jar.fetch(`${this.apiUrl}${this.signInPath}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                email: persona.email,
+                name: persona.name,
+                secret: this.secret,
+            }),
+        });
+        if (!res.ok) {
+            throw await failed('persona sign-in', persona.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 Error(`[scenario] persona sign-in for '${persona.id}' returned no session cookie`);
+        }
+    }
+    headers() {
+        return {};
+    }
+}
+/**
+ * Establish a Fabric operator session against `apiUrl` and resolve the target's
+ * own id for `persona`, which is what the impersonation header names.
+ *
+ * Takes the fetch to use rather than making one, because the two callers need
+ * the cookies to land in different places: an HTTP persona keeps them in its
+ * jar, a browser run plants them on a Playwright context. Both need the same
+ * handshake, and it is the kind of sequence that quietly diverges once it is
+ * written twice.
+ */
+export const establishOperatorSession = async (fetchImpl, apiUrl, persona, options, extraHeaders = {}) => {
+    const signInPath = options.signInPath ?? '/auth/sign-in/fabric';
+    const token = typeof options.token === 'function' ? await options.token() : options.token;
+    const res = await fetchImpl(`${apiUrl}${signInPath}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...extraHeaders },
+        body: JSON.stringify({ token }),
+    });
+    if (!res.ok) {
+        throw await failed('operator sign-in', persona.id, res);
+    }
+    const setCookies = res.headers.getSetCookie?.() ?? [];
+    if (setCookies.length === 0) {
+        throw new Error(`[scenario] operator sign-in for '${persona.id}' returned no session cookie`);
+    }
+    // The lookup runs on the session this handshake just established, and a
+    // plain `fetch` keeps no cookies — the browser path in particular hands the
+    // jar's contents to Playwright only after this returns. Forwarding them
+    // explicitly is what keeps the admin calls authenticated for every caller.
+    const session = setCookies
+        .map((raw) => raw.split(';')[0])
+        .filter((pair) => Boolean(pair))
+        .join('; ');
+    const userId = await resolveUserId(fetchImpl, apiUrl, persona, options, {
+        ...extraHeaders,
+        cookie: session,
+    });
+    return { setCookies, userId };
+};
+/**
+ * The target's own id for this persona's address, since impersonation names a
+ * user id and a persona only knows an email.
+ *
+ * Looked up before creating, so a persona that already exists is never
+ * duplicated and the run reads as "act as this person" rather than "make one".
+ */
+const resolveUserId = async (fetchImpl, apiUrl, persona, options, extraHeaders) => {
+    const adminPath = options.adminPath ?? '/auth/admin';
+    const query = new URLSearchParams({
+        filterField: 'email',
+        filterValue: persona.email,
+        filterOperator: 'eq',
+        limit: '1',
+    });
+    const found = await fetchImpl(`${apiUrl}${adminPath}/list-users?${query}`, {
+        headers: { accept: 'application/json', ...extraHeaders },
+    });
+    if (!found.ok) {
+        throw await failed('persona lookup', persona.id, found);
+    }
+    const listed = (await found.json().catch(() => null));
+    const existing = listed?.users?.find((u) => u.email === persona.email);
+    if (existing?.id) {
+        return String(existing.id);
+    }
+    if (!options.createMissing) {
+        throw new Error(`[scenario] no account on the target for persona '${persona.id}' (${persona.email}) — ` +
+            'provision it, or set createMissing on the operator credentials');
+    }
+    const created = await fetchImpl(`${apiUrl}${adminPath}/create-user`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...extraHeaders },
+        body: JSON.stringify({
+            email: persona.email,
+            name: persona.name,
+            // Never used and never returned: the run impersonates rather than signs
+            // in, so the account is reachable only by someone already holding an
+            // operator token. A derivable password would undo exactly that.
+            password: globalThis.crypto.randomUUID(),
+            ...(persona.roles[0] ? { role: persona.roles[0] } : {}),
+        }),
+    });
+    if (!created.ok) {
+        throw await failed('persona creation', persona.id, created);
+    }
+    const body = (await created.json().catch(() => null));
+    const id = body?.user?.id;
+    if (!id) {
+        throw new Error(`[scenario] creating persona '${persona.id}' returned no user id`);
+    }
+    return String(id);
+};
+/**
+ * Sign a persona in on a DEPLOYED stage, by having a Fabric operator act as
+ * them — the path that needs no test credential to exist anywhere.
+ *
+ * `POST /auth/sign-in/fabric` verifies an RS256 token against the stage's
+ * `FABRIC_AUTH_PUBLIC_KEY` and mints a session for a synthetic operator row
+ * granted the umbrella `admin` scope. Impersonation is then a header on each
+ * request rather than a second session, and its gate is that scope — not
+ * `user.role`, which is why this works without touching the app's roles.
+ *
+ * Asymmetric throughout: the stage can verify an operator token and never mint
+ * one, so nothing in a deployed environment is worth stealing. That is the
+ * property the actor secret cannot have, and the reason these are two classes
+ * instead of one with a flag.
+ */
+export class OperatorSignIn {
+    apiUrl;
+    options;
+    userId = null;
+    constructor(apiUrl, options) {
+        this.apiUrl = apiUrl;
+        this.options = options;
+    }
+    async login(jar, persona) {
+        const { userId } = await establishOperatorSession(jar.fetch, this.apiUrl, persona, this.options);
+        this.userId = userId;
+    }
+    headers() {
+        if (!this.userId) {
+            throw new Error('[scenario] operator session has no persona to act as — login() first');
+        }
+        return { [IMPERSONATE_USER_ID_HEADER]: this.userId };
+    }
+}

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

@@ -29,6 +29,7 @@ import type { AgentRunService } from '../wirings/agent/agent.types.js';
 import type { MiddlewareMetadata } from '../middleware/middleware.types.js';
 import type { PermissionMetadata } from '../function/function-meta.types.js';
 import type { VirtualUserRunStore } from '../wirings/virtual-user/virtual-user-run-store.js';
+import type { VirtualUserScheduleStore } from '../wirings/virtual-user/virtual-user-schedule-store.js';
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js';
 import type { CredentialService } from '../services/credential-service.js';
 import type { EmailService } from '../services/email-service.js';
@@ -135,6 +136,12 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
      * {@link VirtualUserRunStore}.
      */
     virtualUserRunStore?: VirtualUserRunStore;
+    /**
+     * Each persona'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.
+     */
+    virtualUserScheduleStore?: VirtualUserScheduleStore;
     /** V8 precise-coverage collector (`pikku dev --coverage` only) */
     coverageService?: CoverageService;
     audit?: AuditService;