@pikku/core 0.12.74 → 0.12.77

package/src/services/local-secrets.test.ts

@@ -7,14 +7,14 @@ describe('LocalSecretService', () => {
   test('should get secret from local storage', async () => {
     const service = new LocalSecretService()
     await service.setSecret('MY_KEY', { token: 'abc' })
-    const result = await service.getSecret('MY_KEY')
+    const result = (await service.getSecret('MY_KEY')).reveal()
     assert.deepStrictEqual(result, { token: 'abc' })
   })
 
   test('should get secret from environment variables', async () => {
     const vars = new LocalVariablesService({ MY_SECRET: 'secret-value' })
     const service = new LocalSecretService(vars)
-    const result = await service.getSecret('MY_SECRET')
+    const result = (await service.getSecret('MY_SECRET')).reveal()
     assert.strictEqual(result, 'secret-value')
   })
 
@@ -29,14 +29,14 @@ describe('LocalSecretService', () => {
   test('should get JSON secret from local storage', async () => {
     const service = new LocalSecretService()
     await service.setSecret('JSON_KEY', { data: 42 })
-    const result = await service.getSecret('JSON_KEY')
+    const result = (await service.getSecret('JSON_KEY')).reveal()
     assert.deepStrictEqual(result, { data: 42 })
   })
 
   test('should get JSON secret from environment variables', async () => {
     const vars = new LocalVariablesService({ CONFIG: '{"port":3000}' })
     const service = new LocalSecretService(vars)
-    const result = await service.getSecret('CONFIG')
+    const result = (await service.getSecret('CONFIG')).reveal()
     assert.deepStrictEqual(result, { port: 3000 })
   })
 
@@ -52,7 +52,7 @@ describe('LocalSecretService', () => {
     const vars = new LocalVariablesService({ KEY: 'env-value' })
     const service = new LocalSecretService(vars)
     await service.setSecret('KEY', 'local-value')
-    const result = await service.getSecret('KEY')
+    const result = (await service.getSecret('KEY')).reveal()
     assert.strictEqual(result, 'local-value')
   })
 
@@ -78,3 +78,18 @@ describe('LocalSecretService', () => {
     assert.strictEqual(await service.hasSecret('DEL_KEY'), false)
   })
 })
+
+describe('LocalSecretService round-trips a wrapped secret', () => {
+  test('setSecret unwraps rather than storing the redaction', async () => {
+    const service = new LocalSecretService()
+    await service.setSecret('SOURCE', 'sk-live-DEADBEEF')
+    const read = await service.getSecret('SOURCE')
+
+    await service.setSecret('COPY', read)
+
+    assert.strictEqual(
+      (await service.getSecret('COPY')).reveal(),
+      'sk-live-DEADBEEF'
+    )
+  })
+})

package/src/services/local-secrets.ts

@@ -1,5 +1,10 @@
+import {
+  createSecretValue,
+  isSecretValue,
+  type SecretValue,
+} from '../secret-value.js'
 import { LocalVariablesService } from './local-variables.js'
-import type { SecretService } from './secret-service.js'
+import type { SecretService, SecretValues } from './secret-service.js'
 import type { VariablesService } from './variables-service.js'
 
 export class LocalSecretService implements SecretService {
@@ -17,23 +22,26 @@ export class LocalSecretService implements SecretService {
     private variables: VariablesService = new LocalVariablesService()
   ) {}
 
-  public async getSecret<T = string>(key: string): Promise<T> {
+  public async getSecret<T = string>(key: string): Promise<SecretValue<T>> {
     const localValue = this.localSecrets.get(key)
     if (localValue) {
-      return this.parseSecret<T>(localValue)
+      return createSecretValue(this.parseSecret<T>(localValue))
     }
 
     const value = await this.variables.get(key)
     if (value) {
-      return this.parseSecret<T>(value)
+      return createSecretValue(this.parseSecret<T>(value))
     }
     throw new Error('Requested secret not found')
   }
 
   public async setSecret(key: string, value: unknown): Promise<void> {
+    // 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 value === 'string' ? value : JSON.stringify(value)
+      typeof raw === 'string' ? raw : JSON.stringify(raw)
     )
   }
 
@@ -51,13 +59,13 @@ export class LocalSecretService implements SecretService {
 
   public async getSecrets<
     T extends Record<string, unknown> = Record<string, unknown>,
-  >(keys: (keyof T & string)[]): Promise<Partial<T>> {
+  >(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>> {
     const results = await Promise.allSettled(keys.map((k) => this.getSecret(k)))
     const out: Record<string, unknown> = {}
     keys.forEach((key, i) => {
       if (results[i].status === 'fulfilled')
         out[key] = (results[i] as PromiseFulfilledResult<unknown>).value
     })
-    return out as Partial<T>
+    return out as Partial<SecretValues<T>>
   }
 }

package/src/services/logger.ts

@@ -1,3 +1,5 @@
+import type { Safe } from '../secret-value.js'
+
 export enum LogLevel {
   'trace',
   'debug',
@@ -7,19 +9,37 @@ export enum LogLevel {
   'critical',
 }
 
+/**
+ * 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
+  info<M extends string | Record<string, any>, A extends unknown[]>(
+    messageOrObj: Safe<M>,
+    ...meta: { [K in keyof A]: Safe<A[K]> }
+  ): void
 
-  warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void
+  warn<M extends string | Record<string, any>, A extends unknown[]>(
+    messageOrObj: Safe<M>,
+    ...meta: { [K in keyof A]: Safe<A[K]> }
+  ): void
 
-  error(
-    messageOrObj: string | Record<string, any> | Error,
-    ...meta: any[]
+  error<M extends string | Record<string, any> | Error, A extends unknown[]>(
+    messageOrObj: Safe<M>,
+    ...meta: { [K in keyof A]: Safe<A[K]> }
   ): void
 
-  debug(message: string, ...meta: any[]): void
+  debug<A extends unknown[]>(
+    message: string,
+    ...meta: { [K in keyof A]: Safe<A[K]> }
+  ): void
 
-  trace?(message: string, ...meta: any[]): void
+  trace?<A extends unknown[]>(
+    message: string,
+    ...meta: { [K in keyof A]: Safe<A[K]> }
+  ): void
 
   setLevel(level: LogLevel): void
 

package/src/services/queue-webhook-service.test.ts

@@ -14,6 +14,7 @@ import { InMemoryQueueService } from './in-memory-queue-service.js'
 import { wireQueueWorker } from '../wirings/queue/queue-runner.js'
 import { resetPikkuState, pikkuState } from '../pikku-state.js'
 import type { JobOptions } from '../wirings/queue/queue.types.js'
+import { createSecretValue } from '../secret-value.js'
 
 const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
 
@@ -132,7 +133,7 @@ describe('QueueWebhookService.send', () => {
       secrets: {
         getSecret: async (key: string) => {
           assert.equal(key, 'WEBHOOK_SIGNING_KEY')
-          return 'resolved-key'
+          return createSecretValue('resolved-key')
         },
       },
     })

package/src/services/queue-webhook-service.ts

@@ -52,7 +52,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/src/services/scoped-secret-service.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 class ScopedSecretService implements SecretService {
   constructor(
@@ -12,7 +13,7 @@ export class ScopedSecretService implements SecretService {
     }
   }
 
-  async getSecret<T = string>(key: string): Promise<T> {
+  async getSecret<T = string>(key: string): Promise<SecretValue<T>> {
     this.assertAllowed(key)
     return this.secrets.getSecret<T>(key)
   }
@@ -32,7 +33,7 @@ export class ScopedSecretService implements SecretService {
 
   async getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
     keys: (keyof T & string)[]
-  ): Promise<Partial<T>> {
+  ): Promise<Partial<SecretValues<T>>> {
     keys.forEach((k) => this.assertAllowed(k))
     return this.secrets.getSecrets<T>(keys)
   }

package/src/services/secret-service.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>
@@ -12,5 +17,5 @@ export interface SecretService {
    */
   getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
     keys: (keyof T & string)[]
-  ): Promise<Partial<T>>
+  ): Promise<Partial<SecretValues<T>>>
 }

package/src/services/typed-secret-service.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
@@ -25,8 +26,10 @@ export class TypedSecretService<
     private credentialsMeta: Record<string, CredentialMeta>
   ) {}
 
-  async getSecret<K extends keyof TMap & string>(key: K): Promise<TMap[K]>
-  async getSecret<T = string>(key: string): Promise<T>
+  async getSecret<K extends keyof TMap & string>(
+    key: K
+  ): Promise<SecretValue<TMap[K]>>
+  async getSecret<T = string>(key: string): Promise<SecretValue<T>>
   async getSecret(key: string): Promise<unknown> {
     if (this.cache.has(key)) {
       return this.cache.get(key)
@@ -58,12 +61,12 @@ export class TypedSecretService<
 
   async getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
     keys: (keyof T & string)[]
-  ): Promise<Partial<T>> {
-    const result: Partial<T> = {}
+  ): Promise<Partial<SecretValues<T>>> {
+    const result: Partial<SecretValues<T>> = {}
     const missing: (keyof T & string)[] = []
     for (const key of keys) {
       if (this.cache.has(key)) {
-        result[key] = this.cache.get(key) as T[keyof T & string]
+        result[key] = this.cache.get(key) as SecretValues<T>[keyof T & string]
       } else {
         missing.push(key)
       }
@@ -72,7 +75,8 @@ export class TypedSecretService<
       const fetched = await this.secrets.getSecrets<T>(missing)
       for (const [key, value] of Object.entries(fetched)) {
         this.cache.set(key, value)
-        result[key as keyof T & string] = value as T[keyof T & string]
+        result[key as keyof T & string] = value as SecretValues<T>[keyof T &
+          string]
       }
     }
     return result

package/src/services/webhook-service.ts

@@ -1,5 +1,6 @@
 import { NotImplementedError } from '../errors/errors.js'
 import { hmacSha256Hex, timingSafeStringEqual } from '../utils/hmac.js'
+import type { Safe } from '../secret-value.js'
 
 export interface SendWebhookInput {
   url: string
@@ -90,7 +91,9 @@ export const DEFAULT_WEBHOOK_SIGNATURE_HEADER = 'X-Pikku-Signature'
 export const DEFAULT_WEBHOOK_RETRIES = 3
 
 export 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 {

package/src/testing/service-tests.ts

@@ -831,17 +831,17 @@ export function defineServiceTests(config: ServiceTestConfig): void {
           token: string
           endpoint: string
         }>('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 () => {
@@ -862,7 +862,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         await service.setSecret('upsert-key', { v: 1 })
         await service.setSecret('upsert-key', { v: 2 })
         const result = await service.getSecret<{ v: number }>('upsert-key')
-        assert.deepEqual(result, { v: 2 })
+        assert.deepEqual(result.reveal(), { v: 2 })
       })
 
       test('deleteSecret removes the key', async () => {
@@ -887,7 +887,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         const before = await rotatedService.getSecret<{
           important: string
         }>('rotate-test')
-        assert.deepEqual(before, { important: 'data' })
+        assert.deepEqual(before.reveal(), { important: 'data' })
 
         assert.ok(rotatedService.rotateKEK)
         const count = await rotatedService.rotateKEK!()
@@ -900,7 +900,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         const after = await newOnlyService.getSecret<{
           important: string
         }>('rotate-test')
-        assert.deepEqual(after, { important: 'data' })
+        assert.deepEqual(after.reveal(), { important: 'data' })
       })
 
       test('rotateKEK throws without previousKey', async () => {

package/src/types/core.types.ts

@@ -44,6 +44,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'
@@ -125,11 +126,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
@@ -173,6 +175,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
@@ -323,6 +338,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/src/wirings/ai-agent/ai-agent-agui.test.ts

@@ -590,6 +590,22 @@ describe('wrapChannelWithAGUI — speech', () => {
     assert.ok(find(events, 'CUSTOM', 'pikku:audio-done'))
   })
 
+  it('forwards the transcript as a CUSTOM event', () => {
+    const { channel, events } = makeChannel()
+    const wrapped = wrapChannelWithAGUI(channel)
+
+    wrapped.send({
+      type: 'transcript',
+      text: 'what the user said',
+    } as AIStreamEvent)
+
+    // The client sent audio, so this is the only way it learns what its own
+    // turn was. Dropped, the user's message renders as an empty bubble.
+    const custom = find(events, 'CUSTOM', 'pikku:transcript')
+    assert.ok(custom)
+    assert.deepEqual(custom.value, { text: 'what the user said' })
+  })
+
   it('leaves an open text message open, so speech cannot split a reply', () => {
     const { channel, events } = makeChannel()
     const wrapped = wrapChannelWithAGUI(channel)

package/src/wirings/ai-agent/ai-agent-agui.ts

@@ -381,7 +381,11 @@ export function wrapChannelWithAGUI(
           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
         }
@@ -390,6 +394,15 @@ export function wrapChannelWithAGUI(
           send({ type: 'CUSTOM', name: 'pikku:audio-done', value: {} })
           break
         }
+
+        case 'transcript': {
+          send({
+            type: 'CUSTOM',
+            name: 'pikku:transcript',
+            value: { text: event.text },
+          })
+          break
+        }
       }
     },
   }

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -959,7 +959,13 @@ export async function prepareAgentRun(
 
   const userContent: AIMessage['content'] = input.attachments?.length
     ? [
-        { type: 'text' as const, 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' as const, text: input.message }]
+          : []),
         ...input.attachments.map(
           (a) =>
             ({

package/src/wirings/ai-agent/ai-agent-runner.ts

@@ -144,6 +144,9 @@ export async function runAIAgent(
     ...(agent.aiMiddleware ?? []),
   ]
 
+  // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+  const sharedNotes: Record<string, unknown> = {}
+
   let modifiedMessages = runnerParams.messages
   let modifiedInstructions = runnerParams.instructions
   for (const mw of aiMiddlewares) {
@@ -151,6 +154,7 @@ export async function runAIAgent(
       const result = await mw.modifyInput(singletonServices, {
         messages: modifiedMessages,
         instructions: modifiedInstructions,
+        shared: sharedNotes,
       })
       modifiedMessages = result.messages
       modifiedInstructions = result.instructions
@@ -159,6 +163,14 @@ export async function runAIAgent(
   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,
@@ -275,7 +287,7 @@ export async function runAIAgent(
           threadId,
           input.resourceId,
           memoryConfig,
-          userMessage,
+          persistedUserMessage,
           { text: '', steps: completedStepsForSave }
         )
 
@@ -351,7 +363,7 @@ export async function runAIAgent(
       threadId,
       input.resourceId,
       memoryConfig,
-      userMessage,
+      persistedUserMessage,
       {
         ...result,
         text: outputText,
@@ -608,6 +620,9 @@ async function continueAfterToolResultSync(
     }),
     ...(agent.aiMiddleware ?? []),
   ]
+  // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+  const sharedNotes: Record<string, unknown> = {}
+
   let modifiedMessages = trimmedMessages
   let modifiedInstructions = instructions
   for (const mw of aiMiddlewares) {
@@ -615,6 +630,7 @@ async function continueAfterToolResultSync(
       const result = await mw.modifyInput(singletonServices, {
         messages: modifiedMessages,
         instructions: modifiedInstructions,
+        shared: sharedNotes,
       })
       modifiedMessages = result.messages
       modifiedInstructions = result.instructions

package/src/wirings/ai-agent/ai-agent-stream.ts

@@ -12,6 +12,7 @@ import type {
 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,
@@ -672,6 +673,9 @@ export async function streamAIAgent(
     ...(agent.aiMiddleware ?? []),
   ]
 
+  // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+  const sharedNotes: Record<string, unknown> = {}
+
   let modifiedMessages = runnerParams.messages
   let modifiedInstructions = runnerParams.instructions
   for (const mw of aiMiddlewares) {
@@ -679,6 +683,7 @@ export async function streamAIAgent(
       const result = await mw.modifyInput(singletonServices, {
         messages: modifiedMessages,
         instructions: modifiedInstructions,
+        shared: sharedNotes,
       })
       modifiedMessages = result.messages
       modifiedInstructions = result.instructions
@@ -687,6 +692,26 @@ export async function streamAIAgent(
   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,
@@ -706,7 +731,7 @@ export async function streamAIAgent(
   runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle)
 
   if (storage) {
-    await storage.saveMessages(threadId, [userMessage])
+    await storage.saveMessages(threadId, [persistedUserMessage])
   }
 
   const streamMiddleware = aiMiddlewares
@@ -720,6 +745,7 @@ export async function streamAIAgent(
           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,
@@ -1288,6 +1314,9 @@ async function continueAfterToolResult(
     }),
     ...(agent.aiMiddleware ?? []),
   ]
+  // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+  const sharedNotes: Record<string, unknown> = {}
+
   let modifiedMessages = trimmedMessages
   let modifiedInstructions = instructions
   for (const mw of aiMiddlewares) {
@@ -1295,6 +1324,7 @@ async function continueAfterToolResult(
       const result = await mw.modifyInput(singletonServices, {
         messages: modifiedMessages,
         instructions: modifiedInstructions,
+        shared: sharedNotes,
       })
       modifiedMessages = result.messages
       modifiedInstructions = result.instructions
@@ -1318,6 +1348,7 @@ async function continueAfterToolResult(
           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,