@pikku/core 0.12.72 → 0.12.77

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

@@ -1,4 +1,5 @@
 import { pikkuAIMiddleware } from '../../types/core.types.js';
+import { SPOKEN_TURN } from './voice-input.js';
 function bufferToBase64(data) {
     let binary = '';
     for (let i = 0; i < data.length; i++) {
@@ -10,6 +11,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 +90,117 @@ 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, shared, 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)');
+        // Only an explicit `false` silences the reply. `voiceInput` sets this on
+        // every turn it handles, so `false` means a real user really typed; the
+        // key being absent means nothing reported either way — no voice input is
+        // wired — and that caller's replies are spoken exactly as they were before
+        // this option existed.
+        if (!config?.always && shared[SPOKEN_TURN] === false)
+            return event;
+        /**
+         * Queue a finished sentence for speech.
+         *
+         * 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,
+                    text,
                 });
-                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[];

package/dist/wirings/channel/channel-middleware-runner.js

@@ -16,18 +16,6 @@ export const clearChannelMiddlewareCache = () => {
         delete channelMiddlewareCache[key];
     }
 };
-/**
- * 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 const combineChannelMiddleware = (wireType, uid, { wireInheritedChannelMiddleware, wireChannelMiddleware, packageName = null, } = {}) => {
     const cacheKey = `${wireType}:${uid}`;
     let inherited = channelMiddlewareCache[cacheKey];

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

@@ -0,0 +1,31 @@
+import { type ChannelRPCResponse } from './channel-rpc.types.js';
+/**
+ * Tracks in-flight reverse RPC calls for one channel. One registry per
+ * connection: ids are only unique within a socket, and a dropped socket must
+ * reject exactly the calls that were riding on it.
+ */
+export declare class ChannelRPCRegistry {
+    private readonly timeoutMs;
+    private pending;
+    private nextId;
+    private closed;
+    constructor(timeoutMs?: number);
+    get inFlight(): number;
+    register(): {
+        id: string;
+        promise: Promise<unknown>;
+    };
+    /**
+     * Stops the clock on a call whose peer is asking a human. The timeout exists
+     * to bound a peer that has gone away, and a person reading a prompt is not
+     * that; `rejectAll` still fails the call the moment the socket drops.
+     *
+     * Returns false for an unknown id — a pending frame for a call that already
+     * timed out is stale, not an error.
+     */
+    hold(id: string): boolean;
+    /** Returns false for an unknown id, so a late reply is dropped. */
+    settle(response: ChannelRPCResponse): boolean;
+    /** Without this a caller awaits the full timeout on a connection that is gone. */
+    rejectAll(reason?: string): void;
+}

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

@@ -0,0 +1,89 @@
+import { ChannelRPCError, } from './channel-rpc.types.js';
+/**
+ * Tracks in-flight reverse RPC calls for one channel. One registry per
+ * connection: ids are only unique within a socket, and a dropped socket must
+ * reject exactly the calls that were riding on it.
+ */
+export class ChannelRPCRegistry {
+    timeoutMs;
+    pending = new Map();
+    nextId = 0;
+    closed = false;
+    constructor(timeoutMs = 30_000) {
+        this.timeoutMs = timeoutMs;
+    }
+    get inFlight() {
+        return this.pending.size;
+    }
+    register() {
+        if (this.closed) {
+            return {
+                id: '',
+                promise: Promise.reject(new ChannelRPCError('Channel is closed', 'closed')),
+            };
+        }
+        const id = `${++this.nextId}`;
+        const promise = new Promise((resolve, reject) => {
+            const timer = this.timeoutMs > 0
+                ? setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new ChannelRPCError(`Channel RPC ${id} timed out after ${this.timeoutMs}ms`, 'timeout'));
+                }, this.timeoutMs)
+                : undefined;
+            // Never hold the process open waiting on a peer that may not answer.
+            timer?.unref?.();
+            this.pending.set(id, { resolve, reject, timer });
+        });
+        return { id, promise };
+    }
+    /**
+     * Stops the clock on a call whose peer is asking a human. The timeout exists
+     * to bound a peer that has gone away, and a person reading a prompt is not
+     * that; `rejectAll` still fails the call the moment the socket drops.
+     *
+     * Returns false for an unknown id — a pending frame for a call that already
+     * timed out is stale, not an error.
+     */
+    hold(id) {
+        const call = this.pending.get(id);
+        if (!call || call.awaitingHuman) {
+            return false;
+        }
+        clearTimeout(call.timer);
+        call.timer = undefined;
+        call.awaitingHuman = true;
+        return true;
+    }
+    /** Returns false for an unknown id, so a late reply is dropped. */
+    settle(response) {
+        const call = this.pending.get(response.id);
+        if (!call) {
+            return false;
+        }
+        this.pending.delete(response.id);
+        clearTimeout(call.timer);
+        if (response.ok) {
+            call.resolve(response.result);
+        }
+        else {
+            // Peer input: a non-string name or message falls back rather than being
+            // attached to an Error, where it would surface as `[object Object]`.
+            const { name, message } = response.error ?? {};
+            const error = new ChannelRPCError(typeof message === 'string' ? message : 'Remote channel RPC failed', 'remote');
+            if (typeof name === 'string' && name.length > 0) {
+                error.name = name;
+            }
+            call.reject(error);
+        }
+        return true;
+    }
+    /** Without this a caller awaits the full timeout on a connection that is gone. */
+    rejectAll(reason = 'Channel closed') {
+        this.closed = true;
+        for (const [, call] of this.pending) {
+            clearTimeout(call.timer);
+            call.reject(new ChannelRPCError(reason, 'closed'));
+        }
+        this.pending.clear();
+    }
+}

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

@@ -0,0 +1,15 @@
+import { type ApprovalRequester, type Capabilities } from './channel-rpc.types.js';
+/**
+ * Answers reverse RPC requests arriving on a channel.
+ *
+ * `capabilities` is the authorisation boundary, not a convenience: the peer is
+ * asking this process to execute code, so only listed names run. An absent
+ * name is refused exactly like an unknown one, so the caller cannot probe for
+ * what this end can do.
+ */
+export declare const createChannelRPCResponder: ({ capabilities, send, approve, }: {
+    capabilities: Capabilities;
+    send: (data: unknown) => Promise<void> | void;
+    /** Omitted means there is nobody to ask, which refuses rather than runs. */
+    approve?: ApprovalRequester;
+}) => (message: unknown) => Promise<boolean>;