@byokit/realtime 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.2.0 (2026-09-30)
+
+
+
+- FIX: Make each realtime README example independently typecheck against the package exports.
+- FIX: Start phone WebRTC with React Native AbortSignal implementations that have no throwIfAborted method.
+- FIX: Report connected when playback has nothing to drain, and flush queued speech after audio clears while muted.
+- FIX: Offer opt-in PCM capture and playback-tail retention across carrier reconnects, releasing retained media on stop.
+- FIX: Apply app-supplied hangup policy on every route and end the session after the next agent transcript.
+- FIX: Use the host tool watchdog and failure wording instead of a competing fixed 300-second child deadline.
+- FIX: Keep ChatGPT delegations and retransmission results across ordinary user turns; explicit interruption and close still cancel them.
+- FIX: Ignore empty ChatGPT transcripts instead of emitting a failure line or clearing audio.
+- FIX: Drain child output before reporting process disconnection so the provider's final close reason survives.
+- FIX: Preserve transcripts up to 4,000 UTF-8 bytes and bound state details by bytes without splitting Unicode characters.
+- FIX: Preserve sanitized credential-error remedies and accept app-supplied auth failure wording.
+- FIX: Overlap ChatGPT media preparation, child startup and access lookup, keep early offers behind credential configuration, and allow explicit app signaling identity.
+- FIX: Route semantic app tool replies to the host bridge and cancel pending app requests when the session closes.
+- Add structured delegation through app-supplied tools, preserving named targets and operation ids.
+- Add a bounded, read-only advisory auth check that never gates session startup or initiates login.
 - Add interruption fencing and tool cancellation, bounded provider and transport reconnects, and fresh-call ChatGPT subscription voice interruption.
 
 ## 0.1.0 (2026-09-30)

package/README.md

@@ -32,10 +32,176 @@ const client = realtimeClient({
 
 For ChatGPT voice register a `delegate` tool handler receiving `{ request }` and supply the app's planner. API routes use `auth: { kind: 'key', key }`, with billing per use. The subscription route uses the person's ChatGPT sign-in from `@byokit/accounts`; it never reads Codex credentials or starts the Codex CLI. Backend refusal is reported as `not-included`.
 
+## Structured delegation and named targets
+
+`delegationHandler` dispatches a JSON request of the form `{ name, arguments }`
+directly through an app-supplied `toolBridge`. For ordinary spoken requests it
+uses the optional app planner. Invalid structured requests never enter the planner.
+Keep the action bridge separate from the outer `delegate` bridge:
+
+```ts
+import { delegationHandler, toolBridge } from '@byokit/realtime/node';
+import type { ToolHandler } from '@byokit/realtime/node';
+import type { RealtimeHostFrame } from '@byokit/realtime';
+
+declare const emit: (frame: RealtimeHostFrame) => void;
+declare const sendAuthorizedMessage: ToolHandler;
+declare const plan: (request: string, context: Parameters<ToolHandler>[1]) => Promise<string>;
+const actionTools = [{ name: 'message', description: 'Message a named agent', parameters: {
+  type: 'object', properties: { agent: { type: 'string' }, text: { type: 'string' } },
+  required: ['agent', 'text'], additionalProperties: false,
+} }];
+const actions = toolBridge({ tools: actionTools, handlers: { message: sendAuthorizedMessage },
+  emit, failure: () => 'The message could not be confirmed.', timeoutFor: () => 75000 });
+const delegate = delegationHandler({ bridge: actions, plan });
+const tools = [{ name: 'delegate', description: 'Delegate a spoken request', parameters: { type: 'object' } }];
+const bridge = toolBridge({ tools, handlers: { delegate }, emit,
+  timeoutFor: () => 340000, failure: () => 'The request could not be confirmed.' });
+// Pass the outer bridge and its delegate tool to realtimeEngine.
+// A structured request can be:
+// {"name":"message","arguments":{"agent":"Avery","text":"Please report progress"}}
+// Close actions as well as the outer bridge when the session ends.
+```
+
+The kit preserves arguments and operation ids; retries with the same call id
+share a result. Named targets, target lookup, ambiguity checks, authorization,
+argument validation and mutation receipts belong to the app's handlers. Tool
+JSON schemas describe the provider catalog; they are not runtime authorization.
+The app planner owns its model, conversation memory, tool budget and deadline;
+the kit does not add a planner model or any agent runtime dependency. Aborted
+calls must stop in the app too; completed side effects are never rolled back.
+The host bridge owns every tool watchdog and failure message; the child has no
+second deadline. A 340-second planner or a 290-second watch can therefore use
+the app's declared budget. An ordinary ChatGPT user turn preserves unfinished
+delegations and their retransmission cache. Explicit `interrupt` or close aborts
+them; a new turn id still identifies a new request.
+
+## Advisory auth check
+
+Pass a read-only saved-sign-in lookup as `authCheck` on the engine. It starts
+independently, is never awaited by startup, and cannot close the session. It
+does not call `auth.access`, refresh a token, run a CLI or initiate login.
+The app's `peek` callback must also never refresh, prompt or start login.
+
+```ts
+import { realtimeEngine, toolBridge } from '@byokit/realtime/node';
+import type { RealtimeAuth, RealtimeHostFrame, RealtimeTool } from '@byokit/realtime';
+
+declare const auth: Extract<RealtimeAuth, { kind: 'plan' }>;
+declare const tools: RealtimeTool[];
+declare const bridge: ReturnType<typeof toolBridge>;
+declare const emit: (frame: RealtimeHostFrame) => void;
+declare const peekSavedSignIn: (signal: AbortSignal) => Promise<boolean>;
+declare const updateSettingsBadge: (status: 'ready' | 'signed-out' | 'unknown') => void;
+const engine = realtimeEngine({
+  engine: 'chatgpt', auth,
+  tools, bridge, emit,
+  authCheck: { peek: peekSavedSignIn, onStatus: status => updateSettingsBadge(status) },
+});
+```
+
+`ready` means the app reports a saved sign-in, not provider entitlement.
+`signed-out` means the lookup returned false. Errors or a timeout produce
+`unknown`; the default timeout is one second, capped at ten seconds. Close
+cancels pending checks and suppresses late notifications. Normal session
+authentication still needs the credential from `auth.access`.
+For a standalone settings lookup, `realtimeAuthCheck({ peek })` is also exported
+from the portable entry and returns `{ result, close }`. Do not await this check
+before opening a voice session or show a login prompt from its result.
+
+## Lifecycle announcements and semantic app tools
+
+Feed app-confirmed lifecycle reports into the existing speech path. The kit
+does not watch agents or infer their outcome:
+
+```ts
+import type { realtimeClient } from '@byokit/realtime';
+import type { realtimeEngine } from '@byokit/realtime/node';
+declare const client: ReturnType<typeof realtimeClient>;
+declare const engine: ReturnType<typeof realtimeEngine>;
+
+// Called by the app's lifecycle subscription; use bounded, sanitized app wording.
+client.speak('Avery has finished the task.');
+// A host can inject the same report directly:
+engine.receive({ type: 'realtime.say', text: 'Avery has finished the task.' });
+```
+
+`speak` queues at most sixteen reports until the call is ready, waits for local
+playback drain and does not replay sent speech on reconnect. `onTurn` observes
+transcripts and `onStatus` observes playback states; a transcript alone does
+not prove the report was audible. The app owns push delivery, deduplication,
+waking a sleeping call and stopping it after reports.
+When `player.finish(callback)` returns false, the client reports connected
+immediately. True means the player will call back after draining. Clearing
+audio also rechecks queued speech, including while the microphone is muted.
+
+Compose `appBridge` with `toolBridge` to round-trip semantic phone requests:
+
+```ts
+import { appBridge, toolBridge } from '@byokit/realtime/node';
+import type { RealtimeHostFrame } from '@byokit/realtime';
+declare const emit: (frame: RealtimeHostFrame) => void;
+const app = appBridge(emit);
+const navigation = [{ name: 'navigate', description: 'Open an app destination',
+  parameters: { type: 'object', properties: { target: { type: 'string' } }, required: ['target'] } }];
+const bridge = toolBridge({ tools: navigation, app, emit,
+  handlers: { navigate: (args, { signal }) => app.run('navigate', String(args.target), signal) },
+  failure: () => 'The app could not complete that request.',
+});
+// client.onAppRequest handles view/navigate/activate; forward all client frames
+// to engine.receive, which routes app results back to this app bridge.
+// Closing the engine also cancels pending app requests.
+```
+
 The main entry is portable for web and React Native and loads no native code. `./webrtc` supplies `webRtcPeer` for browsers and selects its native implementation under the `react-native` condition; install the optional `react-native-webrtc` 124.0.8 peer in the RN app. All media APIs can be injected for tests. `./node` requires Node 22.18+ and is for the credential host. It starts its own adapter child with an empty environment; credentials travel over private stdin. No provider key or plan token is sent to the device.
 
 `AudioPorts` requires microphone acquisition/release, PCM capture, playback admission/drain and audio routing. The app owns permissions and its microphone service. Acquire must resolve only after that service is ready. The client awaits it before capture. Each client owns its ports; the app must arbitrate shared microphones.
 
 Close the client and engine when the call ends. `client.interrupt()` clears playback and aborts unfinished tools; old response output is fenced. Transient provider and transport failures retry twice, after 500 and 1,000 ms, with a fresh budget after 30 healthy seconds. Sent audio, speech and tool calls are never replayed. The app can mark transport closure terminal with `retryableClose`. Explicit ChatGPT interruption opens a fresh call; explicit Gemini interruption rotates its provider session. Native speech interruption remains provider-driven. No STT/LLM/TTS chain is exported. See [the lift contract](../../docs/realtime-kit.md) for bounds, events and usage.
 
+## Reconnect and host policy
+
+Set `preserveMediaOnReconnect: true` on the client to retain a ready PCM
+recorder, microphone lease, audio route and playback tail across a carrier
+reconnect. Audio captured while the carrier is down is discarded. Pending
+microphone acquisition still releases before retry; WebRTC always creates a
+fresh peer for a fresh call. A changed PCM format releases the old recorder
+before acquiring another. Stop releases retained media even during backoff.
+The default remains release/clear/reacquire.
+
+The engine accepts app phrase policy and credential-error wording:
+
+```ts
+import { realtimeEngine, toolBridge } from '@byokit/realtime/node';
+import type { RealtimeAuth, RealtimeHostFrame, RealtimeTool } from '@byokit/realtime';
+declare const auth: Extract<RealtimeAuth, { kind: 'plan' }>;
+declare const tools: RealtimeTool[];
+declare const bridge: ReturnType<typeof toolBridge>;
+declare const emit: (frame: RealtimeHostFrame) => void;
+
+const engine = realtimeEngine({ engine: 'chatgpt',
+  auth, tools, bridge, emit,
+  hangup: text => /^goodbye[.!]?$/i.test(text.trim()),
+  authFailure: () => 'Sign in again from Settings.',
+  signalingIdentity: { originator: 'voice-app', userAgent: 'voice-app/1' },
+});
+```
+
+Hangup ends after the next completed agent transcript so the provider can
+give a farewell. It is a transcript-level policy, not proof that playback
+drained. Credential errors are sanitized, bounded and emitted as the close
+reason; the kit initiates no login or prompt. Transcripts preserve up to
+4,000 UTF-8 bytes, state details up to 500 bytes, and close reasons up to
+2,048 bytes. Empty ChatGPT transcripts are ignored.
+
+ChatGPT emits `realtime.webrtc.start` while the isolated child starts and
+access is being resolved. Device frames remain bounded and queued until the
+credential/config line is sent. This overlaps local setup without sending a
+signaling request before credentials are available. `signalingIdentity`
+lets the app name its own originator/user-agent; the default for both is
+`byokit`, and identity values must be printable ASCII of at most 160 characters.
+Credentials, endpoint restrictions and redirect rejection are unchanged.
+The identity option allows a consumer to compare signaling latency; offline
+tests prove startup ordering, not a reduction in the remote provider's POST time.
+
 For an explicitly live microphone and subscription-provider proof, run [the bounded voice demo](../../examples/realtime-voice/README.md). It signs in through accounts, keeps credentials only in memory, and records connection facts and turn counts. Offline tests do not establish a live pass.

package/dist/adapter.d.ts

@@ -1,5 +1,9 @@
 import type { toolBridge } from './tools.ts';
 import type { RealtimeTool } from './types.ts';
+export type RealtimeSignalingIdentity = {
+    originator?: string;
+    userAgent?: string;
+};
 export type AdapterOptions = {
     key: string;
     instructions: string;
@@ -10,4 +14,5 @@ export type AdapterOptions = {
     endpoint?: string;
     redact?: RegExp[];
     hangup?: (text: string) => boolean;
+    signalingIdentity?: RealtimeSignalingIdentity;
 };

package/dist/auth.d.ts

@@ -0,0 +1,13 @@
+export type RealtimeAuthStatus = 'ready' | 'signed-out' | 'unknown';
+export type RealtimeAuthCheckOptions = {
+    /** Read-only saved-sign-in check. Must never start login, refresh access or prompt. */
+    peek(signal: AbortSignal): Promise<boolean>;
+    onStatus?(status: RealtimeAuthStatus): void;
+    /** Defaults to 1 second; capped at 10 seconds. */
+    timeoutMs?: number;
+};
+/** Advisory only: session startup must proceed independently of this check. */
+export declare function realtimeAuthCheck(options: RealtimeAuthCheckOptions): {
+    result: Promise<RealtimeAuthStatus>;
+    close(): void;
+};

package/dist/auth.js

@@ -0,0 +1,29 @@
+/** Advisory only: session startup must proceed independently of this check. */
+export function realtimeAuthCheck(options) {
+    const controller = new AbortController();
+    let settled = false;
+    let resolve;
+    const result = new Promise(done => { resolve = done; });
+    const finish = (status, notify = true) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        controller.abort();
+        resolve(status);
+        // A settings observer cannot fail a call or create an unhandled rejection.
+        if (notify) {
+            try {
+                options.onStatus?.(status);
+            }
+            catch { }
+        }
+    };
+    const timeout = options.timeoutMs ?? 1000;
+    const timer = setTimeout(() => finish('unknown'), Number.isFinite(timeout) ? Math.min(10000, Math.max(1, timeout)) : 1000);
+    void Promise.resolve().then(() => {
+        if (!settled)
+            return options.peek(controller.signal);
+    }).then(value => finish(value === true ? 'ready' : value === false ? 'signed-out' : 'unknown'), () => finish('unknown'));
+    return { result, close() { finish('unknown', false); } };
+}

package/dist/chatgpt.js

@@ -1,5 +1,4 @@
-import { responseFence } from "./policy.js";
-import { cleanProse } from "./prose.js";
+import { cleanProse, cleanProseBytes } from "./prose.js";
 import { MAX_REALTIME_SDP_BYTES } from "./frames.js";
 export const CHATGPT_SIGNALING_URL = 'https://chatgpt.com/backend-api/codex/realtime/calls?intent=quicksilver&architecture=avas';
 function emit(frame) { process.stdout.write(`${JSON.stringify(frame)}\n`); }
@@ -36,7 +35,6 @@ export async function boundedBody(response, max = MAX_REALTIME_SDP_BYTES) {
     return new TextDecoder().decode(bytes);
 }
 export function createChatgptAdapter(options) {
-    const fence = responseFence();
     const lifetime = new AbortController();
     let offered = false, closed = false;
     const safe = (text) => cleanProse(text, 'Voice could not complete that request.', 4000, options.redact);
@@ -57,7 +55,7 @@ export function createChatgptAdapter(options) {
             send({ type: id ? 'delegation.context.append' : 'session.context.append', ...(id ? { delegation_item_id: id } : {}), channel: 'speakable', content: [{ type: 'input_text', text }] });
     };
     const close = (reason = 'Voice ended.', retryable = false) => { if (closed)
-        return; closed = true; fence.interrupt(); lifetime.abort(); options.bridge.close(); emit({ type: 'realtime.closed', reason: safe(reason), ...(retryable ? { retryable: true } : {}) }); };
+        return; closed = true; lifetime.abort(); options.bridge.close(); emit({ type: 'realtime.closed', reason: cleanProseBytes(reason, 'Voice ended.', 2048, options.redact), ...(retryable ? { retryable: true } : {}) }); };
     const signalOffer = async (sdp) => {
         if (offered)
             throw new Error('Duplicate voice offer.');
@@ -68,7 +66,7 @@ export function createChatgptAdapter(options) {
             throw new Error('Unsupported voice signaling origin.');
         const response = await fetch(url, {
             method: 'POST', redirect: 'error', signal: AbortSignal.any([lifetime.signal, AbortSignal.timeout(20000)]),
-            headers: { Authorization: `Bearer ${options.key}`, 'chatgpt-account-id': options.accountId, originator: 'byokit', 'User-Agent': 'byokit', 'OpenAI-Alpha': 'quicksilver=v2', 'content-type': 'application/json' },
+            headers: { Authorization: `Bearer ${options.key}`, 'chatgpt-account-id': options.accountId, originator: options.signalingIdentity?.originator ?? 'byokit', 'User-Agent': options.signalingIdentity?.userAgent ?? 'byokit', 'OpenAI-Alpha': 'quicksilver=v2', 'content-type': 'application/json' },
             body: JSON.stringify({ sdp, session: { model: options.model ?? 'gpt-live-1-codex', instructions: options.instructions, audio: { output: { voice: options.voice ?? 'sol' } }, delegation: { type: 'client', ack_filler: false } } }),
         });
         const answer = await boundedBody(response);
@@ -85,13 +83,13 @@ export function createChatgptAdapter(options) {
         // Provider event vocabulary stays inside the credential child.
         const event = JSON.parse(raw);
         if (event.type === 'turn.done' && typeof event.turn?.transcript === 'string') {
+            const text = cleanProseBytes(event.turn.transcript, '', 4000, options.redact);
+            if (!text)
+                return;
             const role = event.turn.role === 'assistant' ? 'agent' : 'user';
-            if (role === 'user') {
-                fence.begin();
-                turns.clear();
+            if (role === 'user')
                 emit({ type: 'realtime.audio.clear' });
-            }
-            emit({ type: 'realtime.transcript', role, text: safe(event.turn.transcript) });
+            emit({ type: 'realtime.transcript', role, text });
             if (role === 'agent')
                 options.bridge.answered();
             options.bridge.state(role === 'agent' ? 'connected' : 'thinking');
@@ -109,20 +107,18 @@ export function createChatgptAdapter(options) {
                 return;
             const turn = event.item.user_bidi_turn_id;
             const share = typeof turn === 'string' && turn.trim() && turn.length <= 128 ? JSON.stringify([turn.trim(), request.trim()]) : undefined;
-            const signal = fence.signal;
             let promise = share ? turns.get(share) : undefined;
             if (!promise) {
-                promise = options.bridge.run('delegate', { request }, `codex:${id}`, AbortSignal.any([lifetime.signal, signal]));
+                promise = options.bridge.run('delegate', { request }, `codex:${id}`, lifetime.signal);
                 if (share)
                     turns.set(share, promise);
             }
             delegations.set(id, promise);
             const result = await promise;
-            if (!closed && !signal.aborted)
+            if (!closed)
                 append(result, id);
         }
     };
-    emit({ type: 'realtime.webrtc.start', dataChannelLabel: 'oai-events' });
     return {
         receive(frame) {
             if (closed)

package/dist/child.js

@@ -7,7 +7,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { createInterface } from 'node:readline';
-import { toolBridge } from "./tools.js";
+import { randomUUID } from 'node:crypto';
 import { parseRealtimeClientFrame } from "./frames.js";
 import { createChatgptAdapter } from "./chatgpt.js";
 const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
@@ -20,14 +20,36 @@ input.on('line', line => {
         if (!starting) {
             const config = JSON.parse(line);
             starting = (async () => {
-                const handlers = Object.fromEntries(config.tools.map(tool => [tool.name, (_args, context) => new Promise(resolve => {
-                        const finish = (value) => { context.signal.removeEventListener('abort', abort); pending.delete(context.id); resolve(value); };
-                        const abort = () => { process.stdout.write(`${JSON.stringify({ type: 'kit.tool.cancel', id: context.id })}\n`); finish('The request was cancelled.'); };
-                        pending.set(context.id, finish);
-                        context.signal.addEventListener('abort', abort, { once: true });
-                        process.stdout.write(`${JSON.stringify({ type: 'kit.tool', name: tool.name, args: _args, id: context.id })}\n`);
-                    })]));
-                const bridge = toolBridge({ tools: config.tools, handlers, emit, timeoutFor: () => 300000, failure: () => 'The request could not be completed.' });
+                // The parent is the single authority for tool bounds, watchdogs, failure
+                // wording and answer state. This proxy adds no competing deadline.
+                const bridge = {
+                    run(name, args = {}, id = randomUUID(), signal) {
+                        if (signal?.aborted)
+                            return Promise.resolve('The request was cancelled.');
+                        if (!config.tools.some(tool => tool.name === name) || !args || typeof args !== 'object' || Array.isArray(args)
+                            || typeof id !== 'string' || id.length > 160 || Buffer.byteLength(JSON.stringify(args)) > 16000)
+                            return Promise.resolve('That request is invalid.');
+                        const key = JSON.stringify([name, args]);
+                        const prior = pending.get(id);
+                        if (prior)
+                            return prior.key === key ? prior.promise : Promise.resolve('Conflicting repeated request. No additional action was performed.');
+                        if (pending.size >= 8)
+                            return Promise.resolve('Requests are at the session limit.');
+                        let finish;
+                        const cancel = () => { process.stdout.write(`${JSON.stringify({ type: 'kit.tool.cancel', id })}\n`); finish('The request was cancelled.'); };
+                        const promise = new Promise(resolve => {
+                            finish = output => { signal?.removeEventListener('abort', cancel); pending.delete(id); resolve(output); };
+                        });
+                        pending.set(id, { key, promise, finish, cancel });
+                        signal?.addEventListener('abort', cancel, { once: true });
+                        process.stdout.write(`${JSON.stringify({ type: 'kit.tool', name, args, id })}\n`);
+                        return promise;
+                    },
+                    state(state, detail) { emit({ type: 'realtime.state', state, ...(detail ? { detail } : {}) }); },
+                    answered() { }, receive: () => false,
+                    close() { for (const call of [...pending.values()])
+                        call.cancel(); },
+                };
                 const options = { ...config, bridge, redact: config.redact?.map(pattern => new RegExp(pattern.source, pattern.flags)) };
                 if (config.engine === 'chatgpt')
                     adapter = createChatgptAdapter({ ...options, accountId: config.accountId ?? '' });
@@ -35,6 +57,7 @@ input.on('line', line => {
                     const module = await import(__rewriteRelativeImportExtension(`./providers/${config.engine}.${import.meta.url.endsWith('.ts') ? 'ts' : 'js'}`));
                     adapter = module.createAdapter(options);
                 }
+                process.stdout.write(`${JSON.stringify({ type: 'kit.ready' })}\n`);
             })();
             await starting;
             return;
@@ -42,7 +65,7 @@ input.on('line', line => {
         await starting;
         const frame = JSON.parse(line);
         if (frame.type === 'kit.tool.result')
-            pending.get(frame.id)?.(String(frame.output));
+            pending.get(frame.id)?.finish(String(frame.output));
         else
             adapter?.receive(parseRealtimeClientFrame(frame));
     })().catch(() => { emit({ type: 'realtime.closed', reason: 'Voice session could not start.' }); process.exit(1); });

package/dist/client.js

@@ -5,6 +5,7 @@ export function realtimeClient(options) {
     let stopped = false, muted = false, epoch = 0, reconnects = 0;
     let retry, reconnectTimer, stableTimer;
     let attempt;
+    let retained;
     const mic = [], speech = [];
     let micBytes = 0;
     const stats = { micCaptured: 0, micSent: 0, micQueued: 0, micDropped: 0, transportReconnects: 0, providerReconnects: 0 };
@@ -29,7 +30,8 @@ export function realtimeClient(options) {
             }
         }
     };
-    const reset = () => { clearTimeout(retry); retry = undefined; clearTimeout(stableTimer); audio.player.clear(); mic.length = 0; micBytes = 0; };
+    const reset = (clearPlayback = true) => { clearTimeout(retry); retry = undefined; clearTimeout(stableTimer); if (clearPlayback)
+        audio.player.clear(); mic.length = 0; micBytes = 0; };
     const stop = (reason) => {
         if (stopped)
             return;
@@ -37,8 +39,9 @@ export function realtimeClient(options) {
         epoch++;
         clearTimeout(reconnectTimer);
         reset();
-        const current = attempt;
+        const current = attempt ?? retained;
         attempt = undefined;
+        retained = undefined;
         current?.stream?.send({ type: 'realtime.control', action: 'stop' });
         void cleanup(current).catch(() => { });
         audio.player.stop();
@@ -84,10 +87,19 @@ export function realtimeClient(options) {
         }
         attempt = undefined;
         epoch++;
-        reset();
+        reset(!options.preserveMediaOnReconnect);
         reconnects++;
         stats.transportReconnects++;
         options.onStatus('connecting', reason);
+        if (options.preserveMediaOnReconnect && current.capture && !current.peer) {
+            retained = current;
+            current.signal.abort();
+            current.stream?.close();
+            if (current.stream)
+                audio.player.unbind(current.stream);
+            reconnectTimer = setTimeout(connect, reconnects * 500);
+            return;
+        }
         // A slow microphone release cannot overlap the next acquisition.
         void cleanup(current).then(() => {
             if (!stopped)
@@ -98,12 +110,17 @@ export function realtimeClient(options) {
         if (stopped)
             return;
         reconnectTimer = undefined;
-        const current = { acquired: false, ready: false, signal: new AbortController() };
+        const current = { ...retained, stream: undefined, acquired: retained?.acquired ?? false, ready: false, signal: new AbortController() };
+        retained = undefined;
         attempt = current;
         const generation = ++epoch;
         const active = () => !stopped && attempt === current && epoch === generation;
         const onAudio = (data) => {
-            if (!active() || muted)
+            // A retained recorder's callback follows its capture handle into the new carrier.
+            const captureActive = options.preserveMediaOnReconnect && current.capture
+                ? !stopped && attempt?.capture === current.capture && attempt.ready
+                : active();
+            if (!captureActive || muted)
                 return;
             try {
                 const bytes = realtimePcm16ByteLength(data);
@@ -131,6 +148,28 @@ export function realtimeClient(options) {
             options.onActivity?.();
             switch (frame.type) {
                 case 'realtime.ready':
+                    if (current.capture && (current.inputRate !== frame.inputRate || current.outputRate !== frame.outputRate)) {
+                        const capture = current.capture, acquired = current.acquired;
+                        current.capture = undefined;
+                        current.acquired = false;
+                        current.ready = false;
+                        // Cleanup also awaits this teardown if stop races a format change.
+                        current.media = (async () => {
+                            try {
+                                await capture.release();
+                            }
+                            finally {
+                                if (acquired) {
+                                    audio.microphone.release();
+                                    await audio.unroute();
+                                }
+                            }
+                        })();
+                        await current.media;
+                        if (!active())
+                            return;
+                        current.media = undefined;
+                    }
                     if (current.media) {
                         current.ready = true;
                         stats.providerReconnects++;
@@ -138,6 +177,8 @@ export function realtimeClient(options) {
                         flush();
                         break;
                     }
+                    current.inputRate = frame.inputRate;
+                    current.outputRate = frame.outputRate;
                     current.media = (async () => {
                         await audio.microphone.acquire();
                         current.acquired = true;
@@ -207,6 +248,7 @@ export function realtimeClient(options) {
                     break;
                 case 'realtime.audio.clear':
                     audio.player.clear();
+                    flush();
                     break;
                 case 'realtime.transcript':
                     options.onTurn(frame.role, frame.text);
@@ -214,11 +256,15 @@ export function realtimeClient(options) {
                 case 'realtime.state':
                     if (frame.state === 'connecting') {
                         current.ready = false;
-                        reset();
+                        reset(!options.preserveMediaOnReconnect);
+                    }
+                    if (frame.state === 'connected') {
+                        let drained = false;
+                        const onDrained = () => { if (!active() || drained)
+                            return; drained = true; options.onStatus('connected', frame.detail); flush(); };
+                        if (!audio.player.finish(onDrained))
+                            onDrained();
                     }
-                    if (frame.state === 'connected')
-                        audio.player.finish(() => { if (active())
-                            options.onStatus('connected', frame.detail); });
                     else
                         options.onStatus(frame.state, frame.detail);
                     break;

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from './types.ts';
 export * from './words.ts';
 export * from './prose.ts';
 export * from './client.ts';
+export * from './auth.ts';
 export { providers, type RealtimeProviderInfo } from './catalogue.ts';

package/dist/index.js

@@ -3,4 +3,5 @@ export * from "./types.js";
 export * from "./words.js";
 export * from "./prose.js";
 export * from "./client.js";
+export * from "./auth.js";
 export { providers } from "./catalogue.js";

package/dist/node.d.ts

@@ -1,8 +1,13 @@
 import type { RealtimeClientFrame, RealtimeHostFrame } from './frames.ts';
 import type { RealtimeAuth, RealtimeConfig, RealtimeProviderId, RealtimeUsage } from './types.ts';
+import type { RealtimeSignalingIdentity } from './adapter.ts';
 import { toolBridge } from './tools.ts';
-export { toolBridge, appBridge } from './tools.ts';
+import type { RealtimeAuthCheckOptions } from './auth.ts';
+export { toolBridge, appBridge, delegationHandler } from './tools.ts';
+export { realtimeAuthCheck } from './auth.ts';
+export type { RealtimeAuthCheckOptions, RealtimeAuthStatus } from './auth.ts';
 export type { ToolHandler, ToolBridgeOptions } from './tools.ts';
+export type { RealtimeSignalingIdentity } from './adapter.ts';
 export type RealtimeEngineOptions = RealtimeConfig & {
     engine: RealtimeProviderId;
     auth: RealtimeAuth;
@@ -12,6 +17,14 @@ export type RealtimeEngineOptions = RealtimeConfig & {
     endpoint?: string;
     redact?: RegExp[];
     onUsage?(usage: RealtimeUsage): void;
+    /** Optional read-only advisory check; never awaited before starting the provider. */
+    authCheck?: RealtimeAuthCheckOptions;
+    /** App phrase policy; close after the next completed agent transcript. */
+    hangup?(text: string): boolean;
+    /** Plain app wording for credential acquisition failures, with kit redaction. */
+    authFailure?(error: unknown): string;
+    /** Explicit app identity for ChatGPT signaling; defaults remain byokit. */
+    signalingIdentity?: RealtimeSignalingIdentity;
 };
 /** Provider sockets and SDP signaling run in a kit-owned child, never in the app process. */
 export declare function realtimeEngine(options: RealtimeEngineOptions): {

package/dist/node.js

@@ -3,8 +3,10 @@ import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { parseRealtimeClientFrame, parseRealtimeHostFrame } from "./frames.js";
 import { RealtimeError } from "./types.js";
-import { cleanProse } from "./prose.js";
-export { toolBridge, appBridge } from "./tools.js";
+import { cleanProseBytes } from "./prose.js";
+import { realtimeAuthCheck } from "./auth.js";
+export { toolBridge, appBridge, delegationHandler } from "./tools.js";
+export { realtimeAuthCheck } from "./auth.js";
 /** Provider sockets and SDP signaling run in a kit-owned child, never in the app process. */
 export function realtimeEngine(options) {
     if (!['chatgpt', 'openai', 'gemini', 'xai'].includes(options.engine))
@@ -13,26 +15,33 @@ export function realtimeEngine(options) {
         throw new RealtimeError('unsupported');
     if ((options.engine === 'chatgpt') !== (options.auth.kind === 'plan'))
         throw new RealtimeError('unsupported');
+    for (const value of Object.values(options.signalingIdentity ?? {})) {
+        if (typeof value !== 'string' || !/^[\x20-\x7E]{1,160}$/.test(value) || !value.trim())
+            throw new RealtimeError('protocol');
+    }
     let stopped = false, emittedClose = false;
+    let ending = false;
     const lifetime = new AbortController();
+    const authCheck = options.authCheck ? realtimeAuthCheck(options.authCheck) : undefined;
     const start = Date.now();
     let child;
+    let configured = false;
     let killTimer;
     let queuedBytes = 0;
     const pending = [];
     const toolCalls = new Map();
-    const secrets = [];
+    const secrets = options.auth.kind === 'key' ? [options.auth.key] : [];
     const usage = { seconds: 0, basis: options.engine === 'chatgpt' ? 'subscription' : options.engine === 'xai' ? 'minutes' : 'tokens' };
-    const safe = (value) => { let result = value; for (const secret of secrets)
+    const safe = (value, max = 2048) => { let result = value; for (const secret of secrets)
         if (secret)
-            result = result.replaceAll(secret, '[hidden]'); return cleanProse(result, 'Voice ended.', 500, options.redact); };
+            result = result.replaceAll(secret, '[hidden]'); return cleanProseBytes(result, 'Voice ended.', max, options.redact); };
     const emit = (frame) => {
         if (frame.type === 'realtime.state' && frame.detail)
-            frame = { ...frame, detail: safe(frame.detail) };
+            frame = { ...frame, detail: safe(frame.detail, 500) };
         if (frame.type === 'realtime.closed' && frame.reason)
             frame = { ...frame, reason: safe(frame.reason) };
         if (frame.type === 'realtime.transcript')
-            frame = { ...frame, text: safe(frame.text) };
+            frame = { ...frame, text: safe(frame.text, 4000) };
         // Inspect every outbound string, including data-channel payloads, for exact credentials.
         const serialized = JSON.stringify(frame);
         if (secrets.some(secret => secret && serialized.includes(secret))) {
@@ -52,6 +61,7 @@ export function realtimeEngine(options) {
         emittedClose = true;
         stopped = true;
         lifetime.abort();
+        authCheck?.close();
         options.bridge.close();
         usage.seconds = (Date.now() - start) / 1000;
         options.onUsage?.({ ...usage });
@@ -70,15 +80,15 @@ export function realtimeEngine(options) {
         return true;
     };
     const ready = (async () => {
-        const credential = options.auth.kind === 'key' ? { access: options.auth.key, accountId: '' } : await options.auth.access(lifetime.signal);
-        if (stopped)
-            return;
-        secrets.push(credential.access);
+        // Warm the isolated child while the app resolves access. No credential is
+        // sent until access succeeds; queued device frames still follow its config.
         const entry = new URL(`./child.${import.meta.url.endsWith('.ts') ? 'ts' : 'js'}`, import.meta.url);
         child = spawn(process.execPath, [fileURLToPath(entry)], { env: {}, stdio: ['pipe', 'pipe', 'pipe'] });
         child.stdin.on('error', () => finish('Voice input failed.'));
         child.on('error', () => finish('Voice could not start.'));
-        child.on('exit', () => { clearTimeout(killTimer); finish('Voice provider disconnected.'); });
+        child.on('exit', () => clearTimeout(killTimer));
+        // 'close' follows drained stdio, so a final provider reason wins over exit.
+        child.on('close', () => finish('Voice provider disconnected.'));
         // Never forward stderr: providers may include credentials in URLs or errors.
         child.stderr.resume();
         let lineBytes = 0;
@@ -98,6 +108,11 @@ export function realtimeEngine(options) {
                 return;
             try {
                 const raw = JSON.parse(line);
+                if (raw.type === 'kit.ready') {
+                    if (options.engine === 'chatgpt')
+                        clearTimeout(startupTimer);
+                    return;
+                }
                 if (raw.type === 'kit.tool.cancel') {
                     toolCalls.get(raw.id)?.abort();
                     return;
@@ -108,6 +123,13 @@ export function realtimeEngine(options) {
                     void options.bridge.run(raw.name, raw.args, raw.id, AbortSignal.any([lifetime.signal, controller.signal])).then(output => { send(`${JSON.stringify({ type: 'kit.tool.result', id: raw.id, output })}\n`); }).catch(() => finish('Voice tool failed.')).finally(() => toolCalls.delete(raw.id));
                     return;
                 }
+                // Normalize prose before byte-bound admission, including provider Unicode.
+                if (raw.type === 'realtime.state' && typeof raw.detail === 'string')
+                    raw.detail = safe(raw.detail, 500);
+                if (raw.type === 'realtime.transcript' && typeof raw.text === 'string')
+                    raw.text = safe(raw.text, 4000);
+                if (raw.type === 'realtime.closed' && typeof raw.reason === 'string')
+                    raw.reason = safe(raw.reason);
                 const frame = parseRealtimeHostFrame(raw);
                 if (frame.type === 'realtime.ready' || frame.type === 'realtime.webrtc.start')
                     clearTimeout(startupTimer);
@@ -125,13 +147,36 @@ export function realtimeEngine(options) {
                 }
                 if (frame.type === 'realtime.transcript' && frame.role === 'agent')
                     options.bridge.answered();
+                if (frame.type === 'realtime.state') {
+                    options.bridge.state(frame.state, frame.detail, emit);
+                    return;
+                }
+                if (frame.type === 'realtime.transcript' && frame.role === 'user' && options.hangup?.(frame.text))
+                    ending = true;
                 emit(frame);
+                if (frame.type === 'realtime.transcript' && frame.role === 'agent' && ending)
+                    finish('ended');
             }
             catch {
                 finish('Voice provider sent an invalid frame.');
             }
         });
-        send(`${JSON.stringify({ engine: options.engine, key: credential.access, accountId: credential.accountId, instructions: options.instructions ?? '', tools: options.tools ?? [], model: options.model, voice: options.voice, endpoint: options.endpoint, redact: options.redact?.map(pattern => ({ source: pattern.source, flags: pattern.flags })) })}\n`);
+        // Local media setup overlaps access and child loading instead of waiting for both.
+        if (options.engine === 'chatgpt')
+            emit({ type: 'realtime.webrtc.start', dataChannelLabel: 'oai-events' });
+        let credential;
+        try {
+            credential = options.auth.kind === 'key' ? { access: options.auth.key, accountId: '' } : await options.auth.access(lifetime.signal);
+        }
+        catch (error) {
+            finish(options.authFailure?.(error) ?? (error instanceof Error ? error.message : 'Voice sign-in is unavailable.'));
+            return;
+        }
+        if (stopped)
+            return;
+        secrets.push(credential.access);
+        send(`${JSON.stringify({ engine: options.engine, key: credential.access, accountId: credential.accountId, instructions: options.instructions ?? '', tools: options.tools ?? [], model: options.model, voice: options.voice, endpoint: options.endpoint, signalingIdentity: options.signalingIdentity, redact: options.redact?.map(pattern => ({ source: pattern.source, flags: pattern.flags })) })}\n`);
+        configured = true;
         for (const line of pending)
             if (!send(line)) {
                 finish('Voice input overflowed.');
@@ -145,8 +190,11 @@ export function realtimeEngine(options) {
         receive(raw) {
             if (stopped)
                 return false;
-            const frame = parseRealtimeClientFrame(raw), line = `${JSON.stringify(frame)}\n`;
-            if (!child) {
+            const frame = parseRealtimeClientFrame(raw);
+            if (options.bridge.receive(frame))
+                return true;
+            const line = `${JSON.stringify(frame)}\n`;
+            if (!configured) {
                 const bytes = Buffer.byteLength(line);
                 if (queuedBytes + bytes > 128 * 1024) {
                     finish('Voice input overflowed.');

package/dist/prose.d.ts

@@ -1,4 +1,6 @@
 export declare const cleanProse: (value: unknown, fallback: string, max: number, redact?: RegExp[]) => string;
+/** Frame limits are UTF-8 bytes; truncate on whole Unicode characters. */
+export declare function cleanProseBytes(value: unknown, fallback: string, max: number, redact?: RegExp[]): string;
 /**
  * The provider explains a refusal in the HTTP body; the close code does not.
  * An out-of-credits 403 is otherwise indistinguishable from a dropped network,

package/dist/prose.js

@@ -14,6 +14,20 @@ export const cleanProse = (value, fallback, max, redact = []) => {
         .replace(/\s+/g, ' ').trim().slice(0, max);
     return clean || fallback;
 };
+/** Frame limits are UTF-8 bytes; truncate on whole Unicode characters. */
+export function cleanProseBytes(value, fallback, max, redact = []) {
+    const clean = cleanProse(value, fallback, max, redact);
+    const encoder = new TextEncoder();
+    let result = '', bytes = 0;
+    for (const char of clean) {
+        const size = encoder.encode(char).length;
+        if (bytes + size > max)
+            break;
+        result += char;
+        bytes += size;
+    }
+    return result.trim();
+}
 /**
  * The provider explains a refusal in the HTTP body; the close code does not.
  * An out-of-credits 403 is otherwise indistinguishable from a dropped network,

package/dist/tools.d.ts

@@ -11,15 +11,22 @@ export type ToolBridgeOptions = {
     timeoutFor?: (name: string) => number;
     answerTimeoutMs?: number;
     failure(name: string, error: unknown, timedOut: boolean): string;
+    /** Route semantic app replies to the same bridge used by tool handlers. */
+    app?: ReturnType<typeof appBridge>;
 };
 /** Bounded, deduplicated tool execution. Product authorization stays in handlers. */
 export declare function toolBridge(options: ToolBridgeOptions): {
     run: (name: string, args?: unknown, id?: string, signal?: AbortSignal) => Promise<string>;
-    state: (value: RealtimeState, detail?: string) => void;
+    state: (value: RealtimeState, detail?: string, emit?: (frame: RealtimeHostFrame) => void) => void;
     answered: () => void;
-    receive: (_frame: RealtimeClientFrame) => boolean;
+    receive: (frame: RealtimeClientFrame) => boolean;
     close(): void;
 };
+/** Structured requests use the app's allowlisted tools; prose uses its planner. */
+export declare function delegationHandler(options: {
+    bridge: ReturnType<typeof toolBridge>;
+    plan?: (request: string, context: Parameters<ToolHandler>[1]) => Promise<string>;
+}): ToolHandler;
 export declare function appBridge(emit: (frame: RealtimeHostFrame) => void | boolean, options?: {
     timeoutMs?: number;
     maxPending?: number;

package/dist/tools.js

@@ -1,11 +1,12 @@
 import { randomUUID } from 'node:crypto';
+import { cleanProseBytes } from "./prose.js";
 /** Bounded, deduplicated tool execution. Product authorization stays in handlers. */
 export function toolBridge(options) {
     const lifetime = new AbortController();
     const requests = new Map();
     let active = 0, waiting = false;
     let answerTimer;
-    const state = (value, detail) => options.emit({ type: 'realtime.state', state: value === 'connected' && (active > 0 || waiting) ? 'thinking' : value, ...(detail ? { detail } : {}) });
+    const state = (value, detail, emit = options.emit) => emit({ type: 'realtime.state', state: value === 'connected' && (active > 0 || waiting) ? 'thinking' : value, ...(detail ? { detail: cleanProseBytes(detail, 'Voice could not complete that request.', 500) } : {}) });
     const answered = () => { if (active)
         return; clearTimeout(answerTimer); waiting = false; };
     const run = (name, args = {}, id = randomUUID(), signal) => {
@@ -57,7 +58,34 @@ export function toolBridge(options) {
         requests.set(id, { key, promise });
         return promise;
     };
-    return { run, state, answered, receive: (_frame) => false, close() { lifetime.abort(); clearTimeout(answerTimer); waiting = false; } };
+    return { run, state, answered, receive: (frame) => options.app?.receive(frame) ?? false, close() { lifetime.abort(); options.app?.close(); clearTimeout(answerTimer); waiting = false; } };
+}
+/** Structured requests use the app's allowlisted tools; prose uses its planner. */
+export function delegationHandler(options) {
+    return async (args, context) => {
+        context.signal.throwIfAborted();
+        const request = args.request;
+        if (typeof request !== 'string' || !request.trim() || Buffer.byteLength(request) > 16000)
+            return 'That delegated request is invalid.';
+        let structured;
+        try {
+            structured = JSON.parse(request);
+        }
+        catch {
+            // JSON-looking input is never reinterpreted as permission to plan an action.
+            if (/^[\s]*[\[{]/.test(request))
+                return 'That delegated request is invalid.';
+            return options.plan ? options.plan(request, context) : 'That delegation needs an app planner.';
+        }
+        if (!structured || typeof structured !== 'object' || Array.isArray(structured))
+            return 'That delegated request is invalid.';
+        const call = structured;
+        if (typeof call.name !== 'string' || !call.name.trim() || call.name === 'delegate'
+            || Object.keys(call).some(key => key !== 'name' && key !== 'arguments'))
+            return 'That delegated request is invalid.';
+        // Arguments, including named targets, stay intact. The app validates and authorizes them.
+        return options.bridge.run(call.name, call.arguments === undefined ? {} : call.arguments, context.id, context.signal);
+    };
 }
 export function appBridge(emit, options = {}) {
     const pending = new Map();

package/dist/types.d.ts

@@ -63,6 +63,7 @@ export type AudioPorts = {
         unbind(sink: PlaybackSink): void;
         admit(base64: string): 'ok' | 'malformed' | 'overflow';
         clear(): void;
+        /** True means a drain callback was scheduled; false means nothing needs draining. */
         finish(onDrained?: () => void): boolean;
         afterDrain(kind: 'connected' | 'speech', run: () => void): boolean;
         stop(): void;
@@ -85,6 +86,9 @@ export type RealtimeClientOptions = {
     audio: AudioPorts;
     /** Transport closures retry by default. Return false for intentional or terminal closures. */
     retryableClose?(reason?: string): boolean;
+    /** Retain ready PCM capture and the playback tail across carrier reconnects.
+     * WebRTC still needs a fresh peer. Pending microphone acquisition is never retained. */
+    preserveMediaOnReconnect?: boolean;
     webrtc?: (options: import('./webrtc.ts').WebRtcOptions) => Promise<import('./webrtc.ts').WebRtcHandle>;
     onStatus(status: 'connecting' | 'connected' | 'thinking' | 'speaking' | 'disconnected', reason?: string): void;
     onTurn(role: 'user' | 'agent', text: string): void;

package/dist/webrtc.js

@@ -36,7 +36,8 @@ export async function webRtcPeer(options) {
     } };
     try {
         options.onConnectionState('connecting');
-        options.signal?.throwIfAborted();
+        if (options.signal?.aborted)
+            throw new Error('Voice is closed.');
         await options.audio.microphone.acquire();
         acquired = true;
         if (stopped) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/realtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Realtime voice sessions with host-held credentials and injected audio.",
   "license": "Apache-2.0",
   "type": "module",