@pikku/core 0.12.74 → 0.12.78

package/src/wirings/ai-agent/voice-input.ts

@@ -70,13 +70,35 @@ async function fetchAsUint8Array(
   return new Uint8Array(buffer)
 }
 
+/**
+ * Shared-notes key recording whether the user's turn arrived as audio.
+ *
+ * Written here because this is the last point at which it is knowable: the
+ * transcript that replaces the audio is indistinguishable from something typed.
+ * Read by `voiceOutput` to decide whether to answer aloud.
+ *
+ * Absent — rather than `false` — when this middleware is not wired at all, which
+ * is what lets `voiceOutput` still speak for a caller that has no voice input.
+ */
+export const SPOKEN_TURN = 'voice:spokenTurn'
+
+/**
+ * Shared-notes key holding what the user was heard to say, when they spoke.
+ *
+ * Absent on a typed turn. Read by the stream wiring, which forwards it to the
+ * client as a `transcript` event — a voice client has no idea what its own
+ * audio said, and without this the user's turn shows up in the UI as an empty
+ * bubble followed by an answer to a question they cannot see.
+ */
+export const SPOKEN_TRANSCRIPT = 'voice:transcript'
+
 export const voiceInput = (config?: {
   language?: string
   model?: string
   allowedAudioHosts?: string[]
 }) =>
   pikkuAIMiddleware({
-    modifyInput: async (services, { messages, instructions }) => {
+    modifyInput: async (services, { messages, instructions, shared }) => {
       const aiAgentRunner = (
         services as {
           aiAgentRunner?: AIAgentRunnerService
@@ -85,19 +107,22 @@ export const voiceInput = (config?: {
       if (!aiAgentRunner?.transcribe) return { messages, instructions }
 
       const last = messages[messages.length - 1]
-      if (!last || last.role !== 'user' || typeof last.content === 'string') {
-        return { messages, instructions }
-      }
-
-      const parts = last.content as AIContentPart[]
-      if (!parts) return { messages, instructions }
+      const parts =
+        last?.role === 'user' && typeof last.content !== 'string'
+          ? (last.content as AIContentPart[] | undefined)
+          : undefined
 
-      const hasAudio = parts.some(
+      const hasAudio = !!parts?.some(
         (p) => p.type === 'file' && !!p.mediaType?.startsWith('audio/')
       )
-      if (!hasAudio) return { messages, instructions }
+      // Recorded on every turn this middleware sees, spoken or not, so that a
+      // typed turn is an explicit `false` downstream rather than a silence that
+      // could equally mean nobody was asked.
+      shared[SPOKEN_TURN] = hasAudio
+      if (!hasAudio || !parts) return { messages, instructions }
 
       const updatedContent: AIContentPart[] = []
+      const heard: string[] = []
       for (const p of parts) {
         if (!(p.type === 'file' && p.mediaType?.startsWith('audio/'))) {
           updatedContent.push(p)
@@ -111,6 +136,9 @@ export const voiceInput = (config?: {
         const audioData = p.data
           ? base64ToUint8Array(p.data)
           : await fetchAsUint8Array(p.url!, config.allowedAudioHosts)
+        if (audioData.byteLength > MAX_AUDIO_SIZE) {
+          throw new Error('Audio file exceeds maximum size')
+        }
         const result = await aiAgentRunner.transcribe({
           model: config.model,
           audio: audioData,
@@ -128,6 +156,7 @@ export const voiceInput = (config?: {
         // model will answer, and what it answers is a guess about what it could
         // not hear.
         if (readsAsNonSpeech(result)) continue
+        heard.push(result.text)
         updatedContent.push({ type: 'text' as const, text: result.text })
       }
 
@@ -135,6 +164,16 @@ export const voiceInput = (config?: {
       // to send, and a message with no content is not a question.
       if (updatedContent.length === 0) throw new NoSpeechDetectedError()
 
+      // Only when something was actually heard. A turn can carry audio that all
+      // reads as non-speech and still have content — an image with a silent
+      // caption clip — which leaves nothing above to throw. Recording `''` here
+      // would send a transcript event saying the user said nothing, and a client
+      // that tells "not transcribed yet" from "transcribed" by the key being
+      // absent would render the turn as an empty bubble rather than a pending one.
+      if (heard.length > 0) {
+        shared[SPOKEN_TRANSCRIPT] = heard.join(' ')
+      }
+
       return {
         messages: [
           ...messages.slice(0, -1),

package/src/wirings/ai-agent/voice-output.test.ts

@@ -7,6 +7,7 @@ import {
   voiceForText,
 } from './voice-output.js'
 import type { AIStreamEvent } from './ai-agent.types.js'
+import { SPOKEN_TURN } from './voice-input.js'
 
 const KOKORO_SCRIPTS = ['latin', 'devanagari', 'han', 'kana']
 
@@ -33,7 +34,8 @@ const deferred = () => {
  */
 const createStream = (
   mw: ReturnType<typeof voiceOutput>,
-  services: unknown
+  services: unknown,
+  shared: Record<string, unknown> = {}
 ) => {
   const state: Record<string, unknown> = {}
   const allEvents: AIStreamEvent[] = []
@@ -54,6 +56,7 @@ const createStream = (
         event,
         allEvents,
         state,
+        shared,
         emit: next,
       })
       if (result == null) return
@@ -314,6 +317,93 @@ describe('voiceOutput', () => {
     ])
   })
 
+  test('a typed turn is answered in text only', async () => {
+    // The cost case. One agent serves both kinds of caller, so a reply to
+    // something typed must not quietly synthesize speech nobody asked to hear
+    // — it is billed per sentence, on every turn.
+    const asked: string[] = []
+    const services = {
+      aiAgentRunner: {
+        generateSpeech: async ({ text }: { text: string }) => {
+          asked.push(text)
+          return speechFor(text)
+        },
+      },
+    }
+    const stream = createStream(voiceOutput({ model: 'mock/tts' }), services, {
+      [SPOKEN_TURN]: false,
+    })
+
+    await stream.send({ type: 'text-delta', text: 'Added it.' })
+    await stream.send({ type: 'done' })
+
+    assert.deepEqual(asked, [])
+    assert.deepEqual(stream.types(), ['text-delta', 'done'])
+  })
+
+  test('a spoken turn is answered aloud', async () => {
+    const asked: string[] = []
+    const services = {
+      aiAgentRunner: {
+        generateSpeech: async ({ text }: { text: string }) => {
+          asked.push(text)
+          return speechFor(text)
+        },
+      },
+    }
+    const stream = createStream(voiceOutput({ model: 'mock/tts' }), services, {
+      [SPOKEN_TURN]: true,
+    })
+
+    await stream.send({ type: 'text-delta', text: 'Added it.' })
+    await stream.send({ type: 'done' })
+
+    assert.deepEqual(asked, ['Added it.'])
+  })
+
+  test('`always` speaks a typed turn too', async () => {
+    // Read-aloud modes exist, and for them speech is not a reply to speech.
+    const asked: string[] = []
+    const services = {
+      aiAgentRunner: {
+        generateSpeech: async ({ text }: { text: string }) => {
+          asked.push(text)
+          return speechFor(text)
+        },
+      },
+    }
+    const stream = createStream(
+      voiceOutput({ model: 'mock/tts', always: true }),
+      services,
+      { [SPOKEN_TURN]: false }
+    )
+
+    await stream.send({ type: 'text-delta', text: 'Added it.' })
+    await stream.send({ type: 'done' })
+
+    assert.deepEqual(asked, ['Added it.'])
+  })
+
+  test('speaks when nothing reported how the turn arrived', async () => {
+    // voiceOutput without voiceInput: nobody set the note, so there is no
+    // evidence the turn was typed and the pre-existing behaviour stands.
+    const asked: string[] = []
+    const services = {
+      aiAgentRunner: {
+        generateSpeech: async ({ text }: { text: string }) => {
+          asked.push(text)
+          return speechFor(text)
+        },
+      },
+    }
+    const stream = createStream(voiceOutput({ model: 'mock/tts' }), services)
+
+    await stream.send({ type: 'text-delta', text: 'Added it.' })
+    await stream.send({ type: 'done' })
+
+    assert.deepEqual(asked, ['Added it.'])
+  })
+
   test('a script with no voice mapped is still refused, not mis-voiced', async () => {
     const asked: string[] = []
     const services = {

package/src/wirings/ai-agent/voice-output.ts

@@ -1,5 +1,6 @@
 import type { AIAgentRunnerService } from '../../services/ai-agent-runner-service.js'
 import { pikkuAIMiddleware } from '../../types/core.types.js'
+import { SPOKEN_TURN } from './voice-input.js'
 
 type VoiceOutputState = {
   textBuffer?: string
@@ -178,15 +179,40 @@ export const voiceOutput = (config?: {
    * the right default for a provider that genuinely is multilingual.
    */
   speakableScripts?: SpeakableScripts
+  /**
+   * Speak every reply, including answers to turns that were typed.
+   *
+   * The default is to speak only what was spoken to. An agent is usually one
+   * agent serving both kinds of caller — the same thread is typed at from a
+   * desk and talked to from a phone — and synthesizing a reply nobody is
+   * listening to costs real money on every sentence of every turn. Whether the
+   * user is in a call is not something the client needs to declare: sending
+   * audio is what saying so looks like.
+   *
+   * Set this for the cases where speech is not a reply to speech at all — a
+   * read-aloud accessibility mode, a kiosk, anything whose whole output is
+   * meant to be heard.
+   */
+  always?: boolean
 }) =>
   pikkuAIMiddleware<VoiceOutputState>({
-    modifyOutputStream: async (services, { event, state, emit, signal }) => {
+    modifyOutputStream: async (
+      services,
+      { event, state, shared, emit, signal }
+    ) => {
       const { aiAgentRunner, logger } = services as {
         aiAgentRunner?: AIAgentRunnerService
         logger?: { error: (message: string) => void }
       }
       if (!aiAgentRunner?.generateSpeech) return event
 
+      // Only an explicit `false` silences the reply. `voiceInput` sets this on
+      // every turn it handles, so `false` means a real user really typed; the
+      // key being absent means nothing reported either way — no voice input is
+      // wired — and that caller's replies are spoken exactly as they were before
+      // this option existed.
+      if (!config?.always && shared[SPOKEN_TURN] === false) return event
+
       /**
        * Queue a finished sentence for speech.
        *
@@ -261,6 +287,7 @@ export const voiceOutput = (config?: {
             type: 'audio-delta',
             data: bufferToBase64(result.audio.bytes),
             format: result.audio.format,
+            text,
           })
         })
       }

package/src/wirings/cli/channel/cli-raw-client-runner.ts

@@ -7,18 +7,48 @@ import type {
   Capabilities,
 } from '../../channel/channel-rpc.js'
 import { approverForMode, takeApprovalFlags } from './cli-approval.js'
-import type { CorePikkuCLIRender } from '../cli.types.js'
+import type { Logger } from '../../../services/logger.js'
+
+/**
+ * Everything a renderer gets when the command ran on the server: a logger, and
+ * nothing else. There is no container on this side of the socket to resolve a
+ * service from, so this is the whole of it rather than a subset of
+ * `CoreSingletonServices` — which requires `config`, `variables` and `secrets`
+ * the client does not have and cannot invent.
+ */
+export type ClientCLIRenderServices = { logger: Logger }
+
+/**
+ * A renderer that runs on the client of a CLI-over-channel connection.
+ *
+ * Deliberately not `CorePikkuCLIRender`: that type's `Services` parameter is
+ * constrained to `CoreSingletonServices`, so the honest logger-only shape
+ * cannot be spelled through it.
+ */
+export type CorePikkuCLIClientRender<Data> = (
+  services: ClientCLIRenderServices,
+  data: Data,
+  session?: undefined
+) => void | Promise<void>
 
 /** The normal case once the server owns the command tree. */
-const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
+const defaultJSONRenderer: CorePikkuCLIClientRender<any> = (_services, data) => {
   console.log(JSON.stringify(data))
 }
 
-/**
- * The command ran on the server, so there are no services here — but a renderer
- * written for local execution can still reach for `services.logger`.
- */
-const clientServices = { logger: console } as any
+// `console` is the whole logger a CLI wants — its output is the command's output.
+// `setLevel` is a no-op rather than an omission because `Logger` requires it and
+// there is no level to set: a renderer writes what the user asked to see.
+const clientServices: ClientCLIRenderServices = {
+  logger: {
+    info: (...args: any[]) => console.info(...(args as [any])),
+    warn: (...args: any[]) => console.warn(...(args as [any])),
+    error: (...args: any[]) => console.error(...(args as [any])),
+    debug: (...args: any[]) => console.debug(...(args as [any])),
+    trace: (...args: any[]) => console.trace(...(args as [any])),
+    setLevel: () => {},
+  },
+}
 
 /**
  * Runs a CLI command entirely on the server. Unlike `executeCLIViaChannel`,
@@ -40,8 +70,8 @@ export async function executeRawCLIViaChannel({
 }: {
   pikkuWS: any // CorePikkuWebsocket instance
   args?: string[]
-  renderers?: Record<string, CorePikkuCLIRender<any>>
-  defaultRenderer?: CorePikkuCLIRender<any>
+  renderers?: Record<string, CorePikkuCLIClientRender<any>>
+  defaultRenderer?: CorePikkuCLIClientRender<any>
   capabilities?: Capabilities
   approve?: ApprovalRequester
 }): Promise<number> {

package/src/wirings/cli/channel/index.ts

@@ -2,6 +2,10 @@ export { executeCLIViaChannel } from './cli-channel-runner.js'
 export { handleRawCLI } from './cli-raw-channel-runner.js'
 export type { RawCLIFrame, RawCLIResult } from './cli-raw-channel-runner.js'
 export { executeRawCLIViaChannel } from './cli-raw-client-runner.js'
+export type {
+  ClientCLIRenderServices,
+  CorePikkuCLIClientRender,
+} from './cli-raw-client-runner.js'
 export {
   APPROVAL_FLAGS,
   approverForMode,

package/src/wirings/persona/define-personas.ts

@@ -11,6 +11,10 @@ import type { CorePersonas } from './persona.types.js'
  * running: a persona that exists only to be acted upon (the account an admin
  * bans, the colleague a document is shared with) is seeded and never run.
  *
+ * Exactly one `definePersonas(...)` is allowed per codebase, so there is one
+ * place to read the cast from and one place to add to. A second call — even in
+ * the same file — fails the build.
+ *
  * @example
  * ```typescript
  * definePersonas({

package/src/wirings/persona/persona.types.ts

@@ -38,6 +38,16 @@ export type CorePersona = {
   name: string
   jobTitle?: string
   description?: string
+  /**
+   * A picture of this person, as any URL a browser can load: a file your app
+   * serves, an asset on a CDN, a Gravatar link.
+   *
+   * Optional because it is decoration. Omitted, the console draws a colour and
+   * an icon derived from the persona's id, which is stable, needs no network and
+   * is more legible than the identicon a synthetic address would resolve to —
+   * which is also why nothing is derived here.
+   */
+  avatarUrl?: string
   /**
    * The roles this person holds. Only system roles may be named — a custom
    * role can be deleted from the console, so a persona pinned to one silently
@@ -112,6 +122,7 @@ export type PersonaMeta = {
   name: string
   jobTitle?: string
   description?: string
+  avatarUrl?: string
   roles: string[]
   personality?: string
   goals: string[]

package/src/wirings/queue/queue-identity.test.ts

@@ -21,6 +21,7 @@ import type {
   QueueJob,
   QueueService,
 } from './queue.types.js'
+import { createSecretValue } from '../../secret-value.js'
 
 const QUEUE_NAME = 'identity-queue'
 const SECRET = 'a'.repeat(48)
@@ -49,7 +50,7 @@ const createSecretService = (secrets: Record<string, string>) =>
       if (value === undefined) {
         throw new Error(`Secret not found: ${key}`)
       }
-      return value
+      return createSecretValue(value)
     },
     hasSecret: async (key: string) => secrets[key] !== undefined,
     setSecret: async () => {},

package/src/wirings/queue/queue-identity.ts

@@ -59,7 +59,10 @@ export const getQueueIdentitySecret = async (
   secrets?: SecretService
 ): Promise<string | undefined> => {
   try {
-    return (await secrets?.getSecret(QUEUE_IDENTITY_SECRET_NAME)) || undefined
+    return (
+      (await secrets?.getSecret(QUEUE_IDENTITY_SECRET_NAME))?.reveal() ||
+      undefined
+    )
   } catch {
     return undefined
   }

package/src/wirings/queue/queue.types.ts

@@ -1,6 +1,7 @@
 import type { CommonWireMeta } from '../../types/core.types.js'
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type { QueueConfigMapping } from './validate-worker-config.js'
+import type { Safe } from '../../secret-value.js'
 
 export interface PikkuWorkerConfig {
   name?: string
@@ -107,7 +108,11 @@ export interface JobOptions {
 export interface QueueService {
   readonly supportsResults: boolean
 
-  add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>
+  add<T>(
+    queueName: string,
+    data: Safe<T>,
+    options?: JobOptions
+  ): Promise<string>
 
   getJob<T, R>(queueName: string, jobId: string): Promise<QueueJob<T, R> | null>
 }

package/src/wirings/queue/signed-queue-service.ts

@@ -1,3 +1,4 @@
+import type { Safe } from '../../secret-value.js'
 import type { Logger } from '../../services/logger.js'
 import type { SecretService } from '../../services/secret-service.js'
 import {
@@ -24,7 +25,7 @@ export class SignedQueueService implements QueueService {
 
   public async add<T>(
     queueName: string,
-    data: T,
+    data: Safe<T>,
     options?: JobOptions
   ): Promise<string> {
     const pikkuUserId = options?.pikkuUserId

package/src/wirings/rpc/remote-addon-auth.ts

@@ -1,5 +1,6 @@
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js'
 import { PikkuError, addError } from '../../errors/error-handler.js'
+import { isSecretValue, type SecretValue } from '../../secret-value.js'
 
 export type RemoteAddonAuthBinding =
   | { credentialId: string }
@@ -8,7 +9,7 @@ export type RemoteAddonAuthBinding =
       resolve: (
         services: CoreServices,
         wire: PikkuRawWire
-      ) => string | Promise<string>
+      ) => string | SecretValue<string> | Promise<string | SecretValue<string>>
     }
 
 export class RemoteAddonAuthError extends PikkuError {
@@ -49,9 +50,13 @@ export async function resolveRemoteAddonToken(
     token = await auth.resolve(services, wire)
   }
 
-  if (token === null || token === undefined || token === '') {
+  // The wire is where a secret is meant to end up, so unwrap it here rather
+  // than at each branch — `resolve` and `getCredential` may hand one back too.
+  const resolved = isSecretValue(token) ? token.reveal() : token
+
+  if (resolved === null || resolved === undefined || resolved === '') {
     throw new RemoteAddonAuthError(namespace, 'resolved token was empty')
   }
 
-  return String(token)
+  return String(resolved)
 }

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

@@ -13,6 +13,7 @@ import {
 import { RemoteAddonAuthError } from './remote-addon-auth.js'
 import { wireAddon } from './wire-addon.js'
 import { wireRemoteAddon } from './wire-remote-addon.js'
+import { createSecretValue } from '../../secret-value.js'
 
 const createLogger = () => ({
   debug: () => {},
@@ -690,7 +691,7 @@ describe('ContextAwareRPCService.remote', () => {
 
 describe('multi-instance addons', () => {
   const createSecretService = () => ({
-    getSecret: async (key: string) => `secret:${key}`,
+    getSecret: async (key: string) => createSecretValue(`secret:${key}`),
     hasSecret: async () => true,
     setSecret: async () => {},
     deleteSecret: async () => {},
@@ -701,7 +702,7 @@ describe('multi-instance addons', () => {
     const createdServices: any[] = []
     pikkuState('@addon/slack', 'package', 'factories', {
       createSingletonServices: async (_config: any, parent: any) => {
-        const token = await parent.secrets.getSecret('slackToken')
+        const token = (await parent.secrets.getSecret('slackToken')).reveal()
         const svc = { logger: createLogger(), token }
         createdServices.push(svc)
         return svc
@@ -748,7 +749,7 @@ describe('multi-instance addons', () => {
         factoryCalls++
         return {
           logger: createLogger(),
-          token: await parent.secrets.getSecret('slackToken'),
+          token: (await parent.secrets.getSecret('slackToken')).reveal(),
         }
       },
     } as never)
@@ -854,7 +855,8 @@ describe('wireRemoteAddon dispatch', () => {
 
   const secretService = () =>
     ({
-      getSecret: async (key: string) => `secret-value-for-${key}`,
+      getSecret: async (key: string) =>
+        createSecretValue(`secret-value-for-${key}`),
       getSecrets: async () => ({}),
       hasSecret: async () => true,
       setSecret: async () => {},

package/src/wirings/virtual-user/index.ts

@@ -31,12 +31,24 @@ export type {
   VirtualUserTally,
   VirtualUserTarget,
 } from './virtual-user.types.js'
+export { PRODUCTION_DISPOSITION } from './virtual-user.types.js'
 export {
   runVirtualUser,
   rememberIds,
   type RunVirtualUserParams,
   type VirtualUserCallContext,
 } from './run-virtual-user.js'
+export {
+  personaScopes,
+  prepareVirtualUserRun,
+  type VirtualUserPreparation,
+} from './prepare-virtual-user-run.js'
+export type {
+  VirtualUserRunOutcome,
+  VirtualUserRunRecord,
+  VirtualUserRunStart,
+  VirtualUserRunStore,
+} from './virtual-user-run-store.js'
 export {
   DISPOSITIONS,
   dispositionProfile,

package/src/wirings/virtual-user/prepare-virtual-user-run.test.ts

@@ -0,0 +1,115 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  personaScopes,
+  prepareVirtualUserRun,
+} from './prepare-virtual-user-run.js'
+
+const ROLE_DEFINITIONS = [
+  { name: 'editor', scopes: ['docs:write', 'docs:read'] },
+  { name: 'viewer', scopes: ['docs:read'] },
+]
+
+const FUNCTIONS_META = {
+  listDocs: { pikkuFuncName: 'listDocs', services: [], expose: true },
+  deleteDoc: { pikkuFuncName: 'deleteDoc', services: [], expose: true },
+} as any
+
+describe('personaScopes', () => {
+  test('expands the roles a persona declares into the scopes functions check', () => {
+    const scopes = personaScopes(
+      { roles: ['editor'] },
+      {
+        editor: ['docs:write', 'docs:read'],
+      }
+    )
+    assert.deepEqual(scopes, ['docs:read', 'docs:write'])
+  })
+
+  test('a persona with no roles holds no scopes', () => {
+    assert.deepEqual(personaScopes({}, { editor: ['docs:write'] }), [])
+  })
+
+  // Two roles granting the same scope is ordinary, and the catalogue narrowing
+  // downstream compares scopes as a set.
+  test('de-duplicates overlapping roles', () => {
+    const scopes = personaScopes(
+      { roles: ['editor', 'viewer'] },
+      {
+        editor: ['docs:write', 'docs:read'],
+        viewer: ['docs:read'],
+      }
+    )
+    assert.deepEqual(scopes, ['docs:read', 'docs:write'])
+  })
+
+  // An undeclared role granting everything would be the worst possible default.
+  test('an unknown role grants nothing', () => {
+    assert.deepEqual(personaScopes({ roles: ['ghost'] }, {}), [])
+  })
+})
+
+describe('prepareVirtualUserRun', () => {
+  // The CLI reads the inspector state, which holds an array; the scaffolded RPC
+  // reads metaService, which hands the same definitions back keyed by name. Both
+  // callers must land on the same scopes or the same persona and seed explore a
+  // different API depending on how the run was started.
+  test('accepts role definitions as an array or keyed by name, identically', () => {
+    const asArray = prepareVirtualUserRun({
+      persona: { roles: ['editor'] },
+      functionsMeta: FUNCTIONS_META,
+      systemRoles: ROLE_DEFINITIONS as any,
+    })
+    const asRecord = prepareVirtualUserRun({
+      persona: { roles: ['editor'] },
+      functionsMeta: FUNCTIONS_META,
+      systemRoles: {
+        editor: ROLE_DEFINITIONS[0],
+        viewer: ROLE_DEFINITIONS[1],
+      } as any,
+    })
+    assert.deepEqual(asArray.scopes, asRecord.scopes)
+    assert.deepEqual(asArray.scopes, ['docs:read', 'docs:write'])
+  })
+
+  test('derives the catalogue from the function meta', () => {
+    const { catalogue } = prepareVirtualUserRun({
+      persona: {},
+      functionsMeta: FUNCTIONS_META,
+    })
+    assert.deepEqual(catalogue.map((entry) => entry.name).sort(), [
+      'deleteDoc',
+      'listDocs',
+    ])
+  })
+
+  // An agent is reached rather than declared: its scopes are checked against the
+  // session, so a persona must find the specialists its roles unlock and no
+  // others.
+  test('narrows agents to the ones the persona s scopes reach', () => {
+    const agentsMeta = {
+      helper: { scopes: [] },
+      auditor: { scopes: ['docs:audit'] },
+    } as any
+
+    const { agents } = prepareVirtualUserRun({
+      persona: { roles: ['viewer'] },
+      functionsMeta: FUNCTIONS_META,
+      systemRoles: ROLE_DEFINITIONS as any,
+      agentsMeta,
+    })
+
+    assert.deepEqual(
+      agents.map((agent) => agent.name),
+      ['helper']
+    )
+  })
+
+  test('a project with no scenarios simply has no intents', () => {
+    const { intents } = prepareVirtualUserRun({
+      persona: {},
+      functionsMeta: FUNCTIONS_META,
+    })
+    assert.deepEqual(intents, [])
+  })
+})