@pikku/core 0.12.100 → 0.12.101

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 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

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

@@ -49,6 +49,17 @@ export interface HttpPersonasConfig {
     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
@@ -86,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

@@ -108,16 +108,46 @@ 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 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}`, {
@@ -152,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) {
@@ -170,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, {
@@ -191,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();
@@ -218,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

@@ -71,16 +71,6 @@ export interface OperatorSignInOptions {
      * 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
@@ -93,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) {
@@ -106,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/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.100",
+  "version": "0.12.101",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/services/http-personas-converse.test.ts

@@ -57,28 +57,37 @@ const startAgentTarget = async () => {
         json({ runId: body.runId, text: 'Created it.', status: 'completed' })
         return
       }
-      if (req.url === '/api/rpc/agent/todoBot') {
+      // The SSE route, because that is the one a persona's turn goes to — the
+      // plain route buffers the whole run and dies on undici's headers timeout.
+      if (req.url === '/api/rpc/agent/todoBot/stream') {
         agentRuns++
-        if (agentRuns === 1) {
-          json({
-            runId: 'run-1',
-            text: 'Let me do that.',
-            status: 'suspended',
-            pendingApprovals: [
-              {
-                toolCallId: 'tc1',
-                toolName: 'createTodo',
-                args: { title: 'x' },
-              },
-            ],
-          })
-          return
+        const runId = `run-${agentRuns}`
+        const events: unknown[] =
+          agentRuns === 1
+            ? [
+                { type: 'RUN_STARTED', runId },
+                { type: 'TEXT_MESSAGE_CONTENT', delta: 'Let me ' },
+                { type: 'TEXT_MESSAGE_CONTENT', delta: 'do that.' },
+                {
+                  type: 'approval-request',
+                  runId,
+                  toolCallId: 'tc1',
+                  toolName: 'createTodo',
+                  args: { title: 'x' },
+                },
+                { type: 'done' },
+              ]
+            : [
+                { type: 'RUN_STARTED', runId },
+                { type: 'TEXT_MESSAGE_CONTENT', delta: 'All set.' },
+                { type: 'RUN_FINISHED', runId },
+                { type: 'done' },
+              ]
+        res.writeHead(200, { 'content-type': 'text/event-stream' })
+        for (const event of events) {
+          res.write(`data: ${JSON.stringify(event)}\n\n`)
         }
-        json({
-          runId: `run-${agentRuns}`,
-          text: 'All set.',
-          status: 'completed',
-        })
+        res.end()
         return
       }
       res.writeHead(404).end()

package/src/services/http-personas.test.ts

@@ -66,6 +66,16 @@ const startTarget = async () => {
           return
         }
         const rpcName = req.url.slice('/api/rpc/'.length)
+        if (rpcName === 'getMyScopes') {
+          res
+            .writeHead(200, { 'content-type': 'application/json' })
+            .end(JSON.stringify({ scopes: ['stays:read'], roles: ['guest'] }))
+          return
+        }
+        if (rpcName === 'noSuchRpc') {
+          res.writeHead(404).end()
+          return
+        }
         if (rpcName === 'html-error') {
           res
             .writeHead(500, { 'content-type': 'text/html' })
@@ -261,12 +271,68 @@ describe('HttpPersona', async () => {
   // mount in `apiUrl`, so it moves `signInPath` instead. The session read has
   // to follow it: a 404 there reads as 'this stage does not report roles' and
   // silently turns the role check off.
+  //
+  // `rolesRpc: false` because this is about the better-auth path specifically —
+  // leaving the RPC in would answer first and the mount would go untested.
   test('reads the session from the mount the sign-in path names', async () => {
     const actors = createHttpPersonas({
       apiUrl: target.origin,
       secret: ROOT,
       signInPath: '/api/auth/sign-in/actor',
       rpcPath: '/api/rpc',
+      rolesRpc: false,
+      personas: {
+        manager: {
+          id: 'manager',
+          name: 'Manager',
+          email: 'manager@personas.invalid',
+          roles: ['admin'],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
+      },
+    })
+
+    assert.deepEqual(await actors.manager!.sessionRoles(), ['admin', 'support'])
+  })
+
+  // Scopes are the model in an app that authorizes on them; better-auth's
+  // `user.role` is a projection kept in step for its own admin endpoints, and
+  // is absent entirely from an app that declares no such field. Reading the
+  // projection is how a guest holding exactly what it should got refused for
+  // "roles drifted".
+  test('reads roles from the app RPC in preference to better-auth', async () => {
+    const actors = createHttpPersonas({
+      apiUrl: target.origin,
+      secret: ROOT,
+      signInPath: '/api/auth/sign-in/actor',
+      rpcPath: '/api/rpc',
+      personas: {
+        manager: {
+          id: 'manager',
+          name: 'Manager',
+          email: 'manager@personas.invalid',
+          roles: ['guest'],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
+      },
+    })
+
+    assert.deepEqual(await actors.manager!.sessionRoles(), ['guest'])
+  })
+
+  // An app without the RPC is not an app reporting "no roles" — going quiet
+  // there would turn every persona into a mismatch against an empty list.
+  test('falls back to better-auth when the roles RPC is absent', async () => {
+    const actors = createHttpPersonas({
+      apiUrl: target.origin,
+      secret: ROOT,
+      signInPath: '/api/auth/sign-in/actor',
+      rpcPath: '/api/rpc',
+      rolesRpc: 'noSuchRpc',
       personas: {
         manager: {
           id: 'manager',