@pikku/core 0.12.100 → 0.12.101

package/src/services/http-personas.ts

@@ -10,6 +10,7 @@ import type {
   ConverseOptions,
   ActorFlowVerdict,
   TargetAgentReply,
+  TargetPendingApproval,
 } from '../wirings/actor-flow/actor-flow.types.js'
 import { runConversation } from '../wirings/actor-flow/run-conversation.js'
 import {
@@ -75,6 +76,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
@@ -207,16 +219,46 @@ export 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.
    */
   async sessionRoles(): Promise<string[] | null> {
     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".
+   */
+  private async rolesFromRpc(): Promise<string[] | null> {
+    const rpcName = this.config.rolesRpc ?? 'getMyScopes'
+    if (rpcName === false) return null
+    let res: Response
+    try {
+      res = await this.postRpc(rpcName, {})
+    } catch {
+      return null
+    }
+    if (!res.ok) return null
+    const { body } = await readScenarioHttpResponse<{
+      roles?: unknown
+      data?: { roles?: unknown }
+    }>(res)
+    const roles = body?.roles ?? body?.data?.roles
+    if (!Array.isArray(roles)) return null
+    return roles.filter((name): name is string => typeof name === 'string')
+  }
+
+  private async rolesFromSession(): Promise<string[] | null> {
     const mount = authMount(
       this.config.operator?.signInPath ?? this.config.signInPath
     )
@@ -254,19 +296,30 @@ export class HttpPersona implements ScenarioPersona {
     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.
+   */
   private async agentRun(
     agentName: string,
     message: string,
     threadId: string,
     resourceId: string
   ): Promise<TargetAgentReply> {
-    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. */
@@ -283,7 +336,7 @@ export class HttpPersona implements ScenarioPersona {
   }
 
   // knowledge: decisions/internals/scenario-agent-calls-sign-in-on-401-only.md
-  private async postAgent(subPath: string, body: unknown): Promise<unknown> {
+  private async sendAgent(subPath: string, body: unknown): Promise<Response> {
     const rpcPath = this.config.rpcPath ?? '/rpc'
     const url = `${this.config.apiUrl}${rpcPath}/${subPath}`
     const send = () =>
@@ -308,6 +361,11 @@ export class HttpPersona implements ScenarioPersona {
         `[scenario] agent call '${subPath}' as '${this.name}' returned ${res.status}: ${text}`
       )
     }
+    return res
+  }
+
+  private async postAgent(subPath: string, body: unknown): Promise<unknown> {
+    const res = await this.sendAgent(subPath, body)
     if (res.status === 204) return undefined
     const text = await res.text()
     return text ? JSON.parse(text) : undefined
@@ -342,6 +400,77 @@ export class HttpPersona implements ScenarioPersona {
   }
 }
 
+/**
+ * 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: Response): Promise<TargetAgentReply> {
+  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: TargetPendingApproval[] = []
+
+  const consume = (line: string) => {
+    if (!line.startsWith('data:')) return
+    const payload = line.slice(5).trim()
+    if (!payload) return
+    let event: Record<string, unknown>
+    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: unknown): TargetAgentReply {
   const r = (raw ?? {}) as Record<string, unknown>

package/src/services/persona-sign-in.test.ts

@@ -14,7 +14,7 @@ const OPERATOR_TOKEN = 'operator.jwt.token'
  */
 const startStage = async (seeded: Array<{ id: string; email: string }>) => {
   const users = [...seeded]
-  let created = 0
+  const sentBodies: unknown[] = []
   const server: Server = createServer((req, res) => {
     const chunks: Buffer[] = []
     req.on('data', (c) => chunks.push(c))
@@ -31,21 +31,15 @@ const startStage = async (seeded: Array<{ id: string; email: string }>) => {
         }
         let actAs: { userId: string } | undefined
         if (body.actAs) {
-          let user = users.find((u) => u.email === body.actAs.email)
+          sentBodies.push(body.actAs)
+          const user = users.find((u) => u.email === body.actAs.email)
           if (!user) {
-            if (!body.actAs.create) {
-              res
-                .writeHead(404)
-                .end(
-                  JSON.stringify({
-                    message: `No account on this stage for ${body.actAs.email}`,
-                  })
-                )
-              return
-            }
-            created++
-            user = { id: `made-${created}`, email: body.actAs.email }
-            users.push(user)
+            res.writeHead(404).end(
+              JSON.stringify({
+                message: `No account on this stage for ${body.actAs.email}`,
+              })
+            )
+            return
           }
           actAs = { userId: user.id }
         }
@@ -74,8 +68,8 @@ const startStage = async (seeded: Array<{ id: string; email: string }>) => {
   return {
     apiUrl: `http://127.0.0.1:${port}/api`,
     server,
-    get createdCount() {
-      return created
+    get sentBodies() {
+      return sentBodies
     },
   }
 }
@@ -112,7 +106,6 @@ describe('operator persona sign-in', () => {
     }
     assert.equal(result.actingAs, 'user-7')
     assert.match(result.cookie, /session=operator/)
-    assert.equal(stage.createdCount, 0)
   })
 
   // An app that mounts auth somewhere other than the root moves both sign-in
@@ -151,24 +144,25 @@ describe('operator persona sign-in', () => {
       () => personas.customer!.invoke('whoami', {}),
       /operator sign-in failed for 'customer' \(404\)/
     )
-    assert.equal(stage.createdCount, 0)
   })
 
-  test('provisions the account only when told to', async () => {
-    const stage = await startStage([])
+  // Provisioning moved into the stage, so the handshake carries an address and
+  // nothing else. A `create` flag or a role list here would be the caller
+  // deciding what the stage holds, which is the arrangement this replaced.
+  test('asks only to act as an address', async () => {
+    const stage = await startStage([
+      { id: 'user-3', email: 'customer@personas.invalid' },
+    ])
     servers.push(stage.server)
 
     const personas = createHttpPersonas({
       apiUrl: stage.apiUrl,
-      operator: { token: OPERATOR_TOKEN, createMissing: true },
-      personas: { customer: persona('fresh@personas.invalid') },
+      operator: { token: OPERATOR_TOKEN },
+      personas: { customer: persona('customer@personas.invalid') },
     })
 
-    const result = (await personas.customer!.invoke('whoami', {})) as {
-      actingAs: string | null
-    }
-    assert.equal(result.actingAs, 'made-1')
-    assert.equal(stage.createdCount, 1)
+    await personas.customer!.invoke('whoami', {})
+    assert.deepEqual(stage.sentBodies, [{ email: 'customer@personas.invalid' }])
   })
 
   test('mints the operator session from a token factory', async () => {

package/src/services/persona-sign-in.ts

@@ -1,4 +1,5 @@
 import { deriveActorSecret } from './persona-actor-secret.js'
+import { PikkuError } from '../errors/error-handler.js'
 import type { ResolvedPersona } from './personas-service.js'
 import type { ScenarioCookieJar } from '../wirings/workflow/scenario-cookie-jar.js'
 
@@ -30,13 +31,19 @@ export interface PersonaSignIn {
   headers(): Record<string, string>
 }
 
+/**
+ * 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: string,
   personaId: string,
   res: Response
 ): Promise<Error> => {
   const body = (await res.text().catch(() => '')).slice(0, 300)
-  return new Error(
+  return new PikkuError(
     `[scenario] ${what} failed for '${personaId}' (${res.status}): ${body}`
   )
 }
@@ -123,16 +130,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
 }
@@ -171,12 +168,7 @@ export const establishOperatorSession = async (
     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) {
@@ -184,7 +176,7 @@ export const establishOperatorSession = async (
   }
   const setCookies = res.headers.getSetCookie?.() ?? []
   if (setCookies.length === 0) {
-    throw new Error(
+    throw new PikkuError(
       `[scenario] operator sign-in for '${persona.id}' returned no session cookie`
     )
   }
@@ -194,7 +186,7 @@ export const establishOperatorSession = async (
   } | null
   const userId = body?.actAs?.userId
   if (!userId) {
-    throw new Error(
+    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'
     )

package/src/wirings/cli/cli-runner.test.ts

@@ -1,6 +1,7 @@
 import { test, describe, beforeEach, afterEach } from 'node:test'
 import * as assert from 'assert'
 import { NotFoundError } from '../../errors/errors.js'
+import { PikkuError } from '../../errors/error-handler.js'
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js'
 import {
   CLIError,
@@ -724,5 +725,108 @@ describe('CLI Runner', () => {
         singletonServices
       )
     })
+    const wireFailingCommand = (error: unknown) => {
+      pikkuState(null, 'cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              boom: {
+                command: 'boom',
+                pikkuFuncId: 'boomFunc',
+                positionals: [],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+      pikkuState(null, 'cli', 'programs', {
+        'test-cli': {
+          defaultRenderer: undefined,
+          middleware: [],
+          renderers: {},
+        },
+      })
+      pikkuState(null, 'function', 'meta', {
+        boomFunc: {
+          pikkuFuncId: 'boomFunc',
+          inputSchemaName: null,
+          outputSchemaName: null,
+          sessionless: true,
+        },
+      })
+      addFunction('boomFunc', {
+        func: async () => {
+          throw error
+        },
+        auth: false,
+      })
+    }
+
+    const captureStderr = async (run: () => Promise<void>) => {
+      const errors: string[] = []
+      const originalError = console.error
+      console.error = (message?: any) => {
+        errors.push(String(message))
+      }
+      try {
+        await assert.rejects(run, CLIError)
+      } finally {
+        console.error = originalError
+      }
+      return errors
+    }
+
+    test('should print an expected failure as its message alone', async () => {
+      wireFailingCommand(new PikkuError('Refusing to run — the seed drifted.'))
+
+      const errors = await captureStderr(() =>
+        executeCLI({
+          programName: 'test-cli',
+          args: ['boom'],
+          createSingletonServices: async () => singletonServices,
+        })
+      )
+
+      assert.deepStrictEqual(errors, ['Refusing to run — the seed drifted.'])
+    })
+
+    test('should keep the stack of an unexpected failure', async () => {
+      wireFailingCommand(new TypeError('cannot read x of undefined'))
+
+      const errors = await captureStderr(() =>
+        executeCLI({
+          programName: 'test-cli',
+          args: ['boom'],
+          createSingletonServices: async () => singletonServices,
+        })
+      )
+
+      assert.strictEqual(errors.length, 1)
+      assert.ok(errors[0]!.startsWith('TypeError: cannot read x of undefined'))
+      assert.ok(errors[0]!.includes('at '))
+      assert.ok(!errors[0]!.includes('Error: Error:'))
+    })
+
+    test('should add the stack of an expected failure when --verbose is passed', async () => {
+      wireFailingCommand(new PikkuError('Refusing to run.'))
+
+      const errors = await captureStderr(() =>
+        executeCLI({
+          programName: 'test-cli',
+          args: ['boom', '--verbose'],
+          createSingletonServices: async () => singletonServices,
+        })
+      )
+
+      // `--verbose` is not an option this command declares, so the parser
+      // warns about it first — the trace is whatever it printed last.
+      const printed = errors.at(-1)!
+      assert.ok(printed.startsWith('Refusing to run.\n'))
+      assert.ok(printed.includes('at '))
+    })
   })
 })

package/src/wirings/cli/cli-runner.ts

@@ -1,5 +1,4 @@
 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 type { CoreUserSession } from '../../types/core.types.js'
@@ -30,6 +29,7 @@ import {
 } 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 {
@@ -532,16 +532,7 @@ export async function executeCLI({
       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/src/wirings/cli/format-cli-error.test.ts

@@ -0,0 +1,91 @@
+import { test, describe } from 'node:test'
+import * as assert from 'assert'
+import { PikkuError } from '../../errors/error-handler.js'
+import { formatCLIError, wantsStackTrace } from './format-cli-error.js'
+
+describe('formatCLIError', () => {
+  test('prints an expected error as its message alone', () => {
+    const error = new PikkuError(
+      "Persona 'guest' missing guest. Refusing to run."
+    )
+    assert.strictEqual(
+      formatCLIError(error),
+      "Persona 'guest' missing guest. Refusing to run."
+    )
+  })
+
+  test('prints an error flagged as expected as its message alone', () => {
+    const error = Object.assign(new Error('token expired'), { expected: true })
+    assert.strictEqual(formatCLIError(error), 'token expired')
+  })
+
+  test('keeps the stack for an unexpected error', () => {
+    const error = new TypeError('cannot read properties of undefined')
+    const output = formatCLIError(error)
+    assert.ok(output.includes('TypeError: cannot read properties of undefined'))
+    assert.ok(output.includes('at '))
+  })
+
+  test('does not double the error name', () => {
+    const output = formatCLIError(new Error('boom'))
+    assert.ok(!output.includes('Error: Error:'))
+    assert.ok(output.startsWith('Error: boom'))
+  })
+
+  test('adds the stack to an expected error when verbose', () => {
+    const error = new PikkuError('nope')
+    const output = formatCLIError(error, { verbose: true })
+    assert.ok(output.startsWith('nope\n'))
+    assert.ok(output.includes('at '))
+  })
+
+  test('summarises a fetch failure without inspecting the response', () => {
+    const error = Object.assign(new Error('Bad Gateway'), {
+      status: 502,
+      statusText: 'Bad Gateway',
+      response: {
+        url: 'https://api.pikkufabric.com/rpc/getDeploymentStatus',
+        headers: { forbidden: 'do not print me' },
+        body: 'a stream',
+      },
+    })
+    assert.strictEqual(
+      formatCLIError(error),
+      '502 Bad Gateway from https://api.pikkufabric.com/rpc/getDeploymentStatus'
+    )
+  })
+
+  test('keeps a fetch failure message that says more than the status', () => {
+    const error = Object.assign(new Error('Deployment not found'), {
+      status: 404,
+      statusText: 'Not Found',
+      response: { url: 'https://api.pikkufabric.com/rpc/getDeploymentStatus' },
+    })
+    assert.strictEqual(
+      formatCLIError(error),
+      'Deployment not found\n' +
+        '  404 Not Found from https://api.pikkufabric.com/rpc/getDeploymentStatus'
+    )
+  })
+
+  test('falls back to a string for a thrown non-error', () => {
+    assert.strictEqual(formatCLIError('just a string'), 'just a string')
+  })
+})
+
+describe('wantsStackTrace', () => {
+  test('is off by default', () => {
+    assert.strictEqual(wantsStackTrace(['deploy'], {}), false)
+  })
+
+  test('honours --verbose and -v', () => {
+    assert.strictEqual(wantsStackTrace(['deploy', '--verbose'], {}), true)
+    assert.strictEqual(wantsStackTrace(['deploy', '-v'], {}), true)
+  })
+
+  test('honours PIKKU_DEBUG, but not when it is switched off', () => {
+    assert.strictEqual(wantsStackTrace(['deploy'], { PIKKU_DEBUG: '1' }), true)
+    assert.strictEqual(wantsStackTrace(['deploy'], { PIKKU_DEBUG: '0' }), false)
+    assert.strictEqual(wantsStackTrace(['deploy'], { PIKKU_DEBUG: '' }), false)
+  })
+})