@byokit/realtime 0.1.0

package/dist/client.js

@@ -0,0 +1,276 @@
+import { parseRealtimeClientFrame, parseRealtimeHostFrame, realtimePcm16ByteLength } from "./frames.js";
+/** Provider-blind client with bounded reconnects and exclusive media ownership. */
+export function realtimeClient(options) {
+    const audio = options.audio;
+    let stopped = false, muted = false, epoch = 0, reconnects = 0;
+    let retry, reconnectTimer, stableTimer;
+    let attempt;
+    const mic = [], speech = [];
+    let micBytes = 0;
+    const stats = { micCaptured: 0, micSent: 0, micQueued: 0, micDropped: 0, transportReconnects: 0, providerReconnects: 0 };
+    const cleanup = async (current) => {
+        if (!current)
+            return;
+        current.signal.abort();
+        current.stream?.close();
+        if (current.stream)
+            audio.player.unbind(current.stream);
+        await current.media?.catch(() => { });
+        current.peer?.stop();
+        await current.routeRelease;
+        try {
+            await current.capture?.release();
+        }
+        finally {
+            if (current.acquired) {
+                current.acquired = false;
+                audio.microphone.release();
+                await audio.unroute();
+            }
+        }
+    };
+    const reset = () => { clearTimeout(retry); retry = undefined; clearTimeout(stableTimer); audio.player.clear(); mic.length = 0; micBytes = 0; };
+    const stop = (reason) => {
+        if (stopped)
+            return;
+        stopped = true;
+        epoch++;
+        clearTimeout(reconnectTimer);
+        reset();
+        const current = attempt;
+        attempt = undefined;
+        current?.stream?.send({ type: 'realtime.control', action: 'stop' });
+        void cleanup(current).catch(() => { });
+        audio.player.stop();
+        audio.player.release();
+        speech.length = 0;
+        options.onStats?.({ ...stats });
+        options.onStatus('disconnected', reason);
+    };
+    const fail = (error) => stop(error instanceof Error ? error.message : String(error));
+    const connected = () => { clearTimeout(stableTimer); stableTimer = setTimeout(() => { reconnects = 0; }, 30000); };
+    const schedule = () => { if (!retry && !stopped)
+        retry = setTimeout(() => { retry = undefined; flush(); }, 20); };
+    const flush = () => {
+        const current = attempt;
+        if (!current?.stream || stopped || !current.ready)
+            return;
+        while (mic.length) {
+            const next = mic[0];
+            if (!current.stream.send({ type: 'realtime.audio', data: next.data })) {
+                schedule();
+                return;
+            }
+            mic.shift();
+            micBytes -= next.bytes;
+            stats.micSent++;
+        }
+        if (speech.length && audio.player.afterDrain('speech', flush))
+            return;
+        while (speech.length) {
+            if (!current.stream.send({ type: 'realtime.say', text: speech[0] })) {
+                schedule();
+                return;
+            }
+            speech.shift();
+        }
+    };
+    const reconnect = (current, reason) => {
+        if (stopped || attempt !== current)
+            return;
+        if (options.retryableClose?.(reason) === false || reconnects >= 2) {
+            stop(reason);
+            return;
+        }
+        attempt = undefined;
+        epoch++;
+        reset();
+        reconnects++;
+        stats.transportReconnects++;
+        options.onStatus('connecting', reason);
+        // A slow microphone release cannot overlap the next acquisition.
+        void cleanup(current).then(() => {
+            if (!stopped)
+                reconnectTimer = setTimeout(connect, reconnects * 500);
+        }).catch(fail);
+    };
+    const connect = () => {
+        if (stopped)
+            return;
+        reconnectTimer = undefined;
+        const current = { acquired: false, ready: false, signal: new AbortController() };
+        attempt = current;
+        const generation = ++epoch;
+        const active = () => !stopped && attempt === current && epoch === generation;
+        const onAudio = (data) => {
+            if (!active() || muted)
+                return;
+            try {
+                const bytes = realtimePcm16ByteLength(data);
+                stats.micCaptured++;
+                options.onActivity?.();
+                options.onLevel?.('input', data);
+                if (micBytes + bytes > 96000) {
+                    stats.micDropped++;
+                    throw new Error('Microphone buffer overflowed.');
+                }
+                mic.push({ data, bytes });
+                micBytes += bytes;
+                if (!current.ready)
+                    stats.micQueued++;
+                flush();
+            }
+            catch (error) {
+                fail(error);
+            }
+        };
+        const handle = async (raw) => {
+            if (!active())
+                return;
+            const frame = parseRealtimeHostFrame(raw);
+            options.onActivity?.();
+            switch (frame.type) {
+                case 'realtime.ready':
+                    if (current.media) {
+                        current.ready = true;
+                        stats.providerReconnects++;
+                        connected();
+                        flush();
+                        break;
+                    }
+                    current.media = (async () => {
+                        await audio.microphone.acquire();
+                        current.acquired = true;
+                        if (!active())
+                            return;
+                        await audio.route();
+                        if (!active())
+                            return;
+                        audio.player.ensure(frame.outputRate);
+                        current.capture = await audio.capture(frame.inputRate, onAudio);
+                        if (!active())
+                            return;
+                        current.ready = true;
+                        for (const data of current.capture.pending)
+                            onAudio(data);
+                        connected();
+                        options.onStatus('connected');
+                        flush();
+                    })();
+                    await current.media;
+                    break;
+                case 'realtime.webrtc.start':
+                    if (current.media)
+                        break;
+                    if (!options.webrtc)
+                        throw new Error('Voice media is unsupported.');
+                    current.media = options.webrtc({ label: frame.dataChannelLabel, audio: { ...audio, unroute() { return current.routeRelease = audio.unroute(); } }, signal: current.signal.signal,
+                        onOffer(sdp) { if (active() && !current.stream?.send({ type: 'realtime.webrtc.offer', sdp }))
+                            reconnect(current, 'Voice offer could not be sent.'); },
+                        onData(data) { if (active() && !current.stream?.send({ type: 'realtime.webrtc.data', data }))
+                            reconnect(current, 'Voice channel overflowed.'); },
+                        onRemoteAudio(speaking) { if (active())
+                            options.onStatus(speaking ? 'speaking' : 'connected'); },
+                        onConnectionState(state) { if (!active())
+                            return; if (state === 'connected') {
+                            current.ready = true;
+                            connected();
+                            flush();
+                        }
+                        else if (state === 'disconnected') {
+                            reconnect(current, 'Voice connection ended.');
+                            return;
+                        } options.onStatus(state); },
+                        onInterruption(interrupted) { if (active())
+                            options.onStatus(interrupted ? 'connecting' : 'connected'); },
+                        onError(error) { if (active())
+                            reconnect(current, error.message); },
+                    }).then(peer => { current.peer = peer; if (active())
+                        peer.setMuted(muted); });
+                    await current.media;
+                    break;
+                case 'realtime.webrtc.answer':
+                    await current.media;
+                    if (active())
+                        await current.peer?.acceptAnswer(frame.sdp);
+                    break;
+                case 'realtime.webrtc.data':
+                    await current.media;
+                    if (active() && !current.peer?.sendData(frame.data))
+                        throw new Error('Voice channel overflowed.');
+                    break;
+                case 'realtime.audio':
+                    options.onLevel?.('output', frame.data);
+                    if (audio.player.admit(frame.data) !== 'ok')
+                        throw new Error('Voice playback could not accept audio.');
+                    options.onStatus('speaking');
+                    break;
+                case 'realtime.audio.clear':
+                    audio.player.clear();
+                    break;
+                case 'realtime.transcript':
+                    options.onTurn(frame.role, frame.text);
+                    break;
+                case 'realtime.state':
+                    if (frame.state === 'connecting') {
+                        current.ready = false;
+                        reset();
+                    }
+                    if (frame.state === 'connected')
+                        audio.player.finish(() => { if (active())
+                            options.onStatus('connected', frame.detail); });
+                    else
+                        options.onStatus(frame.state, frame.detail);
+                    break;
+                case 'realtime.closed':
+                    if (frame.retryable)
+                        reconnect(current, frame.reason);
+                    else
+                        stop(frame.reason);
+                    break;
+                case 'realtime.app.request': {
+                    const result = await options.onAppRequest?.(frame.action, frame.target) ?? { ok: false, text: 'The app cannot answer that request.' };
+                    if (active() && !current.stream?.send(parseRealtimeClientFrame({ type: 'realtime.app.result', requestId: frame.requestId, ...result })))
+                        throw new Error('App answer could not be sent.');
+                    break;
+                }
+                case 'realtime.usage':
+                    options.onUsage?.(frame.usage);
+                    break;
+            }
+        };
+        void options.open().then(stream => {
+            if (!active()) {
+                stream.close();
+                return;
+            }
+            current.stream = stream;
+            audio.player.bind(stream);
+            stream.onFrame(frame => { void handle(frame).catch(error => { if (active())
+                fail(error); }); });
+            stream.onClose(reason => reconnect(current, reason));
+            stream.start();
+        }).catch(error => { if (active())
+            reconnect(current, error instanceof Error ? error.message : String(error)); });
+    };
+    options.onStatus('connecting');
+    connect();
+    return {
+        stop,
+        interrupt() { if (stopped)
+            return; audio.player.clear(); speech.length = 0; if (!attempt?.stream?.send({ type: 'realtime.control', action: 'interrupt' })) {
+            if (attempt)
+                reconnect(attempt, 'Voice interruption could not be sent.');
+        } },
+        setMuted(value) { muted = value; attempt?.peer?.setMuted(value); if (value) {
+            mic.length = 0;
+            micBytes = 0;
+        } },
+        speak(text) { if (stopped)
+            return; const frame = parseRealtimeClientFrame({ type: 'realtime.say', text }); if (frame.type !== 'realtime.say')
+            return; if (speech.length >= 16) {
+            fail(new Error('Voice request buffer overflowed.'));
+            return;
+        } speech.push(frame.text); flush(); },
+    };
+}

package/dist/frames.d.ts

@@ -0,0 +1,107 @@
+import type { RealtimeUsage } from './types.ts';
+/**
+ * Provider-neutral realtime voice channel.
+ *
+ * The phone owns only microphone capture, PCM playback and these generic frames.
+ * Provider authentication, event vocabularies, models, tools and prompts live in
+ * the host plugin process behind the channel.
+ */
+export declare const REALTIME_INPUT_RATE = 24000;
+export declare const REALTIME_OUTPUT_RATE = 24000;
+export declare const MAX_REALTIME_AUDIO_BASE64_BYTES: number;
+export declare const MAX_REALTIME_TEXT_BYTES: number;
+export declare const MAX_REALTIME_SDP_BYTES: number;
+export declare const MAX_REALTIME_WEBRTC_DATA_BYTES: number;
+export declare const MAX_REALTIME_CLOSE_REASON_BYTES: number;
+export type RealtimeOpen = {
+    type: 'realtime.open';
+    context?: unknown;
+};
+export type RealtimeState = 'connecting' | 'connected' | 'thinking' | 'speaking';
+export type RealtimeControlAction = 'mute' | 'unmute' | 'interrupt' | 'stop' | 'pause_output' | 'resume_output' | 'output_drained';
+export type RealtimeAppAction = 'view' | 'navigate' | 'activate';
+export interface RealtimeAudioClientFrame {
+    type: 'realtime.audio';
+    /** base64 PCM16 mono at the rate named by realtime.ready. */
+    data: string;
+}
+export interface RealtimeControlFrame {
+    type: 'realtime.control';
+    action: RealtimeControlAction;
+}
+export interface RealtimeSayFrame {
+    type: 'realtime.say';
+    text: string;
+}
+export interface RealtimeAppResultFrame {
+    type: 'realtime.app.result';
+    requestId: string;
+    ok: boolean;
+    text: string;
+}
+export interface RealtimeWebRtcOfferFrame {
+    type: 'realtime.webrtc.offer';
+    sdp: string;
+}
+export interface RealtimeWebRtcDataClientFrame {
+    type: 'realtime.webrtc.data';
+    data: string;
+}
+export type RealtimeClientFrame = RealtimeAudioClientFrame | RealtimeControlFrame | RealtimeSayFrame | RealtimeAppResultFrame | RealtimeWebRtcOfferFrame | RealtimeWebRtcDataClientFrame;
+export interface RealtimeReadyFrame {
+    type: 'realtime.ready';
+    inputRate: number;
+    outputRate: number;
+}
+export interface RealtimeAudioHostFrame {
+    type: 'realtime.audio';
+    /** base64 PCM16 mono at realtime.ready's outputRate. */
+    data: string;
+}
+export interface RealtimeAudioClearFrame {
+    type: 'realtime.audio.clear';
+}
+export interface RealtimeStateFrame {
+    type: 'realtime.state';
+    state: RealtimeState;
+    detail?: string;
+}
+export interface RealtimeTranscriptFrame {
+    type: 'realtime.transcript';
+    role: 'user' | 'agent';
+    text: string;
+}
+export interface RealtimeClosedFrame {
+    type: 'realtime.closed';
+    reason?: string;
+    retryable?: boolean;
+}
+export interface RealtimeAppRequestFrame {
+    type: 'realtime.app.request';
+    requestId: string;
+    action: RealtimeAppAction;
+    target?: string;
+}
+export interface RealtimeWebRtcStartFrame {
+    type: 'realtime.webrtc.start';
+    dataChannelLabel: string;
+}
+export interface RealtimeWebRtcAnswerFrame {
+    type: 'realtime.webrtc.answer';
+    sdp: string;
+}
+export interface RealtimeWebRtcDataHostFrame {
+    type: 'realtime.webrtc.data';
+    data: string;
+}
+export type RealtimeUsageFrame = {
+    type: 'realtime.usage';
+    usage: RealtimeUsage;
+};
+export type RealtimeHostFrame = RealtimeUsageFrame | RealtimeReadyFrame | RealtimeAudioHostFrame | RealtimeAudioClearFrame | RealtimeStateFrame | RealtimeTranscriptFrame | RealtimeAppRequestFrame | RealtimeClosedFrame | RealtimeWebRtcStartFrame | RealtimeWebRtcAnswerFrame | RealtimeWebRtcDataHostFrame;
+export declare function realtimePcm16ByteLength(value: unknown): number;
+export declare function parseRealtimeClientFrame(value: unknown): RealtimeClientFrame;
+export declare function parseRealtimeHostFrame(value: unknown): RealtimeHostFrame;
+export declare function encodeRealtimeFrame(frame: RealtimeClientFrame | RealtimeHostFrame): string;
+/** Random channel id for a link voice stream. */
+export declare function newRealtimeChannel(): string;

package/dist/frames.js

@@ -0,0 +1,188 @@
+/**
+ * Provider-neutral realtime voice channel.
+ *
+ * The phone owns only microphone capture, PCM playback and these generic frames.
+ * Provider authentication, event vocabularies, models, tools and prompts live in
+ * the host plugin process behind the channel.
+ */
+export const REALTIME_INPUT_RATE = 24_000;
+export const REALTIME_OUTPUT_RATE = 24_000;
+export const MAX_REALTIME_AUDIO_BASE64_BYTES = 96 * 1024;
+export const MAX_REALTIME_TEXT_BYTES = 4 * 1024;
+export const MAX_REALTIME_SDP_BYTES = 128 * 1024;
+export const MAX_REALTIME_WEBRTC_DATA_BYTES = 32 * 1024;
+export const MAX_REALTIME_CLOSE_REASON_BYTES = 2 * 1024;
+const REALTIME_CONTROL_ACTIONS = new Set(['mute', 'unmute', 'interrupt', 'stop', 'pause_output', 'resume_output', 'output_drained']);
+const REALTIME_APP_ACTIONS = { view: true, navigate: true, activate: true };
+const REALTIME_STATES = new Set(['connecting', 'connected', 'thinking', 'speaking']);
+function record(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error('invalid realtime frame');
+    return value;
+}
+function boundedText(value, max, label) {
+    if (typeof value !== 'string')
+        throw new Error(`invalid realtime ${label}`);
+    const clean = value.replace(/[\u0000-\u001F\u007F]/g, '').trim();
+    if (clean.length === 0 || new TextEncoder().encode(clean).length > max)
+        throw new Error(`invalid realtime ${label}`);
+    return clean;
+}
+function requestId(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9._:-]{1,160}$/.test(value))
+        throw new Error('invalid realtime request id');
+    return value;
+}
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+export function realtimePcm16ByteLength(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > MAX_REALTIME_AUDIO_BASE64_BYTES || value.length % 4 !== 0
+        || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+        throw new Error('invalid realtime audio');
+    }
+    let padding = 0;
+    if (value.endsWith('=='))
+        padding = 2;
+    else if (value.endsWith('='))
+        padding = 1;
+    const trailingSextet = BASE64_ALPHABET.indexOf(value.charAt(value.length - padding - 1));
+    let nonCanonicalPadding = false;
+    if (padding === 2)
+        nonCanonicalPadding = (trailingSextet & 15) !== 0;
+    else if (padding === 1)
+        nonCanonicalPadding = (trailingSextet & 3) !== 0;
+    const bytes = value.length / 4 * 3 - padding;
+    if (nonCanonicalPadding || bytes === 0 || bytes % 2 !== 0)
+        throw new Error('invalid realtime audio');
+    return bytes;
+}
+function audio(value) {
+    realtimePcm16ByteLength(value);
+    return value;
+}
+function rate(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || ![8_000, 16_000, 22_050, 24_000, 32_000, 44_100, 48_000].includes(value)) {
+        throw new Error('invalid realtime audio rate');
+    }
+    return value;
+}
+function webRtcSdp(value) {
+    if (typeof value !== 'string' || !value.startsWith('v=0') || value.includes('\u0000')
+        || new TextEncoder().encode(value).length > MAX_REALTIME_SDP_BYTES) {
+        throw new Error('invalid realtime WebRTC SDP');
+    }
+    return value;
+}
+function webRtcData(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.includes('\u0000')
+        || new TextEncoder().encode(value).length > MAX_REALTIME_WEBRTC_DATA_BYTES) {
+        throw new Error('invalid realtime WebRTC data');
+    }
+    return value;
+}
+function dataChannelLabel(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9._-]{1,64}$/.test(value)) {
+        throw new Error('invalid realtime WebRTC data channel');
+    }
+    return value;
+}
+export function parseRealtimeClientFrame(value) {
+    const frame = record(value);
+    if (frame.type === 'realtime.audio')
+        return { type: 'realtime.audio', data: audio(frame.data) };
+    if (frame.type === 'realtime.control') {
+        if (typeof frame.action !== 'string' || !REALTIME_CONTROL_ACTIONS.has(frame.action)) {
+            throw new Error('invalid realtime control');
+        }
+        return { type: 'realtime.control', action: frame.action };
+    }
+    if (frame.type === 'realtime.say')
+        return { type: 'realtime.say', text: boundedText(frame.text, MAX_REALTIME_TEXT_BYTES, 'speech') };
+    if (frame.type === 'realtime.app.result') {
+        if (typeof frame.ok !== 'boolean')
+            throw new Error('invalid realtime app result');
+        return {
+            type: 'realtime.app.result',
+            requestId: requestId(frame.requestId),
+            ok: frame.ok,
+            text: boundedText(frame.text, MAX_REALTIME_TEXT_BYTES, 'app result'),
+        };
+    }
+    if (frame.type === 'realtime.webrtc.offer')
+        return { type: 'realtime.webrtc.offer', sdp: webRtcSdp(frame.sdp) };
+    if (frame.type === 'realtime.webrtc.data')
+        return { type: 'realtime.webrtc.data', data: webRtcData(frame.data) };
+    throw new Error('unknown realtime client frame');
+}
+export function parseRealtimeHostFrame(value) {
+    const frame = record(value);
+    if (frame.type === 'realtime.usage') {
+        const usage = record(frame.usage);
+        if (!['tokens', 'minutes', 'subscription'].includes(String(usage.basis)) || typeof usage.seconds !== 'number' || !Number.isFinite(usage.seconds) || usage.seconds < 0)
+            throw new Error('invalid realtime usage');
+        const result = { basis: usage.basis, seconds: usage.seconds };
+        for (const key of ['inputTokens', 'outputTokens', 'audioInTokens', 'audioOutTokens', 'cachedTokens']) {
+            if (usage[key] === undefined)
+                continue;
+            if (typeof usage[key] !== 'number' || !Number.isSafeInteger(usage[key]) || usage[key] < 0)
+                throw new Error('invalid realtime usage');
+            result[key] = usage[key];
+        }
+        return { type: 'realtime.usage', usage: result };
+    }
+    if (frame.type === 'realtime.ready')
+        return { type: 'realtime.ready', inputRate: rate(frame.inputRate), outputRate: rate(frame.outputRate) };
+    if (frame.type === 'realtime.audio')
+        return { type: 'realtime.audio', data: audio(frame.data) };
+    if (frame.type === 'realtime.audio.clear')
+        return { type: 'realtime.audio.clear' };
+    if (frame.type === 'realtime.state') {
+        if (typeof frame.state !== 'string' || !REALTIME_STATES.has(frame.state)) {
+            throw new Error('invalid realtime state');
+        }
+        return {
+            type: 'realtime.state', state: frame.state,
+            ...(frame.detail === undefined ? {} : { detail: boundedText(frame.detail, 500, 'state detail') }),
+        };
+    }
+    if (frame.type === 'realtime.transcript') {
+        if (frame.role !== 'user' && frame.role !== 'agent')
+            throw new Error('invalid realtime transcript role');
+        return { type: 'realtime.transcript', role: frame.role, text: boundedText(frame.text, MAX_REALTIME_TEXT_BYTES, 'transcript') };
+    }
+    if (frame.type === 'realtime.app.request') {
+        if (typeof frame.action !== 'string' || REALTIME_APP_ACTIONS[frame.action] !== true) {
+            throw new Error('invalid realtime app action');
+        }
+        const action = frame.action;
+        if (action === 'view' && frame.target !== undefined)
+            throw new Error('invalid realtime app target');
+        if (action !== 'view' && frame.target === undefined)
+            throw new Error('invalid realtime app target');
+        return {
+            type: 'realtime.app.request',
+            requestId: requestId(frame.requestId),
+            action,
+            ...(frame.target === undefined ? {} : { target: boundedText(frame.target, 160, 'app target') }),
+        };
+    }
+    if (frame.type === 'realtime.closed') {
+        if (frame.retryable !== undefined && typeof frame.retryable !== 'boolean')
+            throw new Error('invalid realtime retry policy');
+        return { type: 'realtime.closed', ...(frame.retryable === undefined ? {} : { retryable: frame.retryable }), ...(frame.reason === undefined ? {} : { reason: boundedText(frame.reason, MAX_REALTIME_CLOSE_REASON_BYTES, 'close reason') }) };
+    }
+    if (frame.type === 'realtime.webrtc.start') {
+        return { type: 'realtime.webrtc.start', dataChannelLabel: dataChannelLabel(frame.dataChannelLabel) };
+    }
+    if (frame.type === 'realtime.webrtc.answer')
+        return { type: 'realtime.webrtc.answer', sdp: webRtcSdp(frame.sdp) };
+    if (frame.type === 'realtime.webrtc.data')
+        return { type: 'realtime.webrtc.data', data: webRtcData(frame.data) };
+    throw new Error('unknown realtime host frame');
+}
+export function encodeRealtimeFrame(frame) {
+    return JSON.stringify(frame);
+}
+/** Random channel id for a link voice stream. */
+export function newRealtimeChannel() {
+    return `rs_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './frames.ts';
+export * from './types.ts';
+export * from './words.ts';
+export * from './prose.ts';
+export * from './client.ts';
+export { providers, type RealtimeProviderInfo } from './catalogue.ts';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./frames.js";
+export * from "./types.js";
+export * from "./words.js";
+export * from "./prose.js";
+export * from "./client.js";
+export { providers } from "./catalogue.js";

package/dist/node.d.ts

@@ -0,0 +1,22 @@
+import type { RealtimeClientFrame, RealtimeHostFrame } from './frames.ts';
+import type { RealtimeAuth, RealtimeConfig, RealtimeProviderId, RealtimeUsage } from './types.ts';
+import { toolBridge } from './tools.ts';
+export { toolBridge, appBridge } from './tools.ts';
+export type { ToolHandler, ToolBridgeOptions } from './tools.ts';
+export type RealtimeEngineOptions = RealtimeConfig & {
+    engine: RealtimeProviderId;
+    auth: RealtimeAuth;
+    bridge: ReturnType<typeof toolBridge>;
+    emit(frame: RealtimeHostFrame): void;
+    /** Only loopback overrides are accepted, for fake-provider flows. */
+    endpoint?: string;
+    redact?: RegExp[];
+    onUsage?(usage: RealtimeUsage): void;
+};
+/** Provider sockets and SDP signaling run in a kit-owned child, never in the app process. */
+export declare function realtimeEngine(options: RealtimeEngineOptions): {
+    ready: Promise<void>;
+    usage: RealtimeUsage;
+    receive(raw: RealtimeClientFrame): boolean;
+    close(reason?: string): void;
+};