@urun-sh/sense 0.0.0-stage → 0.1.1

package/dist/transport.js

@@ -0,0 +1,467 @@
+/** Transport layer: one standing bidirectional event wire per session.
+ *
+ * Every transport carries the SAME OpenAI JSON events (media rides the event
+ * channel as `input_audio_buffer.append` / `conversation.item.create`), so the
+ * session loop is transport-agnostic:
+ *
+ * - `quic`   — WebTransport: POST /v1/realtime/calls?transport=quic →
+ *              {callId, url, token, certHashes}, then a WT session with a
+ *              msgpack hello control stream and an NDJSON events stream.
+ *              Native `globalThis.WebTransport` (browsers; Node only if the
+ *              global exists).
+ * - `webrtc` — RTCPeerConnection: POST the SDP offer, events on the
+ *              `oai-events` data channel (byte-for-byte the WS protocol).
+ *              Browsers only; Node falls through to WS.
+ * - `ws`     — the original websocket wire (Node `ws`, auth via header).
+ *
+ * `auto` tries QUIC (short dial: UDP may be blocked) → WebRTC → WS.
+ */
+import { encode as msgpackEncode, decode as msgpackDecode } from '@msgpack/msgpack';
+export const TRANSPORT_DIAL_TIMEOUT_MS = {
+    quic: 2_000, // UDP blocked ⇒ QUIC never completes; fail fast
+    webrtc: 10_000, // ICE + DTLS + datachannel open
+};
+/** A non-WS transport could not be established (fallback signal in auto). */
+export class TransportDialError extends Error {
+}
+/** The WS dial was refused with 503/429 — worth a backoff redial (§7). */
+export class DialRefused extends Error {
+    status;
+    constructor(status) {
+        super(`dial refused: ${status}`);
+        this.status = status;
+    }
+}
+function globalCtor(name) {
+    // Cross-runtime constructor probe: this package's tsconfig has no DOM/node
+    // lib, so globalThis is not typed for WebTransport/RTCPeerConnection.
+    const g = globalThis;
+    const value = g[name];
+    return typeof value === 'function' ? value : undefined;
+}
+// ---------------------------------------------------------------------------
+// shared helpers
+// ---------------------------------------------------------------------------
+export async function withTimeout(p, ms, label) {
+    const { promise, reject } = Promise.withResolvers();
+    const timer = setTimeout(() => reject(new TransportDialError(`${label} timed out after ${ms}ms`)), ms);
+    try {
+        return await Promise.race([p, promise]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** certHashes entries: the gateway serves base64 sha-256; tolerate lowercase hex. */
+export function hashToBytes(h) {
+    if (h.length === 64 && /^[0-9a-fA-F]+$/.test(h)) {
+        const out = new Uint8Array(32);
+        for (let i = 0; i < 32; i++)
+            out[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+        return out;
+    }
+    let bin;
+    try {
+        bin = atob(h);
+    }
+    catch {
+        throw new TransportDialError(`certHashes entry is neither base64 nor hex sha-256: ${h}`);
+    }
+    if (bin.length !== 32)
+        throw new TransportDialError(`certHashes entry is neither base64 nor hex sha-256: ${h}`);
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** Incremental NDJSON splitter: feed bytes, get complete lines. */
+export class NdjsonSplitter {
+    buf = '';
+    push(text) {
+        this.buf += text;
+        const out = [];
+        for (;;) {
+            const i = this.buf.indexOf('\n');
+            if (i < 0)
+                break;
+            const line = this.buf.slice(0, i);
+            this.buf = this.buf.slice(i + 1);
+            if (line.trim())
+                out.push(line);
+        }
+        return out;
+    }
+}
+const WT_CONTROL_FRAME_MAX = 256 * 1024;
+function encodeWtControlFrame(msg) {
+    const body = msgpackEncode(msg);
+    const framed = new Uint8Array(4 + body.byteLength);
+    new DataView(framed.buffer).setUint32(0, body.byteLength, true);
+    framed.set(body, 4);
+    return framed;
+}
+class WtControlDecoder {
+    buf = new Uint8Array(0);
+    push(bytes) {
+        const merged = new Uint8Array(this.buf.byteLength + bytes.byteLength);
+        merged.set(this.buf);
+        merged.set(bytes, this.buf.byteLength);
+        this.buf = merged;
+        const out = [];
+        while (this.buf.byteLength >= 4) {
+            const len = new DataView(this.buf.buffer, this.buf.byteOffset).getUint32(0, true);
+            if (len > WT_CONTROL_FRAME_MAX)
+                throw new TransportDialError('wt control frame too large');
+            if (this.buf.byteLength < 4 + len)
+                break;
+            const body = this.buf.subarray(4, 4 + len);
+            this.buf = this.buf.subarray(4 + len);
+            out.push(msgpackDecode(body));
+        }
+        return out;
+    }
+}
+// ---------------------------------------------------------------------------
+// WebSocket
+// ---------------------------------------------------------------------------
+export class WsWire {
+    ws;
+    kind = 'ws';
+    messageCb = null;
+    closeCb = null;
+    constructor(ws) {
+        this.ws = ws;
+        ws.on?.('message', (data) => this.messageCb?.(String(data)));
+        ws.on?.('close', (code) => this.closeCb?.(code));
+        // EventEmitter: an unhandled 'error' throws (crashes the host process);
+        // 'close' follows and reports the death through closeCb.
+        ws.on?.('error', () => undefined);
+    }
+    sendJson(obj) {
+        this.ws.send(JSON.stringify(obj));
+    }
+    onMessage(cb) {
+        this.messageCb = cb;
+    }
+    onClose(cb) {
+        this.closeCb = cb;
+    }
+    close() {
+        const { promise, resolve } = Promise.withResolvers();
+        this.ws.once?.('close', () => resolve());
+        this.ws.close();
+        return promise;
+    }
+}
+/** Dial the WS wire. Node uses the `ws` package (Authorization header
+ * support); a browser global WebSocket cannot set headers, so browser WS
+ * fallback is only viable where the proxy accepts URL-carried auth.
+ *
+ * Dynamic import: `ws` is a Node-only package — a static import would break
+ * every browser bundle of this SDK (the platform-specific-module exception). */
+export const dialWs = async (opts) => {
+    const Impl = await webSocketImpl();
+    const { promise, resolve, reject } = Promise.withResolvers();
+    const ws = new Impl(opts.wsUrl, { headers: { Authorization: `Bearer ${opts.apiKey}` } });
+    const fail = (err) => {
+        ws.removeAllListeners?.();
+        reject(err);
+    };
+    ws.once?.('unexpected-response', (_req, res) => {
+        const status = res.statusCode ?? 0;
+        fail(status === 503 || status === 429 ? new DialRefused(status) : new TransportDialError(`handshake refused: ${status}`));
+    });
+    ws.once?.('error', fail);
+    const onOpen = () => {
+        ws.off?.('error', fail);
+        resolve(new WsWire(ws));
+    };
+    if (typeof ws.once === 'function')
+        ws.once('open', onOpen);
+    else
+        ws.addEventListener?.('open', onOpen, { once: true });
+    return promise;
+};
+async function webSocketImpl() {
+    // Cross-runtime Node probe: globalThis.process is untyped (no node lib here).
+    const env = globalThis;
+    const isNode = typeof env.process?.versions?.node === 'string';
+    if (isNode) {
+        const { default: WS } = await import('ws');
+        return WS; // `ws`'s typed ctor accepts the structural WsLike surface
+    }
+    const ctor = globalCtor('WebSocket');
+    if (ctor === undefined)
+        throw new TransportDialError('no WebSocket implementation on this platform');
+    // Browser WebSocket cannot set the Authorization header ({headers} becomes
+    // the protocols arg → SyntaxError) and has no EventEmitter surface — dialWs
+    // needs both. Fail clearly instead of a fallback that can never work.
+    throw new TransportDialError('browser WebSocket fallback is unsupported (no header auth)');
+}
+// ---------------------------------------------------------------------------
+// QUIC / WebTransport
+// ---------------------------------------------------------------------------
+export class QuicWire {
+    opts;
+    kind = 'quic';
+    messageCb = null;
+    closeCb = null;
+    writer = null;
+    splitter = new NdjsonSplitter();
+    wt = null;
+    closedSent = false;
+    static available() {
+        return globalCtor('WebTransport') !== undefined;
+    }
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async connect() {
+        const WT = globalCtor('WebTransport');
+        if (WT === undefined)
+            throw new TransportDialError('no WebTransport implementation on this platform');
+        const res = await fetch(`${this.opts.apiBaseUrl.replace(/\/+$/, '')}/v1/realtime/calls?model=${encodeURIComponent(this.opts.model)}&transport=quic`, { method: 'POST', headers: { authorization: `Bearer ${this.opts.apiKey}` } });
+        if (res.status !== 201) {
+            throw new TransportDialError(`POST /v1/realtime/calls?transport=quic -> ${res.status}: ${(await res.text()).slice(0, 200)}`);
+        }
+        const answer = (await res.json());
+        const wt = new WT(answer.url, {
+            serverCertificateHashes: (answer.certHashes ?? []).map((h) => ({ algorithm: 'sha-256', value: hashToBytes(h) })),
+        });
+        this.wt = wt;
+        await wt.ready;
+        // canonical control dance: msgpack hello {token, sessionId} → hello-ack
+        const ctrl = await wt.createBidirectionalStream();
+        const ctrlWriter = ctrl.writable.getWriter();
+        await ctrlWriter.write(encodeWtControlFrame({ t: 'hello', token: answer.token, sessionId: answer.callId }));
+        const helloAcked = Promise.withResolvers();
+        const pumpControl = async () => {
+            const reader = ctrl.readable.getReader();
+            const decoder = new WtControlDecoder();
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    throw new TransportDialError('gateway closed the control stream before hello-ack');
+                for (const msg of decoder.push(value)) {
+                    if (msg.t === 'hello-ack') {
+                        helloAcked.resolve();
+                    }
+                    else if (msg.t === 'ping') {
+                        // ponytail: u64 ping ids ride through as Numbers (exact < 2^53);
+                        // byte-mirror the msgpack body if a gateway ever checks wider ids.
+                        await ctrlWriter.write(encodeWtControlFrame({ t: 'pong', ts: msg.ts ?? 0, id: msg.id ?? 0 }));
+                    }
+                }
+            }
+        };
+        pumpControl().catch((err) => {
+            helloAcked.reject(err);
+            this.signalClosed();
+        });
+        await helloAcked.promise;
+        // events stream: NDJSON, both directions, exact OpenAI JSON
+        const events = await wt.createBidirectionalStream();
+        this.writer = events.writable.getWriter();
+        const pumpEvents = async () => {
+            const reader = events.readable.getReader();
+            const decoder = new TextDecoder();
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                for (const line of this.splitter.push(decoder.decode(value, { stream: true }))) {
+                    this.messageCb?.(line);
+                }
+            }
+        };
+        pumpEvents()
+            .catch(() => undefined) // read side died — report closed below
+            .finally(() => this.signalClosed());
+        wt.closed.then(() => this.signalClosed()).catch(() => this.signalClosed());
+    }
+    signalClosed() {
+        if (this.closedSent)
+            return;
+        this.closedSent = true;
+        this.closeCb?.();
+    }
+    sendJson(obj) {
+        if (this.writer === null || this.closedSent)
+            throw new TransportDialError('quic wire closed');
+        // ponytail: no backpressure handling; the events channel is low-volume JSON.
+        this.writer.write(new TextEncoder().encode(JSON.stringify(obj) + '\n')).catch(() => this.signalClosed());
+    }
+    onMessage(cb) {
+        this.messageCb = cb;
+    }
+    onClose(cb) {
+        this.closeCb = cb;
+    }
+    async close() {
+        try {
+            this.wt?.close();
+        }
+        catch {
+            // already closed
+        }
+        this.signalClosed();
+    }
+}
+// ---------------------------------------------------------------------------
+// WebRTC
+// ---------------------------------------------------------------------------
+export class RtcWire {
+    opts;
+    kind = 'webrtc';
+    messageCb = null;
+    closeCb = null;
+    pc = null;
+    dc = null;
+    static available() {
+        return globalCtor('RTCPeerConnection') !== undefined;
+    }
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async connect() {
+        const RTCP = globalCtor('RTCPeerConnection');
+        if (RTCP === undefined)
+            throw new TransportDialError('no RTCPeerConnection on this platform');
+        // No STUN/TURN: the SFU is reached via host candidates on its announced ports.
+        const pc = new RTCP({ iceServers: [] });
+        this.pc = pc;
+        const dc = pc.createDataChannel('oai-events');
+        this.dc = dc;
+        // The SDK's media rides the event channel as JSON; the audio m-line exists
+        // so the SFU's sendrecv merge can answer. We listen only.
+        pc.addTransceiver('audio', { direction: 'recvonly' });
+        dc.onmessage = (ev) => {
+            const data = ev.data;
+            this.messageCb?.(typeof data === 'string' ? data : new TextDecoder().decode(data));
+        };
+        dc.onclose = () => this.closeCb?.();
+        pc.onconnectionstatechange = () => {
+            if (pc.connectionState === 'failed' || pc.connectionState === 'closed')
+                this.closeCb?.();
+        };
+        await pc.setLocalDescription(await pc.createOffer());
+        const res = await fetch(`${this.opts.apiBaseUrl.replace(/\/+$/, '')}/v1/realtime/calls?model=${encodeURIComponent(this.opts.model)}`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${this.opts.apiKey}`, 'content-type': 'application/sdp' },
+            body: pc.localDescription.sdp,
+        });
+        if (res.status !== 201) {
+            throw new TransportDialError(`POST /v1/realtime/calls -> ${res.status}: ${(await res.text()).slice(0, 200)}`);
+        }
+        await pc.setRemoteDescription({ type: 'answer', sdp: await res.text() });
+        await this.waitDcOpen();
+    }
+    async waitDcOpen() {
+        const { promise, resolve, reject } = Promise.withResolvers();
+        const dc = this.dc;
+        const pc = this.pc;
+        if (dc.readyState === 'open')
+            return;
+        const poll = setInterval(() => {
+            if (pc.connectionState === 'failed' || pc.iceConnectionState === 'failed') {
+                clearInterval(poll);
+                reject(new TransportDialError('peer connection failed before datachannel open'));
+            }
+        }, 100);
+        dc.onopen = () => {
+            clearInterval(poll);
+            resolve();
+        };
+        await promise;
+    }
+    sendJson(obj) {
+        if (this.dc === null || this.dc.readyState !== 'open')
+            throw new TransportDialError('webrtc wire closed');
+        this.dc.send(JSON.stringify(obj));
+    }
+    onMessage(cb) {
+        this.messageCb = cb;
+    }
+    onClose(cb) {
+        this.closeCb = cb;
+    }
+    async close() {
+        try {
+            this.dc?.close();
+        }
+        catch {
+            // already closed
+        }
+        try {
+            this.pc?.close();
+        }
+        catch {
+            // already closed
+        }
+        this.closeCb?.();
+    }
+}
+// ---------------------------------------------------------------------------
+// selection
+// ---------------------------------------------------------------------------
+/** Dial order. Auto = quic → webrtc → ws, skipping platforms without the
+ * client stack. Explicit overrides dial exactly one. */
+export function transportOrder(transport) {
+    if (transport !== 'auto')
+        return [transport];
+    const order = [];
+    if (QuicWire.available())
+        order.push('quic');
+    if (RtcWire.available())
+        order.push('webrtc');
+    order.push('ws');
+    return order;
+}
+export const defaultDialers = {
+    ws: dialWs,
+    quic: async (opts) => {
+        const wire = new QuicWire(opts);
+        try {
+            await wire.connect();
+        }
+        catch (err) {
+            await wire.close();
+            throw err;
+        }
+        return wire;
+    },
+    webrtc: async (opts) => {
+        const wire = new RtcWire(opts);
+        try {
+            await wire.connect();
+        }
+        catch (err) {
+            await wire.close();
+            throw err;
+        }
+        return wire;
+    },
+};
+export async function connectWire(opts, dialers = {}) {
+    const dial = (name) => dialers[name] ? dialers[name](opts) : defaultDialers[name](opts);
+    for (const name of transportOrder(opts.transport)) {
+        if (name === 'ws') {
+            console.info('[sense] transport=ws');
+            return await dial('ws');
+        }
+        const pending = dial(name);
+        try {
+            const wire = await withTimeout(pending, TRANSPORT_DIAL_TIMEOUT_MS[name], `transport=${name} dial`);
+            console.info(`[sense] transport=${name} live`);
+            return wire;
+        }
+        catch (err) {
+            // A late-resolving dial must not leak an orphaned live wire.
+            void pending.then((w) => w.close(), () => undefined);
+            if (opts.transport !== 'auto')
+                throw err;
+            console.info(`[sense] transport=${name} failed (${err instanceof Error ? err.message : String(err)}) — falling back`);
+        }
+    }
+    throw new TransportDialError('no usable transport (auto order exhausted)');
+}

package/dist/wave.d.ts

@@ -0,0 +1,58 @@
+/** Wave + results: the decoded answer set for one cadence tick (protocol §6). */
+import type { Question } from "./question.js";
+/** One question's answer in a wave. */
+export declare class Result {
+    readonly id: string;
+    readonly kind: "noul" | "choice" | "score";
+    readonly waveId: number;
+    /** noul: boolean; choice: top option name; score: expected ordinal Σi·p. */
+    readonly value: boolean | string | number;
+    /** noul: P(true); choice: P(top); score: P(top level). */
+    readonly p: number;
+    readonly confidence: number;
+    /** Label-keyed probabilities (score: level names). */
+    readonly distribution: Record<string, number>;
+    /** argmax label ("true"/"false" for noul, option name, level name). */
+    readonly top: string;
+    constructor(init: {
+        id: string;
+        kind: "noul" | "choice" | "score";
+        waveId: number;
+        value: boolean | string | number;
+        p: number;
+        confidence: number;
+        distribution: Record<string, number>;
+        top: string;
+    });
+    pOption(name: string): number;
+    /** Only valid on score results: Σ p over levels >= the given level. */
+    pAtLeast(level: string): number;
+}
+/** Score result: ordinal distribution over ordered levels. */
+export declare class Score extends Result {
+    readonly kind: "score";
+    readonly value: number;
+    readonly levels: string[];
+    /** argmax level name. */
+    readonly level: string;
+    constructor(init: {
+        id: string;
+        waveId: number;
+        probs: Record<string, number>;
+        levels: string[];
+        confidence: number;
+    });
+    pAtLeast(level: string): number;
+}
+/** One wave: exactly one answer per registered question (§6). */
+export declare class Wave {
+    readonly waveId: number;
+    readonly tMs: number;
+    private readonly results;
+    constructor(waveId: number, tMs: number, results: Record<string, Result>);
+    result(qid: string): Result;
+    has(qid: string): boolean;
+    questionIds(): string[];
+    /** Decode one wire payload ({wave_id, t_ms, results}) against registered questions. */
+    static decode(questions: readonly Question[], payload: unknown): Wave;
+}