@pyai/sdk 0.2.0 → 0.2.1

package/README.md

@@ -31,13 +31,13 @@ import PyAI from "@pyai/sdk";
 const pyai = new PyAI({ apiKey: process.env.PYAI_API_KEY! });
 
 // Text-to-speech
-const audio = await pyai.audio.speech({ input: "Hello from PyAI.", voice: "stock_sarah_style2" });
+const audio = await pyai.audio.speech({ input: "Hello from PyAI.", voice: "stock_emma_en_gb" });
 await Bun.write?.("hello.wav", audio); // or fs.writeFile in Node
 
 // Text-to-speech, streamed — start playing/forwarding at the first chunk
 // (tens of ms) instead of waiting for the whole clip. Use mp3 for smooth
 // progressive playback.
-const stream = await pyai.audio.speechStream({ input: "Hello from PyAI.", voice: "stock_sarah_style2", response_format: "mp3" });
+const stream = await pyai.audio.speechStream({ input: "Hello from PyAI.", voice: "stock_emma_en_gb", response_format: "mp3" });
 for await (const chunk of stream) writeToSpeakerOrResponse(chunk);
 
 // Voices
@@ -53,20 +53,42 @@ const done = await pyai.transcriptionJobs.get(job.job_id);
 
 ## Realtime (Omni)
 
-Keys travel as a WebSocket subprotocol so this works in the browser:
+`omni.connect()` opens an agentic-voice session and hides the wire protocol —
+including its **frame-key asymmetry** (your control frames are keyed on `type`,
+the server's frames are keyed on `event`). It sends a `type`-keyed `configure`
+the instant the socket opens and routes server frames to typed callbacks, so you
+**can't** trip the #1 Omni integration bug (a hand-rolled `{"event":"configure"}`
+is acked but silently dropped, giving you a connected session with zero turns):
 
 ```ts
-const ws = pyai.connectRealtime({ product: "omni", agentId: "agent_123" });
-ws.addEventListener("message", (e) => console.log(e.data));
+// Omni is zero-state: the key's org authorizes the session — nothing to create.
+const omni = pyai.omni.connect({
+  rate: 16000, // 24000 browser · 16000 wideband telephony · 8000 G.711/Twilio
+  configure: { voice_id: "stock_emma_en_gb", persona: "You are a receptionist." },
+  onAudio: (chunk) => speaker.write(chunk), // binary agent audio — play it out
+  onTranscript: (f) => console.log(f.text),
+  onError: (e) => console.error(e),
+});
+
+omni.sendAudio(pcm16Chunk); // stream caller audio continuously (server-side VAD)
+omni.sendDtmf("5");
+omni.close();
+```
+
+From the browser, mint an ephemeral token server-side with
+`pyai.omni.createSession({ allowedOrigins })` and pass it as `token` so the page
+never holds a secret key:
 
-// Or build the pieces yourself for a custom WS library:
-const url = pyai.realtimeURL({ product: "omni", agentId: "agent_123" });
-const proto = pyai.realtimeSubprotocol();
+```ts
+const omni = pyai.omni.connect({ token: session.token, configure: { voice_id, persona } });
 ```
 
-> Omni uses the native `wss://api.pyai.com/v1/omni` surface. `connectRealtime`
-> targets it by default (`product: "omni"`); `product: "flow"` uses
-> `/v1/realtime`. The older `/v2/omni/chat` URL is deprecated but still works.
+> Omni uses the native `wss://api.pyai.com/v1/omni` surface and is **zero-state**
+> — no agent to create, `sessionLabel` is an optional opaque tag (never
+> required). Need the raw socket? `pyai.realtimeURL({ product: "omni" })` +
+> `pyai.realtimeSubprotocol()` (or `pyai.connectRealtime()`) still work;
+> `product: "flow"` uses `/v1/realtime`. The older `/v2/omni/chat` URL and the
+> `agentId` option are deprecated but still work.
 
 ## Streaming speech-to-text (Hear / Cue)
 
@@ -116,7 +138,7 @@ drop the hand-rolled resampler + μ-law encoder entirely:
 // Twilio/SIP-ready in one param: raw 8 kHz mono μ-law, no client-side DSP.
 const ulaw = await pyai.audio.speech({
   input: "Your appointment is confirmed.",
-  voice: "stock_sarah_style2",
+  voice: "stock_emma_en_gb",
   response_format: "g711_ulaw", // -> audio/basic, forced 8 kHz
 });
 // base64-encode `ulaw` straight into a Twilio media frame.
@@ -176,7 +198,7 @@ const quality = detail.quality_metrics;                    // { wer?, ttfb_ms?,
 once the engine supports them and otherwise ignored — so it's always safe to send:
 
 ```ts
-await pyai.audio.speech({ input: "Hello", voice: "stock_sarah_style2", seed: 42, temperature: 0 });
+await pyai.audio.speech({ input: "Hello", voice: "stock_emma_en_gb", seed: 42, temperature: 0 });
 await pyai.audio.transcriptions.create({ file: wavBlob, seed: 42 });
 ```
 
@@ -225,7 +247,7 @@ Other commands:
 ```bash
 pyai models
 pyai voices --gender female --region en_us
-pyai speak --text "Hello" --voice stock_sarah_style2 --out hello.wav
+pyai speak --text "Hello" --voice stock_emma_en_gb --out hello.wav
 pyai transcribe --url https://example.com/call.wav --diarize --poll
 ```
 

package/dist/index.d.ts

@@ -121,13 +121,52 @@ export interface CreateJobParams {
     webhook_url?: string;
 }
 export interface RealtimeOptions {
-    /** "omni" (agentic, needs agentId) or "flow" (voice duplex). Default "omni". */
+    /** "omni" (agentic voice) or "flow" (legacy voice duplex). Default "omni". */
     product?: "omni" | "flow";
-    /** Required for omni: the agent to drive. */
+    /**
+     * Optional opaque tag echoed to your `kb_endpoint` and recorded on the call.
+     * Omni is zero-state: the session is authorized by the key's org, so there is
+     * nothing to create first and this tag is never required.
+     */
+    sessionLabel?: string;
+    /**
+     * @deprecated Use {@link sessionLabel}. Kept for back-compat — emitted as the
+     * `agent_id` query alias, which the gateway still accepts. Ignored if
+     * `sessionLabel` is set.
+     */
     agentId?: string;
     /** Extra query params (e.g. format, rate). */
     query?: Record<string, string>;
 }
+/** Parameters for minting an ephemeral browser Omni session token (server-side). */
+export interface OmniSessionParams {
+    /**
+     * Browser origins (scheme://host[:port]) the minted token may connect from.
+     * Required and non-empty — a browser token must be origin-locked. `*` is not
+     * allowed.
+     */
+    allowedOrigins: string[];
+    /** Token lifetime in seconds. Default 60 server-side; max 600. Keep it short. */
+    ttlSeconds?: number;
+    /** Optional opaque tag echoed back to your `kb_endpoint` and recorded on the call. */
+    sessionLabel?: string;
+}
+/**
+ * The result of {@link PyAI.omni}.createSession — a short-lived credential safe
+ * to hand to the browser. Use {@link OmniSession.token} as the WebSocket
+ * subprotocol `pyai-key.<token>` against {@link OmniSession.url}.
+ */
+export interface OmniSession {
+    object?: "omni.session";
+    /** The ephemeral session token. Short-lived + origin-locked; browser-safe. */
+    token: string;
+    /** Token expiry, Unix epoch milliseconds. */
+    expires_at: number;
+    /** The Omni realtime WebSocket URL to connect to. */
+    url: string;
+    /** Echoed back when supplied on the request. */
+    session_label?: string;
+}
 /** Frame `type`s emitted by the Hear streaming-STT WebSocket. */
 export declare const HearFrameType: {
     /** Eager live hypothesis for the current utterance. */
@@ -138,6 +177,8 @@ export declare const HearFrameType: {
     readonly SpeechFinal: "speech_final";
     /** Corrected, full-context transcript following `speech_final`. */
     readonly Final: "final";
+    /** Final billed-usage summary, emitted just before a graceful close. */
+    readonly Usage: "usage";
     /** Server-side fault frame. */
     readonly Error: "error";
 };
@@ -203,13 +244,28 @@ export interface HearFinalFrame {
     /** Present only with Cue grounding enabled (top KB passages). */
     grounding?: HearGroundingPassage[];
 }
+/** Final billed-usage summary (`usage`), emitted just before a graceful close
+ * so realtime spend can be reconciled in-band (a realtime WS carries no
+ * `x-pyai-units` response header). Best-effort: absent if there was no billable
+ * audio or the close was abnormal. */
+export interface HearUsageFrame {
+    type: "usage";
+    /** `hear` for plain streaming, `cue` when grounding was enabled. */
+    product: "hear" | "cue";
+    /** The billed meter (`hear.requests` or `cue.minutes`). */
+    meter: string;
+    /** Summed active-speech audio billed for the session, in seconds. */
+    audio_seconds: number;
+    /** The same quantity in minutes. */
+    minutes: number;
+}
 /** Server fault frame (`error`). */
 export interface HearErrorFrame {
     type: "error";
     code?: string;
     message: string;
 }
-export type HearFrame = HearPartialFrame | HearFinalFrame | HearErrorFrame;
+export type HearFrame = HearPartialFrame | HearFinalFrame | HearUsageFrame | HearErrorFrame;
 /**
  * Minimal structural WebSocket — matches both the browser/Node global
  * `WebSocket` and the `ws` package, and lets tests inject a mock.
@@ -240,12 +296,32 @@ export interface HearStreamOptions {
     encoding?: "pcm16" | "opus";
     /** Emit eager partial hypotheses. Default true server-side. */
     interimResults?: boolean;
+    /**
+     * Format spoken numbers as digits in the transcript (e.g. "one two three" →
+     * "123"). Useful for voice agents that read back phone numbers, codes, and
+     * amounts. Default false (spoken form). Forwards `?numerals=true` on the URL.
+     */
+    numerals?: boolean;
+    /**
+     * Turn-segmentation tuning: trailing-pause (ms, 50–2000) that ends an
+     * utterance. Forwards `?endpointing_ms=` — clamped + honored once the engine
+     * supports it; a no-op when omitted. Drive end-of-turn yourself with
+     * {@link HearStream.commit} for full control today.
+     */
+    endpointingMs?: number;
     /**
      * Enable Cue knowledge-base grounding: sends `{type:"config",grounding:true}`
      * on open, after which `speech_final`/`final` frames carry a `grounding`
      * array. Bills a single `cue.minutes` line instead of the Hear rate.
      */
     grounding?: boolean;
+    /** Cue: number of KB passages to retrieve per turn (1–20, default 3). */
+    groundingK?: number;
+    /** Cue: drop passages scoring below this (0–1, default 0 = keep all). */
+    groundingMinScore?: number;
+    /** Cue: max ms to wait for retrieval at the final before failing open to
+     * `grounding: []` (50–2000, default 450). */
+    groundingTimeoutMs?: number;
     /** Extra query params merged onto the connect URL. */
     query?: Record<string, string>;
     /** Fired once the socket opens (after the optional grounding config). */
@@ -254,6 +330,8 @@ export interface HearStreamOptions {
     onPartial?: (frame: HearPartialFrame) => void;
     /** Fired on `speech_final` / `final`. */
     onFinal?: (frame: HearFinalFrame) => void;
+    /** Fired on the final `usage` summary (in-band realtime reconciliation). */
+    onUsage?: (frame: HearUsageFrame) => void;
     /** Fired on an `error` frame or a transport-level error. */
     onError?: (err: HearErrorFrame | Error) => void;
     /** Fired when the socket closes (code per `WSCloseCode`). */
@@ -284,6 +362,152 @@ export declare class HearStream {
     /** Current WebSocket readyState. */
     get readyState(): number;
 }
+/**
+ * Event names on Omni **server → client** frames. ⚠️ Note the asymmetry:
+ * inbound frames are keyed on `event`, but your **outbound** control frames
+ * (`configure`, `dtmf`, …) are keyed on `type`. {@link OmniConnection} handles
+ * both sides for you; this map is for matching frames in `onEvent`.
+ */
+export declare const OmniEvent: {
+    /** Handshake; advertises protocol version + audio formats. */
+    readonly Hello: "hello";
+    /** Ack for your `configure` frame (echoes the resolved `voice_id`). */
+    readonly Configured: "configured";
+    /** Session is live; includes the resolved agent + audio caps. */
+    readonly SessionStarted: "session_started";
+    /** Turn boundary (user/assistant speaking). */
+    readonly Turn: "turn";
+    /** Incremental/final transcript text. */
+    readonly Transcript: "transcript";
+    /** User interrupted; assistant audio is being cut. */
+    readonly BargeIn: "barge_in";
+    /** Alias for barge-in on some engine builds. */
+    readonly Flush: "flush";
+    /** Session is closing; see close code. */
+    readonly SessionEnd: "session_end";
+    /** Server fault frame. */
+    readonly Error: "error";
+};
+export type OmniEvent = (typeof OmniEvent)[keyof typeof OmniEvent];
+/** A server → client Omni frame. Keyed on `event` (not `type`); open for forward-compat. */
+export interface OmniServerFrame {
+    event: string;
+    [k: string]: unknown;
+}
+/** A binary agent-audio chunk delivered to {@link OmniConnectOptions.onAudio}. */
+export type OmniAudioChunk = ArrayBuffer | ArrayBufferView | Blob;
+/**
+ * The agent config sent as the `configure` control frame. These are the wire
+ * (snake_case) fields the engine reads; it's an **open bag**, so forward-compat
+ * fields (e.g. `greeting` / `language` once the engine acks them) pass straight
+ * through. The SDK supplies the `{"type":"configure"}` envelope for you — which
+ * is the whole point: a hand-rolled `{"event":"configure"}` is acked but
+ * silently dropped, leaving the agent with no brain and zero turns.
+ */
+export interface OmniConfigure {
+    /** Voice to speak with (stock / clone / designed id). */
+    voice_id?: string;
+    /** System prompt / role + instructions for the agent. */
+    persona?: string;
+    /** Customer-hosted URL the engine calls per turn for grounding. */
+    kb_endpoint?: string;
+    /** Bearer the engine presents to `kb_endpoint`. */
+    kb_token?: string;
+    /** Forward-compatible: any other key the engine honors. */
+    [k: string]: unknown;
+}
+export interface OmniConnectOptions {
+    /** Optional opaque per-session tag echoed to your `kb_endpoint`. Omni is zero-state. */
+    sessionLabel?: string;
+    /**
+     * Ephemeral browser token from `omni.createSession`. When set it is used as
+     * the WS subprotocol (`pyai-key.<token>`) instead of the client's secret key,
+     * so a page never holds a secret key.
+     */
+    token?: string;
+    /** Connect-URL sample rate: 24000 browser, 16000 wideband telephony, 8000 G.711/Twilio. */
+    rate?: 24000 | 16000 | 8000;
+    /** Connect-URL audio format. Default `pcm16`. */
+    format?: "pcm16";
+    /**
+     * Agent config sent as `{"type":"configure",...}` the instant the socket
+     * opens. Omit to send it yourself later via {@link OmniConnection.configure}.
+     */
+    configure?: OmniConfigure;
+    /** Extra query params merged onto the connect URL. */
+    query?: Record<string, string>;
+    /** Fired once the socket opens (after the optional auto-configure). */
+    onOpen?: () => void;
+    /** Fired for each binary agent-audio chunk — play it out as it arrives. */
+    onAudio?: (chunk: OmniAudioChunk) => void;
+    /** Fired on the `hello` handshake frame. */
+    onHello?: (frame: OmniServerFrame) => void;
+    /** Fired on the `configured` ack. */
+    onConfigured?: (frame: OmniServerFrame) => void;
+    /** Fired on `session_started`. */
+    onSessionStarted?: (frame: OmniServerFrame) => void;
+    /** Fired on `turn` boundaries. */
+    onTurn?: (frame: OmniServerFrame) => void;
+    /** Fired on `transcript` text frames. */
+    onTranscript?: (frame: OmniServerFrame) => void;
+    /** Fired on `barge_in` / `flush` (user interrupted). */
+    onBargeIn?: (frame: OmniServerFrame) => void;
+    /** Fired on `session_end`. */
+    onSessionEnd?: (frame: OmniServerFrame) => void;
+    /** Fired on EVERY JSON frame (including unknown/forward-compat ones). */
+    onEvent?: (frame: OmniServerFrame) => void;
+    /** Fired on an `error` frame or a transport-level error. */
+    onError?: (err: OmniServerFrame | Error) => void;
+    /** Fired when the socket closes (code per {@link WSCloseCode}). */
+    onClose?: (code: number, reason: string) => void;
+    /** Injectable WebSocket constructor (defaults to the global). */
+    webSocket?: WebSocketCtor;
+}
+/**
+ * A live Omni agentic-voice session over `/v1/omni`. Hides the wire protocol's
+ * frame-key asymmetry: it sends control frames keyed on `type` (`configure`,
+ * `dtmf`) and parses server frames keyed on `event`, so you cannot trip the #1
+ * Omni integration bug (mirroring the server's `event` key on outbound, which
+ * is silently dropped). Construct via `pyai.omni.connect()`.
+ *
+ * @example
+ * const omni = pyai.omni.connect({
+ *   rate: 16000,
+ *   configure: { voice_id: "stock_emma_en_gb", persona: "You are a receptionist." },
+ *   onAudio: (chunk) => speaker.write(chunk),
+ *   onTranscript: (f) => console.log(f.text),
+ * });
+ * omni.sendAudio(pcm16Chunk); // stream caller audio continuously
+ */
+export declare class OmniConnection {
+    private readonly ws;
+    private readonly opts;
+    private closed;
+    constructor(url: string, subprotocol: string, opts: OmniConnectOptions);
+    private handleMessage;
+    /**
+     * Send (or update) the agent config. Always emitted as
+     * `{"type":"configure", ...}` — the correct key. (A hand-rolled
+     * `{"event":"configure"}` is acked but silently dropped by the engine.)
+     */
+    configure(cfg: OmniConfigure): void;
+    /** Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate). */
+    sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void;
+    /** Send DTMF digits as a `{"type":"dtmf"}` control frame. */
+    sendDtmf(digits: string): void;
+    /**
+     * Send an arbitrary control frame for forward-compat control types the SDK
+     * does not model yet. Reminder: client → server frames are keyed on `type`,
+     * never `event`.
+     */
+    send(frame: Record<string, unknown>): void;
+    /** Close the session. */
+    close(code?: number, reason?: string): void;
+    /** The underlying socket (escape hatch for advanced use). */
+    get socket(): WebSocketLike;
+    /** Current WebSocket readyState. */
+    get readyState(): number;
+}
 /** Shape of `GET /v1/me`. Fields are best-effort / forward-compatible. */
 export interface MeResponse {
     object?: string;
@@ -744,6 +968,29 @@ export declare class PyAI {
             trigger: (callId: string, input: RecapCallTriggerInput) => Promise<RecapCallSummary>;
         };
     };
+    omni: {
+        /**
+         * Mint an ephemeral, origin-locked Omni session token a browser can use to
+         * open ONE realtime session **directly** — the public/private split for
+         * realtime. **Call this from your server** with a secret key holding
+         * `omni:session`; never ship the secret key to a page. Hand the returned
+         * `token` to the browser, which connects with
+         * `new WebSocket(session.url, ["pyai-key." + session.token])`. The token
+         * expires after `ttlSeconds` (default 60s) and only works from
+         * `allowedOrigins`. Scope `omni:session`.
+         */
+        createSession: (params: OmniSessionParams) => Promise<OmniSession>;
+        /**
+         * Open a live Omni agentic-voice session over `/v1/omni`. Returns an
+         * {@link OmniConnection} that handles the wire protocol's frame-key
+         * asymmetry for you — it sends `type`-keyed control frames (`configure`,
+         * `dtmf`) and parses `event`-keyed server frames — so you can't trip the #1
+         * Omni integration bug. Omni is zero-state: nothing to create first; the
+         * agent's behavior travels in the `configure` frame. Pass `token` (from
+         * `createSession`) to connect from a browser without the secret key.
+         */
+        connect: (opts?: OmniConnectOptions) => OmniConnection;
+    };
     /** Build the realtime WebSocket URL for the chosen product. */
     realtimeURL(opts?: RealtimeOptions): string;
     /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */

package/dist/index.js

@@ -45,6 +45,8 @@ export const HearFrameType = {
     SpeechFinal: "speech_final",
     /** Corrected, full-context transcript following `speech_final`. */
     Final: "final",
+    /** Final billed-usage summary, emitted just before a graceful close. */
+    Usage: "usage",
     /** Server-side fault frame. */
     Error: "error",
 };
@@ -99,7 +101,14 @@ export class HearStream {
         this.ws.onopen = () => {
             if (opts.grounding) {
                 try {
-                    this.ws.send(JSON.stringify({ type: "config", grounding: true }));
+                    const cfg = { type: "config", grounding: true };
+                    if (opts.groundingK != null)
+                        cfg.grounding_k = opts.groundingK;
+                    if (opts.groundingMinScore != null)
+                        cfg.grounding_min_score = opts.groundingMinScore;
+                    if (opts.groundingTimeoutMs != null)
+                        cfg.grounding_timeout_ms = opts.groundingTimeoutMs;
+                    this.ws.send(JSON.stringify(cfg));
                 }
                 catch {
                     /* surfaced via onerror */
@@ -135,6 +144,9 @@ export class HearStream {
             case HearFrameType.Final:
                 this.opts.onFinal?.(frame);
                 break;
+            case HearFrameType.Usage:
+                this.opts.onUsage?.(frame);
+                break;
             case HearFrameType.Error:
                 this.opts.onError?.(frame);
                 break;
@@ -165,6 +177,164 @@ export class HearStream {
         return this.ws.readyState;
     }
 }
+/* ------------------------------------------------------------------------- *
+ * Omni realtime (agentic voice) — typed client over the /v1/omni WebSocket
+ * ------------------------------------------------------------------------- */
+/**
+ * Event names on Omni **server → client** frames. ⚠️ Note the asymmetry:
+ * inbound frames are keyed on `event`, but your **outbound** control frames
+ * (`configure`, `dtmf`, …) are keyed on `type`. {@link OmniConnection} handles
+ * both sides for you; this map is for matching frames in `onEvent`.
+ */
+export const OmniEvent = {
+    /** Handshake; advertises protocol version + audio formats. */
+    Hello: "hello",
+    /** Ack for your `configure` frame (echoes the resolved `voice_id`). */
+    Configured: "configured",
+    /** Session is live; includes the resolved agent + audio caps. */
+    SessionStarted: "session_started",
+    /** Turn boundary (user/assistant speaking). */
+    Turn: "turn",
+    /** Incremental/final transcript text. */
+    Transcript: "transcript",
+    /** User interrupted; assistant audio is being cut. */
+    BargeIn: "barge_in",
+    /** Alias for barge-in on some engine builds. */
+    Flush: "flush",
+    /** Session is closing; see close code. */
+    SessionEnd: "session_end",
+    /** Server fault frame. */
+    Error: "error",
+};
+/**
+ * A live Omni agentic-voice session over `/v1/omni`. Hides the wire protocol's
+ * frame-key asymmetry: it sends control frames keyed on `type` (`configure`,
+ * `dtmf`) and parses server frames keyed on `event`, so you cannot trip the #1
+ * Omni integration bug (mirroring the server's `event` key on outbound, which
+ * is silently dropped). Construct via `pyai.omni.connect()`.
+ *
+ * @example
+ * const omni = pyai.omni.connect({
+ *   rate: 16000,
+ *   configure: { voice_id: "stock_emma_en_gb", persona: "You are a receptionist." },
+ *   onAudio: (chunk) => speaker.write(chunk),
+ *   onTranscript: (f) => console.log(f.text),
+ * });
+ * omni.sendAudio(pcm16Chunk); // stream caller audio continuously
+ */
+export class OmniConnection {
+    ws;
+    opts;
+    closed = false;
+    constructor(url, subprotocol, opts) {
+        this.opts = opts;
+        const WS = opts.webSocket ?? globalThis.WebSocket;
+        if (!WS) {
+            throw new Error("No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to omni.connect()");
+        }
+        this.ws = new WS(url, [subprotocol]);
+        this.ws.onopen = () => {
+            if (opts.configure) {
+                try {
+                    this.configure(opts.configure);
+                }
+                catch {
+                    /* surfaced via onerror */
+                }
+            }
+            opts.onOpen?.();
+        };
+        this.ws.onmessage = (ev) => this.handleMessage(ev.data);
+        this.ws.onerror = (ev) => opts.onError?.(ev instanceof Error ? ev : new Error("WebSocket error"));
+        this.ws.onclose = (ev) => {
+            this.closed = true;
+            opts.onClose?.(ev.code, ev.reason);
+        };
+    }
+    handleMessage(data) {
+        // Binary = agent audio (play it out). JSON text = an `event`-keyed frame.
+        if (typeof data !== "string") {
+            this.opts.onAudio?.(data);
+            return;
+        }
+        let frame;
+        try {
+            frame = JSON.parse(data);
+        }
+        catch {
+            this.opts.onError?.(new Error(`Unparseable Omni frame: ${data.slice(0, 120)}`));
+            return;
+        }
+        this.opts.onEvent?.(frame);
+        switch (frame.event) {
+            case OmniEvent.Hello:
+                this.opts.onHello?.(frame);
+                break;
+            case OmniEvent.Configured:
+                this.opts.onConfigured?.(frame);
+                break;
+            case OmniEvent.SessionStarted:
+                this.opts.onSessionStarted?.(frame);
+                break;
+            case OmniEvent.Turn:
+                this.opts.onTurn?.(frame);
+                break;
+            case OmniEvent.Transcript:
+                this.opts.onTranscript?.(frame);
+                break;
+            case OmniEvent.BargeIn:
+            case OmniEvent.Flush:
+                this.opts.onBargeIn?.(frame);
+                break;
+            case OmniEvent.SessionEnd:
+                this.opts.onSessionEnd?.(frame);
+                break;
+            case OmniEvent.Error:
+                this.opts.onError?.(frame);
+                break;
+            default:
+                // Unknown/forward-compatible frame — already delivered via onEvent.
+                break;
+        }
+    }
+    /**
+     * Send (or update) the agent config. Always emitted as
+     * `{"type":"configure", ...}` — the correct key. (A hand-rolled
+     * `{"event":"configure"}` is acked but silently dropped by the engine.)
+     */
+    configure(cfg) {
+        this.ws.send(JSON.stringify({ type: "configure", ...cfg }));
+    }
+    /** Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate). */
+    sendAudio(chunk) {
+        this.ws.send(chunk);
+    }
+    /** Send DTMF digits as a `{"type":"dtmf"}` control frame. */
+    sendDtmf(digits) {
+        this.ws.send(JSON.stringify({ type: "dtmf", digits }));
+    }
+    /**
+     * Send an arbitrary control frame for forward-compat control types the SDK
+     * does not model yet. Reminder: client → server frames are keyed on `type`,
+     * never `event`.
+     */
+    send(frame) {
+        this.ws.send(JSON.stringify(frame));
+    }
+    /** Close the session. */
+    close(code = WSCloseCode.Normal, reason = "") {
+        if (!this.closed)
+            this.ws.close(code, reason);
+    }
+    /** The underlying socket (escape hatch for advanced use). */
+    get socket() {
+        return this.ws;
+    }
+    /** Current WebSocket readyState. */
+    get readyState() {
+        return this.ws.readyState;
+    }
+}
 const RETRYABLE = new Set([429, 500, 502, 503, 504]);
 export class PyAI {
     apiKey;
@@ -510,17 +680,57 @@ export class PyAI {
             trigger: (callId, input) => this.postJson(`/v1/recap/calls/${encodeURIComponent(callId)}`, input),
         },
     };
+    // --- omni (agentic voice) ----------------------------------------------
+    omni = {
+        /**
+         * Mint an ephemeral, origin-locked Omni session token a browser can use to
+         * open ONE realtime session **directly** — the public/private split for
+         * realtime. **Call this from your server** with a secret key holding
+         * `omni:session`; never ship the secret key to a page. Hand the returned
+         * `token` to the browser, which connects with
+         * `new WebSocket(session.url, ["pyai-key." + session.token])`. The token
+         * expires after `ttlSeconds` (default 60s) and only works from
+         * `allowedOrigins`. Scope `omni:session`.
+         */
+        createSession: (params) => this.postJson("/v1/omni/sessions", {
+            allowed_origins: params.allowedOrigins,
+            ...(params.ttlSeconds !== undefined ? { ttl_seconds: params.ttlSeconds } : {}),
+            ...(params.sessionLabel !== undefined ? { session_label: params.sessionLabel } : {}),
+        }),
+        /**
+         * Open a live Omni agentic-voice session over `/v1/omni`. Returns an
+         * {@link OmniConnection} that handles the wire protocol's frame-key
+         * asymmetry for you — it sends `type`-keyed control frames (`configure`,
+         * `dtmf`) and parses `event`-keyed server frames — so you can't trip the #1
+         * Omni integration bug. Omni is zero-state: nothing to create first; the
+         * agent's behavior travels in the `configure` frame. Pass `token` (from
+         * `createSession`) to connect from a browser without the secret key.
+         */
+        connect: (opts = {}) => {
+            const query = { ...(opts.query ?? {}) };
+            if (opts.format)
+                query.format = opts.format;
+            if (opts.rate)
+                query.rate = String(opts.rate);
+            const url = this.realtimeURL({ product: "omni", sessionLabel: opts.sessionLabel, query });
+            const sub = opts.token ? `pyai-key.${opts.token}` : this.realtimeSubprotocol();
+            return new OmniConnection(url, sub, opts);
+        },
+    };
     // --- realtime (WebSocket) ----------------------------------------------
     /** Build the realtime WebSocket URL for the chosen product. */
     realtimeURL(opts = {}) {
         const wsBase = this.baseURL.replace(/^http/, "ws");
         const q = new URLSearchParams(opts.query ?? {});
         if ((opts.product ?? "omni") === "omni") {
-            // Omni's native realtime surface is /v1/omni. agentId is an opaque label
-            // authorized by the key's org. format/rate are load-bearing on the
-            // connect URL, so default to browser-grade PCM16/24kHz.
-            if (opts.agentId)
-                q.set("agent_id", opts.agentId);
+            // Omni's native realtime surface is /v1/omni. The session is authorized by
+            // the key's org (zero-state) — sessionLabel is an optional opaque tag.
+            // format/rate are load-bearing on the connect URL, so default to
+            // browser-grade PCM16/24kHz.
+            if (opts.sessionLabel)
+                q.set("session_label", opts.sessionLabel);
+            else if (opts.agentId)
+                q.set("agent_id", opts.agentId); // deprecated alias
             if (!q.has("format"))
                 q.set("format", "pcm16");
             if (!q.has("rate"))
@@ -549,6 +759,10 @@ export class PyAI {
             q.set("encoding", opts.encoding);
         if (opts.interimResults !== undefined)
             q.set("interim_results", String(opts.interimResults));
+        if (opts.numerals !== undefined)
+            q.set("numerals", String(opts.numerals));
+        if (opts.endpointingMs !== undefined)
+            q.set("endpointing_ms", String(opts.endpointingMs));
         const qs = q.toString();
         return `${wsBase}/v1/audio/transcriptions/stream${qs ? `?${qs}` : ""}`;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyai/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Official TypeScript/JavaScript SDK for PyAI — speech-to-text (Hear), text-to-speech (Speak), realtime voice agents (Omni), and call compliance (Trace).",
   "type": "module",
   "main": "dist/index.js",
@@ -22,6 +22,7 @@
   },
   "homepage": "https://pyai.com",
   "bugs": "https://github.com/atomsai/pyai-platform-backend/issues",
+  "author": "PyAI",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "node --test test/**/*.test.ts",

package/src/index.ts

@@ -139,14 +139,55 @@ export interface CreateJobParams {
 }
 
 export interface RealtimeOptions {
-  /** "omni" (agentic, needs agentId) or "flow" (voice duplex). Default "omni". */
+  /** "omni" (agentic voice) or "flow" (legacy voice duplex). Default "omni". */
   product?: "omni" | "flow";
-  /** Required for omni: the agent to drive. */
+  /**
+   * Optional opaque tag echoed to your `kb_endpoint` and recorded on the call.
+   * Omni is zero-state: the session is authorized by the key's org, so there is
+   * nothing to create first and this tag is never required.
+   */
+  sessionLabel?: string;
+  /**
+   * @deprecated Use {@link sessionLabel}. Kept for back-compat — emitted as the
+   * `agent_id` query alias, which the gateway still accepts. Ignored if
+   * `sessionLabel` is set.
+   */
   agentId?: string;
   /** Extra query params (e.g. format, rate). */
   query?: Record<string, string>;
 }
 
+/** Parameters for minting an ephemeral browser Omni session token (server-side). */
+export interface OmniSessionParams {
+  /**
+   * Browser origins (scheme://host[:port]) the minted token may connect from.
+   * Required and non-empty — a browser token must be origin-locked. `*` is not
+   * allowed.
+   */
+  allowedOrigins: string[];
+  /** Token lifetime in seconds. Default 60 server-side; max 600. Keep it short. */
+  ttlSeconds?: number;
+  /** Optional opaque tag echoed back to your `kb_endpoint` and recorded on the call. */
+  sessionLabel?: string;
+}
+
+/**
+ * The result of {@link PyAI.omni}.createSession — a short-lived credential safe
+ * to hand to the browser. Use {@link OmniSession.token} as the WebSocket
+ * subprotocol `pyai-key.<token>` against {@link OmniSession.url}.
+ */
+export interface OmniSession {
+  object?: "omni.session";
+  /** The ephemeral session token. Short-lived + origin-locked; browser-safe. */
+  token: string;
+  /** Token expiry, Unix epoch milliseconds. */
+  expires_at: number;
+  /** The Omni realtime WebSocket URL to connect to. */
+  url: string;
+  /** Echoed back when supplied on the request. */
+  session_label?: string;
+}
+
 /* ------------------------------------------------------------------------- *
  * Stable enums — mirror the server so callers branch on named constants, not
  * magic strings, and a contract change surfaces in one place. These are plain
@@ -164,6 +205,8 @@ export const HearFrameType = {
   SpeechFinal: "speech_final",
   /** Corrected, full-context transcript following `speech_final`. */
   Final: "final",
+  /** Final billed-usage summary, emitted just before a graceful close. */
+  Usage: "usage",
   /** Server-side fault frame. */
   Error: "error",
 } as const;
@@ -239,6 +282,22 @@ export interface HearFinalFrame {
   grounding?: HearGroundingPassage[];
 }
 
+/** Final billed-usage summary (`usage`), emitted just before a graceful close
+ * so realtime spend can be reconciled in-band (a realtime WS carries no
+ * `x-pyai-units` response header). Best-effort: absent if there was no billable
+ * audio or the close was abnormal. */
+export interface HearUsageFrame {
+  type: "usage";
+  /** `hear` for plain streaming, `cue` when grounding was enabled. */
+  product: "hear" | "cue";
+  /** The billed meter (`hear.requests` or `cue.minutes`). */
+  meter: string;
+  /** Summed active-speech audio billed for the session, in seconds. */
+  audio_seconds: number;
+  /** The same quantity in minutes. */
+  minutes: number;
+}
+
 /** Server fault frame (`error`). */
 export interface HearErrorFrame {
   type: "error";
@@ -246,7 +305,7 @@ export interface HearErrorFrame {
   message: string;
 }
 
-export type HearFrame = HearPartialFrame | HearFinalFrame | HearErrorFrame;
+export type HearFrame = HearPartialFrame | HearFinalFrame | HearUsageFrame | HearErrorFrame;
 
 /**
  * Minimal structural WebSocket — matches both the browser/Node global
@@ -275,12 +334,32 @@ export interface HearStreamOptions {
   encoding?: "pcm16" | "opus";
   /** Emit eager partial hypotheses. Default true server-side. */
   interimResults?: boolean;
+  /**
+   * Format spoken numbers as digits in the transcript (e.g. "one two three" →
+   * "123"). Useful for voice agents that read back phone numbers, codes, and
+   * amounts. Default false (spoken form). Forwards `?numerals=true` on the URL.
+   */
+  numerals?: boolean;
+  /**
+   * Turn-segmentation tuning: trailing-pause (ms, 50–2000) that ends an
+   * utterance. Forwards `?endpointing_ms=` — clamped + honored once the engine
+   * supports it; a no-op when omitted. Drive end-of-turn yourself with
+   * {@link HearStream.commit} for full control today.
+   */
+  endpointingMs?: number;
   /**
    * Enable Cue knowledge-base grounding: sends `{type:"config",grounding:true}`
    * on open, after which `speech_final`/`final` frames carry a `grounding`
    * array. Bills a single `cue.minutes` line instead of the Hear rate.
    */
   grounding?: boolean;
+  /** Cue: number of KB passages to retrieve per turn (1–20, default 3). */
+  groundingK?: number;
+  /** Cue: drop passages scoring below this (0–1, default 0 = keep all). */
+  groundingMinScore?: number;
+  /** Cue: max ms to wait for retrieval at the final before failing open to
+   * `grounding: []` (50–2000, default 450). */
+  groundingTimeoutMs?: number;
   /** Extra query params merged onto the connect URL. */
   query?: Record<string, string>;
   /** Fired once the socket opens (after the optional grounding config). */
@@ -289,6 +368,8 @@ export interface HearStreamOptions {
   onPartial?: (frame: HearPartialFrame) => void;
   /** Fired on `speech_final` / `final`. */
   onFinal?: (frame: HearFinalFrame) => void;
+  /** Fired on the final `usage` summary (in-band realtime reconciliation). */
+  onUsage?: (frame: HearUsageFrame) => void;
   /** Fired on an `error` frame or a transport-level error. */
   onError?: (err: HearErrorFrame | Error) => void;
   /** Fired when the socket closes (code per `WSCloseCode`). */
@@ -320,7 +401,11 @@ export class HearStream {
     this.ws.onopen = () => {
       if (opts.grounding) {
         try {
-          this.ws.send(JSON.stringify({ type: "config", grounding: true }));
+          const cfg: Record<string, unknown> = { type: "config", grounding: true };
+          if (opts.groundingK != null) cfg.grounding_k = opts.groundingK;
+          if (opts.groundingMinScore != null) cfg.grounding_min_score = opts.groundingMinScore;
+          if (opts.groundingTimeoutMs != null) cfg.grounding_timeout_ms = opts.groundingTimeoutMs;
+          this.ws.send(JSON.stringify(cfg));
         } catch {
           /* surfaced via onerror */
         }
@@ -354,6 +439,9 @@ export class HearStream {
       case HearFrameType.Final:
         this.opts.onFinal?.(frame);
         break;
+      case HearFrameType.Usage:
+        this.opts.onUsage?.(frame);
+        break;
       case HearFrameType.Error:
         this.opts.onError?.(frame);
         break;
@@ -389,6 +477,254 @@ export class HearStream {
   }
 }
 
+/* ------------------------------------------------------------------------- *
+ * Omni realtime (agentic voice) — typed client over the /v1/omni WebSocket
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Event names on Omni **server → client** frames. ⚠️ Note the asymmetry:
+ * inbound frames are keyed on `event`, but your **outbound** control frames
+ * (`configure`, `dtmf`, …) are keyed on `type`. {@link OmniConnection} handles
+ * both sides for you; this map is for matching frames in `onEvent`.
+ */
+export const OmniEvent = {
+  /** Handshake; advertises protocol version + audio formats. */
+  Hello: "hello",
+  /** Ack for your `configure` frame (echoes the resolved `voice_id`). */
+  Configured: "configured",
+  /** Session is live; includes the resolved agent + audio caps. */
+  SessionStarted: "session_started",
+  /** Turn boundary (user/assistant speaking). */
+  Turn: "turn",
+  /** Incremental/final transcript text. */
+  Transcript: "transcript",
+  /** User interrupted; assistant audio is being cut. */
+  BargeIn: "barge_in",
+  /** Alias for barge-in on some engine builds. */
+  Flush: "flush",
+  /** Session is closing; see close code. */
+  SessionEnd: "session_end",
+  /** Server fault frame. */
+  Error: "error",
+} as const;
+export type OmniEvent = (typeof OmniEvent)[keyof typeof OmniEvent];
+
+/** A server → client Omni frame. Keyed on `event` (not `type`); open for forward-compat. */
+export interface OmniServerFrame {
+  event: string;
+  [k: string]: unknown;
+}
+
+/** A binary agent-audio chunk delivered to {@link OmniConnectOptions.onAudio}. */
+export type OmniAudioChunk = ArrayBuffer | ArrayBufferView | Blob;
+
+/**
+ * The agent config sent as the `configure` control frame. These are the wire
+ * (snake_case) fields the engine reads; it's an **open bag**, so forward-compat
+ * fields (e.g. `greeting` / `language` once the engine acks them) pass straight
+ * through. The SDK supplies the `{"type":"configure"}` envelope for you — which
+ * is the whole point: a hand-rolled `{"event":"configure"}` is acked but
+ * silently dropped, leaving the agent with no brain and zero turns.
+ */
+export interface OmniConfigure {
+  /** Voice to speak with (stock / clone / designed id). */
+  voice_id?: string;
+  /** System prompt / role + instructions for the agent. */
+  persona?: string;
+  /** Customer-hosted URL the engine calls per turn for grounding. */
+  kb_endpoint?: string;
+  /** Bearer the engine presents to `kb_endpoint`. */
+  kb_token?: string;
+  /** Forward-compatible: any other key the engine honors. */
+  [k: string]: unknown;
+}
+
+export interface OmniConnectOptions {
+  /** Optional opaque per-session tag echoed to your `kb_endpoint`. Omni is zero-state. */
+  sessionLabel?: string;
+  /**
+   * Ephemeral browser token from `omni.createSession`. When set it is used as
+   * the WS subprotocol (`pyai-key.<token>`) instead of the client's secret key,
+   * so a page never holds a secret key.
+   */
+  token?: string;
+  /** Connect-URL sample rate: 24000 browser, 16000 wideband telephony, 8000 G.711/Twilio. */
+  rate?: 24000 | 16000 | 8000;
+  /** Connect-URL audio format. Default `pcm16`. */
+  format?: "pcm16";
+  /**
+   * Agent config sent as `{"type":"configure",...}` the instant the socket
+   * opens. Omit to send it yourself later via {@link OmniConnection.configure}.
+   */
+  configure?: OmniConfigure;
+  /** Extra query params merged onto the connect URL. */
+  query?: Record<string, string>;
+  /** Fired once the socket opens (after the optional auto-configure). */
+  onOpen?: () => void;
+  /** Fired for each binary agent-audio chunk — play it out as it arrives. */
+  onAudio?: (chunk: OmniAudioChunk) => void;
+  /** Fired on the `hello` handshake frame. */
+  onHello?: (frame: OmniServerFrame) => void;
+  /** Fired on the `configured` ack. */
+  onConfigured?: (frame: OmniServerFrame) => void;
+  /** Fired on `session_started`. */
+  onSessionStarted?: (frame: OmniServerFrame) => void;
+  /** Fired on `turn` boundaries. */
+  onTurn?: (frame: OmniServerFrame) => void;
+  /** Fired on `transcript` text frames. */
+  onTranscript?: (frame: OmniServerFrame) => void;
+  /** Fired on `barge_in` / `flush` (user interrupted). */
+  onBargeIn?: (frame: OmniServerFrame) => void;
+  /** Fired on `session_end`. */
+  onSessionEnd?: (frame: OmniServerFrame) => void;
+  /** Fired on EVERY JSON frame (including unknown/forward-compat ones). */
+  onEvent?: (frame: OmniServerFrame) => void;
+  /** Fired on an `error` frame or a transport-level error. */
+  onError?: (err: OmniServerFrame | Error) => void;
+  /** Fired when the socket closes (code per {@link WSCloseCode}). */
+  onClose?: (code: number, reason: string) => void;
+  /** Injectable WebSocket constructor (defaults to the global). */
+  webSocket?: WebSocketCtor;
+}
+
+/**
+ * A live Omni agentic-voice session over `/v1/omni`. Hides the wire protocol's
+ * frame-key asymmetry: it sends control frames keyed on `type` (`configure`,
+ * `dtmf`) and parses server frames keyed on `event`, so you cannot trip the #1
+ * Omni integration bug (mirroring the server's `event` key on outbound, which
+ * is silently dropped). Construct via `pyai.omni.connect()`.
+ *
+ * @example
+ * const omni = pyai.omni.connect({
+ *   rate: 16000,
+ *   configure: { voice_id: "stock_emma_en_gb", persona: "You are a receptionist." },
+ *   onAudio: (chunk) => speaker.write(chunk),
+ *   onTranscript: (f) => console.log(f.text),
+ * });
+ * omni.sendAudio(pcm16Chunk); // stream caller audio continuously
+ */
+export class OmniConnection {
+  private readonly ws: WebSocketLike;
+  private readonly opts: OmniConnectOptions;
+  private closed = false;
+
+  constructor(url: string, subprotocol: string, opts: OmniConnectOptions) {
+    this.opts = opts;
+    const WS = opts.webSocket ?? (globalThis as { WebSocket?: WebSocketCtor }).WebSocket;
+    if (!WS) {
+      throw new Error(
+        "No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to omni.connect()",
+      );
+    }
+    this.ws = new WS(url, [subprotocol]);
+    this.ws.onopen = () => {
+      if (opts.configure) {
+        try {
+          this.configure(opts.configure);
+        } catch {
+          /* surfaced via onerror */
+        }
+      }
+      opts.onOpen?.();
+    };
+    this.ws.onmessage = (ev) => this.handleMessage(ev.data);
+    this.ws.onerror = (ev) => opts.onError?.(ev instanceof Error ? ev : new Error("WebSocket error"));
+    this.ws.onclose = (ev) => {
+      this.closed = true;
+      opts.onClose?.(ev.code, ev.reason);
+    };
+  }
+
+  private handleMessage(data: unknown): void {
+    // Binary = agent audio (play it out). JSON text = an `event`-keyed frame.
+    if (typeof data !== "string") {
+      this.opts.onAudio?.(data as OmniAudioChunk);
+      return;
+    }
+    let frame: OmniServerFrame;
+    try {
+      frame = JSON.parse(data) as OmniServerFrame;
+    } catch {
+      this.opts.onError?.(new Error(`Unparseable Omni frame: ${data.slice(0, 120)}`));
+      return;
+    }
+    this.opts.onEvent?.(frame);
+    switch (frame.event) {
+      case OmniEvent.Hello:
+        this.opts.onHello?.(frame);
+        break;
+      case OmniEvent.Configured:
+        this.opts.onConfigured?.(frame);
+        break;
+      case OmniEvent.SessionStarted:
+        this.opts.onSessionStarted?.(frame);
+        break;
+      case OmniEvent.Turn:
+        this.opts.onTurn?.(frame);
+        break;
+      case OmniEvent.Transcript:
+        this.opts.onTranscript?.(frame);
+        break;
+      case OmniEvent.BargeIn:
+      case OmniEvent.Flush:
+        this.opts.onBargeIn?.(frame);
+        break;
+      case OmniEvent.SessionEnd:
+        this.opts.onSessionEnd?.(frame);
+        break;
+      case OmniEvent.Error:
+        this.opts.onError?.(frame);
+        break;
+      default:
+        // Unknown/forward-compatible frame — already delivered via onEvent.
+        break;
+    }
+  }
+
+  /**
+   * Send (or update) the agent config. Always emitted as
+   * `{"type":"configure", ...}` — the correct key. (A hand-rolled
+   * `{"event":"configure"}` is acked but silently dropped by the engine.)
+   */
+  configure(cfg: OmniConfigure): void {
+    this.ws.send(JSON.stringify({ type: "configure", ...cfg }));
+  }
+
+  /** Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate). */
+  sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void {
+    this.ws.send(chunk);
+  }
+
+  /** Send DTMF digits as a `{"type":"dtmf"}` control frame. */
+  sendDtmf(digits: string): void {
+    this.ws.send(JSON.stringify({ type: "dtmf", digits }));
+  }
+
+  /**
+   * Send an arbitrary control frame for forward-compat control types the SDK
+   * does not model yet. Reminder: client → server frames are keyed on `type`,
+   * never `event`.
+   */
+  send(frame: Record<string, unknown>): void {
+    this.ws.send(JSON.stringify(frame));
+  }
+
+  /** Close the session. */
+  close(code: number = WSCloseCode.Normal, reason = ""): void {
+    if (!this.closed) this.ws.close(code, reason);
+  }
+
+  /** The underlying socket (escape hatch for advanced use). */
+  get socket(): WebSocketLike {
+    return this.ws;
+  }
+
+  /** Current WebSocket readyState. */
+  get readyState(): number {
+    return this.ws.readyState;
+  }
+}
+
 /* ------------------------------------------------------------------------- *
  * Key introspection — GET /v1/me
  * ------------------------------------------------------------------------- */
@@ -1064,6 +1400,45 @@ export class PyAI {
     },
   };
 
+  // --- omni (agentic voice) ----------------------------------------------
+
+  omni = {
+    /**
+     * Mint an ephemeral, origin-locked Omni session token a browser can use to
+     * open ONE realtime session **directly** — the public/private split for
+     * realtime. **Call this from your server** with a secret key holding
+     * `omni:session`; never ship the secret key to a page. Hand the returned
+     * `token` to the browser, which connects with
+     * `new WebSocket(session.url, ["pyai-key." + session.token])`. The token
+     * expires after `ttlSeconds` (default 60s) and only works from
+     * `allowedOrigins`. Scope `omni:session`.
+     */
+    createSession: (params: OmniSessionParams): Promise<OmniSession> =>
+      this.postJson("/v1/omni/sessions", {
+        allowed_origins: params.allowedOrigins,
+        ...(params.ttlSeconds !== undefined ? { ttl_seconds: params.ttlSeconds } : {}),
+        ...(params.sessionLabel !== undefined ? { session_label: params.sessionLabel } : {}),
+      }),
+
+    /**
+     * Open a live Omni agentic-voice session over `/v1/omni`. Returns an
+     * {@link OmniConnection} that handles the wire protocol's frame-key
+     * asymmetry for you — it sends `type`-keyed control frames (`configure`,
+     * `dtmf`) and parses `event`-keyed server frames — so you can't trip the #1
+     * Omni integration bug. Omni is zero-state: nothing to create first; the
+     * agent's behavior travels in the `configure` frame. Pass `token` (from
+     * `createSession`) to connect from a browser without the secret key.
+     */
+    connect: (opts: OmniConnectOptions = {}): OmniConnection => {
+      const query: Record<string, string> = { ...(opts.query ?? {}) };
+      if (opts.format) query.format = opts.format;
+      if (opts.rate) query.rate = String(opts.rate);
+      const url = this.realtimeURL({ product: "omni", sessionLabel: opts.sessionLabel, query });
+      const sub = opts.token ? `pyai-key.${opts.token}` : this.realtimeSubprotocol();
+      return new OmniConnection(url, sub, opts);
+    },
+  };
+
   // --- realtime (WebSocket) ----------------------------------------------
 
   /** Build the realtime WebSocket URL for the chosen product. */
@@ -1071,10 +1446,12 @@ export class PyAI {
     const wsBase = this.baseURL.replace(/^http/, "ws");
     const q = new URLSearchParams(opts.query ?? {});
     if ((opts.product ?? "omni") === "omni") {
-      // Omni's native realtime surface is /v1/omni. agentId is an opaque label
-      // authorized by the key's org. format/rate are load-bearing on the
-      // connect URL, so default to browser-grade PCM16/24kHz.
-      if (opts.agentId) q.set("agent_id", opts.agentId);
+      // Omni's native realtime surface is /v1/omni. The session is authorized by
+      // the key's org (zero-state) — sessionLabel is an optional opaque tag.
+      // format/rate are load-bearing on the connect URL, so default to
+      // browser-grade PCM16/24kHz.
+      if (opts.sessionLabel) q.set("session_label", opts.sessionLabel);
+      else if (opts.agentId) q.set("agent_id", opts.agentId); // deprecated alias
       if (!q.has("format")) q.set("format", "pcm16");
       if (!q.has("rate")) q.set("rate", "24000");
       const qs = q.toString();
@@ -1098,6 +1475,8 @@ export class PyAI {
     if (opts.sampleRate !== undefined) q.set("sample_rate", String(opts.sampleRate));
     if (opts.encoding) q.set("encoding", opts.encoding);
     if (opts.interimResults !== undefined) q.set("interim_results", String(opts.interimResults));
+    if (opts.numerals !== undefined) q.set("numerals", String(opts.numerals));
+    if (opts.endpointingMs !== undefined) q.set("endpointing_ms", String(opts.endpointingMs));
     const qs = q.toString();
     return `${wsBase}/v1/audio/transcriptions/stream${qs ? `?${qs}` : ""}`;
   }