@byokit/realtime 0.1.0

package/dist/node.js

@@ -0,0 +1,163 @@
+import { spawn } from 'node:child_process';
+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";
+/** 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))
+        throw new RealtimeError('unsupported');
+    if (options.endpoint && !['127.0.0.1', '[::1]', 'localhost'].includes(new URL(options.endpoint).hostname))
+        throw new RealtimeError('unsupported');
+    if ((options.engine === 'chatgpt') !== (options.auth.kind === 'plan'))
+        throw new RealtimeError('unsupported');
+    let stopped = false, emittedClose = false;
+    const lifetime = new AbortController();
+    const start = Date.now();
+    let child;
+    let killTimer;
+    let queuedBytes = 0;
+    const pending = [];
+    const toolCalls = new Map();
+    const secrets = [];
+    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)
+        if (secret)
+            result = result.replaceAll(secret, '[hidden]'); return cleanProse(result, 'Voice ended.', 500, options.redact); };
+    const emit = (frame) => {
+        if (frame.type === 'realtime.state' && frame.detail)
+            frame = { ...frame, detail: safe(frame.detail) };
+        if (frame.type === 'realtime.closed' && frame.reason)
+            frame = { ...frame, reason: safe(frame.reason) };
+        if (frame.type === 'realtime.transcript')
+            frame = { ...frame, text: safe(frame.text) };
+        // Inspect every outbound string, including data-channel payloads, for exact credentials.
+        const serialized = JSON.stringify(frame);
+        if (secrets.some(secret => secret && serialized.includes(secret))) {
+            if (frame.type === 'realtime.webrtc.answer') {
+                finish('Voice answer included private credentials.');
+                return;
+            }
+            for (const secret of secrets)
+                if (secret)
+                    frame = JSON.parse(JSON.stringify(frame).replaceAll(secret, '[hidden]'));
+        }
+        options.emit(frame);
+    };
+    const finish = (reason, retryable = false) => {
+        if (emittedClose)
+            return;
+        emittedClose = true;
+        stopped = true;
+        lifetime.abort();
+        options.bridge.close();
+        usage.seconds = (Date.now() - start) / 1000;
+        options.onUsage?.({ ...usage });
+        emit({ type: 'realtime.usage', usage: { ...usage } });
+        emit({ type: 'realtime.closed', ...(retryable ? { retryable: true } : {}), ...(reason ? { reason: safe(reason) } : {}) });
+        if (child && child.exitCode === null) {
+            child.kill('SIGTERM');
+            killTimer = setTimeout(() => child?.kill('SIGKILL'), 1000);
+            killTimer.unref();
+        }
+    };
+    const send = (line) => {
+        if (!child?.stdin || stopped || child.stdin.destroyed || child.stdin.writableLength + Buffer.byteLength(line) > 512 * 1024)
+            return false;
+        child.stdin.write(line);
+        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);
+        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.'); });
+        // Never forward stderr: providers may include credentials in URLs or errors.
+        child.stderr.resume();
+        let lineBytes = 0;
+        const startupTimer = setTimeout(() => finish('Voice setup timed out.'), 20000);
+        child.once('exit', () => clearTimeout(startupTimer));
+        child.stdout.on('data', (chunk) => { for (const byte of chunk) {
+            if (byte === 10)
+                lineBytes = 0;
+            else if (++lineBytes > 128 * 1024) {
+                finish('Voice frame exceeded its limit.');
+                break;
+            }
+        } });
+        const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        lines.on('line', line => {
+            if (stopped)
+                return;
+            try {
+                const raw = JSON.parse(line);
+                if (raw.type === 'kit.tool.cancel') {
+                    toolCalls.get(raw.id)?.abort();
+                    return;
+                }
+                if (raw.type === 'kit.tool') {
+                    const controller = toolCalls.get(raw.id) ?? new AbortController();
+                    toolCalls.set(raw.id, controller);
+                    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;
+                }
+                const frame = parseRealtimeHostFrame(raw);
+                if (frame.type === 'realtime.ready' || frame.type === 'realtime.webrtc.start')
+                    clearTimeout(startupTimer);
+                if (frame.type === 'realtime.closed') {
+                    finish(frame.reason, frame.retryable);
+                    return;
+                }
+                if (frame.type === 'realtime.usage') {
+                    for (const key of ['inputTokens', 'outputTokens', 'audioInTokens', 'audioOutTokens', 'cachedTokens'])
+                        if (frame.usage[key] !== undefined)
+                            usage[key] = (usage[key] ?? 0) + frame.usage[key];
+                    usage.seconds = (Date.now() - start) / 1000;
+                    emit({ type: 'realtime.usage', usage: { ...usage } });
+                    return;
+                }
+                if (frame.type === 'realtime.transcript' && frame.role === 'agent')
+                    options.bridge.answered();
+                emit(frame);
+            }
+            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`);
+        for (const line of pending)
+            if (!send(line)) {
+                finish('Voice input overflowed.');
+                break;
+            }
+        pending.length = 0;
+        queuedBytes = 0;
+    })().catch(() => finish('Voice sign-in is unavailable.'));
+    return {
+        ready, usage,
+        receive(raw) {
+            if (stopped)
+                return false;
+            const frame = parseRealtimeClientFrame(raw), line = `${JSON.stringify(frame)}\n`;
+            if (!child) {
+                const bytes = Buffer.byteLength(line);
+                if (queuedBytes + bytes > 128 * 1024) {
+                    finish('Voice input overflowed.');
+                    return false;
+                }
+                pending.push(line);
+                queuedBytes += bytes;
+                return true;
+            }
+            return send(line);
+        },
+        close(reason) { finish(reason); },
+    };
+}

package/dist/policy.d.ts

@@ -0,0 +1,7 @@
+/** A new turn invalidates unfinished tools and output from the prior turn. */
+export declare function responseFence(): {
+    interrupt: () => void;
+    begin(next?: string): boolean;
+    accepts(next?: string): boolean;
+    readonly signal: AbortSignal;
+};

package/dist/policy.js

@@ -0,0 +1,24 @@
+/** A new turn invalidates unfinished tools and output from the prior turn. */
+export function responseFence() {
+    let controller = new AbortController(), id, fenced = false;
+    const retired = new Set();
+    const interrupt = () => { controller.abort(); if (id) {
+        retired.add(id);
+        if (retired.size > 128)
+            retired.delete(retired.values().next().value);
+    } fenced = true; };
+    return {
+        interrupt,
+        begin(next) {
+            if (next && (retired.has(next) || next === id && !fenced))
+                return false;
+            interrupt();
+            controller = new AbortController();
+            id = next;
+            fenced = false;
+            return true;
+        },
+        accepts(next) { return !fenced && (!next || !id || next === id) && (!next || !retired.has(next)); },
+        get signal() { return controller.signal; },
+    };
+}

package/dist/prose.d.ts

@@ -0,0 +1,7 @@
+export declare const cleanProse: (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,
+ * and reporting only the code costs a debugging session to rediscover.
+ */
+export declare function providerRefusal(status: number | undefined, body: string, redact?: RegExp[]): string;

package/dist/prose.js

@@ -0,0 +1,42 @@
+const redactCredentials = (value) => String(value ?? '')
+    .normalize('NFKC')
+    .replace(/["'](?:[A-Za-z][A-Za-z0-9]*_)*(?:api[_-]?key|access[_-]?token|token|secret|password)["']\s*[:=]\s*["']?[^"'{}\s,;]+["']?/gi, '[credential redacted]')
+    .replace(/\b(Bearer)\s+[A-Za-z0-9._~+/-]{12,}/gi, '$1 [redacted]')
+    .replace(/\b(?:[A-Za-z][A-Za-z0-9]*_)+(?:api_key|token|secret|password)\s*[:=]\s*[^\s,;]+/gi, '[credential redacted]')
+    .replace(/\b((?:api[_-]?)?key|token|secret|password)\s*[:=]\s*[^\s,;]+/gi, '$1=[redacted]')
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/gi, '[credential redacted]')
+    .replace(/\beyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gi, '[credential redacted]');
+export const cleanProse = (value, fallback, max, redact = []) => {
+    const clean = redact.reduce((text, pattern) => text.replace(pattern, '[hidden]'), redactCredentials(value))
+        .replace(/(?<![A-Za-z0-9_/])\/(?!\/)(?:[^\s\/<>"']+\/)+[^\s\/<>"']+/gm, '[path hidden]')
+        .replace(/\b[A-Za-z]:\\(?:[^\s\\]+\\)+[^\s,;]*/g, '[path hidden]')
+        .replace(/[\u0000-\u001F\u007F<>`{}\\/]/g, ' ')
+        .replace(/\s+/g, ' ').trim().slice(0, max);
+    return clean || fallback;
+};
+/**
+ * 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,
+ * and reporting only the code costs a debugging session to rediscover.
+ */
+export function providerRefusal(status, body, redact = []) {
+    let detail = '';
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed?.error === 'string')
+            detail = parsed.error;
+        else if (typeof parsed?.error?.message === 'string')
+            detail = parsed.error.message;
+        else if (typeof parsed?.error?.status === 'string')
+            detail = parsed.error.status;
+        else if (typeof parsed?.code === 'string')
+            detail = parsed.code;
+    }
+    catch { /* not JSON: fall back to the raw body */ }
+    if (detail === '')
+        detail = body.trim();
+    const safe = cleanProse(detail, '', 300, redact);
+    return safe === ''
+        ? `Voice provider refused the connection (HTTP ${status}).`
+        : `Voice provider refused the connection (HTTP ${status}): ${safe}`;
+}

package/dist/providers/gemini.d.ts

@@ -0,0 +1,6 @@
+import type { AdapterOptions } from '../adapter.ts';
+import type { RealtimeClientFrame } from '../frames.ts';
+export declare function createAdapter(options: AdapterOptions): {
+    receive(frame: RealtimeClientFrame): void;
+    close(reason?: string): void;
+};