@byokit/realtime 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.3.0 (2026-10-01)
+
+
+
+- Add opt-in lazy WebRTC microphone capture: preconnect without a microphone lease, attach and release capture without renegotiation, and release pending capture on close.
+
+## 0.2.1 (2026-09-30)
+
+
+
+- FIX: Report saved-sign-in failure reasons and plain remedies in advisory auth checks while preserving existing status results.
+
 ## 0.2.0 (2026-09-30)
 
 

package/README.md

@@ -85,28 +85,40 @@ 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';
+import type { RealtimeAuth, RealtimeHostFrame, RealtimeTool, RealtimeAuthPeekResult, RealtimeAuthResult } 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 peekSavedSignIn: (signal: AbortSignal) => Promise<RealtimeAuthPeekResult>;
 declare const updateSettingsBadge: (status: 'ready' | 'signed-out' | 'unknown') => void;
+declare const showSignInMessage: (result: RealtimeAuthResult) => void;
 const engine = realtimeEngine({
   engine: 'chatgpt', auth,
   tools, bridge, emit,
-  authCheck: { peek: peekSavedSignIn, onStatus: status => updateSettingsBadge(status) },
+  authCheck: { peek: peekSavedSignIn, onStatus: status => updateSettingsBadge(status), onResult: showSignInMessage },
 });
 ```
 
 `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
+`signed-out` means the lookup returned false or found an unusable saved sign-in.
+Unrecognized 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
+from the portable entry and returns `{ result, details, close }`. `result` still
+resolves to the status string; `details` resolves to `{ state, reason?, message? }`,
+and engine `onResult` receives the same diagnostic object. A boolean or
+`{ state }` peek keeps the previous behavior without adding a reason.
+
+To report an expired saved sign-in, the read-only peek can return
+`{ state: 'signed-out', reason: 'login-expired' }`. Built-in reasons are
+`credential-permissions`, `login-expired`, `missing` and `unknown`; apps can
+supply additional reason strings. Messages use fixed plain wording and never
+copy exception text or credential paths. Missing-file errors map to `missing`,
+permission errors to `credential-permissions`, and expired-login errors to
+`login-expired`; unrecognized errors and timeouts report `unknown`. Do not await this check
 before opening a voice session or show a login prompt from its result.
 
 ## Lifecycle announcements and semantic app tools
@@ -157,6 +169,46 @@ The main entry is portable for web and React Native and loads no native code. `.
 
 `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.
 
+## Preconnect without microphone capture
+
+Set `capture: 'lazy'` for a browser or React Native WebRTC session. Startup
+negotiates one `sendrecv` audio transceiver with no sender track: it calls
+neither `audio.microphone.acquire()` nor `getUserMedia`, so the app's microphone
+foreground service stays stopped. The playback route remains available.
+
+```ts
+import { realtimeClient, type AudioPorts, type RealtimeStream } from '@byokit/realtime';
+import { webRtcPeer } from '@byokit/realtime/webrtc';
+declare const audio: AudioPorts;
+declare const openVoiceStream: () => Promise<RealtimeStream>;
+const client = realtimeClient({
+  open: openVoiceStream, audio, webrtc: webRtcPeer, capture: 'lazy',
+  onStatus() {}, onTurn() {},
+});
+// Once WebRTC setup has started, await this before accepting speech:
+async function beginTalking() { await client.attachMic(); }
+// When idle, release hardware capture while keeping the call connected:
+async function becomeIdle() { await client.releaseMic(); }
+// End the call and release all media:
+function endCall() { client.stop(); }
+```
+
+`attachMic()` awaits the app's microphone permission/service lease, captures
+an audio track and uses `sender.replaceTrack(track)`. `releaseMic()` awaits
+`replaceTrack(null)`, stops capture tracks and releases the lease so the app
+can stop its microphone service and clear the OS indicator. Neither operation
+renegotiates. Repeated calls are safe; release or stop during pending capture
+cleans up when that capture resolves. Reconnecting starts another lazy peer;
+the app explicitly attaches again when it needs input.
+
+The built-in `webRtcPeer` handle also exposes both methods for direct use.
+Custom peer factories may implement these optional methods; client attach
+rejects if the current peer does not support them or setup has not started.
+The default is eager capture, and PCM capture is unchanged. `setMuted()` still
+only toggles track delivery; use `releaseMic()` to relinquish capture. Mute
+state persists when a new track is attached. Each client owns its `AudioPorts`;
+`microphone.release()` must stop the app-owned foreground service.
+
 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

package/dist/auth.d.ts

@@ -1,7 +1,20 @@
 export type RealtimeAuthStatus = 'ready' | 'signed-out' | 'unknown';
+/** Additional app-defined reasons are allowed without changing the state contract. */
+export type RealtimeAuthReason = 'credential-permissions' | 'login-expired' | 'missing' | 'unknown' | (string & {});
+export type RealtimeAuthResult = {
+    state: RealtimeAuthStatus;
+    reason?: RealtimeAuthReason;
+    message?: string;
+};
+export type RealtimeAuthPeekResult = boolean | {
+    state: RealtimeAuthStatus;
+    reason?: RealtimeAuthReason;
+};
 export type RealtimeAuthCheckOptions = {
     /** Read-only saved-sign-in check. Must never start login, refresh access or prompt. */
-    peek(signal: AbortSignal): Promise<boolean>;
+    peek(signal: AbortSignal): Promise<RealtimeAuthPeekResult>;
+    /** Diagnostic observer, also available through the standalone details promise. */
+    onResult?(result: RealtimeAuthResult): void;
     onStatus?(status: RealtimeAuthStatus): void;
     /** Defaults to 1 second; capped at 10 seconds. */
     timeoutMs?: number;
@@ -9,5 +22,6 @@ export type RealtimeAuthCheckOptions = {
 /** Advisory only: session startup must proceed independently of this check. */
 export declare function realtimeAuthCheck(options: RealtimeAuthCheckOptions): {
     result: Promise<RealtimeAuthStatus>;
+    details: Promise<RealtimeAuthResult>;
     close(): void;
 };

package/dist/auth.js

@@ -1,29 +1,58 @@
+function describe(state, reason) {
+    if (!reason)
+        return { state };
+    const message = reason === 'credential-permissions' ? 'Your saved sign-in must be readable only by you.'
+        : reason === 'login-expired' ? 'Your saved sign-in has expired. Sign in again in settings.'
+            : reason === 'missing' ? 'No saved sign-in was found. Sign in in settings.'
+                : 'Your saved sign-in could not be checked.';
+    return { state, reason, message };
+}
+function failure(error) {
+    const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+    const reason = error && typeof error === 'object' && 'reason' in error ? error.reason : undefined;
+    if (reason === 'credential-permissions' || reason === 'login-expired' || reason === 'missing' || reason === 'unknown')
+        return describe(reason === 'unknown' ? 'unknown' : 'signed-out', reason);
+    if (code === 'ENOENT')
+        return describe('signed-out', 'missing');
+    if (code === 'EACCES' || code === 'EPERM' || code === 'credential-permissions' || (error instanceof Error && /owner.only|readable only by|permissions.*(?:credential|sign-in)|(?:credential|sign-in).*permissions/i.test(error.message)))
+        return describe('signed-out', 'credential-permissions');
+    if (code === 'login-expired' || code === 'TOKEN_EXPIRED' || (error instanceof Error && /\b(?:login|sign-in|token|credential)\b.*\bexpired\b/i.test(error.message)))
+        return describe('signed-out', 'login-expired');
+    return describe('unknown', 'unknown');
+}
 /** 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) => {
+    let resolveDetails;
+    const details = new Promise(done => { resolveDetails = done; });
+    const finish = (value, notify = true) => {
         if (settled)
             return;
         settled = true;
         clearTimeout(timer);
         controller.abort();
-        resolve(status);
+        resolve(value.state);
+        resolveDetails(value);
         // A settings observer cannot fail a call or create an unhandled rejection.
         if (notify) {
             try {
-                options.onStatus?.(status);
+                options.onStatus?.(value.state);
+            }
+            catch { }
+            try {
+                options.onResult?.(value);
             }
             catch { }
         }
     };
     const timeout = options.timeoutMs ?? 1000;
-    const timer = setTimeout(() => finish('unknown'), Number.isFinite(timeout) ? Math.min(10000, Math.max(1, timeout)) : 1000);
+    const timer = setTimeout(() => finish(describe('unknown', '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); } };
+    }).then(value => finish(typeof value === 'object' && value !== null ? describe(value.state, value.reason) : describe(value === true ? 'ready' : value === false ? 'signed-out' : 'unknown')), error => finish(failure(error)));
+    return { result, details, close() { finish(describe('unknown', 'unknown'), false); } };
 }

package/dist/client.d.ts

@@ -2,6 +2,8 @@ import type { RealtimeClientOptions } from './types.ts';
 /** Provider-blind client with bounded reconnects and exclusive media ownership. */
 export declare function realtimeClient(options: RealtimeClientOptions): {
     stop: (reason?: string) => void;
+    attachMic(): Promise<void>;
+    releaseMic(): Promise<void>;
     interrupt(): void;
     setMuted(value: boolean): void;
     speak(text: string): void;

package/dist/client.js

@@ -18,6 +18,7 @@ export function realtimeClient(options) {
             audio.player.unbind(current.stream);
         await current.media?.catch(() => { });
         current.peer?.stop();
+        await current.peer?.releaseMic?.();
         await current.routeRelease;
         try {
             await current.capture?.release();
@@ -205,7 +206,7 @@ export function realtimeClient(options) {
                         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,
+                    current.media = options.webrtc({ label: frame.dataChannelLabel, capture: options.capture, 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 }))
@@ -303,6 +304,22 @@ export function realtimeClient(options) {
     connect();
     return {
         stop,
+        async attachMic() {
+            const current = attempt;
+            if (stopped || !current?.media)
+                throw new Error('Voice media is unavailable.');
+            await current.media;
+            if (stopped || attempt !== current || !current.peer?.attachMic)
+                throw new Error('Voice media is unavailable.');
+            await current.peer.attachMic();
+        },
+        async releaseMic() {
+            const current = attempt;
+            if (!current?.media)
+                return;
+            await current.media;
+            await current.peer?.releaseMic?.();
+        },
         interrupt() { if (stopped)
             return; audio.player.clear(); speech.length = 0; if (!attempt?.stream?.send({ type: 'realtime.control', action: 'interrupt' })) {
             if (attempt)

package/dist/node.d.ts

@@ -5,7 +5,7 @@ import { toolBridge } 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 { RealtimeAuthCheckOptions, RealtimeAuthStatus, RealtimeAuthReason, RealtimeAuthResult, RealtimeAuthPeekResult } from './auth.ts';
 export type { ToolHandler, ToolBridgeOptions } from './tools.ts';
 export type { RealtimeSignalingIdentity } from './adapter.ts';
 export type RealtimeEngineOptions = RealtimeConfig & {

package/dist/rn-webrtc.d.ts

@@ -1,5 +1,8 @@
 import { type WebRtcOptions } from './webrtc.ts';
 export type { WebRtcOptions, WebRtcHandle } from './webrtc.ts';
 /** Native media stays unloaded until the app actually starts a voice session. */
-export declare function webRtcPeer(options: WebRtcOptions): Promise<import("./webrtc.ts").WebRtcHandle>;
+export declare function webRtcPeer(options: WebRtcOptions): Promise<import("./webrtc.ts").WebRtcHandle & {
+    attachMic(): Promise<void>;
+    releaseMic(): Promise<void>;
+}>;
 export { webRtcPeer as reactNativeWebRtcPeer };

package/dist/types.d.ts

@@ -89,6 +89,8 @@ export type RealtimeClientOptions = {
     /** 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 only: negotiate without capture, then use attachMic/releaseMic. PCM is unchanged. */
+    capture?: 'eager' | 'lazy';
     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.d.ts

@@ -3,11 +3,15 @@ export type WebRtcHandle = {
     acceptAnswer(sdp: string): Promise<void>;
     sendData(data: string): boolean;
     setMuted(muted: boolean): void;
+    attachMic?(): Promise<void>;
+    releaseMic?(): Promise<void>;
     stop(): void;
 };
 export type WebRtcOptions = {
     label: string;
     audio: Pick<AudioPorts, 'microphone' | 'route' | 'unroute'>;
+    /** Lazy WebRTC starts with no microphone lease or capture; attach explicitly when speaking. */
+    capture?: 'eager' | 'lazy';
     signal?: AbortSignal;
     platform?: {
         createPeer(): RTCPeerConnection;
@@ -20,5 +24,8 @@ export type WebRtcOptions = {
     onInterruption(active: boolean): void;
     onError(error: Error): void;
 };
-/** One peer per handle. Microphone permission/service readiness precedes media capture. */
-export declare function webRtcPeer(options: WebRtcOptions): Promise<WebRtcHandle>;
+/** One peer per handle. Microphone permission/service readiness precedes each capture. */
+export declare function webRtcPeer(options: WebRtcOptions): Promise<WebRtcHandle & {
+    attachMic(): Promise<void>;
+    releaseMic(): Promise<void>;
+}>;

package/dist/webrtc.js

@@ -4,27 +4,40 @@ function sdp(value) {
         throw new Error('Invalid voice connection answer.');
     return value;
 }
-/** One peer per handle. Microphone permission/service readiness precedes media capture. */
+/** One peer per handle. Microphone permission/service readiness precedes each capture. */
 export async function webRtcPeer(options) {
     if (!/^[A-Za-z0-9._-]{1,64}$/.test(options.label))
         throw new Error('Invalid voice channel.');
     const platform = options.platform ?? { createPeer: () => new RTCPeerConnection({ bundlePolicy: 'max-bundle', rtcpMuxPolicy: 'require' }), getUserMedia: () => navigator.mediaDevices.getUserMedia({ audio: true, video: false }) };
     let acquired = false, stopped = false, stream, peer, channel;
+    let sender, muted = false, micEpoch = 0;
+    let micOperation = Promise.resolve();
+    const serializeMic = (run) => {
+        const operation = micOperation.then(run);
+        micOperation = operation.catch(() => { });
+        return operation;
+    };
+    const clearMic = () => {
+        const previous = stream;
+        stream = undefined;
+        previous?.getTracks().forEach(track => { track.onmute = null; track.onunmute = null; track.onended = null; track.stop(); });
+        if (acquired) {
+            acquired = false;
+            options.audio.microphone.release();
+        }
+    };
     const queue = [];
     let queuedBytes = 0;
     const stop = () => {
         if (stopped)
             return;
         stopped = true;
-        stream?.getTracks().forEach(track => track.stop());
+        micEpoch++;
+        clearMic();
         channel?.close();
         peer?.close();
         queue.length = 0;
         void options.audio.unroute().catch(() => { });
-        if (acquired) {
-            options.audio.microphone.release();
-            acquired = false;
-        }
         options.signal?.removeEventListener('abort', stop);
         options.onRemoteAudio(false);
         options.onConnectionState('disconnected');
@@ -34,26 +47,87 @@ export async function webRtcPeer(options) {
         options.onError(error);
         stop();
     } };
+    const captureMic = async (generation) => {
+        await options.audio.microphone.acquire();
+        acquired = true;
+        if (stopped || generation !== micEpoch) {
+            clearMic();
+            return;
+        }
+        stream = await platform.getUserMedia();
+        if (stopped || generation !== micEpoch) {
+            clearMic();
+            return;
+        }
+        const input = stream.getAudioTracks()[0];
+        if (!input)
+            throw new Error('Microphone is unavailable.');
+        input.enabled = !muted;
+        input.onmute = () => options.onInterruption(true);
+        input.onunmute = () => options.onInterruption(false);
+        input.onended = () => fail(new Error('Microphone ended.'));
+        return stream;
+    };
+    const attachMic = () => {
+        const generation = micEpoch;
+        return serializeMic(async () => {
+            if (stopped)
+                throw new Error('Voice is closed.');
+            if (generation !== micEpoch || stream)
+                return;
+            try {
+                const captured = await captureMic(generation);
+                if (captured) {
+                    await sender.replaceTrack(captured.getAudioTracks()[0]);
+                    if (stopped || generation !== micEpoch) {
+                        if (!stopped)
+                            await sender.replaceTrack(null);
+                        clearMic();
+                    }
+                }
+            }
+            catch (error) {
+                clearMic();
+                throw error;
+            }
+        });
+    };
+    const releaseMic = () => {
+        micEpoch++;
+        stream?.getAudioTracks().forEach(track => { track.enabled = false; });
+        return serializeMic(async () => {
+            try {
+                if (!stopped && stream)
+                    await sender.replaceTrack(null);
+            }
+            finally {
+                clearMic();
+            }
+        });
+    };
     try {
         options.onConnectionState('connecting');
         if (options.signal?.aborted)
             throw new Error('Voice is closed.');
-        await options.audio.microphone.acquire();
-        acquired = true;
-        if (stopped) {
-            options.audio.microphone.release();
-            acquired = false;
-            throw new Error('Voice is closed.');
+        if (options.capture !== 'lazy') {
+            await options.audio.microphone.acquire();
+            acquired = true;
+            if (stopped) {
+                clearMic();
+                throw new Error('Voice is closed.');
+            }
         }
         await options.audio.route();
         if (stopped) {
             await options.audio.unroute();
             throw new Error('Voice is closed.');
         }
-        stream = await platform.getUserMedia();
-        if (stopped) {
-            stream.getTracks().forEach(track => track.stop());
-            throw new Error('Voice is closed.');
+        if (options.capture !== 'lazy') {
+            stream = await platform.getUserMedia();
+            if (stopped) {
+                clearMic();
+                throw new Error('Voice is closed.');
+            }
         }
         peer = platform.createPeer();
         channel = peer.createDataChannel(options.label);
@@ -79,13 +153,17 @@ export async function webRtcPeer(options) {
             options.onConnectionState('connecting'); };
         current.ontrack = event => { const track = event.track; if (track.kind !== 'audio' || stopped)
             return; options.onRemoteAudio(!track.muted); track.onmute = () => options.onRemoteAudio(false); track.onunmute = () => options.onRemoteAudio(true); track.onended = () => options.onRemoteAudio(false); };
-        const input = stream.getAudioTracks()[0];
-        if (!input)
-            throw new Error('Microphone is unavailable.');
-        input.onmute = () => options.onInterruption(true);
-        input.onunmute = () => options.onInterruption(false);
-        input.onended = () => fail(new Error('Microphone ended.'));
-        current.addTrack(input, stream);
+        if (options.capture === 'lazy')
+            sender = current.addTransceiver('audio', { direction: 'sendrecv' }).sender;
+        else {
+            const input = stream.getAudioTracks()[0];
+            if (!input)
+                throw new Error('Microphone is unavailable.');
+            input.onmute = () => options.onInterruption(true);
+            input.onunmute = () => options.onInterruption(false);
+            input.onended = () => fail(new Error('Microphone ended.'));
+            sender = current.addTrack(input, stream);
+        }
         await current.setLocalDescription(await current.createOffer());
         if (current.iceGatheringState !== 'complete')
             await new Promise((resolve, reject) => {
@@ -124,7 +202,7 @@ export async function webRtcPeer(options) {
                 flush();
                 return true;
             },
-            setMuted(muted) { stream?.getAudioTracks().forEach(track => { track.enabled = !muted; }); }, stop,
+            setMuted(value) { muted = value; stream?.getAudioTracks().forEach(track => { track.enabled = !value; }); }, attachMic, releaseMic, stop,
         };
     }
     catch (error) {

package/package.json

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