@pikku/core 0.12.100 → 0.12.102

package/src/services/email-service.test.ts

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import type {
+  EmailAttachment,
+  EmailService,
+  SendEmailInput,
+  SendEmailResult,
+  SendHTMLEmailInput,
+  SendTemplateEmailInput,
+  SendTextEmailInput,
+} from './email-service.js'
+
+const receipt: EmailAttachment = {
+  filename: 'receipt.pdf',
+  content: new Uint8Array([1, 2, 3]),
+  contentType: 'application/pdf',
+}
+
+const logo: EmailAttachment = {
+  filename: 'logo.png',
+  content: 'aGVsbG8=',
+  contentType: 'image/png',
+  contentId: 'logo',
+  disposition: 'inline',
+}
+
+test('a text email carries attachments', () => {
+  const input: SendTextEmailInput = {
+    to: 'user@example.com',
+    text: 'Your receipt is attached',
+    attachments: [receipt],
+  }
+
+  assert.deepEqual(input.attachments, [receipt])
+})
+
+test('an html email carries attachments', () => {
+  const input: SendHTMLEmailInput = {
+    to: 'user@example.com',
+    html: '<img src="cid:logo" />',
+    attachments: [logo],
+  }
+
+  assert.equal(input.attachments?.[0]?.disposition, 'inline')
+  assert.equal(input.attachments?.[0]?.contentId, 'logo')
+})
+
+test('a template email carries attachments', () => {
+  const input: SendTemplateEmailInput = {
+    to: 'user@example.com',
+    template: { name: 'receipt', locale: 'en', data: { total: 10 } },
+    attachments: [receipt, logo],
+  }
+
+  assert.equal(input.attachments?.length, 2)
+})
+
+test('attachments are optional on every variant', () => {
+  const inputs: SendEmailInput[] = [
+    { to: 'user@example.com', text: 'hello' },
+    { to: 'user@example.com', html: '<p>hello</p>' },
+    { to: 'user@example.com', template: { name: 'welcome' } },
+  ]
+
+  for (const input of inputs) {
+    assert.equal(input.attachments, undefined)
+  }
+})
+
+test('a wrapping service forwards attachments to its delegate', async () => {
+  const sent: SendEmailInput[] = []
+  const delegate: EmailService = {
+    async send(input): Promise<SendEmailResult> {
+      sent.push(input as SendEmailInput)
+      return { messageId: 'delegated' }
+    },
+  }
+
+  const wrapper: EmailService = {
+    async send(input): Promise<SendEmailResult> {
+      const { template, ...rest } = input as SendTemplateEmailInput
+      return delegate.send({
+        ...rest,
+        subject: `rendered:${template.name}`,
+        html: '<p>rendered</p>',
+      })
+    },
+  }
+
+  const result = await wrapper.send({
+    to: 'user@example.com',
+    template: { name: 'receipt' },
+    attachments: [receipt],
+  })
+
+  assert.equal(result.messageId, 'delegated')
+  assert.equal(sent.length, 1)
+  assert.deepEqual(sent[0]!.attachments, [receipt])
+})

package/src/services/email-service.ts

@@ -6,6 +6,19 @@ export interface EmailTemplateReference {
   data?: Record<string, unknown>
 }
 
+export interface EmailAttachment {
+  filename: string
+  /**
+   * Raw bytes, or the content already base64-encoded. A `string` is always
+   * read as base64 — never as a plain-text body — so text attachments must be
+   * encoded by the caller.
+   */
+  content: Uint8Array | string
+  contentType?: string
+  contentId?: string
+  disposition?: 'attachment' | 'inline'
+}
+
 export interface BaseSendEmailInput {
   to: string | string[]
   from?: string
@@ -14,6 +27,7 @@ export interface BaseSendEmailInput {
   replyTo?: string | string[]
   headers?: Record<string, string>
   subject?: string
+  attachments?: EmailAttachment[]
 }
 
 export interface SendTextEmailInput extends BaseSendEmailInput {

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',

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/index.ts

@@ -46,6 +46,7 @@ export type {
 // knowledge: decisions/internals/the-persona-runtime-is-exported-from-the-persona-entry-point.md
 export type { JWTService } from './jwt-service.js'
 export type {
+  EmailAttachment,
   EmailService,
   SendEmailInput,
   SendEmailResult,

package/src/services/local-email-service.test.ts

@@ -106,3 +106,77 @@ test('LocalEmailService logs null textLength for HTML email without plain text',
   assert.equal(payload.htmlLength, '<p>Hello</p>'.length)
   assert.equal(payload.textLength, null)
 })
+
+test('LocalEmailService logs attachment metadata without the content', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({
+      to: 'user@example.com',
+      html: '<img src="cid:logo" />',
+      attachments: [
+        {
+          filename: 'receipt.pdf',
+          content: new Uint8Array([1, 2, 3, 4]),
+          contentType: 'application/pdf',
+        },
+        {
+          filename: 'logo.png',
+          content: 'aGVsbG8=',
+          contentType: 'image/png',
+          contentId: 'logo',
+          disposition: 'inline',
+        },
+      ],
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  const payload = JSON.parse(writes[0])
+  assert.deepEqual(payload.attachments, [
+    {
+      filename: 'receipt.pdf',
+      contentType: 'application/pdf',
+      contentId: null,
+      disposition: 'attachment',
+      contentLength: 4,
+    },
+    {
+      filename: 'logo.png',
+      contentType: 'image/png',
+      contentId: 'logo',
+      disposition: 'inline',
+      contentLength: 8,
+    },
+  ])
+  assert.equal(writes[0].includes('aGVsbG8='), false)
+})
+
+test('LocalEmailService omits attachments when there are none', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({ to: 'user@example.com', text: 'no files' })
+    await service.send({
+      to: 'user@example.com',
+      text: 'no files',
+      attachments: [],
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  assert.equal(JSON.parse(writes[0]).attachments, undefined)
+  assert.equal(JSON.parse(writes[1]).attachments, undefined)
+})

package/src/services/local-email-service.ts

@@ -27,6 +27,15 @@ export class LocalEmailService implements EmailService {
     if ('text' in input && typeof input.text === 'string') {
       payload.textLength = input.text.length
     }
+    if (input.attachments?.length) {
+      payload.attachments = input.attachments.map((attachment) => ({
+        filename: attachment.filename,
+        contentType: attachment.contentType ?? null,
+        contentId: attachment.contentId ?? null,
+        disposition: attachment.disposition ?? 'attachment',
+        contentLength: attachment.content.length,
+      }))
+    }
 
     console.info(JSON.stringify(payload))
     return {}

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 () => {