@pikku/core 0.12.74 → 0.12.77

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 };
+};

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

@@ -0,0 +1,90 @@
+import type { VirtualUserDisposition, VirtualUserFinding, VirtualUserTally } from './virtual-user.types.js';
+/**
+ * One recorded run: who ran, what they were told, and what came back.
+ *
+ * A run is dispatched and answered for later, so the record is created before
+ * the work starts and is the thing the returned `runId` addresses.
+ *
+ * This record is a run's ONLY trace. A virtual user is not a workflow — it
+ * explores, so no two attempts take the same steps and there is nothing to
+ * replay — and it is not queued either, because the record already carries the
+ * progress a queue would only be holding on the way here.
+ *
+ * The cost of that is the one thing to know when reading `status`: a restart
+ * mid-run leaves a record at `running` with nothing left to finish it. A run
+ * older than its budget window and still `running` is dead, not working.
+ */
+export interface VirtualUserRunRecord {
+    runId: string;
+    persona: string;
+    disposition: VirtualUserDisposition;
+    /** What makes a run replayable at all — a finding without it is an anecdote. */
+    seed: number;
+    /**
+     * `running` until the engine returns. Not derived from `finishedAt` being
+     * unset: a crashed run has no finish time either, and the two are not the
+     * same result.
+     */
+    status: 'running' | 'completed' | 'failed';
+    /** The caller's situational goals, run alongside the derived intents. */
+    goals: string[];
+    /**
+     * Ids and slugs the user carried in, and whatever it learned on the way out.
+     * Kept because a finding only reproduces alongside the notes that produced it.
+     */
+    memory: Record<string, string>;
+    findings: VirtualUserFinding[];
+    tally: VirtualUserTally | null;
+    /** Which budget or stopping rule ended the run. */
+    stoppedBy: string | null;
+    /**
+     * Why the run itself failed, as opposed to what it found. A run that could
+     * not start has no findings and is not a clean empty result.
+     */
+    error: string | null;
+    /** The session that started it, where the host tracks one. */
+    startedBy: string | null;
+    createdAt: Date;
+    finishedAt: Date | null;
+}
+/** What a run is created with — everything else is filled in by the outcome. */
+export interface VirtualUserRunStart {
+    persona: string;
+    disposition: VirtualUserDisposition;
+    seed: number;
+    goals?: readonly string[];
+    memory?: Record<string, string>;
+    startedBy?: string | null;
+}
+/** The outcome of a run that reached the end of its budget without throwing. */
+export interface VirtualUserRunOutcome {
+    findings: readonly VirtualUserFinding[];
+    tally: VirtualUserTally;
+    memory: Record<string, string>;
+    stoppedBy: string | null;
+}
+/**
+ * Where runs are kept. Declared here rather than in a database package so the
+ * scaffolded RPCs depend on the shape and not on kysely — `@pikku/kysely` ships
+ * one implementation, and an app with its own store satisfies this instead.
+ *
+ * SECURITY: findings from an `adversarial` run are working exploits carrying
+ * live ids. An implementation is a privileged store; the scaffold gates every
+ * read behind a scope for that reason, and a host exposing these records more
+ * widely is publishing its own exploits.
+ */
+export interface VirtualUserRunStore {
+    /** Records a run as `running` and returns its id. */
+    start(run: VirtualUserRunStart): Promise<string>;
+    /** Marks a run `completed` and stores what it found. */
+    complete(runId: string, outcome: VirtualUserRunOutcome): Promise<void>;
+    /** Marks a run `failed`. The run itself broke; it has no findings. */
+    fail(runId: string, error: string): Promise<void>;
+    get(runId: string): Promise<VirtualUserRunRecord | null>;
+    /** Newest first. `persona` narrows to one persona's history. */
+    list(options?: {
+        persona?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<VirtualUserRunRecord[]>;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -62,7 +62,7 @@ export type WorkflowWireDoRPC = <TOutput = any, TInput = any>(stepName: string,
  */
 export type WorkflowWireDoInline = <T>(stepName: string, fn: () => Promise<T> | T, options?: WorkflowStepOptions) => Promise<T>;
 /**
- * Type signature for scenario.step/given/when/then - used by inspector.
+ * Type signature for scenario.given/when/then - used by inspector.
  *
  * Deliberately mirrors WorkflowWireDoRPC's shape: the target is a string, not
  * an imported symbol, so the extractor reads it as a literal.
@@ -181,7 +181,7 @@ export interface RpcStepMeta {
     expectEventually?: boolean;
 }
 /**
- * Scenario step metadata — a call to `scenario.step/given/when/then`.
+ * Scenario step metadata — a call to `scenario.given/when/then`.
  *
  * Distinct from RpcStepMeta on purpose: a step runs locally through
  * runPikkuFunc and must never be treated as dispatchable on the queue/replay
@@ -194,7 +194,7 @@ export interface ScenarioStepMeta {
     stepName: string;
     /** Registered name of the step function being run */
     stepFunc: string;
-    /** Which keyword the reporter prefixes — given/when/then, or none for `step` */
+    /** Which keyword the reporter prefixes — Given, When or Then */
     phase: ScenarioStepPhase;
     /** Output variable name (if assigned) */
     outputVar?: string;
@@ -484,18 +484,22 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     /** Stub-assertion step: asserts `service.method` was called on the target server */
     expectService: (stepName: string, serviceMethod: string, options?: WorkflowExpectServiceOptions) => Promise<void>;
     /**
-     * Run a registered scenario step. Shaped exactly like `do`'s RPC form —
-     * `(stepName, target, data, options)` — so the inspector reads the target as
-     * a string literal rather than resolving an imported symbol.
+     * Run a registered scenario step, as the setup the scenario starts from.
+     *
+     * Shaped exactly like `do`'s RPC form — `(stepName, target, data, options)` —
+     * so the inspector reads the target as a string literal rather than resolving
+     * an imported symbol.
      *
      * The generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
      */
-    step(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
-    /** `step` with a "Given" prefix in the rendered prose */
     given(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
-    /** `step` with a "When" prefix in the rendered prose */
+    /** `when`: the same call as `given`, rendered as the action under test */
     when(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
-    /** `step` with a "Then" prefix in the rendered prose */
+    /**
+     * `then`: a claim about what the action left behind. Unlike `given`/`when`
+     * this is not prose alone — the step's bindings become witnesses, so every
+     * declared surface is observed and the observations must agree.
+     */
     then(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
     runScheduledTask: (name: string) => Promise<unknown>;
 }

package/dist/wirings/workflow/pikku-scenario-service.js

@@ -452,12 +452,11 @@ export class PikkuScenarioService {
                 }, options);
             },
             // Scenario steps: a named `pikkuScenarioStep` run as one durable step.
-            // `given`/`when`/`step` are sugar for each other, differing only in the
+            // `given`/`when` are sugar for each other, differing only in the
             // prose a reporter renders. `then` is not: the phase is what decides
             // whether the step's bindings are alternatives or witnesses, so the same
             // step function called two ways runs differently. See
             // {@link resolveScenarioSurfaces}.
-            step: (stepName, stepFunc, data, options) => this.scenarioStep('step', scenarioStepContext(), stepName, stepFunc, data, options),
             given: (stepName, stepFunc, data, options) => this.scenarioStep('given', scenarioStepContext(), stepName, stepFunc, data, options),
             when: (stepName, stepFunc, data, options) => this.scenarioStep('when', scenarioStepContext(), stepName, stepFunc, data, options),
             then: (stepName, stepFunc, data, options) => this.scenarioStep('then', scenarioStepContext(), stepName, stepFunc, data, options),

package/dist/wirings/workflow/scenario-prose.js

@@ -15,7 +15,7 @@ const formatValue = (value) => {
     return String(value);
 };
 export const composeStepProse = ({ phase, description, template, input, actor, keywordWidth, }) => {
-    const keyword = phase === 'step' ? '' : capitalise(phase);
+    const keyword = capitalise(phase);
     const subject = actor ? `the ${actor}` : '';
     const rendered = template ? renderStepTemplate(template, input) : description;
     const sentence = [subject, rendered].filter(Boolean).join(' ');