@pyai/sdk 0.2.0 → 0.2.2

package/src/index.ts

@@ -1,10 +1,9 @@
 /**
- * @pyai/sdk — official TypeScript/JavaScript client for the PyAI API.
+ * @pyai/sdk, official TypeScript/JavaScript client for the PyAI API.
  *
  * Thin, dependency-free wrapper over the public OpenAI-compatible surface at
  * https://api.pyai.com (contract: https://api.pyai.com/openapi.json). Runs in
- * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque —
- * never parsed.
+ * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque, * never parsed.
  */
 
 export interface PyAIOptions {
@@ -61,7 +60,7 @@ export interface TranscriptionJob {
 
 /**
  * Output container/codec for `audio.speech`. This is the **exact** set the
- * server accepts on `POST /v1/audio/speech` — any other value is rejected with
+ * server accepts on `POST /v1/audio/speech`, any other value is rejected with
  * `400 unsupported_format`. The default (when `response_format` is omitted) is
  * `mp3`. Omit `sample_rate` for the engine's native 24 kHz (`g711_*` is always
  * 8 kHz).
@@ -96,20 +95,20 @@ export interface SpeechParams {
   model?: string;
   /**
    * Output container/codec, resampled+encoded server-side. One of
-   * {@link SpeechFormat} — anything else is a `400 unsupported_format`. Omit for
+   * {@link SpeechFormat}, anything else is a `400 unsupported_format`. Omit for
    * the default of `mp3`.
    *
-   * `g711_ulaw`/`g711_alaw` return raw 8 kHz mono G.711 — the bytes Twilio/SIP
+   * `g711_ulaw`/`g711_alaw` return raw 8 kHz mono G.711, the bytes Twilio/SIP
    * media streams expect, so you can hand the response straight to a telephony
    * frame without a client-side resampler or μ-law encoder. `sample_rate` is
    * forced to 8000 for those (omit it, or set exactly 8000). `pcm` is raw,
    * headerless int16 LE mono at `sample_rate`. `mp3`/`opus` are buffered (not
-   * chunk-streamed) — use them with `speech`, not `speechStream`.
+   * chunk-streamed), use them with `speech`, not `speechStream`.
    */
   response_format?: SpeechFormat;
   /**
    * Output sample rate in Hz. One of {@link SpeechSampleRate}
-   * (8000/16000/24000/48000) — anything else is a `400`. Omit for the engine's
+   * (8000/16000/24000/48000), anything else is a `400`. Omit for the engine's
    * native 24 kHz; `g711_*` is always 8000 (forced). Set `8000`/`16000` for
    * telephony pipelines, most often with `response_format: "pcm"`.
    */
@@ -122,8 +121,7 @@ export interface SpeechParams {
    */
   seed?: number;
   /**
-   * Sampling temperature (lower = more deterministic). Forward-compatible —
-   * honored once the engine supports it, otherwise ignored.
+   * Sampling temperature (lower = more deterministic). Forward-compatible, * honored once the engine supports it, otherwise ignored.
    */
   temperature?: number;
 }
@@ -139,16 +137,57 @@ 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
+ * 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
  * `as const` objects (not TS `enum`s) so the source still runs directly under
  * Node's type-stripping and stays tree-shakeable.
@@ -164,6 +203,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;
@@ -184,7 +225,7 @@ export type WSCloseCode = (typeof WSCloseCode)[keyof typeof WSCloseCode];
 
 /**
  * Stable, machine-readable error `code`s (the documented contract). Branch on
- * these. The set is treated as open — `PyAIError.code` stays `string` — so a
+ * these. The set is treated as open, `PyAIError.code` stays `string`, so a
  * new server code never breaks the build, but the known ones are named here.
  */
 export const ErrorCode = {
@@ -239,6 +280,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,10 +303,10 @@ 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
+ * Minimal structural WebSocket, matches both the browser/Node global
  * `WebSocket` and the `ws` package, and lets tests inject a mock.
  */
 export interface WebSocketLike {
@@ -275,12 +332,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 +366,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 +399,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,11 +437,14 @@ 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;
       default:
-        // Unknown/forward-compatible frame — ignore.
+        // Unknown/forward-compatible frame, ignore.
         break;
     }
   }
@@ -389,8 +475,448 @@ export class HearStream {
   }
 }
 
+/**
+ * A live AMD (answering-machine-detection) stream. The wire is Twilio's Media
+ * Streams protocol, so if you're already on Twilio the usual path is one line of
+ * TwiML pointing `<Stream url="wss://api.pyai.com/v1/amd/stream">` at PyAI, no
+ * SDK needed. This helper is for server-side clients that fork the media
+ * themselves: send Twilio `start`/`media`/`stop` frames with {@link AmdStream.send}
+ * (or raw μ-law audio with {@link AmdStream.sendAudio}) and receive the `amd`
+ * decision via `onDecision`. Construct via `pyai.amd.stream()`.
+ */
+export class AmdStream {
+  private readonly ws: WebSocketLike;
+  private readonly opts: AmdStreamOptions;
+  private closed = false;
+
+  constructor(url: string, subprotocol: string, opts: AmdStreamOptions) {
+    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 amd.stream()",
+      );
+    }
+    this.ws = new WS(url, [subprotocol]);
+    this.ws.onopen = () => 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 {
+    if (typeof data !== "string") return; // AMD decisions are JSON text frames
+    let frame: Record<string, unknown>;
+    try {
+      frame = JSON.parse(data) as Record<string, unknown>;
+    } catch {
+      this.opts.onError?.(new Error(`Unparseable AMD frame: ${data.slice(0, 120)}`));
+      return;
+    }
+    if (frame.event === "amd") this.opts.onDecision?.(frame as AmdDecisionEvent);
+    this.opts.onMessage?.(frame);
+  }
+
+  /** Send a Twilio Media Streams control/media frame (JSON) or a raw string. */
+  send(frame: string | Record<string, unknown>): void {
+    this.ws.send(typeof frame === "string" ? frame : JSON.stringify(frame));
+  }
+
+  /** Send a raw audio chunk (G.711 μ-law 8 kHz for the Twilio-native path). */
+  sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void {
+    this.ws.send(chunk);
+  }
+
+  /** Close the socket. */
+  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;
+  }
+}
+
+/* ------------------------------------------------------------------------- *
+ * 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",
+  /** Engine requests a client-loop tool invocation. */
+  ToolCall: "tool_call",
+  /** 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;
+
+/** Extract a byte view from a binary WS frame (Buffer / ArrayBuffer / typed
+ * array). Returns null for a Blob or unknown (can't be read synchronously). */
+function omniToBytes(data: unknown): Uint8Array | null {
+  if (data instanceof Uint8Array) return data; // also covers Node Buffer
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data)) {
+    const v = data as ArrayBufferView;
+    return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+  }
+  return null;
+}
+
+/** A 0x01-prefixed audio frame, the engine's client→server framing for caller
+ * PCM16 LE (see OMNI_PROTOCOL_V2.md §2). */
+function omniAudioFrame(pcm: Uint8Array): Uint8Array {
+  const out = new Uint8Array(pcm.length + 1);
+  out[0] = 0x01;
+  out.set(pcm, 1);
+  return out;
+}
+
+/** A 0x03-prefixed control frame, the engine's client→server framing for
+ * `configure`/`dtmf`/`tool_result` (see OMNI_PROTOCOL_V2.md §2/§3). */
+function omniControlFrame(obj: unknown): Uint8Array {
+  const json = new TextEncoder().encode(JSON.stringify(obj));
+  const out = new Uint8Array(json.length + 1);
+  out[0] = 0x03;
+  out.set(json, 1);
+  return out;
+}
+
+export interface OmniToolDef {
+  name: string;
+  description?: string;
+  parameters?: Record<string, unknown>;
+  /** When set, engine-POST mode. Omit for client-loop (default). */
+  endpoint?: string;
+}
+
+export interface OmniToolCallFrame {
+  type: "tool_call";
+  call_id: string;
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+/**
+ * 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`, or `model_tier` once the engine acks it) 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;
+  /**
+   * Session language, end to end (recognition, reasoning, voice). Also
+   * settable on the agent profile (`language` on `POST /v1/agents`), which
+   * applies automatically when connecting with `session_label={agent_id}`;
+   * an inline value here wins for the session. Default `en`. Fail-safe: an
+   * unknown/not-yet-enabled language falls back to `en` (the `configured`
+   * ack carries `language_active` + `language_fallback: true`), the call
+   * proceeds and bills as what was served. Per-language availability is
+   * staged, see the Language support reference.
+   */
+  language?: "en" | "fr" | "es" | "de" | "hi";
+  /** Function calling definitions (client-loop when `endpoint` is omitted). */
+  tools?: OmniToolDef[];
+  /** 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 when the engine requests a client-loop tool invocation. */
+  onToolCall?: (frame: OmniToolCallFrame) => 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;
+  /** Serializes async Blob reads in {@link sendAudio} so frames stay ordered. */
+  private blobTail: Promise<void> = Promise.resolve();
+
+  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 {
+    // Server → client binary frames are TYPE-TAGGED by their first byte:
+    // 0x01 = agent audio (PCM16) · 0x02 = transcript JSON · 0x03 = control JSON.
+    // (Treating every binary frame as audio, the old behavior, plays the
+    // 0x03/0x02 frames as a glitch and drops every event/transcript.)
+    if (typeof data !== "string") {
+      const bytes = omniToBytes(data);
+      if (!bytes) {
+        this.opts.onAudio?.(data as OmniAudioChunk); // Blob/unknown, best-effort
+        return;
+      }
+      const tag = bytes[0];
+      if (tag === 0x01) {
+        this.opts.onAudio?.(bytes.slice(1) as OmniAudioChunk); // copy → aligned PCM16
+        return;
+      }
+      if (tag === 0x02 || tag === 0x03) {
+        try {
+          const parsed = JSON.parse(new TextDecoder().decode(bytes.subarray(1))) as OmniServerFrame;
+          // The 0x02 tag is authoritative for transcript even if the JSON omits `event`.
+          this.dispatchFrame(tag === 0x02 ? { ...parsed, event: "transcript" } : parsed);
+        } catch {
+          this.opts.onError?.(new Error("Unparseable Omni binary frame"));
+        }
+        return;
+      }
+      this.opts.onAudio?.(data as OmniAudioChunk); // untagged, forward-compat as audio
+      return;
+    }
+    // Text frame (e.g. a server-side broker relay).
+    try {
+      this.dispatchFrame(JSON.parse(data) as OmniServerFrame);
+    } catch {
+      this.opts.onError?.(new Error(`Unparseable Omni frame: ${data.slice(0, 120)}`));
+    }
+  }
+
+  private dispatchFrame(frame: OmniServerFrame): void {
+    const raw = frame as unknown as { event?: unknown; type?: unknown };
+    const eventName =
+      typeof raw.event === "string"
+        ? raw.event
+        : typeof raw.type === "string"
+          ? raw.type
+          : "";
+    this.opts.onEvent?.({ ...frame, event: eventName });
+    switch (eventName) {
+      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.ToolCall:
+        this.opts.onToolCall?.(frame as unknown as OmniToolCallFrame);
+        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(omniControlFrame({ type: "configure", ...cfg }));
+  }
+
+  /**
+   * Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate) as a
+   * `0x01`-prefixed frame. The engine demuxes on the first byte and has no
+   * default branch, so an untagged chunk is dropped with no error.
+   */
+  sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void {
+    const bytes = omniToBytes(chunk);
+    if (bytes) {
+      this.ws.send(omniAudioFrame(bytes));
+      return;
+    }
+    // A Blob can only be read asynchronously; queue behind the previous read so
+    // frames still reach the engine in call order.
+    this.blobTail = this.blobTail
+      .then(async () => {
+        const buf = await (chunk as Blob).arrayBuffer();
+        this.ws.send(omniAudioFrame(new Uint8Array(buf)));
+      })
+      .catch((err) => this.opts.onError?.(err instanceof Error ? err : new Error(String(err))));
+  }
+
+  /** Send DTMF digits as a `{"type":"dtmf"}` control frame. */
+  sendDtmf(digits: string): void {
+    this.ws.send(omniControlFrame({ type: "dtmf", digits }));
+  }
+
+  /** Reply to a client-loop {@link OmniEvent.ToolCall}. */
+  toolResult(callId: string, payload: { result?: unknown; error?: string }): void {
+    this.ws.send(omniControlFrame({ type: "tool_result", call_id: callId, ...payload }));
+  }
+
+  /**
+   * 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(omniControlFrame(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
+ * Key introspection, GET /v1/me
  * ------------------------------------------------------------------------- */
 
 /** Shape of `GET /v1/me`. Fields are best-effort / forward-compatible. */
@@ -511,7 +1037,7 @@ export interface TraceBargeMetrics {
 
 /**
  * Known timeline-turn roles. Left open (see {@link TraceTimelineTurn.role}) so a
- * new server-side role never breaks the build — branch defensively.
+ * new server-side role never breaks the build, branch defensively.
  */
 export type TraceTimelineRole = "agent" | "caller" | "system" | "tool";
 
@@ -537,18 +1063,18 @@ export interface TraceTimelineTurn {
 
 /**
  * Aggregate per-call quality metrics (eval scorecard-v1). All optional and
- * forward-compatible — present once the engine emits them.
+ * forward-compatible, present once the engine emits them.
  */
 export interface QualityMetrics {
-  /** Word error rate vs. reference transcript, 0–1 (lower is better). */
+  /** Word error rate vs. reference transcript, 0-1 (lower is better). */
   wer?: number;
   /** Representative time-to-first-audio across turns, ms. */
   ttfb_ms?: number;
   /** 95th-percentile end-to-end turn latency, ms. */
   turn_p95_ms?: number;
-  /** Barge-in recovery rate, 0–1. */
+  /** Barge-in recovery rate, 0-1. */
   barge_recovery?: number;
-  /** Task-success score, 0–1. */
+  /** Task-success score, 0-1. */
   task_success?: number;
   /** Composite voice-agent quality index (engine-defined scale). */
   vaqi?: number;
@@ -682,6 +1208,103 @@ export interface RecapCallTriggerInput {
   crm_fields?: Record<string, unknown>;
 }
 
+// --- AMD (answering-machine detection) -----------------------------------
+
+/** PyAI's richer answered-by vocabulary (superset of Twilio's enum). */
+export type AmdAnsweredBy =
+  | "human"
+  | "voicemail"
+  | "live_voicemail"
+  | "screening" // iPhone / Google Call Screen
+  | "ivr"
+  | "human_gatekeeper"
+  | "sit_invalid" // dead / disconnected number
+  | "fax"
+  | "silence"
+  | "unknown";
+
+/** Twilio's `AnsweredBy` enum, echoed for drop-in migration parity. */
+export type AmdTwilioAnsweredBy =
+  | "human"
+  | "machine_start"
+  | "machine_end_beep"
+  | "machine_end_silence"
+  | "machine_end_other"
+  | "fax"
+  | "unknown";
+
+export interface AmdConfigInput {
+  /** Operating point on the ROC curve, [0,1]. Near 0 = human-safe (never hang up
+   * on a person); near 1 = fire `machine` fast. A per-call TwiML `<Parameter>`
+   * overrides this. */
+  aggressiveness?: number;
+  /** Signed POST target for `amd.call.completed` events (https). */
+  webhookUrl?: string | null;
+}
+
+export interface AmdConfig {
+  object?: "amd.config";
+  aggressiveness?: number;
+  webhook_url?: string | null;
+  updated_at?: number;
+}
+
+export interface AmdCallSummary {
+  object?: "amd.call";
+  call_id: string;
+  session_label?: string | null;
+  status?: "completed" | "failed";
+  answered_by?: AmdAnsweredBy;
+  /** Twilio-enum projection of `answered_by` for drop-in routing parity. */
+  answered_by_twilio?: string | null;
+  confidence?: number | null;
+  /** Latency from answer to decision, in ms. */
+  decision_ms?: number | null;
+  created_at?: number;
+}
+
+export interface AmdCall extends AmdCallSummary {
+  /** Human-readable evidence, e.g. "machine phrase: 'leave a message' @1.2s". */
+  reason?: string | null;
+  aggressiveness?: number | null;
+  started_at?: number | null;
+  meta?: Record<string, unknown> | null;
+  error?: string | null;
+}
+
+/** A mid-call AMD decision event pushed on the stream (and to the webhook). */
+export interface AmdDecisionEvent {
+  event?: "amd";
+  call_id?: string;
+  answered_by?: AmdAnsweredBy;
+  answered_by_twilio?: string | null;
+  confidence?: number | null;
+  decision_ms?: number | null;
+  reason?: string | null;
+  [k: string]: unknown;
+}
+
+export interface AmdStreamOptions {
+  /** Per-call operating point override (0-1), sent on the connect URL. */
+  aggressiveness?: number;
+  /** Opaque per-call tag, echoed back on the decision. */
+  sessionLabel?: string;
+  /** Extra query params merged onto the connect URL. */
+  query?: Record<string, string>;
+  /** Fired once the socket opens. */
+  onOpen?: () => void;
+  /** Fired when PyAI emits the `amd` decision event mid-call. */
+  onDecision?: (event: AmdDecisionEvent) => void;
+  /** Fired on any other JSON frame (forward-compatible). */
+  onMessage?: (frame: Record<string, unknown>) => void;
+  /** Fired on a transport-level error. */
+  onError?: (err: Error) => void;
+  /** Fired when the socket closes. */
+  onClose?: (code: number, reason: string) => void;
+  /** Injectable WebSocket constructor (defaults to the global). */
+  webSocket?: WebSocketCtor;
+}
+
 const RETRYABLE = new Set([429, 500, 502, 503, 504]);
 
 export class PyAI {
@@ -810,7 +1433,7 @@ export class PyAI {
       const res = await this.request("/v1/audio/speech", {
         method: "POST",
         headers: this.authHeaders({ "Content-Type": "application/json" }),
-        body: JSON.stringify({ model: "pyai-voice", ...params }),
+        body: JSON.stringify({ model: "pyai-voice", ...params, stream: true }),
       });
       if (!res.body) throw new PyAIError(res.status, "Response had no body to stream");
       return res.body as ReadableStream<Uint8Array>;
@@ -884,7 +1507,7 @@ export class PyAI {
 
   /**
    * Introspect the calling key: scopes, environment, and limits. Useful for a
-   * preflight/doctor check. (New route; older deployments may 404 — handle it.)
+   * preflight/doctor check. (New route; older deployments may 404, handle it.)
    */
   me = (): Promise<MeResponse> => this.getJson<MeResponse>("/v1/me");
 
@@ -988,7 +1611,7 @@ export class PyAI {
       },
     },
     findings: {
-      /** List Tier-2 (async semantic) findings — advisory, non-blocking. Scope `trace:read`. */
+      /** List Tier-2 (async semantic) findings, advisory, non-blocking. Scope `trace:read`. */
       list: (
         params: {
           checkId?: string;
@@ -1064,6 +1687,81 @@ export class PyAI {
     },
   };
 
+  // --- amd (answering-machine detection) ---------------------------------
+
+  amd = {
+    config: {
+      /** The org's AMD operating point + webhook. Scope `amd:configure`. */
+      get: (): Promise<AmdConfig> => this.getJson("/v1/amd/config"),
+      /** Set the account-default `aggressiveness` (0-1) and webhook. Scope `amd:configure`. */
+      set: (input: AmdConfigInput): Promise<AmdConfig> =>
+        this.postJson("/v1/amd/config", {
+          ...(input.aggressiveness !== undefined ? { aggressiveness: input.aggressiveness } : {}),
+          ...(input.webhookUrl !== undefined ? { webhook_url: input.webhookUrl } : {}),
+        }),
+    },
+    calls: {
+      /** Recent AMD decisions, newest first. Scope `amd:read`. */
+      list: (params: { limit?: number; cursor?: string; sessionLabel?: string } = {}): Promise<ListResponse<AmdCallSummary>> => {
+        const q = new URLSearchParams();
+        if (params.limit !== undefined) q.set("limit", String(params.limit));
+        if (params.cursor) q.set("cursor", params.cursor);
+        if (params.sessionLabel) q.set("session_label", params.sessionLabel);
+        const qs = q.toString();
+        return this.getJson(`/v1/amd/calls${qs ? `?${qs}` : ""}`);
+      },
+      /** The full decision (answered_by, reason, …) for one call. Scope `amd:read`. */
+      get: (callId: string): Promise<AmdCall> =>
+        this.getJson(`/v1/amd/calls/${encodeURIComponent(callId)}`),
+    },
+    /**
+     * Open a live AMD stream over `/v1/amd/stream` (Twilio Media Streams
+     * protocol). Server-side helper for forking media yourself; the common
+     * Twilio path is one line of TwiML, no SDK. Scope `amd:detect`.
+     */
+    stream: (opts: AmdStreamOptions = {}): AmdStream =>
+      new AmdStream(this.amdStreamURL(opts), this.realtimeSubprotocol(), opts),
+  };
+
+  // --- 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 +1769,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,10 +1798,22 @@ 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}` : ""}`;
   }
 
+  /** Build the AMD detection WebSocket URL (`/v1/amd/stream`). */
+  amdStreamURL(opts: AmdStreamOptions = {}): string {
+    const wsBase = this.baseURL.replace(/^http/, "ws");
+    const q = new URLSearchParams(opts.query ?? {});
+    if (opts.aggressiveness !== undefined) q.set("aggressiveness", String(opts.aggressiveness));
+    if (opts.sessionLabel) q.set("session_label", opts.sessionLabel);
+    const qs = q.toString();
+    return `${wsBase}/v1/amd/stream${qs ? `?${qs}` : ""}`;
+  }
+
   /**
    * Open a realtime WebSocket. Uses the global WebSocket (browser, Node 22+).
    * The key travels as a subprotocol so it works from the browser without