@byokit/realtime weekly downloads statistics

@byokit/realtime

Realtime voice sessions with injected audio and provider adapters in a child process. First consumer: muxr.

import { realtimeClient, type AudioPorts, type RealtimeHostFrame, type RealtimeStream } from '@byokit/realtime';
import { realtimeEngine, toolBridge } from '@byokit/realtime/node';

// The app supplies its sign-in, carrier, audio implementation and authorized planner.
declare const accounts: { access(member: number, signal?: AbortSignal): Promise<{ access: string; accountId: string }> };
declare const emit: (frame: RealtimeHostFrame) => void;
declare const runPlanner: (request: string, signal: AbortSignal) => Promise<string>;
declare const openVoiceStream: () => Promise<RealtimeStream>;
declare const audio: AudioPorts;
const member = 1;
const tools = [{ name: 'delegate', description: 'Handle a spoken request', parameters: { type: 'object', properties: { request: { type: 'string' } } } }];
const bridge = toolBridge({
  tools, handlers: { delegate: async (args, { signal }) => runPlanner(String(args.request), signal) },
  emit, failure: () => 'That request could not be completed.',
});
const engine = realtimeEngine({
  engine: 'chatgpt', auth: { kind: 'plan', access: signal => accounts.access(member, signal) },
  tools, bridge, instructions: 'Answer briefly.', emit,
});
// Forward device frames to engine.receive(frame); engine.close() ends the child.
const client = realtimeClient({
  open: openVoiceStream, audio,
  onStatus: status => console.log(status),
  onTurn: (role, text) => console.log(role, text),
});

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:

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.

import { realtimeEngine, toolBridge } from '@byokit/realtime/node';
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<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), onResult: showSignInMessage },
});
```…