@pikku/core 0.12.74 → 0.12.78

package/dist/wirings/ai-agent/ai-agent.types.d.ts

@@ -163,6 +163,23 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
     modifyInput?: (services: Services, ctx: {
         messages: AIMessage[];
         instructions: string;
+        /**
+         * Notes about this run that every middleware can read and write, as
+         * opposed to {@link modifyOutputStream}'s `state`, which is private to
+         * one middleware.
+         *
+         * It exists because middlewares transform the turn for each other, and
+         * the transformation can destroy what a later one needed to know. Voice
+         * is the case in point: `voiceInput` replaces the user's audio with its
+         * transcript, so by the time anything downstream looks, the turn is
+         * indistinguishable from one that was typed — and whether it was typed is
+         * exactly what `voiceOutput` needs in order to decide whether to answer
+         * aloud. Only the middleware that consumed the audio can still say so.
+         *
+         * Namespace what you put here (`voice:spokenTurn`); it is one bag for
+         * everybody. Cleared between runs.
+         */
+        shared: Record<string, unknown>;
     }) => Promise<{
         messages: AIMessage[];
         instructions: string;
@@ -173,7 +190,10 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
     modifyOutputStream?: (services: Services, ctx: {
         event: AIStreamEvent;
         allEvents: readonly AIStreamEvent[];
+        /** Private to this middleware, for this run. Cross-middleware facts go in `shared`. */
         state: State;
+        /** Per-run notes shared with every middleware — see {@link modifyInput}. */
+        shared: Record<string, unknown>;
         /**
          * Push an event into the stream *after* this call has returned.
          *
@@ -412,12 +432,32 @@ export type AIStreamEvent = {
     type: 'audio-delta';
     data: string;
     format: string;
+    /**
+     * The sentence this audio says.
+     *
+     * Carried alongside the bytes because a client that gets talked over has
+     * to tell the model what the user actually heard, and playback position
+     * is the only place that is knowable. Without it a barge-in can stop the
+     * sound but not report it, and the next turn is answered as though the
+     * whole reply had landed.
+     */
+    text?: string;
     agent?: string;
     session?: string;
 } | {
     type: 'audio-done';
     agent?: string;
     session?: string;
+} | {
+    /**
+     * What the user was heard to say, sent once at the start of a spoken
+     * turn. Only the server knows this — the client sent audio — and a chat
+     * surface needs it to show the user's own message.
+     */
+    type: 'transcript';
+    text: string;
+    agent?: string;
+    session?: string;
 } | {
     type: 'data';
     name: string;

package/dist/wirings/ai-agent/index.d.ts

@@ -2,7 +2,7 @@ export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from '
 export { wrapChannelWithAGUI, type AGUIEvent } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
-export { voiceInput, readsAsNonSpeech, NoSpeechDetectedError, } from './voice-input.js';
+export { voiceInput, readsAsNonSpeech, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } from './voice-input.js';
 export { voiceOutput, unspeakableScripts, voiceForText, type SpeakableScripts, } from './voice-output.js';
 export { AgentInterruptedError, awaitPendingInterruptNote, getInFlightTools, isAbortError, isRunInterruptible, persistOrphanedToolResults, registerInterruptibleRun, signalRunInterrupt, trackInterruptNote, trackToolExecution, } from './ai-agent-interrupt.js';
 export type { AgentInterruption, AgentInterruptResult, InterruptibleRunHandle, OrphanedToolResult, } from './ai-agent-interrupt.js';

package/dist/wirings/ai-agent/index.js

@@ -2,7 +2,7 @@ export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from '
 export { wrapChannelWithAGUI } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
-export { voiceInput, readsAsNonSpeech, NoSpeechDetectedError, } from './voice-input.js';
+export { voiceInput, readsAsNonSpeech, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } from './voice-input.js';
 export { voiceOutput, unspeakableScripts, voiceForText, } from './voice-output.js';
 export { AgentInterruptedError, awaitPendingInterruptNote, getInFlightTools, isAbortError, isRunInterruptible, persistOrphanedToolResults, registerInterruptibleRun, signalRunInterrupt, trackInterruptNote, trackToolExecution, } from './ai-agent-interrupt.js';
 export { ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, sessionPrincipals, threadOwnerConstraint, } from './ai-agent-prepare.js';

package/dist/wirings/ai-agent/voice-input.d.ts

@@ -34,6 +34,26 @@ export declare class NoSpeechDetectedError extends Error {
 export declare const readsAsNonSpeech: (result: {
     text?: string;
 }) => boolean;
+/**
+ * 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 declare 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 declare const SPOKEN_TRANSCRIPT = "voice:transcript";
 export declare const voiceInput: (config?: {
     language?: string;
     model?: string;

package/dist/wirings/ai-agent/voice-input.js

@@ -58,22 +58,44 @@ async function fetchAsUint8Array(url, allowedAudioHosts) {
     }
     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) => pikkuAIMiddleware({
-    modifyInput: async (services, { messages, instructions }) => {
+    modifyInput: async (services, { messages, instructions, shared }) => {
         const aiAgentRunner = services.aiAgentRunner;
         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;
-        if (!parts)
-            return { messages, instructions };
-        const hasAudio = parts.some((p) => p.type === 'file' && !!p.mediaType?.startsWith('audio/'));
-        if (!hasAudio)
+        const parts = last?.role === 'user' && typeof last.content !== 'string'
+            ? last.content
+            : undefined;
+        const hasAudio = !!parts?.some((p) => p.type === 'file' && !!p.mediaType?.startsWith('audio/'));
+        // 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 = [];
+        const heard = [];
         for (const p of parts) {
             if (!(p.type === 'file' && p.mediaType?.startsWith('audio/'))) {
                 updatedContent.push(p);
@@ -85,6 +107,9 @@ export const voiceInput = (config) => pikkuAIMiddleware({
             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,
@@ -103,12 +128,22 @@ export const voiceInput = (config) => pikkuAIMiddleware({
             // not hear.
             if (readsAsNonSpeech(result))
                 continue;
+            heard.push(result.text);
             updatedContent.push({ type: 'text', text: result.text });
         }
         // Every part was audio, and none of it was speech. There is nothing left
         // 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/dist/wirings/ai-agent/voice-output.d.ts

@@ -59,6 +59,21 @@ export declare 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;
 }) => import("./ai-agent.types.js").PikkuAIMiddlewareHooks<VoiceOutputState, import("../../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {

package/dist/wirings/ai-agent/voice-output.js

@@ -1,4 +1,5 @@
 import { pikkuAIMiddleware } from '../../types/core.types.js';
+import { SPOKEN_TURN } from './voice-input.js';
 function bufferToBase64(data) {
     let binary = '';
     for (let i = 0; i < data.length; i++) {
@@ -100,10 +101,17 @@ async function synthesizeAudio(aiAgentRunner, input) {
     };
 }
 export const voiceOutput = (config) => pikkuAIMiddleware({
-    modifyOutputStream: async (services, { event, state, emit, signal }) => {
+    modifyOutputStream: async (services, { event, state, shared, emit, signal }) => {
         const { aiAgentRunner, logger } = services;
         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.
          *
@@ -167,6 +175,7 @@ export const voiceOutput = (config) => pikkuAIMiddleware({
                     type: 'audio-delta',
                     data: bufferToBase64(result.audio.bytes),
                     format: result.audio.format,
+                    text,
                 });
             });
         };

package/dist/wirings/cli/channel/cli-raw-client-runner.d.ts

@@ -1,5 +1,23 @@
 import type { ApprovalRequester, Capabilities } from '../../channel/channel-rpc.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>;
 /**
  * Runs a CLI command entirely on the server. Unlike `executeCLIViaChannel`,
  * argv is forwarded untouched and never parsed here, so the client carries no
@@ -13,8 +31,8 @@ import type { CorePikkuCLIRender } from '../cli.types.js';
 export declare function executeRawCLIViaChannel({ pikkuWS, args, renderers, defaultRenderer, capabilities, approve, }: {
     pikkuWS: any;
     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/dist/wirings/cli/channel/cli-raw-client-runner.js

@@ -4,11 +4,19 @@ import { approverForMode, takeApprovalFlags } from './cli-approval.js';
 const defaultJSONRenderer = (_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 };
+// `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 = {
+    logger: {
+        info: (...args) => console.info(...args),
+        warn: (...args) => console.warn(...args),
+        error: (...args) => console.error(...args),
+        debug: (...args) => console.debug(...args),
+        trace: (...args) => console.trace(...args),
+        setLevel: () => { },
+    },
+};
 /**
  * Runs a CLI command entirely on the server. Unlike `executeCLIViaChannel`,
  * argv is forwarded untouched and never parsed here, so the client carries no

package/dist/wirings/cli/channel/index.d.ts

@@ -2,5 +2,6 @@ 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, createTerminalApprover, takeApprovalFlags, } from './cli-approval.js';
 export type { ApprovalMode } from './cli-approval.js';

package/dist/wirings/persona/define-personas.d.ts

@@ -10,6 +10,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/dist/wirings/persona/define-personas.js

@@ -9,6 +9,10 @@
  * 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/dist/wirings/persona/persona.types.d.ts

@@ -36,6 +36,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
@@ -107,6 +117,7 @@ export type PersonaMeta = {
     name: string;
     jobTitle?: string;
     description?: string;
+    avatarUrl?: string;
     roles: string[];
     personality?: string;
     goals: string[];

package/dist/wirings/queue/queue-identity.js

@@ -25,7 +25,8 @@ const canonicalizePayload = (data) => stableStringify(JSON.parse(JSON.stringify(
 const signingPayload = (encodedClaim, data) => `${QUEUE_IDENTITY_CLAIM_VERSION}.${encodedClaim}.${canonicalizePayload(data)}`;
 export const getQueueIdentitySecret = async (secrets) => {
     try {
-        return (await secrets?.getSecret(QUEUE_IDENTITY_SECRET_NAME)) || undefined;
+        return ((await secrets?.getSecret(QUEUE_IDENTITY_SECRET_NAME))?.reveal() ||
+            undefined);
     }
     catch {
         return undefined;

package/dist/wirings/queue/queue.types.d.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;
     /** Total worker concurrency. */
@@ -95,7 +96,7 @@ 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>;
 }
 export interface QueueWorkers {

package/dist/wirings/queue/signed-queue-service.d.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 type { JobOptions, QueueJob, QueueService } from './queue.types.js';
@@ -11,6 +12,6 @@ export declare class SignedQueueService implements QueueService {
     private readonly logger;
     constructor(queueService: QueueService, secrets: SecretService, logger: Logger);
     get 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/dist/wirings/rpc/remote-addon-auth.d.ts

@@ -1,11 +1,12 @@
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
 import { PikkuError } from '../../errors/error-handler.js';
+import { type SecretValue } from '../../secret-value.js';
 export type RemoteAddonAuthBinding = {
     credentialId: string;
 } | {
     secretId: string;
 } | {
-    resolve: (services: CoreServices, wire: PikkuRawWire) => string | Promise<string>;
+    resolve: (services: CoreServices, wire: PikkuRawWire) => string | SecretValue<string> | Promise<string | SecretValue<string>>;
 };
 export declare class RemoteAddonAuthError extends PikkuError {
     readonly namespace: string;

package/dist/wirings/rpc/remote-addon-auth.js

@@ -1,4 +1,5 @@
 import { PikkuError, addError } from '../../errors/error-handler.js';
+import { isSecretValue } from '../../secret-value.js';
 export class RemoteAddonAuthError extends PikkuError {
     namespace;
     constructor(namespace, detail) {
@@ -28,8 +29,11 @@ export async function resolveRemoteAddonToken(auth, services, wire, namespace) {
     else if (typeof auth.resolve === 'function') {
         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/dist/wirings/virtual-user/index.d.ts

@@ -17,7 +17,10 @@
  * signed in as a real user against staging or production.
  */
 export type { ApiCatalogueEntry, IntentRecord, IntentSource, IntentStatus, StepRecord, VirtualUserAction, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserFindingKind, VirtualUserRunResult, 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, type DispositionProfile, type VirtualUserTuning, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueIndex, catalogueLookup, describeEntry, isReadOnly, reachableCatalogue, renderCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { reachableAgents, type AgentReachability, type ReachableAgent, } from './virtual-user-agents.js';

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

@@ -1,4 +1,6 @@
+export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
 export { runVirtualUser, rememberIds, } from './run-virtual-user.js';
+export { personaScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
 export { DISPOSITIONS, dispositionProfile, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueIndex, catalogueLookup, describeEntry, isReadOnly, reachableCatalogue, renderCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { reachableAgents, } from './virtual-user-agents.js';

package/dist/wirings/virtual-user/prepare-virtual-user-run.d.ts

@@ -0,0 +1,54 @@
+import type { FunctionsMeta } from '../../types/core.types.js';
+import type { WorkflowsMeta } from '../workflow/workflow.types.js';
+import type { SystemRoleDefinitions, SystemRoleDefinitionsMeta } from '../role/role.types.js';
+import { type SchemaMap } from './virtual-user-derive.js';
+import { type AgentReachability, type ReachableAgent } from './virtual-user-agents.js';
+import type { ApiCatalogueEntry, IntentSource } from './virtual-user.types.js';
+/**
+ * The scopes a persona holds, resolved through its roles.
+ *
+ * Roles are the only thing a persona declares; scopes are what a function
+ * checks. Narrowing a virtual user's catalogue needs the second, so the
+ * expansion happens once, here, against the same `defineSystemRole` definitions
+ * the seed grants from.
+ */
+export declare const personaScopes: (persona: {
+    roles?: readonly string[];
+}, roleScopes: Record<string, readonly string[]>) => string[];
+/** Everything a run needs that is derived rather than decided. */
+export interface VirtualUserPreparation {
+    /** Every RPC the app exposes, narrowed to what this persona can reach. */
+    catalogue: ApiCatalogueEntry[];
+    intents: IntentSource[];
+    scopes: string[];
+    agents: ReachableAgent[];
+}
+/**
+ * Derive what a virtual user needs from what the project already generates.
+ *
+ * Shared because there are two callers with the same problem and different
+ * sources for it: `pikku persona run` reads the inspector state at build time,
+ * and the scaffolded `runVirtualUser` RPC reads `metaService` at runtime. They
+ * must agree — a persona whose catalogue is narrower over RPC than on the CLI
+ * finds different things from the same seed, which is exactly the property a
+ * seed exists to give.
+ *
+ * Nothing here is authored for the virtual user's benefit: the function meta is
+ * the catalogue, the scenario meta is the intents, and the role definitions are
+ * what turn a persona's declared roles into the scopes a function checks.
+ */
+export declare const prepareVirtualUserRun: (input: {
+    persona: {
+        roles?: readonly string[];
+    };
+    functionsMeta: FunctionsMeta;
+    schemas?: SchemaMap;
+    workflowsMeta?: WorkflowsMeta;
+    /**
+     * Either shape: the inspector holds an array, `metaService` hands back the
+     * same definitions keyed by name. Accepting both is what lets the CLI and the
+     * scaffolded RPC share this.
+     */
+    systemRoles?: SystemRoleDefinitions | SystemRoleDefinitionsMeta;
+    agentsMeta?: Readonly<Record<string, AgentReachability>>;
+}) => VirtualUserPreparation;

package/dist/wirings/virtual-user/prepare-virtual-user-run.js

@@ -0,0 +1,49 @@
+import { flattenSystemRoleDefinitions } from '../role/validate-role-definitions.js';
+import { deriveCatalogue, deriveIntents, } from './virtual-user-derive.js';
+import { reachableAgents, } from './virtual-user-agents.js';
+/**
+ * The scopes a persona holds, resolved through its roles.
+ *
+ * Roles are the only thing a persona declares; scopes are what a function
+ * checks. Narrowing a virtual user's catalogue needs the second, so the
+ * expansion happens once, here, against the same `defineSystemRole` definitions
+ * the seed grants from.
+ */
+export const personaScopes = (persona, roleScopes) => {
+    const scopes = new Set();
+    for (const role of persona.roles ?? []) {
+        for (const scope of roleScopes[role] ?? []) {
+            scopes.add(scope);
+        }
+    }
+    return [...scopes].sort();
+};
+/**
+ * Derive what a virtual user needs from what the project already generates.
+ *
+ * Shared because there are two callers with the same problem and different
+ * sources for it: `pikku persona run` reads the inspector state at build time,
+ * and the scaffolded `runVirtualUser` RPC reads `metaService` at runtime. They
+ * must agree — a persona whose catalogue is narrower over RPC than on the CLI
+ * finds different things from the same seed, which is exactly the property a
+ * seed exists to give.
+ *
+ * Nothing here is authored for the virtual user's benefit: the function meta is
+ * the catalogue, the scenario meta is the intents, and the role definitions are
+ * what turn a persona's declared roles into the scopes a function checks.
+ */
+export const prepareVirtualUserRun = (input) => {
+    const catalogue = deriveCatalogue(input.functionsMeta, input.schemas ?? {});
+    const intents = deriveIntents(input.workflowsMeta ?? {}, input.functionsMeta);
+    const declared = input.systemRoles ?? [];
+    const roleScopes = {};
+    for (const role of flattenSystemRoleDefinitions(Array.isArray(declared) ? declared : Object.values(declared))) {
+        roleScopes[role.name] = role.scopes;
+    }
+    const scopes = personaScopes(input.persona, roleScopes);
+    // Gated by the same scopes as the RPCs, because an agent is reached rather
+    // than declared: `CoreAIAgent.scopes` is checked against the session, so a
+    // persona finds the specialists its roles unlock and no others.
+    const agents = reachableAgents(input.agentsMeta ?? {}, scopes);
+    return { catalogue, intents, scopes, agents };
+};