@pikku/core 0.12.99 → 0.12.101

package/CHANGELOG.md

@@ -1,3 +1,51 @@
+## 0.12.101
+
+### Patch Changes
+
+- e92e30b: Print a CLI failure as its message, not as a JS stack trace.
+
+  Every error that reached the top of `executeCLI` was logged with `console.error('Error:', error)`, which node renders as the full stack — and prefixed it a second time, so a refusal read `Error: Error: Persona 'guest' missing guest…` above ten frames of pikku internals. A `PikkuFetchError` was worse: node inspects an error's own properties, so the whole `Response` came out with it, headers and body stream included, to say `502`.
+
+  An expected failure — a `PikkuError`, or anything carrying `expected: true` — now prints its message alone, and a fetch failure prints `502 Bad Gateway from <url>` without touching the response. Anything else keeps its stack, because a `TypeError` with its frames removed is undiagnosable. `--verbose`/`-v`, or `PIKKU_DEBUG=1` where the flag cannot be typed, adds the stack back to an expected failure.
+
+  The refusals behind the examples — a persona whose roles have drifted, a sign-in the stage rejected — are raised as `PikkuError` so they are classed as deliberate.
+
+- 781797c: Drive a persona's agent turn over the SSE route. The plain `POST /rpc/agent/:name` buffers the entire run before sending a byte, so any run longer than undici's 300s headers timeout failed with `UND_ERR_HEADERS_TIMEOUT` — which is most conversational agents.
+- ccab6ed: Verify a persona's roles against the app's own `getMyScopes` RPC before better-auth's `user.role`. In an app that authorizes on scopes that column is a projection — kept in step for better-auth's own admin endpoints, and absent entirely from an app that declares no such field — so a persona holding exactly what it should was refused for "roles drifted". Configurable via `rolesRpc`; `false` reads better-auth only.
+- 4d0a548: Provision the declared personas from the fabric plugin instead of the server lifecycle.
+
+  `provisionPersonas` was documented as a call an app makes from `pikkuServerLifecycle`'s `afterStart`. That hook is invoked by `pikku serve` and `pikku dev` and by nothing else — no deploy runtime calls it — so on any stage deployed to Workers or a serverless target the provisioning never ran, and every persona signed in holding no roles.
+
+  `pikkuFabric` now takes `personas`. The operator endpoint resolves the address the caller wants to act as; a miss provisions the declaration and looks again. On a stage that already holds the persona that is one query, and the pass only runs when there is genuinely something absent to create.
+
+  Sign-in no longer creates accounts of its own. `OperatorSignInOptions.createMissing` and `PIKKU_PERSONA_CREATE_MISSING` are gone, and an address no declaration claims stays a 404 however many times it is asked for. `provisionPersonas` is no longer exported — the plugin is the only caller.
+
+  `pikku persona sync <environment>` is unchanged: it still reports who an environment will provision and why anyone was skipped, and still writes nothing.
+
+## 0.12.100
+
+### Patch Changes
+
+- a0ed1e8: Derive a persona's session and operator paths from the mount its sign-in path names.
+
+  Both `sessionRoles()` and the Fabric operator handshake asked for a fixed
+  `/auth/…` no matter where auth was mounted. An app serving better-auth under
+  `/api/auth` while keeping its RPCs at the root cannot put the mount in
+  `apiUrl`, so it moves `signInPath` — and the other two stayed behind.
+
+  For the session read that meant a 404, which returns `null`, which means "this
+  stage does not report roles": every `pikku persona run` on such an app warned
+  "running unverified" and lost the one thing that tells a permissions finding
+  from seed drift. For the operator handshake it was worse — `HttpPersona`
+  reused the _actor_ path verbatim, so an operator token was posted to the actor
+  endpoint and came back as a validation error about a missing email and secret,
+  which reads like a broken persona rather than a wrong URL. The browser provider
+  had the same fixed default.
+
+  All three now follow `signInPath`, and `environments[].sessionPath` in
+  pikku.config.json overrides the session read for a stage that reports it
+  elsewhere.
+
 ## 0.12.99
 
 ### Patch Changes

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

@@ -40,10 +40,26 @@ export interface HttpPersonasConfig {
      * {@link OperatorSignInOptions.signInPath} overrides it.
      */
     signInPath?: string;
-    /** Where the session (and its roles) is read back. Default `/auth/get-session`. */
+    /**
+     * Where the session (and its roles) is read back. Defaults to `get-session`
+     * under the same auth mount as {@link HttpPersonasConfig.signInPath}, so an
+     * app that moved auth under `/api` moves this with it and does not have to
+     * say so twice.
+     */
     sessionPath?: string;
     /** Exposed-RPC path prefix under apiUrl. Default `/rpc`. */
     rpcPath?: string;
+    /**
+     * Exposed RPC that reports the CALLER's own roles, as `{ roles: string[] }`.
+     * Default `getMyScopes`. Pass `false` to skip it and read better-auth only.
+     *
+     * Asked before better-auth's `user.role`, because in an app that authorizes
+     * on scopes that column is a projection rather than the model — it exists so
+     * better-auth's own admin endpoints have something to read, is written by
+     * whatever keeps it in step, and is absent entirely from an app that declares
+     * no such field. A persona verified against it is verified against a copy.
+     */
+    rolesRpc?: string | false;
     /**
      * Default model a persona thinks with when `converse(...)` is called without
      * an explicit `model`. Its own turns/approvals/evaluation run in-process via
@@ -81,17 +97,36 @@ export declare class HttpPersona implements ScenarioPersona {
     /**
      * The roles the stage says this session holds.
      *
-     * Read from better-auth's `get-session`, which is what most pikku apps are
-     * running and where its admin plugin puts `role` — on the user, as a
-     * comma-separated list. A target that answers something else returns `null`
-     * rather than an empty list, because "this stage does not report roles" and
-     * "this person has none" call for opposite responses from the caller.
+     * {@link HttpPersonasConfig.rolesRpc} first, then better-auth's
+     * `get-session` — where its admin plugin puts `role` on the user, as a
+     * comma-separated list. A target that answers neither returns `null` rather
+     * than an empty list, because "this stage does not report roles" and "this
+     * person has none" call for opposite responses from the caller.
      */
     sessionRoles(): Promise<string[] | null>;
-    /** Start/continue the target agent's run over HTTP as this persona. */
+    /**
+     * The caller's own roles, from the app's own RPC. `null` for every answer
+     * that is not a role list — an app without the RPC 404s here, which is a
+     * reason to go on and ask better-auth, not a reason to report "none".
+     */
+    private rolesFromRpc;
+    private rolesFromSession;
+    /**
+     * Start/continue the target agent's run over HTTP as this persona.
+     *
+     * The SSE route, not the plain one. `POST /rpc/agent/:name` buffers the whole
+     * run before it sends a single byte, so a run longer than the client's
+     * headers timeout — 300s in undici, which is what Node and Bun both use —
+     * fails with `UND_ERR_HEADERS_TIMEOUT` and no way to tell it apart from a
+     * stage that is down. An agent that talks for several minutes, which is the
+     * normal case for anything conversational, cannot be driven that way at all.
+     * The stream sends its first event immediately and the run's length stops
+     * mattering.
+     */
     private agentRun;
     /** Answer the target agent's pending approvals over HTTP and continue. */
     private agentApprove;
+    private sendAgent;
     private postAgent;
     private postRpc;
     /** Drop the session, so the next call signs in again before it goes out. */

package/dist/services/http-personas.js

@@ -1,7 +1,7 @@
 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 { ActorSignIn, OperatorSignIn, authMount, } from './persona-sign-in.js';
 import { getSingletonServices } from '../pikku-state.js';
 import { AIProviderNotConfiguredError } from '../errors/errors.js';
 /**
@@ -34,7 +34,10 @@ export class HttpPersona {
         if (config.operator) {
             this.signIn = new OperatorSignIn(config.apiUrl, {
                 ...config.operator,
-                signInPath: config.operator.signInPath ?? config.signInPath,
+                signInPath: config.operator.signInPath ??
+                    (authMount(config.signInPath)
+                        ? `${authMount(config.signInPath)}/sign-in/fabric`
+                        : undefined),
             });
         }
         else if (config.secret) {
@@ -105,17 +108,48 @@ export class HttpPersona {
     /**
      * The roles the stage says this session holds.
      *
-     * Read from better-auth's `get-session`, which is what most pikku apps are
-     * running and where its admin plugin puts `role` — on the user, as a
-     * comma-separated list. A target that answers something else returns `null`
-     * rather than an empty list, because "this stage does not report roles" and
-     * "this person has none" call for opposite responses from the caller.
+     * {@link HttpPersonasConfig.rolesRpc} first, then better-auth's
+     * `get-session` — where its admin plugin puts `role` on the user, as a
+     * comma-separated list. A target that answers neither returns `null` rather
+     * than an empty list, because "this stage does not report roles" and "this
+     * person has none" call for opposite responses from the caller.
      */
     async sessionRoles() {
         if (!this.signedIn) {
             await this.login();
         }
-        const sessionPath = this.config.sessionPath ?? '/auth/get-session';
+        const fromRpc = await this.rolesFromRpc();
+        if (fromRpc)
+            return fromRpc;
+        return await this.rolesFromSession();
+    }
+    /**
+     * The caller's own roles, from the app's own RPC. `null` for every answer
+     * that is not a role list — an app without the RPC 404s here, which is a
+     * reason to go on and ask better-auth, not a reason to report "none".
+     */
+    async rolesFromRpc() {
+        const rpcName = this.config.rolesRpc ?? 'getMyScopes';
+        if (rpcName === false)
+            return null;
+        let res;
+        try {
+            res = await this.postRpc(rpcName, {});
+        }
+        catch {
+            return null;
+        }
+        if (!res.ok)
+            return null;
+        const { body } = await readScenarioHttpResponse(res);
+        const roles = body?.roles ?? body?.data?.roles;
+        if (!Array.isArray(roles))
+            return null;
+        return roles.filter((name) => typeof name === 'string');
+    }
+    async rolesFromSession() {
+        const mount = authMount(this.config.operator?.signInPath ?? this.config.signInPath);
+        const sessionPath = this.config.sessionPath ?? `${mount ?? '/auth'}/get-session`;
         const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`, {
             headers: this.signIn.headers(),
         });
@@ -148,14 +182,25 @@ export class HttpPersona {
         // stage reporting "none", not a stage that cannot report.
         return user ? [] : null;
     }
-    /** Start/continue the target agent's run over HTTP as this persona. */
+    /**
+     * Start/continue the target agent's run over HTTP as this persona.
+     *
+     * The SSE route, not the plain one. `POST /rpc/agent/:name` buffers the whole
+     * run before it sends a single byte, so a run longer than the client's
+     * headers timeout — 300s in undici, which is what Node and Bun both use —
+     * fails with `UND_ERR_HEADERS_TIMEOUT` and no way to tell it apart from a
+     * stage that is down. An agent that talks for several minutes, which is the
+     * normal case for anything conversational, cannot be driven that way at all.
+     * The stream sends its first event immediately and the run's length stops
+     * mattering.
+     */
     async agentRun(agentName, message, threadId, resourceId) {
-        const raw = await this.postAgent(`agent/${agentName}`, {
+        const res = await this.sendAgent(`agent/${agentName}/stream`, {
             message,
             threadId,
             resourceId,
         });
-        return normalizeAgentReply(raw);
+        return await collectAgentStream(res);
     }
     /** Answer the target agent's pending approvals over HTTP and continue. */
     async agentApprove(agentName, runId, decisions) {
@@ -166,7 +211,7 @@ export class HttpPersona {
         return normalizeAgentReply(raw);
     }
     // knowledge: decisions/internals/scenario-agent-calls-sign-in-on-401-only.md
-    async postAgent(subPath, body) {
+    async sendAgent(subPath, body) {
         const rpcPath = this.config.rpcPath ?? '/rpc';
         const url = `${this.config.apiUrl}${rpcPath}/${subPath}`;
         const send = () => this.jar.fetch(url, {
@@ -187,6 +232,10 @@ export class HttpPersona {
             const text = (await res.text().catch(() => '')).slice(0, 300);
             throw new Error(`[scenario] agent call '${subPath}' as '${this.name}' returned ${res.status}: ${text}`);
         }
+        return res;
+    }
+    async postAgent(subPath, body) {
+        const res = await this.sendAgent(subPath, body);
         if (res.status === 204)
             return undefined;
         const text = await res.text();
@@ -214,6 +263,80 @@ export class HttpPersona {
         this.signedIn = true;
     }
 }
+/**
+ * Reduce the agent's SSE run into the same reply shape the plain route returns.
+ *
+ * `RUN_ERROR` is raised rather than returned: the plain route answers a failed
+ * run with a non-2xx, and a scenario that read an error as an empty transcript
+ * would score the agent on silence it never produced.
+ */
+async function collectAgentStream(res) {
+    const body = res.body;
+    if (!body) {
+        throw new Error('[scenario] the agent stream carried no body');
+    }
+    const decoder = new TextDecoder();
+    const reader = body.getReader();
+    let buffer = '';
+    let text = '';
+    let runId = '';
+    const pendingApprovals = [];
+    const consume = (line) => {
+        if (!line.startsWith('data:'))
+            return;
+        const payload = line.slice(5).trim();
+        if (!payload)
+            return;
+        let event;
+        try {
+            event = JSON.parse(payload);
+        }
+        catch {
+            return;
+        }
+        if (typeof event.runId === 'string' && event.runId)
+            runId = event.runId;
+        if (event.type === 'TEXT_MESSAGE_CONTENT' &&
+            typeof event.delta === 'string') {
+            text += event.delta;
+        }
+        else if (event.type === 'approval-request') {
+            pendingApprovals.push({
+                toolCallId: String(event.toolCallId),
+                toolName: String(event.toolName),
+                args: event.args,
+                reason: typeof event.reason === 'string' ? event.reason : undefined,
+            });
+        }
+        else if (event.type === 'RUN_ERROR' || event.type === 'error') {
+            const message = event.message ?? event.errorText ?? 'the agent run failed';
+            throw new Error(`[scenario] agent run failed: ${String(message)}`);
+        }
+    };
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines)
+                consume(line);
+        }
+        if (buffer)
+            consume(buffer);
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return {
+        text,
+        runId,
+        status: pendingApprovals.length > 0 ? 'suspended' : 'completed',
+        pendingApprovals: pendingApprovals.length > 0 ? pendingApprovals : undefined,
+    };
+}
 /** Normalize an agentRun/agentApprove HTTP response into a TargetAgentReply. */
 function normalizeAgentReply(raw) {
     const r = (raw ?? {});

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

@@ -53,22 +53,24 @@ export declare class ActorSignIn implements PersonaSignIn {
     login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
     headers(): Record<string, string>;
 }
+/**
+ * The auth mount a configured sign-in path sits under, or `undefined` when it
+ * names nothing recognisable.
+ *
+ * better-auth serves sign-in, operator sign-in and `get-session` from one
+ * prefix, so an app that mounts it at `/api/auth` moves all three together and
+ * says so once through `signInPath`. Reading the other two from a hardcoded
+ * `/auth` on such an app 404s — and for `get-session` 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;
 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;
     /** Fabric operator sign-in path under apiUrl. Default `/auth/sign-in/fabric`. */
     signInPath?: string;
 }

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

@@ -1,4 +1,5 @@
 import { deriveActorSecret } from './persona-actor-secret.js';
+import { PikkuError } from '../errors/error-handler.js';
 /**
  * The header `resolveImpersonatedSession` reads the target user id from.
  *
@@ -7,9 +8,15 @@ import { deriveActorSecret } from './persona-actor-secret.js';
  * 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';
+/**
+ * A sign-in the target refused. `PikkuError`, not `Error`, so the CLI prints
+ * this message alone: an expired token or a persona 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, personaId, res) => {
     const body = (await res.text().catch(() => '')).slice(0, 300);
-    return new Error(`[scenario] ${what} failed for '${personaId}' (${res.status}): ${body}`);
+    return new PikkuError(`[scenario] ${what} failed for '${personaId}' (${res.status}): ${body}`);
 };
 /**
  * Sign a persona in through the Better Auth actor plugin — the local-development
@@ -60,6 +67,21 @@ export class ActorSignIn {
         return {};
     }
 }
+/**
+ * The auth mount a configured sign-in path sits under, or `undefined` when it
+ * names nothing recognisable.
+ *
+ * better-auth serves sign-in, operator sign-in and `get-session` from one
+ * prefix, so an app that mounts it at `/api/auth` moves all three together and
+ * says so once through `signInPath`. Reading the other two from a hardcoded
+ * `/auth` on such an app 404s — and for `get-session` 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);
+};
 /**
  * Establish a Fabric operator session against `apiUrl` and resolve the target's
  * own id for `persona`, which is what the impersonation header names.
@@ -78,12 +100,7 @@ export const establishOperatorSession = async (fetchImpl, apiUrl, persona, optio
         headers: { 'content-type': 'application/json', ...extraHeaders },
         body: JSON.stringify({
             token,
-            actAs: {
-                email: persona.email,
-                name: persona.name,
-                create: options.createMissing ?? false,
-                ...(persona.roles[0] ? { role: persona.roles[0] } : {}),
-            },
+            actAs: { email: persona.email },
         }),
     });
     if (!res.ok) {
@@ -91,12 +108,12 @@ export const establishOperatorSession = async (fetchImpl, apiUrl, persona, optio
     }
     const setCookies = res.headers.getSetCookie?.() ?? [];
     if (setCookies.length === 0) {
-        throw new Error(`[scenario] operator sign-in for '${persona.id}' returned no session cookie`);
+        throw new PikkuError(`[scenario] operator sign-in for '${persona.id}' returned no session cookie`);
     }
     const body = (await res.json().catch(() => null));
     const userId = body?.actAs?.userId;
     if (!userId) {
-        throw new Error(`[scenario] operator sign-in for '${persona.id}' returned no user to act as — ` +
+        throw new PikkuError(`[scenario] operator sign-in for '${persona.id}' returned no user to act as — ` +
             'the target is running a @pikku/better-auth too old to resolve one');
     }
     return { setCookies, userId: String(userId) };

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

@@ -1,11 +1,11 @@
 import { NotFoundError } from '../../errors/errors.js';
-import { isExpectedError } from '../../errors/error-handler.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { pikkuState } from '../../pikku-state.js';
 import { unsupportedChannelRemote } from '../channel/channel-rpc.types.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 import { LocalVariablesService } from '../../services/local-variables.js';
 import { generateCommandHelp, parseCLIArguments } from './command-parser.js';
+import { formatCLIError, wantsStackTrace } from './format-cli-error.js';
 /** The caller is expected to catch this and call `process.exit(exitCode)`. */
 export class CLIError extends Error {
     exitCode;
@@ -323,16 +323,7 @@ export async function executeCLI({ programName, args, createConfig, createSingle
         if (error instanceof CLIError) {
             throw error;
         }
-        // An expected PikkuError's message is written to be the whole output.
-        if (isExpectedError(error)) {
-            console.error(error.message);
-        }
-        else {
-            console.error('Error:', error);
-        }
-        if (args.includes('--verbose') || args.includes('-v')) {
-            console.error('Stack trace:', error.stack);
-        }
+        console.error(formatCLIError(error, { verbose: wantsStackTrace(args) }));
         throw new CLIError(error.message || String(error), 1);
     }
 }

package/dist/wirings/cli/format-cli-error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The user asked to see the machinery. `--verbose`/`-v` is the flag the CLI
+ * already documents; `PIKKU_DEBUG` is for the times the flag cannot be typed —
+ * a command that does not declare the option, or a CLI run from a script.
+ */
+export declare const wantsStackTrace: (args: string[], env?: Record<string, string | undefined>) => boolean;
+/**
+ * What the CLI prints when a command throws.
+ *
+ * A stack trace is an answer to "which line of pikku broke", and almost every
+ * failure a user actually hits is not that question: a missing role, an expired
+ * token, a gateway that is down. Those errors are written to be read, so the
+ * message alone is the whole output — an expected error is one deliberately
+ * raised as `PikkuError` (or carrying `expected: true`), and everything else
+ * keeps its stack, because an unexpected `TypeError` with its frames removed is
+ * a bug nobody can diagnose.
+ *
+ * A stack already begins with `Name: message`, so it is returned as-is: the
+ * `console.error('Error:', error)` this replaced produced the doubled
+ * `Error: Error: …` prefix that made even real traces look broken.
+ */
+export declare const formatCLIError: (error: unknown, { verbose }?: {
+    verbose?: boolean;
+}) => string;

package/dist/wirings/cli/format-cli-error.js

@@ -0,0 +1,68 @@
+import { isExpectedError } from '../../errors/error-handler.js';
+const isFetchFailure = (error) => {
+    const candidate = error;
+    return (typeof candidate?.status === 'number' &&
+        typeof candidate?.statusText === 'string' &&
+        typeof candidate?.response === 'object' &&
+        candidate.response !== null);
+};
+/**
+ * The user asked to see the machinery. `--verbose`/`-v` is the flag the CLI
+ * already documents; `PIKKU_DEBUG` is for the times the flag cannot be typed —
+ * a command that does not declare the option, or a CLI run from a script.
+ */
+export const wantsStackTrace = (args, env = process.env) => args.includes('--verbose') ||
+    args.includes('-v') ||
+    (env.PIKKU_DEBUG !== undefined &&
+        env.PIKKU_DEBUG !== '' &&
+        env.PIKKU_DEBUG !== '0');
+/**
+ * What the CLI prints when a command throws.
+ *
+ * A stack trace is an answer to "which line of pikku broke", and almost every
+ * failure a user actually hits is not that question: a missing role, an expired
+ * token, a gateway that is down. Those errors are written to be read, so the
+ * message alone is the whole output — an expected error is one deliberately
+ * raised as `PikkuError` (or carrying `expected: true`), and everything else
+ * keeps its stack, because an unexpected `TypeError` with its frames removed is
+ * a bug nobody can diagnose.
+ *
+ * A stack already begins with `Name: message`, so it is returned as-is: the
+ * `console.error('Error:', error)` this replaced produced the doubled
+ * `Error: Error: …` prefix that made even real traces look broken.
+ */
+export const formatCLIError = (error, { verbose = false } = {}) => {
+    if (isFetchFailure(error)) {
+        return formatFetchFailure(error, verbose);
+    }
+    const stack = error?.stack;
+    const message = error?.message;
+    if (!isExpectedError(error)) {
+        return typeof stack === 'string' && stack ? stack : String(error);
+    }
+    const text = typeof message === 'string' && message ? message : String(error);
+    return verbose && typeof stack === 'string' && stack
+        ? `${text}\n${stack}`
+        : text;
+};
+/**
+ * A failed HTTP call, as the line the user needs: which status, from which URL.
+ *
+ * Never the `Response` itself. Node inspects an error's own properties when it
+ * prints one, so a thrown fetch error used to dump the headers, the body stream
+ * and the redirect flags — pages of output whose only real content was the
+ * status code.
+ */
+const formatFetchFailure = (error, verbose) => {
+    const url = error.response?.url;
+    const where = url ? ` from ${url}` : '';
+    const summary = `${error.status} ${error.statusText}${where}`;
+    const message = error.message;
+    const text = message && message !== error.statusText
+        ? `${message}\n  ${summary}`
+        : summary;
+    const stack = error.stack;
+    return verbose && typeof stack === 'string' && stack
+        ? `${text}\n${stack}`
+        : text;
+};

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

@@ -18,6 +18,6 @@ export type { CorePersona, CorePersonas, PersonaAccountMeta, PersonaDefinitions,
  * Lambda deploy would load outright.
  */
 export { HttpPersona, createHttpPersonas, type HttpPersonasConfig, } from '../../services/http-personas.js';
-export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, type ActorSecretResolver, type PersonaSignIn, type OperatorSignInOptions, type OperatorSessionResult, } from '../../services/persona-sign-in.js';
+export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, type ActorSecretResolver, type PersonaSignIn, type OperatorSignInOptions, type OperatorSessionResult, authMount, } from '../../services/persona-sign-in.js';
 export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from '../../services/persona-actor-secret.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

package/dist/wirings/persona/index.js

@@ -14,6 +14,6 @@ export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './persona-
  * Lambda deploy would load outright.
  */
 export { HttpPersona, createHttpPersonas, } from '../../services/http-personas.js';
-export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, } from '../../services/persona-sign-in.js';
+export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, authMount, } from '../../services/persona-sign-in.js';
 export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from '../../services/persona-actor-secret.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

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

@@ -57,7 +57,6 @@ export declare const VIRTUAL_USER_VARIABLES: {
      * fallback for a run nobody handed a token to, which is what a schedule is.
      */
     readonly operatorToken: "FABRIC_OPERATOR_TOKEN";
-    readonly createMissing: "PIKKU_PERSONA_CREATE_MISSING";
 };
 /**
  * Which door under the auth mount, given the credential in hand.

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

@@ -34,7 +34,6 @@ export const VIRTUAL_USER_VARIABLES = {
      * fallback for a run nobody handed a token to, which is what a schedule is.
      */
     operatorToken: 'FABRIC_OPERATOR_TOKEN',
-    createMissing: 'PIKKU_PERSONA_CREATE_MISSING',
 };
 /**
  * Which door under the auth mount, given the credential in hand.
@@ -330,8 +329,6 @@ export const executeVirtualUserRun = async ({ runStore, metaService, agentRunner
             throw new Error(`Neither an operator token nor ${VIRTUAL_USER_VARIABLES.secret} is available — there is nobody for the virtual user to be. ` +
                 `Hand a Fabric operator token in with the run against a deployed stage, or export ${VIRTUAL_USER_VARIABLES.secret} against a local \`pikku dev\` target.`);
         }
-        const createMissing = String(await variables.get(VIRTUAL_USER_VARIABLES.createMissing)) ===
-            'true';
         const model = await variables.get(VIRTUAL_USER_VARIABLES.model);
         if (!model) {
             throw new Error(`${VIRTUAL_USER_VARIABLES.model} is not set — no model to think with.`);
@@ -362,7 +359,6 @@ export const executeVirtualUserRun = async ({ runStore, metaService, agentRunner
                 ? {
                     operator: {
                         token,
-                        createMissing,
                         signInPath: signInPathFor(configuredSignInPath, 'fabric'),
                     },
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.99",
+  "version": "0.12.101",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/public-surface.json

@@ -299,6 +299,7 @@
     "OperatorSignIn",
     "actorSecretSubject",
     "appScopeId",
+    "authMount",
     "buildAppScopeDefinition",
     "createHttpPersonas",
     "definePersonas",