@pikku/core 0.12.74 → 0.12.77

package/dist/services/local-secrets.js

@@ -1,3 +1,4 @@
+import { createSecretValue, isSecretValue, } from '../secret-value.js';
 import { LocalVariablesService } from './local-variables.js';
 export class LocalSecretService {
     variables;
@@ -16,16 +17,19 @@ export class LocalSecretService {
     async getSecret(key) {
         const localValue = this.localSecrets.get(key);
         if (localValue) {
-            return this.parseSecret(localValue);
+            return createSecretValue(this.parseSecret(localValue));
         }
         const value = await this.variables.get(key);
         if (value) {
-            return this.parseSecret(value);
+            return createSecretValue(this.parseSecret(value));
         }
         throw new Error('Requested secret not found');
     }
     async setSecret(key, value) {
-        this.localSecrets.set(key, typeof value === 'string' ? value : JSON.stringify(value));
+        // Storing the wrapper would serialize it to '[secret]', so unwrap first —
+        // writing a secret back to the vault is exactly what this method is for.
+        const raw = isSecretValue(value) ? value.reveal() : value;
+        this.localSecrets.set(key, typeof raw === 'string' ? raw : JSON.stringify(raw));
     }
     async hasSecret(key) {
         if (this.localSecrets.has(key)) {

package/dist/services/logger.d.ts

@@ -1,3 +1,4 @@
+import type { Safe } from '../secret-value.js';
 export declare enum LogLevel {
     'trace' = 0,
     'debug' = 1,
@@ -6,12 +7,28 @@ export declare enum LogLevel {
     'error' = 4,
     'critical' = 5
 }
+/**
+ * A log line is the easiest place to leak a vault secret, so every parameter is
+ * `Safe<>`-guarded: a `SecretValue` anywhere in the message or the metadata,
+ * however deeply nested, collapses to `never` and fails the build. Reveal it
+ * first if you genuinely mean to log it.
+ */
 export interface Logger {
-    info(messageOrObj: string | Record<string, any>, ...meta: any[]): void;
-    warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void;
-    error(messageOrObj: string | Record<string, any> | Error, ...meta: any[]): void;
-    debug(message: string, ...meta: any[]): void;
-    trace?(message: string, ...meta: any[]): void;
+    info<M extends string | Record<string, any>, A extends unknown[]>(messageOrObj: Safe<M>, ...meta: {
+        [K in keyof A]: Safe<A[K]>;
+    }): void;
+    warn<M extends string | Record<string, any>, A extends unknown[]>(messageOrObj: Safe<M>, ...meta: {
+        [K in keyof A]: Safe<A[K]>;
+    }): void;
+    error<M extends string | Record<string, any> | Error, A extends unknown[]>(messageOrObj: Safe<M>, ...meta: {
+        [K in keyof A]: Safe<A[K]>;
+    }): void;
+    debug<A extends unknown[]>(message: string, ...meta: {
+        [K in keyof A]: Safe<A[K]>;
+    }): void;
+    trace?<A extends unknown[]>(message: string, ...meta: {
+        [K in keyof A]: Safe<A[K]>;
+    }): void;
     setLevel(level: LogLevel): void;
     /** A logger carrying a traceId on every entry, taken per-request to correlate calls. */
     scope?(traceId: string): Logger;

package/dist/services/queue-webhook-service.js

@@ -32,7 +32,7 @@ export class QueueWebhookService extends WebhookService {
         let secret = input.secret;
         if (secret === undefined && webhookConfig?.secret) {
             // Naive read: caching is the secret service's concern, not ours.
-            secret = await services.secrets.getSecret(webhookConfig.secret);
+            secret = (await services.secrets.getSecret(webhookConfig.secret)).reveal();
             if (!secret) {
                 services.logger.error(`Webhook signing secret '${webhookConfig.secret}' (config.webhook.secret) resolved to nothing — outgoing webhooks will be sent UNSIGNED.`);
             }

package/dist/services/scoped-secret-service.d.ts

@@ -1,12 +1,13 @@
-import type { SecretService } from './secret-service.js';
+import type { SecretValue } from '../secret-value.js';
+import type { SecretService, SecretValues } from './secret-service.js';
 export declare class ScopedSecretService implements SecretService {
     private secrets;
     private allowedKeys;
     constructor(secrets: SecretService, allowedKeys: Set<string>);
     private assertAllowed;
-    getSecret<T = string>(key: string): Promise<T>;
+    getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     hasSecret(key: string): Promise<boolean>;
     setSecret(_key: string, _value: unknown): Promise<void>;
     deleteSecret(_key: string): Promise<void>;
-    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
 }

package/dist/services/secret-service.d.ts

@@ -1,6 +1,11 @@
+import type { SecretValue } from '../secret-value.js';
+/** A record of secrets, each still wrapped. */
+export type SecretValues<T> = {
+    [K in keyof T]: SecretValue<T[K]>;
+};
 export interface SecretService {
-    /** Throws if the secret is not found. */
-    getSecret<T = string>(key: string): Promise<T>;
+    /** Throws if the secret is not found. Unwrap the result with `.reveal()`. */
+    getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     /** Answers for any key, including a disallowed one — it must not throw. */
     hasSecret(key: string): Promise<boolean>;
     setSecret(key: string, value: unknown): Promise<void>;
@@ -10,5 +15,5 @@ export interface SecretService {
      * must handle keys absent at runtime. Pass a shape as `T` to avoid casting,
      * e.g. `getSecrets<{ FOO: string; BAR: { id: string } }>(['FOO', 'BAR'])`.
      */
-    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
 }

package/dist/services/typed-secret-service.d.ts

@@ -1,4 +1,5 @@
-import type { SecretService } from './secret-service.js';
+import type { SecretValue } from '../secret-value.js';
+import type { SecretService, SecretValues } from './secret-service.js';
 export interface CredentialStatus {
     secretId: string;
     name: string;
@@ -20,12 +21,12 @@ export declare class TypedSecretService<TMap = Record<string, unknown>> implemen
     private credentialsMeta;
     private cache;
     constructor(secrets: SecretService, credentialsMeta: Record<string, CredentialMeta>);
-    getSecret<K extends keyof TMap & string>(key: K): Promise<TMap[K]>;
-    getSecret<T = string>(key: string): Promise<T>;
+    getSecret<K extends keyof TMap & string>(key: K): Promise<SecretValue<TMap[K]>>;
+    getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     hasSecret(key: string): Promise<boolean>;
     setSecret<K extends string>(key: K, value: K extends keyof TMap ? TMap[K] : unknown): Promise<void>;
     deleteSecret(key: string): Promise<void>;
-    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
     getAllStatus(): Promise<CredentialStatus[]>;
     getMissing(): Promise<CredentialStatus[]>;
 }

package/dist/services/webhook-service.d.ts

@@ -1,3 +1,4 @@
+import type { Safe } from '../secret-value.js';
 export interface SendWebhookInput {
     url: string;
     /** Sent as the `X-Pikku-Event` header. */
@@ -76,7 +77,7 @@ export declare const PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME = "pikku-outgoing-webhook
 export declare const DEFAULT_WEBHOOK_SIGNATURE_HEADER = "X-Pikku-Signature";
 export declare const DEFAULT_WEBHOOK_RETRIES = 3;
 export declare abstract class WebhookService {
-    abstract send(input: SendWebhookInput): Promise<SendWebhookResult>;
+    abstract send<T extends SendWebhookInput>(input: Safe<T>): Promise<SendWebhookResult>;
     /** Produces the header value, `sha256=<hex>`, not the bare digest. */
     protected sign(secret: string, body: string): string;
     /** Public because receivers verify with it; they share the signing scheme. */

package/dist/testing/service-tests.js

@@ -542,16 +542,16 @@ export function defineServiceTests(config) {
                     endpoint: 'https://api.example.com',
                 });
                 const result = await service.getSecret('api-key');
-                assert.deepEqual(result, {
+                assert.deepEqual(result.reveal(), {
                     token: 'sk-123',
                     endpoint: 'https://api.example.com',
                 });
             });
-            test('getSecret returns raw string', async () => {
+            test('getSecret wraps the raw string rather than returning it', async () => {
                 const service = await factory({ key: kek });
                 await service.setSecret('string-secret', 'plain-value');
                 const result = await service.getSecret('string-secret');
-                assert.strictEqual(result, 'plain-value');
+                assert.strictEqual(result.reveal(), 'plain-value');
             });
             test('hasSecret returns true/false', async () => {
                 const service = await factory({ key: kek });
@@ -569,7 +569,7 @@ export function defineServiceTests(config) {
                 await service.setSecret('upsert-key', { v: 1 });
                 await service.setSecret('upsert-key', { v: 2 });
                 const result = await service.getSecret('upsert-key');
-                assert.deepEqual(result, { v: 2 });
+                assert.deepEqual(result.reveal(), { v: 2 });
             });
             test('deleteSecret removes the key', async () => {
                 const service = await factory({ key: kek });
@@ -588,7 +588,7 @@ export function defineServiceTests(config) {
                     previousKey: kek,
                 });
                 const before = await rotatedService.getSecret('rotate-test');
-                assert.deepEqual(before, { important: 'data' });
+                assert.deepEqual(before.reveal(), { important: 'data' });
                 assert.ok(rotatedService.rotateKEK);
                 const count = await rotatedService.rotateKEK();
                 assert.ok(count > 0);
@@ -597,7 +597,7 @@ export function defineServiceTests(config) {
                     keyVersion: 2,
                 });
                 const after = await newOnlyService.getSecret('rotate-test');
-                assert.deepEqual(after, { important: 'data' });
+                assert.deepEqual(after.reveal(), { important: 'data' });
             });
             test('rotateKEK throws without previousKey', async () => {
                 const service = await factory({ key: kek });

package/dist/types/core.types.d.ts

@@ -25,6 +25,7 @@ import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.j
 import type { AIEmbeddingService } from '../services/ai-embedding-service.js';
 import type { AIRunStateService } from '../services/ai-run-state-service.js';
 import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js';
+import type { VirtualUserRunStore } from '../wirings/virtual-user/virtual-user-run-store.js';
 import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js';
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js';
 import type { CredentialService } from '../services/credential-service.js';
@@ -79,11 +80,12 @@ export type FunctionRuntimeMeta = {
      */
     auth?: boolean;
     /**
-     * The author's declaration that this function authorizes callers in its own
-     * body. Carries no runtime effect — it records a gate codegen cannot see, so
-     * an audit is not left to guess whether a sessionless function is open.
+     * The author's declaration that this function's permission check lives in its
+     * own body. Carries no runtime effect — it records a gate codegen cannot see,
+     * so an audit is not left to guess whether a sessionless function is open.
+     * Refused unless `allow.permissionsInBody` is set in `pikku.config.json`.
      */
-    selfAuthenticated?: boolean;
+    permissionsInBody?: boolean;
     remote?: boolean;
     /**
      * A step RPC: invoked by name only from a scenario run and refused
@@ -127,6 +129,19 @@ export type FunctionRuntimeMeta = {
     scenarioStepAddon?: string;
     /** Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input. */
     scenarioStepTemplate?: string;
+    /**
+     * The function's `audit` config, resolved — `audit: true` reads as
+     * `{ durability: 'best-effort' }`. Absent means the function records nothing:
+     * `auditLog.write()` from an unmarked function is dropped with a warning, so
+     * this is the only place a reader can see which functions have a trail at all
+     * without running them.
+     *
+     * Informational. The runner resolves audit from the live function config, not
+     * from here, so meta and runtime cannot disagree about whether audit is on.
+     */
+    audit?: {
+        durability: AuditDurability;
+    };
     /** Keeps the full `SecretService`. Set by the inspector, read by the runner. */
     secretBroker?: boolean;
     version?: number;
@@ -255,6 +270,12 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
      */
     webhookService?: WebhookService;
     metaService?: MetaService;
+    /**
+     * Where virtual-user runs are recorded. A run is dispatched and answered for
+     * later, so this store is the only trace it leaves — see
+     * {@link VirtualUserRunStore}.
+     */
+    virtualUserRunStore?: VirtualUserRunStore;
     /** V8 precise-coverage collector (`pikku dev --coverage` only) */
     coverageService?: CoverageService;
     audit?: AuditService;

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

@@ -305,7 +305,11 @@ export function wrapChannelWithAGUI(inner, options) {
                     send({
                         type: 'CUSTOM',
                         name: 'pikku:audio-delta',
-                        value: { data: event.data, format: event.format },
+                        value: {
+                            data: event.data,
+                            format: event.format,
+                            ...(event.text === undefined ? {} : { text: event.text }),
+                        },
                     });
                     break;
                 }
@@ -313,6 +317,14 @@ export function wrapChannelWithAGUI(inner, options) {
                     send({ type: 'CUSTOM', name: 'pikku:audio-done', value: {} });
                     break;
                 }
+                case 'transcript': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:transcript',
+                        value: { text: event.text },
+                    });
+                    break;
+                }
             }
         },
     };

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

@@ -660,7 +660,13 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     const contextMessages = await loadContextMessages(memoryConfig, storage, input, workingMemoryJsonSchema);
     const userContent = input.attachments?.length
         ? [
-            { type: 'text', text: input.message },
+            // Omitted when there is nothing to say. An attachment on its own is a
+            // real turn — a spoken one carries audio and no text at all — and an
+            // empty text part alongside it is a part providers are entitled to
+            // reject, for a caller who never wrote one.
+            ...(input.message
+                ? [{ type: 'text', text: input.message }]
+                : []),
             ...input.attachments.map((a) => ({
                 type: a.type,
                 data: a.data,

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

@@ -73,6 +73,8 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
         }),
         ...(agent.aiMiddleware ?? []),
     ];
+    // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+    const sharedNotes = {};
     let modifiedMessages = runnerParams.messages;
     let modifiedInstructions = runnerParams.instructions;
     for (const mw of aiMiddlewares) {
@@ -80,6 +82,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
             const result = await mw.modifyInput(singletonServices, {
                 messages: modifiedMessages,
                 instructions: modifiedInstructions,
+                shared: sharedNotes,
             });
             modifiedMessages = result.messages;
             modifiedInstructions = result.instructions;
@@ -87,6 +90,12 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
     }
     runnerParams.messages = modifiedMessages;
     runnerParams.instructions = modifiedInstructions;
+    // History records what the model was asked, which for a spoken turn is the
+    // transcript rather than the base64 audio that arrived — see the same note on
+    // the streaming path. Identity-checked, because a middleware may legitimately
+    // replace the message list with something unrelated to this turn.
+    const lastModified = modifiedMessages[modifiedMessages.length - 1];
+    const persistedUserMessage = lastModified?.id === userMessage.id ? lastModified : userMessage;
     const runId = await aiRunState.createRun({
         agentName,
         threadId,
@@ -181,7 +190,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
                         args: a.args,
                     });
                 const completedStepsForSave = accumulatedSteps.slice(0, -1);
-                await saveMessages(storage, threadId, input.resourceId, memoryConfig, userMessage, { text: '', steps: completedStepsForSave });
+                await saveMessages(storage, threadId, input.resourceId, memoryConfig, persistedUserMessage, { text: '', steps: completedStepsForSave });
                 if (storage) {
                     await storage.saveMessages(threadId, [
                         {
@@ -242,7 +251,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
                 outputMessages = modResult.messages;
             }
         }
-        await saveMessages(storage, threadId, input.resourceId, memoryConfig, userMessage, {
+        await saveMessages(storage, threadId, input.resourceId, memoryConfig, persistedUserMessage, {
             ...result,
             text: outputText,
             uiSpec: structuredOutput.uiSpec,
@@ -416,6 +425,8 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
         }),
         ...(agent.aiMiddleware ?? []),
     ];
+    // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+    const sharedNotes = {};
     let modifiedMessages = trimmedMessages;
     let modifiedInstructions = instructions;
     for (const mw of aiMiddlewares) {
@@ -423,6 +434,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
             const result = await mw.modifyInput(singletonServices, {
                 messages: modifiedMessages,
                 instructions: modifiedInstructions,
+                shared: sharedNotes,
             });
             modifiedMessages = result.messages;
             modifiedInstructions = result.instructions;

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

@@ -1,6 +1,7 @@
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.js';
+import { SPOKEN_TRANSCRIPT } from './voice-input.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
 import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, assertResourcePrincipalOwner, assertAgentAuthorized, ToolApprovalRequired, ToolCredentialRequired, APPROVAL_REQUIRED, CREDENTIAL_REQUIRED, } from './ai-agent-prepare.js';
@@ -411,6 +412,8 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         }),
         ...(agent.aiMiddleware ?? []),
     ];
+    // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+    const sharedNotes = {};
     let modifiedMessages = runnerParams.messages;
     let modifiedInstructions = runnerParams.instructions;
     for (const mw of aiMiddlewares) {
@@ -418,6 +421,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             const result = await mw.modifyInput(singletonServices, {
                 messages: modifiedMessages,
                 instructions: modifiedInstructions,
+                shared: sharedNotes,
             });
             modifiedMessages = result.messages;
             modifiedInstructions = result.instructions;
@@ -425,6 +429,23 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     }
     runnerParams.messages = modifiedMessages;
     runnerParams.instructions = modifiedInstructions;
+    // Sent on the raw channel, ahead of the run. A voice client sent audio and so
+    // has no idea what it said; until this arrives its own message is a blank
+    // bubble. Ahead of the run rather than alongside it because the answer starts
+    // streaming within a few hundred milliseconds, and a question that appears
+    // after its answer reads as the wrong question.
+    const transcript = sharedNotes[SPOKEN_TRANSCRIPT];
+    if (typeof transcript === 'string') {
+        channel.send({ type: 'transcript', text: transcript });
+    }
+    // What goes into thread history is what the model was actually asked. For a
+    // spoken turn that is not what arrived over the wire: the wire carried a
+    // base64 audio blob, and persisting it would write megabytes of unreadable
+    // data into the history while losing the only readable record of the turn.
+    // Identity-checked rather than assumed — a middleware is free to rewrite the
+    // message list into something with no relation to the turn.
+    const lastModified = modifiedMessages[modifiedMessages.length - 1];
+    const persistedUserMessage = lastModified?.id === userMessage.id ? lastModified : userMessage;
     const runId = await aiRunState.createRun({
         agentName,
         threadId,
@@ -442,7 +463,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     runnerParams.abortSignal = interruptHandle.signal;
     runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle);
     if (storage) {
-        await storage.saveMessages(threadId, [userMessage]);
+        await storage.saveMessages(threadId, [persistedUserMessage]);
     }
     const streamMiddleware = aiMiddlewares
         .filter((mw) => mw.modifyOutputStream)
@@ -455,6 +476,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
                 event,
                 allEvents,
                 state,
+                shared: sharedNotes,
                 // Sends downstream directly, so a hook can hand back the fast event
                 // now and push the slow one when it is ready.
                 emit: next,
@@ -841,6 +863,8 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
         }),
         ...(agent.aiMiddleware ?? []),
     ];
+    // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+    const sharedNotes = {};
     let modifiedMessages = trimmedMessages;
     let modifiedInstructions = instructions;
     for (const mw of aiMiddlewares) {
@@ -848,6 +872,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             const result = await mw.modifyInput(singletonServices, {
                 messages: modifiedMessages,
                 instructions: modifiedInstructions,
+                shared: sharedNotes,
             });
             modifiedMessages = result.messages;
             modifiedInstructions = result.instructions;
@@ -869,6 +894,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
                 event,
                 allEvents,
                 state,
+                shared: sharedNotes,
                 // Sends downstream directly, so a hook can hand back the fast event
                 // now and push the slow one when it is ready.
                 emit: next,

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;