@pikku/core 0.12.74 → 0.12.78

package/dist/services/local-content-request-handler.js

@@ -0,0 +1,176 @@
+import { createReadStream } from 'fs';
+import { mkdir, stat, writeFile } from 'fs/promises';
+import { normalize, resolve } from 'path';
+import { Readable } from 'stream';
+import { signedContentPath } from './local-content.js';
+const matchesPrefix = (pathname, prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`);
+const contentKey = (pathname, prefix) => pathname.slice(prefix.length).replace(/^\/+/, '');
+/**
+ * Resolve a key against the content root, or `null` if it escapes. `normalize`
+ * first so `..` segments are collapsed before the prefix check, and the
+ * comparison carries a trailing separator so a sibling directory whose name
+ * merely starts with the root's cannot pass as being inside it.
+ */
+const toTargetPath = (basePath, key) => {
+    const normalizedBasePath = resolve(basePath);
+    const targetPath = resolve(normalizedBasePath, normalize(key));
+    return targetPath.startsWith(`${normalizedBasePath}/`) ? targetPath : null;
+};
+const parseSizeLimit = (sizeLimit) => {
+    const match = /^(\d+(?:\.\d+)?)(b|kb|mb|gb)?$/i.exec(sizeLimit.trim());
+    if (!match) {
+        throw new Error(`Invalid size limit: ${sizeLimit}`);
+    }
+    const value = Number(match[1]);
+    const unit = (match[2] ?? 'b').toLowerCase();
+    const multiplier = unit === 'gb'
+        ? 1024 * 1024 * 1024
+        : unit === 'mb'
+            ? 1024 * 1024
+            : unit === 'kb'
+                ? 1024
+                : 1;
+    return value * multiplier;
+};
+const text = (status, body) => new Response(body, {
+    status,
+    headers: { 'content-type': 'text/plain; charset=utf-8' },
+});
+export const createLocalContentRequestHandler = ({ content, logger, getJWT, }) => {
+    // Logged at most once. An unverifiable request is attacker-triggerable, so
+    // this reports a startup misconfiguration rather than per-request news.
+    let loggedMissingJWT = false;
+    const validateSignedAssetRequest = async (requestUrl) => {
+        const signedAtValue = requestUrl.searchParams.get('signedAt');
+        const expiresAtValue = requestUrl.searchParams.get('expiresAt');
+        const notBeforeValue = requestUrl.searchParams.get('notBefore');
+        const signature = requestUrl.searchParams.get('signature');
+        if (!signedAtValue || !expiresAtValue) {
+            return { ok: false, status: 403, body: 'Signed URL required' };
+        }
+        const signedAt = Number(signedAtValue);
+        const expiresAt = Number(expiresAtValue);
+        const notBefore = notBeforeValue == null ? undefined : Number(notBeforeValue);
+        if (!Number.isFinite(signedAt) ||
+            !Number.isFinite(expiresAt) ||
+            (notBefore != null && !Number.isFinite(notBefore))) {
+            return { ok: false, status: 403, body: 'Invalid signed URL' };
+        }
+        const now = Date.now();
+        if (now > expiresAt || (notBefore != null && now < notBefore)) {
+            return { ok: false, status: 403, body: 'Signed URL expired' };
+        }
+        const jwt = getJWT();
+        if (!jwt) {
+            if (!loggedMissingJWT) {
+                loggedMissingJWT = true;
+                logger.error('pikku: refusing signed asset reads — no JWTService is available to verify them. Pass `contentSigningJWT` (the same service LocalContent signs with) or expose it as `singletonServices.jwt`.');
+            }
+            return { ok: false, status: 403, body: 'Invalid signed URL' };
+        }
+        if (!signature) {
+            return { ok: false, status: 403, body: 'Signed URL signature required' };
+        }
+        try {
+            const payload = await jwt.decode(signature);
+            // Every claim is compared, the path included: without it a signature
+            // minted for one asset would read any other.
+            if (payload.signedAt !== signedAt ||
+                payload.expiresAt !== expiresAt ||
+                payload.notBefore !== notBefore ||
+                payload.path !== signedContentPath(requestUrl.pathname)) {
+                return { ok: false, status: 403, body: 'Invalid signed URL' };
+            }
+        }
+        catch {
+            return { ok: false, status: 403, body: 'Invalid signed URL' };
+        }
+        return { ok: true };
+    };
+    const handleUpload = async (request, pathname) => {
+        const key = contentKey(pathname, content.uploadUrlPrefix);
+        const targetPath = toTargetPath(content.localFileUploadPath, key);
+        if (!targetPath) {
+            return text(400, 'Invalid path');
+        }
+        const maxBytes = parseSizeLimit(content.sizeLimit ?? '1mb');
+        // Counted as it arrives and abandoned the moment it goes over, so an
+        // oversized upload costs the limit rather than its own size — `arrayBuffer()`
+        // would have to hold all of it first, which hands an unauthenticated caller
+        // a way to spend the server's memory. Mirrors node-http-server's
+        // `readRequestBody`, which aborts the same way.
+        const chunks = [];
+        let bytesRead = 0;
+        const reader = request.body?.getReader();
+        if (reader) {
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    bytesRead += value.byteLength;
+                    if (bytesRead > maxBytes) {
+                        await reader.cancel();
+                        return text(413, 'Content too large');
+                    }
+                    chunks.push(Buffer.from(value));
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+        await mkdir(resolve(targetPath, '..'), { recursive: true });
+        await writeFile(targetPath, Buffer.concat(chunks));
+        return new Response(null, { status: 200 });
+    };
+    const handleAsset = async (request, requestUrl, pathname) => {
+        const key = contentKey(pathname, content.assetUrlPrefix);
+        const targetPath = toTargetPath(content.localFileUploadPath, key);
+        if (!targetPath) {
+            return text(400, 'Invalid path');
+        }
+        const signed = await validateSignedAssetRequest(requestUrl);
+        if (!signed.ok) {
+            return text(signed.status, signed.body);
+        }
+        try {
+            const file = await stat(targetPath);
+            if (!file.isFile()) {
+                return new Response(null, { status: 404 });
+            }
+            const headers = {
+                'content-length': String(file.size),
+                'content-type': 'application/octet-stream',
+            };
+            if (request.method === 'HEAD') {
+                return new Response(null, { status: 200, headers });
+            }
+            // Streamed rather than buffered: assets are user uploads, and their size
+            // is bounded by `sizeLimit` at write time, not by anything here.
+            return new Response(Readable.toWeb(createReadStream(targetPath)), { status: 200, headers });
+        }
+        catch {
+            return new Response(null, { status: 404 });
+        }
+    };
+    return async (request) => {
+        let requestUrl;
+        try {
+            requestUrl = new URL(request.url);
+        }
+        catch {
+            return null;
+        }
+        const pathname = decodeURIComponent(requestUrl.pathname);
+        if (request.method === 'PUT' &&
+            matchesPrefix(pathname, content.uploadUrlPrefix)) {
+            return handleUpload(request, pathname);
+        }
+        if ((request.method === 'GET' || request.method === 'HEAD') &&
+            matchesPrefix(pathname, content.assetUrlPrefix)) {
+            return handleAsset(request, requestUrl, pathname);
+        }
+        return null;
+    };
+};

package/dist/services/local-secrets.d.ts

@@ -1,13 +1,14 @@
-import type { SecretService } from './secret-service.js';
+import { type SecretValue } from '../secret-value.js';
+import type { SecretService, SecretValues } from './secret-service.js';
 import type { VariablesService } from './variables-service.js';
 export declare class LocalSecretService implements SecretService {
     private variables;
     private localSecrets;
     private parseSecret;
     constructor(variables?: VariablesService);
-    getSecret<T = string>(key: string): Promise<T>;
+    getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     setSecret(key: string, value: unknown): Promise<void>;
     hasSecret(key: string): Promise<boolean>;
     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/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,