@pikku/core 0.12.72 → 0.12.74

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

@@ -1,10 +1,48 @@
+/**
+ * Raised when every audio part in a turn turned out to be non-speech.
+ *
+ * Distinct from a transcription failure, because the response is different: a
+ * failure is worth reporting, whereas this is the microphone doing its job on a
+ * pause. A voice loop should catch it and go back to listening without running
+ * the agent — answering a hallucinated sentence is worse than answering nothing.
+ */
+export declare class NoSpeechDetectedError extends Error {
+    constructor();
+}
+/**
+ * Whether nothing usable was said — an empty transcript, and nothing cleverer
+ * than that.
+ *
+ * There was a confidence gate here once, and it is worth recording why it is
+ * gone. Whisper is trained on subtitles, so audio it cannot parse comes back
+ * not as nothing but as stock filler appended to real speech: "Hello, my name
+ * is Yasir. Thank you." where only the first sentence was spoken. The obvious
+ * defence is to drop low-confidence segments, and it does not work. Measured on
+ * a real turn, the invented "Thank you." scored `avg_logprob` -0.52 against
+ * -0.30 for the genuine sentence beside it, and `no_speech_prob` read 0.000 for
+ * both. Whisper is *confident* when it invents, because the text it invents is
+ * high-probability text. No threshold separates those two numbers, and one set
+ * low enough to try would take real quiet speech with it.
+ *
+ * The fix belongs at the model, not behind it: an ASR that is not a
+ * subtitle-trained autoregressive decoder returns an empty string on non-speech
+ * and there is nothing left to filter. Hence this reduces to asking whether
+ * anything came back at all — which is a property every provider reports
+ * honestly, unlike per-segment confidence (Nemotron, for one, hardcodes
+ * `avg_logprob` to 0.0).
+ */
+export declare const readsAsNonSpeech: (result: {
+    text?: string;
+}) => boolean;
 export declare const voiceInput: (config?: {
     language?: string;
     model?: string;
     allowedAudioHosts?: string[];
 }) => import("./ai-agent.types.js").PikkuAIMiddlewareHooks<Record<string, unknown>, import("../../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../../services/logger.js").LogLevel;
-    secrets?: {};
+    secrets?: {
+        requireAllowedHosts?: boolean;
+    };
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
     webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;

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

@@ -9,6 +9,43 @@ function base64ToUint8Array(base64) {
     return bytes;
 }
 const MAX_AUDIO_SIZE = 50 * 1024 * 1024;
+/**
+ * Raised when every audio part in a turn turned out to be non-speech.
+ *
+ * Distinct from a transcription failure, because the response is different: a
+ * failure is worth reporting, whereas this is the microphone doing its job on a
+ * pause. A voice loop should catch it and go back to listening without running
+ * the agent — answering a hallucinated sentence is worse than answering nothing.
+ */
+export class NoSpeechDetectedError extends Error {
+    constructor() {
+        super('No speech was detected in the audio.');
+        this.name = 'NoSpeechDetectedError';
+    }
+}
+/**
+ * Whether nothing usable was said — an empty transcript, and nothing cleverer
+ * than that.
+ *
+ * There was a confidence gate here once, and it is worth recording why it is
+ * gone. Whisper is trained on subtitles, so audio it cannot parse comes back
+ * not as nothing but as stock filler appended to real speech: "Hello, my name
+ * is Yasir. Thank you." where only the first sentence was spoken. The obvious
+ * defence is to drop low-confidence segments, and it does not work. Measured on
+ * a real turn, the invented "Thank you." scored `avg_logprob` -0.52 against
+ * -0.30 for the genuine sentence beside it, and `no_speech_prob` read 0.000 for
+ * both. Whisper is *confident* when it invents, because the text it invents is
+ * high-probability text. No threshold separates those two numbers, and one set
+ * low enough to try would take real quiet speech with it.
+ *
+ * The fix belongs at the model, not behind it: an ASR that is not a
+ * subtitle-trained autoregressive decoder returns an empty string on non-speech
+ * and there is nothing left to filter. Hence this reduces to asking whether
+ * anything came back at all — which is a property every provider reports
+ * honestly, unlike per-segment confidence (Nemotron, for one, hardcodes
+ * `avg_logprob` to 0.0).
+ */
+export const readsAsNonSpeech = (result) => !(result.text ?? '').trim();
 async function fetchAsUint8Array(url, allowedAudioHosts) {
     const response = await safeFetch(url, {}, { allowedHosts: allowedAudioHosts });
     const contentLength = response.headers.get('content-length');
@@ -36,9 +73,6 @@ export const voiceInput = (config) => pikkuAIMiddleware({
         const hasAudio = parts.some((p) => p.type === 'file' && !!p.mediaType?.startsWith('audio/'));
         if (!hasAudio)
             return { messages, instructions };
-        // Process parts in order, replacing each audio part with its transcription
-        // in place. Sequential, so no unbounded parallel downloads/transcriptions
-        // and original content ordering is preserved.
         const updatedContent = [];
         for (const p of parts) {
             if (!(p.type === 'file' && p.mediaType?.startsWith('audio/'))) {
@@ -64,8 +98,17 @@ export const voiceInput = (config) => pikkuAIMiddleware({
                     }
                     : {}),
             });
+            // Dropped when nothing was said: an empty text part is still a turn the
+            // model will answer, and what it answers is a guess about what it could
+            // not hear.
+            if (readsAsNonSpeech(result))
+                continue;
             updatedContent.push({ type: 'text', text: result.text });
         }
+        // Every part was audio, and none of it was speech. There is nothing left
+        // to send, and a message with no content is not a question.
+        if (updatedContent.length === 0)
+            throw new NoSpeechDetectedError();
         return {
             messages: [
                 ...messages.slice(0, -1),

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

@@ -1,6 +1,47 @@
 type VoiceOutputState = {
     textBuffer?: string;
+    /**
+     * The audio emitted so far, as a chain.
+     *
+     * Synthesis for every finished sentence starts immediately, so the second
+     * sentence is being generated while the first is still being spoken. That
+     * also means the second can finish first — a short sentence after a long one
+     * routinely does. Chaining the *emissions* keeps the client receiving audio
+     * in the order it was written while leaving the generation overlapped.
+     */
+    tail?: Promise<void>;
+    /** Whether this reply has already said it cannot be spoken aloud. */
+    reportedUnspeakable?: boolean;
 };
+/**
+ * The scripts a model can pronounce, and optionally the voice each one needs.
+ *
+ * The array form is for a model whose voice is the same whatever the script.
+ * The record form exists because that is not the common case: Kokoro speaks
+ * Mandarin, Japanese and Hindi well, but only through a voice belonging to that
+ * language. Asked for Chinese in its default American-English voice it spells
+ * the characters out — 9.9 seconds of "Chinese letter, Chinese letter" for a
+ * sentence the right voice says in 3.5. Same model, same text, same price.
+ */
+export type SpeakableScripts = string[] | Record<string, string>;
+/**
+ * The scripts present in `text` that the model was not said to handle.
+ *
+ * Silence would be the wrong answer here and so would a best effort. Handed
+ * Arabic — which it has no voice for at all — Kokoro does not fail and does not
+ * stay quiet: it reads out the *letter names*, twenty-four seconds of "Arabic
+ * meem, Arabic ra" for a one-line sentence, which is worse than either. Naming
+ * the gap lets the caller say so instead.
+ */
+export declare const unspeakableScripts: (text: string, speakable: SpeakableScripts) => string[];
+/**
+ * The voice to speak `text` in, or `fallback` if no mapped script appears.
+ *
+ * A sentence is regularly in more than one script, so which one decides is
+ * settled by {@link SCRIPT_PRECEDENCE} rather than by the order the config
+ * happens to be written in.
+ */
+export declare const voiceForText: (text: string, speakable: SpeakableScripts, fallback?: string) => string | undefined;
 export declare const voiceOutput: (config?: {
     model?: string;
     format?: string;
@@ -8,9 +49,21 @@ export declare const voiceOutput: (config?: {
     instructions?: string;
     speed?: number;
     language?: string;
+    /**
+     * Scripts the configured model can actually pronounce, and the voice each
+     * needs — see {@link SpeakableScripts}. Anything written in another script is
+     * left unspoken and reported once, as a `voice-unsupported` data event,
+     * rather than sent to a model that will mangle it.
+     *
+     * Omitted means no check: every model is trusted with every script, which is
+     * the right default for a provider that genuinely is multilingual.
+     */
+    speakableScripts?: SpeakableScripts;
 }) => import("./ai-agent.types.js").PikkuAIMiddlewareHooks<VoiceOutputState, import("../../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../../services/logger.js").LogLevel;
-    secrets?: {};
+    secrets?: {
+        requireAllowedHosts?: boolean;
+    };
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
     webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;

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

@@ -10,6 +10,76 @@ const SENTENCE_BOUNDARY = /[.!?]\s*$/;
 function isSentenceBoundary(text) {
     return SENTENCE_BOUNDARY.test(text);
 }
+/**
+ * Scripts a speech model can pronounce, as named by {@link voiceOutput}'s
+ * `speakableScripts`.
+ *
+ * Script rather than language because script is what is decidable from the text
+ * alone. Spanish, French and English are one test, not three — and the models
+ * that handle one Latin-script language generally handle the others. What a
+ * model cannot do is invent a phoneme set it was never given.
+ */
+const SCRIPT_RANGES = {
+    latin: /[A-ɏ]/,
+    devanagari: /[ऀ-ॿ]/,
+    han: /[㐀-鿿]/,
+    kana: /[぀-ヿ]/,
+    arabic: /[؀-ۿݐ-ݿ]/,
+    cyrillic: /[Ѐ-ӿ]/,
+    hangul: /[가-힯ᄀ-ᇿ]/,
+    hebrew: /[֐-׿]/,
+    greek: /[Ͱ-Ͽ]/,
+    thai: /[฀-๿]/,
+};
+/**
+ * Which script decides the voice when a sentence contains several.
+ *
+ * The ordering is by how much a script narrows down the language, not by
+ * preference. Kana appears only in Japanese, so a sentence holding any settles
+ * it — while Han is written in both Chinese and Japanese and so cannot, which
+ * matters because ordinary Japanese is mostly kanji. Latin comes last for the
+ * same reason from the other end: it turns up inside sentences in every other
+ * script, and it is the one whose voice is least often the one that counts. A
+ * Chinese voice reading an English word is accented; an English voice reading
+ * Chinese spells it out.
+ *
+ * Everything else — Han included — sits between the two in config order.
+ */
+const SCRIPT_PRECEDENCE = { kana: -1, latin: 1 };
+const scriptRank = (name) => SCRIPT_PRECEDENCE[name] ?? 0;
+const scriptNames = (speakable) => Array.isArray(speakable) ? speakable : Object.keys(speakable);
+/**
+ * The scripts present in `text` that the model was not said to handle.
+ *
+ * Silence would be the wrong answer here and so would a best effort. Handed
+ * Arabic — which it has no voice for at all — Kokoro does not fail and does not
+ * stay quiet: it reads out the *letter names*, twenty-four seconds of "Arabic
+ * meem, Arabic ra" for a one-line sentence, which is worse than either. Naming
+ * the gap lets the caller say so instead.
+ */
+export const unspeakableScripts = (text, speakable) => {
+    const allowed = new Set(scriptNames(speakable));
+    return Object.entries(SCRIPT_RANGES)
+        .filter(([name, range]) => !allowed.has(name) && range.test(text))
+        .map(([name]) => name);
+};
+/**
+ * The voice to speak `text` in, or `fallback` if no mapped script appears.
+ *
+ * A sentence is regularly in more than one script, so which one decides is
+ * settled by {@link SCRIPT_PRECEDENCE} rather than by the order the config
+ * happens to be written in.
+ */
+export const voiceForText = (text, speakable, fallback) => {
+    if (Array.isArray(speakable))
+        return fallback;
+    const mapped = Object.entries(speakable).sort(([a], [b]) => scriptRank(a) - scriptRank(b));
+    for (const [name, voice] of mapped) {
+        if (SCRIPT_RANGES[name]?.test(text))
+            return voice;
+    }
+    return fallback;
+};
 async function synthesizeAudio(aiAgentRunner, input) {
     const result = await aiAgentRunner.generateSpeech?.({
         model: input.model,
@@ -19,76 +89,109 @@ async function synthesizeAudio(aiAgentRunner, input) {
         instructions: input.instructions,
         speed: input.speed,
         language: input.language,
+        abortSignal: input.abortSignal,
     });
     if (!result) {
         throw new Error('voiceOutput requires an aiAgentRunner with generateSpeech support');
     }
-    // Label chunks with the format the provider actually returned (config.format
-    // is only a request), falling back to the requested format then pcm16.
     return {
         bytes: result.audio.uint8Array,
         format: result.audio.format || input.format || 'pcm16',
     };
 }
 export const voiceOutput = (config) => pikkuAIMiddleware({
-    modifyOutputStream: async (services, { event, state }) => {
-        const aiAgentRunner = services.aiAgentRunner;
+    modifyOutputStream: async (services, { event, state, emit, signal }) => {
+        const { aiAgentRunner, logger } = services;
         if (!aiAgentRunner?.generateSpeech)
             return event;
-        if (event.type === 'done') {
-            const remaining = state.textBuffer ?? '';
-            if (remaining) {
-                state.textBuffer = '';
-                if (!config?.model) {
-                    throw new Error('voiceOutput requires a speech model (e.g. openai/tts-1)');
+        /**
+         * Queue a finished sentence for speech.
+         *
+         * Nothing here is awaited by the caller. Synthesis is kicked off at once
+         * and its emission is chained behind the previous sentence, which is
+         * what keeps the text flowing at the speed the model writes it instead
+         * of the speed the speech provider answers.
+         */
+        const speak = (text) => {
+            if (!config?.model) {
+                throw new Error('voiceOutput requires a speech model (e.g. openai/tts-1)');
+            }
+            // Checked per sentence but announced once per reply: a bilingual answer
+            // should still speak the half it can, and repeating the notice for
+            // every sentence of a long one would bury the reply itself.
+            //
+            // Per sentence is also what makes the voice right. A reply that answers
+            // in English and then quotes a Chinese title is two sentences in two
+            // scripts, and each is synthesized in the voice its own script needs.
+            let voice = config.voice;
+            if (config.speakableScripts) {
+                const unspeakable = unspeakableScripts(text, config.speakableScripts);
+                voice = voiceForText(text, config.speakableScripts, config.voice);
+                if (unspeakable.length > 0) {
+                    if (!state.reportedUnspeakable) {
+                        state.reportedUnspeakable = true;
+                        state.tail = (state.tail ?? Promise.resolve()).then(() => emit({
+                            type: 'data',
+                            name: 'voice-unsupported',
+                            data: { model: config.model, scripts: unspeakable },
+                        }));
+                    }
+                    return;
                 }
-                const audio = await synthesizeAudio(aiAgentRunner, {
-                    model: config.model,
-                    text: remaining,
-                    voice: config?.voice,
-                    format: config?.format,
-                    instructions: config?.instructions,
-                    speed: config?.speed,
-                    language: config?.language,
+            }
+            // Settled into a value rather than left as a rejectable promise: it
+            // sits unobserved until the chain reaches it, and an unhandled
+            // rejection in that window would take the process down.
+            const synthesis = synthesizeAudio(aiAgentRunner, {
+                model: config.model,
+                text,
+                voice,
+                format: config?.format,
+                instructions: config?.instructions,
+                speed: config?.speed,
+                language: config?.language,
+                // Barge-in should stop the bill, not just the playback. Without this
+                // every sentence already in flight is synthesized in full and paid
+                // for after the user has stopped listening.
+                abortSignal: signal,
+            }).then((audio) => ({ ok: true, audio }), (error) => ({ ok: false, error }));
+            state.tail = (state.tail ?? Promise.resolve()).then(async () => {
+                const result = await synthesis;
+                if (!result.ok) {
+                    // One sentence going unspoken is better than the rest of the reply
+                    // never arriving, so the chain carries on.
+                    logger?.error(`voiceOutput could not synthesize a sentence: ${String(result.error)}`);
+                    return;
+                }
+                await emit({
+                    type: 'audio-delta',
+                    data: bufferToBase64(result.audio.bytes),
+                    format: result.audio.format,
                 });
-                return [
-                    {
-                        type: 'audio-delta',
-                        data: bufferToBase64(audio.bytes),
-                        format: audio.format,
-                    },
-                    { type: 'audio-done' },
-                    event,
-                ];
+            });
+        };
+        if (event.type === 'done') {
+            const remaining = state.textBuffer ?? '';
+            state.textBuffer = '';
+            if (remaining.trim()) {
+                speak(remaining);
             }
+            // The only place this hook waits. The reply is already over, so the
+            // wait costs the reader nothing, and it is what makes `audio-done`
+            // mean what it says rather than racing the last chunk.
+            await state.tail;
+            state.tail = undefined;
             return [{ type: 'audio-done' }, event];
         }
         if (event.type !== 'text-delta')
             return event;
         state.textBuffer = `${state.textBuffer ?? ''}${event.text}`;
-        if (!isSentenceBoundary(state.textBuffer))
-            return event;
-        const text = state.textBuffer;
-        state.textBuffer = '';
-        if (!config?.model) {
-            throw new Error('voiceOutput requires a speech model (e.g. openai/tts-1)');
+        if (isSentenceBoundary(state.textBuffer)) {
+            const text = state.textBuffer;
+            state.textBuffer = '';
+            speak(text);
         }
-        const audio = await synthesizeAudio(aiAgentRunner, {
-            model: config.model,
-            text,
-            voice: config?.voice,
-            format: config?.format,
-            instructions: config?.instructions,
-            speed: config?.speed,
-            language: config?.language,
-        });
-        return [
-            event,
-            {
-                type: 'audio-delta',
-                data: bufferToBase64(audio.bytes),
-                format: audio.format,
-            },
-        ];
+        // Returned without waiting for any audio — the entire point.
+        return event;
     },
 });

package/dist/wirings/channel/channel-common.d.ts

@@ -1,25 +1,7 @@
 import type { CoreSingletonServices, MiddlewareMetadata } from '../../types/core.types.js';
 import type { CoreChannel, ChannelMessageMeta } from './channel.types.js';
-/**
- * Runs a channel lifecycle function (onConnect or onDisconnect) with proper middleware handling.
- *
- * This function:
- * 1. Extracts inline middleware from the lifecycle config if present
- * 2. Combines metadata middleware with inline middleware using combineMiddleware()
- * 3. Wraps the channel with channel middleware if present
- * 4. Runs the lifecycle function with middleware support
- *
- * @param channelConfig - The channel configuration
- * @param meta - Metadata for the lifecycle function (connect or disconnect)
- * @param lifecycleConfig - The onConnect or onDisconnect config (can be function or object with middleware)
- * @param lifecycleType - Type of lifecycle for cache key ('connect' or 'disconnect')
- * @param services - All services (singleton + session)
- * @param channel - The channel instance
- * @param data - Optional data to pass to the lifecycle function (for onConnect)
- * @param channelMiddlewareMeta - Optional channel middleware metadata for wrapping channel.send()
- * @returns Promise<unknown> - Result from the lifecycle function (if any)
- */
-export declare const runChannelLifecycleWithMiddleware: ({ channelConfig, meta, lifecycleConfig, lifecycleType, services, channel, data, channelMiddlewareMeta, }: {
+import { type PikkuSessionService } from '../../services/user-session-service.js';
+export declare const runChannelLifecycleWithMiddleware: ({ channelConfig, meta, lifecycleConfig, lifecycleType, services, channel, data, channelMiddlewareMeta, userSession, }: {
     channelConfig: CoreChannel<unknown, any>;
     meta: ChannelMessageMeta;
     lifecycleConfig: any;
@@ -28,4 +10,9 @@ export declare const runChannelLifecycleWithMiddleware: ({ channelConfig, meta,
     channel: any;
     data?: unknown;
     channelMiddlewareMeta?: MiddlewareMetadata[];
+    /**
+     * Established while the socket was upgrading, so `onConnect` can tell who
+     * just connected.
+     */
+    userSession?: PikkuSessionService<any>;
 }) => Promise<unknown>;

package/dist/wirings/channel/channel-common.js

@@ -1,26 +1,8 @@
 import { combineMiddleware, runMiddleware } from '../../middleware-runner.js';
 import { runPikkuFunc } from '../../function/function-runner.js';
+import { createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from './channel-middleware-runner.js';
-/**
- * Runs a channel lifecycle function (onConnect or onDisconnect) with proper middleware handling.
- *
- * This function:
- * 1. Extracts inline middleware from the lifecycle config if present
- * 2. Combines metadata middleware with inline middleware using combineMiddleware()
- * 3. Wraps the channel with channel middleware if present
- * 4. Runs the lifecycle function with middleware support
- *
- * @param channelConfig - The channel configuration
- * @param meta - Metadata for the lifecycle function (connect or disconnect)
- * @param lifecycleConfig - The onConnect or onDisconnect config (can be function or object with middleware)
- * @param lifecycleType - Type of lifecycle for cache key ('connect' or 'disconnect')
- * @param services - All services (singleton + session)
- * @param channel - The channel instance
- * @param data - Optional data to pass to the lifecycle function (for onConnect)
- * @param channelMiddlewareMeta - Optional channel middleware metadata for wrapping channel.send()
- * @returns Promise<unknown> - Result from the lifecycle function (if any)
- */
-export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, lifecycleConfig, lifecycleType, services, channel, data, channelMiddlewareMeta, }) => {
+export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, lifecycleConfig, lifecycleType, services, channel, data, channelMiddlewareMeta, userSession, }) => {
     const lifecycleMiddleware = typeof lifecycleConfig === 'object' && 'middleware' in lifecycleConfig
         ? lifecycleConfig.middleware || []
         : [];
@@ -32,7 +14,10 @@ export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, l
         wireInheritedChannelMiddleware: channelMiddlewareMeta,
         wireChannelMiddleware: channelConfig.channelMiddleware,
     });
-    let wire = { channel };
+    let wire = {
+        channel,
+        ...(userSession ? createMiddlewareSessionWireProps(userSession) : {}),
+    };
     if (allChannelMiddleware.length > 0) {
         wire = wrapChannelWithMiddleware(wire, services, allChannelMiddleware);
     }
@@ -41,6 +26,7 @@ export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, l
             singletonServices: services,
             data: () => data,
             wire,
+            sessionService: userSession,
             tags: meta.tags ?? [],
             packageName: meta.packageName ?? null,
         });

package/dist/wirings/channel/channel-handler.js

@@ -1,5 +1,7 @@
 import { pikkuState } from '../../pikku-state.js';
 import { runPikkuFunc } from '../../function/function-runner.js';
+import { isChannelRPCPending, isChannelRPCResponse } from './channel-rpc.js';
+import { handleChannelRPCResponse } from './channel-host-rpc.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
 const getChannelMeta = (channelName) => {
     return pikkuState(null, 'channel', 'meta')[channelName];
@@ -95,15 +97,25 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
     const onMessage = async (rawData) => {
         let result;
         let processed = false;
-        // Route-specific handling
-        if (typeof rawData === 'string' && channelConfig.onMessageWiring) {
-            let messageData;
+        let frame;
+        if (typeof rawData === 'string') {
             try {
-                messageData = JSON.parse(rawData);
+                frame = JSON.parse(rawData);
             }
             catch {
                 // Most likely a json error.. ignore
             }
+        }
+        // Taken ahead of routing so every channel gets reverse RPC without
+        // declaring a route for replies, and so an answer to a call someone is
+        // still awaiting can never be mistaken for a new message.
+        if (isChannelRPCResponse(frame) || isChannelRPCPending(frame)) {
+            handleChannelRPCResponse(channelHandler.getChannel().channelId, frame);
+            return;
+        }
+        // Route-specific handling
+        if (typeof rawData === 'string' && channelConfig.onMessageWiring) {
+            const messageData = frame;
             if (messageData) {
                 const entries = Object.entries(channelConfig.onMessageWiring);
                 for (const [routingProperty, routes] of entries) {
@@ -111,9 +123,16 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
                     if (routerValue && routes[routerValue]) {
                         const { [routingProperty]: _, ...data } = messageData;
                         processed = true;
+                        const routeResult = await processMessage(data, routes[routerValue], routingProperty, routerValue);
+                        // The routing key is echoed so the client can match the reply.
+                        // Assigning it to a primitive throws under ESM strict mode, so a
+                        // primitive result is wrapped rather than mutated.
                         result =
-                            (await processMessage(data, routes[routerValue], routingProperty, routerValue)) || {};
-                        result[routingProperty] = routerValue;
+                            routeResult !== null && typeof routeResult === 'object'
+                                ? Object.assign(routeResult, { [routingProperty]: routerValue })
+                                : routeResult === undefined
+                                    ? { [routingProperty]: routerValue }
+                                    : { [routingProperty]: routerValue, result: routeResult };
                         break;
                     }
                 }

package/dist/wirings/channel/channel-host-rpc.d.ts

@@ -0,0 +1,25 @@
+import { ChannelDeploymentService } from './channel-rpc.js';
+import type { ChannelRPCValidator } from './channel-rpc.js';
+import type { PikkuChannel } from './channel.types.js';
+/**
+ * The transport for a connection, created on first use. `options` apply only
+ * to the call that creates it — one connection has one transport, so the first
+ * caller's timeout and validators become the connection's.
+ */
+export declare const getChannelHostRPC: (channel: PikkuChannel<unknown, any>, options?: {
+    timeoutMs?: number;
+    validateInput?: ChannelRPCValidator;
+    validateResult?: ChannelRPCValidator;
+}) => ChannelDeploymentService;
+/**
+ * Kept out of the channel handler so a channel nobody calls back on pays for no
+ * registry, and because a handler has no services to build a validator with.
+ */
+export declare const channelRemote: (channel: PikkuChannel<unknown, any, any>, funcName: string, data?: unknown) => Promise<unknown>;
+/** False for an unknown connection or id, so a stray frame is dropped. */
+export declare const handleChannelRPCResponse: (channelId: string, message: unknown) => boolean;
+/**
+ * Must run on disconnect: without it a caller waits out the full timeout on a
+ * dead socket, and the map grows for the life of the process.
+ */
+export declare const releaseChannelHostRPC: (channelId: string) => Promise<void>;

package/dist/wirings/channel/channel-host-rpc.js

@@ -0,0 +1,38 @@
+import { ChannelDeploymentService, createChannelRPCInputValidator, createChannelRPCResultValidator, } from './channel-rpc.js';
+import { getSingletonServices } from '../../pikku-state.js';
+/** Reverse-RPC transports, one per open connection. */
+const hostRPCByChannel = new Map();
+/**
+ * The transport for a connection, created on first use. `options` apply only
+ * to the call that creates it — one connection has one transport, so the first
+ * caller's timeout and validators become the connection's.
+ */
+export const getChannelHostRPC = (channel, options = {}) => {
+    let service = hostRPCByChannel.get(channel.channelId);
+    if (!service) {
+        service = new ChannelDeploymentService((data) => channel.send(data), options);
+        hostRPCByChannel.set(channel.channelId, service);
+    }
+    return service;
+};
+/**
+ * Kept out of the channel handler so a channel nobody calls back on pays for no
+ * registry, and because a handler has no services to build a validator with.
+ */
+export const channelRemote = async (channel, funcName, data) => getChannelHostRPC(channel, {
+    validateInput: createChannelRPCInputValidator(getSingletonServices()),
+    validateResult: createChannelRPCResultValidator(getSingletonServices()),
+}).invoke(funcName, data);
+/** False for an unknown connection or id, so a stray frame is dropped. */
+export const handleChannelRPCResponse = (channelId, message) => hostRPCByChannel.get(channelId)?.handleResponse(message) ?? false;
+/**
+ * Must run on disconnect: without it a caller waits out the full timeout on a
+ * dead socket, and the map grows for the life of the process.
+ */
+export const releaseChannelHostRPC = async (channelId) => {
+    const service = hostRPCByChannel.get(channelId);
+    if (service) {
+        hostRPCByChannel.delete(channelId);
+        await service.stop();
+    }
+};

package/dist/wirings/channel/channel-middleware-runner.d.ts

@@ -2,18 +2,6 @@ import type { CoreSingletonServices, MiddlewareMetadata, PikkuRawWire } from '..
 import type { CorePikkuChannelMiddleware } from './channel.types.js';
 export declare const addChannelMiddleware: (tag: string, middleware: CorePikkuChannelMiddleware[], packageName?: string | null) => CorePikkuChannelMiddleware[];
 export declare const clearChannelMiddlewareCache: () => void;
-/**
- * Combine the inherited (tag/named) channel middleware with any per-run
- * middleware for a wiring.
- *
- * Only the statically-resolved inherited middleware is deterministic per `uid`
- * and safe to cache. `wireChannelMiddleware` is a per-run set of closures (e.g.
- * an AI agent's per-invocation stream middleware holding that run's
- * thread/session state) and MUST NOT be cached — caching it lets a later run of
- * the same `uid` reuse an earlier run's closures, leaking that run's state (and
- * growing memory) across invocations. It is therefore appended fresh on every
- * call after the cached inherited slice.
- */
 export declare const combineChannelMiddleware: (wireType: string, uid: string, { wireInheritedChannelMiddleware, wireChannelMiddleware, packageName, }?: {
     wireInheritedChannelMiddleware?: MiddlewareMetadata[];
     wireChannelMiddleware?: CorePikkuChannelMiddleware[];