@pyai/sdk 0.1.2 → 0.2.1

package/src/index.ts

@@ -59,18 +59,73 @@ export interface TranscriptionJob {
   error?: string;
 }
 
+/**
+ * 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
+ * `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).
+ *
+ * | format | rates (Hz) | Content-Type |
+ * |---|---|---|
+ * | `mp3` (default) | 8000/16000/24000/48000 | `audio/mpeg` |
+ * | `wav` | 8000/16000/24000/48000 | `audio/wav` |
+ * | `opus` | 8000/16000/24000/48000 | `audio/ogg` |
+ * | `aac` | 8000/16000/24000/48000 | `audio/aac` |
+ * | `flac` | 8000/16000/24000/48000 | `audio/flac` |
+ * | `pcm` | 8000/16000/24000/48000 | `audio/pcm` (raw int16 LE mono, no header) |
+ * | `g711_ulaw` | 8000 (forced) | `audio/basic` |
+ * | `g711_alaw` | 8000 (forced) | `audio/basic` |
+ */
+export type SpeechFormat = "wav" | "mp3" | "opus" | "aac" | "flac" | "pcm" | "g711_ulaw" | "g711_alaw";
+
+/**
+ * The runtime list of accepted `audio.speech` formats (mirrors {@link SpeechFormat}),
+ * for building dropdowns / validating input before a request. Branch on the
+ * named values; the order matches the contract doc.
+ */
+export const SPEECH_FORMATS = ["wav", "mp3", "opus", "aac", "flac", "pcm", "g711_ulaw", "g711_alaw"] as const;
+
+/** Sample rates (Hz) the server accepts for `audio.speech` (`g711_*` is always 8 kHz). */
+export const SPEECH_SAMPLE_RATES = [8000, 16000, 24000, 48000] as const;
+export type SpeechSampleRate = (typeof SPEECH_SAMPLE_RATES)[number];
+
 export interface SpeechParams {
   input: string;
   voice?: string;
   model?: string;
-  response_format?: "wav" | "mp3" | "opus" | "aac" | "flac" | "pcm";
   /**
-   * Output sample rate in Hz (8000-48000). Omit for the native 24 kHz. Most
-   * useful with `response_format: "pcm"` (raw 16-bit mono samples), e.g. set
-   * `8000`/`16000` for telephony pipelines.
+   * Output container/codec, resampled+encoded server-side. One of
+   * {@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
+   * 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`.
    */
-  sample_rate?: number;
+  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
+   * native 24 kHz; `g711_*` is always 8000 (forced). Set `8000`/`16000` for
+   * telephony pipelines, most often with `response_format: "pcm"`.
+   */
+  sample_rate?: SpeechSampleRate;
   speed?: number;
+  /**
+   * Deterministic sampling seed for reproducible eval runs. Forward-compatible:
+   * honored once the engine supports it (otherwise ignored server-side), so it's
+   * always safe to send.
+   */
+  seed?: number;
+  /**
+   * Sampling temperature (lower = more deterministic). Forward-compatible —
+   * honored once the engine supports it, otherwise ignored.
+   */
+  temperature?: number;
 }
 
 export interface CreateJobParams {
@@ -84,14 +139,885 @@ 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
+ * `as const` objects (not TS `enum`s) so the source still runs directly under
+ * Node's type-stripping and stays tree-shakeable.
+ * ------------------------------------------------------------------------- */
+
+/** Frame `type`s emitted by the Hear streaming-STT WebSocket. */
+export const HearFrameType = {
+  /** Eager live hypothesis for the current utterance. */
+  Partial: "partial",
+  /** Partial whose prefix has stabilized (won't be revised). */
+  PartialStable: "partial_stable",
+  /** Stable transcript at end-of-utterance (endpoint or commit). */
+  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;
+export type HearFrameType = (typeof HearFrameType)[keyof typeof HearFrameType];
+
+/** WebSocket close codes used across the PyAI realtime/streaming surfaces. */
+export const WSCloseCode = {
+  /** Normal closure. */
+  Normal: 1000,
+  /** Auth/policy: bad key, missing scope, or revoked token. */
+  PolicyViolation: 1008,
+  /** Engine/internal error. */
+  InternalError: 1011,
+  /** Over the concurrency cap (PyAI-specific; mirrors HTTP 429). */
+  OverCapacity: 4429,
+} as const;
+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
+ * new server code never breaks the build, but the known ones are named here.
+ */
+export const ErrorCode = {
+  Unauthorized: "unauthorized",
+  Forbidden: "forbidden",
+  OriginNotAllowed: "origin_not_allowed",
+  InvalidAgentId: "invalid_agent_id",
+  CreditExhausted: "credit_exhausted",
+  KeyBudgetExceeded: "key_budget_exceeded",
+  InsufficientQuota: "insufficient_quota",
+  RateLimitExceeded: "rate_limit_exceeded",
+  ConcurrencyLimitExceeded: "concurrency_limit_exceeded",
+  DailyCapExceeded: "daily_cap_exceeded",
+  IdempotencyConflict: "idempotency_conflict",
+  NotFound: "not_found",
+  NumberInUse: "number_in_use",
+} as const;
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+/* ------------------------------------------------------------------------- *
+ * Hear streaming STT (and Cue grounding)
+ * ------------------------------------------------------------------------- */
+
+/** A top-3 knowledge-base passage attached to Cue (grounded) finals. */
+export interface HearGroundingPassage {
+  content: string;
+  score: number;
+}
+
+/** Live hypothesis frame (`partial` / `partial_stable`). */
+export interface HearPartialFrame {
+  type: "partial" | "partial_stable";
+  text: string;
+  /** Prefix that has stabilized (won't change). */
+  stable_text?: string;
+  /** The still-changing tail. */
+  active_text?: string;
+  utterance_id: string;
+  /** Audio-timeline position of the hypothesis, ms. */
+  t_ms: number;
+}
+
+/** Finalized-utterance frame (`speech_final` / `final`). */
+export interface HearFinalFrame {
+  type: "speech_final" | "final";
+  text: string;
+  utterance_id: string;
+  t_ms: number;
+  /** Active-speech length of the utterance (the billed signal), ms. */
+  audio_ms: number;
+  /** 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 | HearUsageFrame | HearErrorFrame;
+
+/**
+ * Minimal structural WebSocket — matches both the browser/Node global
+ * `WebSocket` and the `ws` package, and lets tests inject a mock.
+ */
+export interface WebSocketLike {
+  send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+  close(code?: number, reason?: string): void;
+  readonly readyState: number;
+  onopen: ((ev: unknown) => void) | null;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+  onclose: ((ev: { code: number; reason: string }) => void) | null;
+}
+
+export type WebSocketCtor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+
+export interface HearStreamOptions {
+  /** Streaming STT model. Server default `pyai-hear`. */
+  model?: string;
+  /** ISO-639-1 hint, e.g. "en". */
+  language?: string;
+  /** Input PCM sample rate in Hz. Default 16000 server-side. */
+  sampleRate?: number;
+  /** Audio frame encoding. Default "pcm16". */
+  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). */
+  onOpen?: () => void;
+  /** Fired on `partial` / `partial_stable`. */
+  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`). */
+  onClose?: (code: number, reason: string) => void;
+  /** Injectable WebSocket constructor (defaults to the global). */
+  webSocket?: WebSocketCtor;
+}
+
+/**
+ * A live Hear streaming-STT session. Hides the frame protocol: stream audio
+ * with {@link HearStream.sendAudio}, get `onPartial`/`onFinal`/`onError`
+ * callbacks, force-finalize with {@link HearStream.commit}, and flush+close
+ * with {@link HearStream.close}. Construct via `pyai.audio.transcriptions.stream()`.
+ */
+export class HearStream {
+  private readonly ws: WebSocketLike;
+  private readonly opts: HearStreamOptions;
+  private closed = false;
+
+  constructor(url: string, subprotocol: string, opts: HearStreamOptions) {
+    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 transcriptions.stream()",
+      );
+    }
+    this.ws = new WS(url, [subprotocol]);
+    this.ws.onopen = () => {
+      if (opts.grounding) {
+        try {
+          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 */
+        }
+      }
+      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 {
+    // Hear emits JSON text frames; ignore any unexpected binary.
+    if (typeof data !== "string") return;
+    let frame: HearFrame;
+    try {
+      frame = JSON.parse(data) as HearFrame;
+    } catch {
+      this.opts.onError?.(new Error(`Unparseable Hear frame: ${data.slice(0, 120)}`));
+      return;
+    }
+    switch (frame.type) {
+      case HearFrameType.Partial:
+      case HearFrameType.PartialStable:
+        this.opts.onPartial?.(frame);
+        break;
+      case HearFrameType.SpeechFinal:
+      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.
+        break;
+    }
+  }
+
+  /** Send a chunk of audio (PCM16 or opus per `encoding`). */
+  sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void {
+    this.ws.send(chunk);
+  }
+
+  /** Force-finalize the current utterance (e.g. on VAD end-of-turn). */
+  commit(): void {
+    this.ws.send(JSON.stringify({ type: "commit" }));
+  }
+
+  /** Close the socket; the server flushes a final for any buffered audio. */
+  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",
+  /** 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
+ * ------------------------------------------------------------------------- */
+
+/** Shape of `GET /v1/me`. Fields are best-effort / forward-compatible. */
+export interface MeResponse {
+  object?: string;
+  key_id?: string;
+  org_id?: string;
+  /** "live" | "test" (a.k.a. environment). */
+  environment?: string;
+  env?: string;
+  scopes?: string[];
+  limits?: Record<string, unknown>;
+  [k: string]: unknown;
+}
+
+/* ------------------------------------------------------------------------- *
+ * Telephony
+ * ------------------------------------------------------------------------- */
+
+export interface TelephonyCapabilities {
+  voice?: boolean;
+  sms?: boolean;
+}
+
+export interface TelephonyAvailableNumber {
+  object?: "telephony.available_number";
+  /** E.164. */
+  phone_number: string;
+  country?: string;
+  area_code?: string | null;
+  locality?: string | null;
+  region?: string | null;
+  capabilities?: TelephonyCapabilities;
+  monthly_cost_cents?: number;
+}
+
+export interface TelephonyNumber {
+  object?: "telephony.number";
+  id: string;
+  /** E.164. */
+  phone_number: string;
+  country?: string;
+  area_code?: string | null;
+  capabilities?: TelephonyCapabilities;
+  /** Agent that answers inbound calls to this number. */
+  agent_id?: string | null;
+  recording?: boolean;
+  monthly_cost_cents?: number;
+  status?: "active" | "released";
+  created_at?: number;
+  released_at?: number | null;
+}
+
+/* ------------------------------------------------------------------------- *
+ * Trace (compliance)
+ * ------------------------------------------------------------------------- */
+
+export type TraceVerdict = "PASS" | "WARN" | "FAIL";
+export type TraceSeverity = "low" | "medium" | "high" | "critical";
+
+export interface TraceInteraction {
+  object?: "trace.interaction";
+  /** call_id */
+  id: string;
+  agent_id?: string | null;
+  product?: string | null;
+  verdict: TraceVerdict;
+  findings?: number;
+  blocked_turns?: number;
+  modified_turns?: number;
+  packs_enforced?: string;
+  scored_at?: number;
+}
+
+export interface TraceFinding {
+  object?: "trace.finding";
+  id: string;
+  /** call_id */
+  interaction_id: string;
+  agent_id?: string | null;
+  check_id: string;
+  severity: TraceSeverity;
+  verdict?: string;
+  confidence?: number;
+  action?: "flag" | "preempt_next" | "escalate";
+  speaker?: "agent" | "caller" | "any" | null;
+  reason?: string;
+  preempt_instruction?: string | null;
+  at_t?: number | null;
+  tier?: number;
+}
+
+/* --- per-call eval scorecard (scorecard-v1) -----------------------------
+ * Forward-compatible operational timeline + quality metrics for a single call,
+ * surfaced on the interaction detail. All fields are optional and present only
+ * once the engine emits them (see docs/PLATFORM_ASK_EVALS_ENGINE_2026-06-16.md),
+ * so existing callers keep working unchanged.
+ */
+
+/** A tool invocation recorded on a timeline turn. */
+export interface TraceToolCall {
+  name: string;
+  /** Arguments the agent passed (engine-shaped JSON). */
+  args?: unknown;
+  /** Tool result returned to the agent (engine-shaped JSON). */
+  result?: unknown;
+  /** Audio-timeline position of the call, ms. */
+  t_ms?: number;
+}
+
+/** Barge-in timing for a timeline turn. */
+export interface TraceBargeMetrics {
+  /** Time from caller speech onset to barge-in detection, ms. */
+  detect_ms?: number;
+  /** Whether the agent cleanly recovered after the barge-in. */
+  recovered?: boolean;
+}
+
+/**
+ * Known timeline-turn roles. Left open (see {@link TraceTimelineTurn.role}) so a
+ * new server-side role never breaks the build — branch defensively.
+ */
+export type TraceTimelineRole = "agent" | "caller" | "system" | "tool";
+
+/** One turn of a per-call operational timeline (eval scorecard-v1). */
+export interface TraceTimelineTurn {
+  /** Monotonic turn index within the call. */
+  seq: number;
+  /** Audio-timeline position of the turn, ms. */
+  t_ms: number;
+  /** Who spoke/acted this turn. Open-ended for forward-compat. */
+  role: TraceTimelineRole | (string & {});
+  /** Transcript/text for the turn, when available. */
+  text?: string;
+  /** Time-to-first-audio for the turn (latency scoring), ms. */
+  ttfb_ms?: number;
+  /** Turn-detection (endpointing) latency, ms. */
+  endpointing_ms?: number;
+  /** Barge-in detect/recovery timing for the turn. */
+  barge?: TraceBargeMetrics;
+  /** Tool calls made during the turn (tool-use scoring). */
+  tool_calls?: TraceToolCall[];
+}
+
+/**
+ * Aggregate per-call quality metrics (eval scorecard-v1). All optional and
+ * forward-compatible — present once the engine emits them.
+ */
+export interface QualityMetrics {
+  /** 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_recovery?: number;
+  /** Task-success score, 0–1. */
+  task_success?: number;
+  /** Composite voice-agent quality index (engine-defined scale). */
+  vaqi?: number;
+  [k: string]: unknown;
+}
+
+export interface TraceInteractionDetail extends TraceInteraction {
+  /** Hash-chain link proving the record is unaltered. */
+  audit_hash?: string;
+  scorecard?: Record<string, unknown>;
+  tier2_findings?: TraceFinding[];
+  /**
+   * Scorecard schema version, e.g. `"trace-scorecard-v1"`. Present once the
+   * engine emits the eval block below.
+   */
+  scorecard_version?: string;
+  /**
+   * Per-call operational timeline. Forward-compatible: empty/undefined until
+   * the engine emits per-turn timing (Ask 1 of the evals engine plan).
+   */
+  timeline?: TraceTimelineTurn[];
+  /** Aggregate per-call quality metrics. Forward-compatible (see above). */
+  quality_metrics?: QualityMetrics;
+}
+
+export interface TraceViolation {
+  object?: "trace.violation";
+  id: string;
+  /** call_id */
+  interaction_id: string;
+  agent_id?: string | null;
+  rule_id: string;
+  pack_id?: string | null;
+  severity: TraceSeverity;
+  action_taken?: "pass" | "flag" | "modify" | "block";
+  citation?: string;
+  reason?: string;
+  at_t?: number | null;
+}
+
+export interface TraceConfigInput {
+  agent_id?: string;
+  enabled?: boolean;
+  channels?: Array<"voice" | "text">;
+  /** Map of pack_id → { enabled, version }. */
+  rule_packs?: Record<string, { enabled?: boolean; version?: string | null }>;
+  guardrails?: Record<string, unknown>;
+  [k: string]: unknown;
+}
+
+export interface TraceConfig {
+  object?: "trace.config";
+  agent_id?: string | null;
+  enabled?: boolean;
+  mode?: "warn" | "modify" | "block" | "human_handoff";
+  etag?: string;
+  updated_at?: number;
+  config?: TraceConfigInput;
+}
+
+export interface TraceRulePackSpec {
+  pack_id: string;
+  version: string;
+  jurisdiction?: string;
+  legal_status?: string;
+  rules: Array<Record<string, unknown>>;
+}
+
+export interface TraceRulePack {
+  object?: "trace.rule_pack";
+  id?: string;
+  pack_id: string;
+  version?: string;
+  builtin?: boolean;
+  jurisdiction?: string | null;
+  legal_status?: string | null;
+  etag?: string;
+  status?: "active" | "deprecated";
+  created_at?: number;
+  /** The authored DSL (only on the single-pack GET). */
+  spec?: Record<string, unknown>;
+}
+
+export interface TraceExposure {
+  object?: "trace.exposure";
+  window_days?: number;
+  interactions_scanned?: number;
+  with_a_gap?: number;
+  gap_rate?: number;
+  by_rule?: Array<{ rule_id: string; pack_id?: string | null; count: number; rate: number }>;
+  by_verdict?: { PASS?: number; WARN?: number; FAIL?: number };
+  top_exposure?: string | null;
+}
+
+export interface RecapConfigInput {
+  enabled?: boolean;
+  webhook_url?: string | null;
+  default_pack_id?: string;
+}
+
+export interface RecapConfig {
+  object?: "recap.config";
+  enabled?: boolean;
+  webhook_url?: string | null;
+  default_pack_id?: string;
+  updated_at?: number;
+}
+
+export interface RecapCallSummary {
+  object?: "recap.call";
+  call_id: string;
+  pack_id?: string;
+  status?: "pending" | "processing" | "complete" | "failed";
+  call_duration_s?: number | null;
+  created_at?: number;
+  completed_at?: number | null;
+}
+
+export interface RecapCall extends RecapCallSummary {
+  record?: unknown;
+  error?: string | null;
+  crm_write_status?: string | null;
+}
+
+export interface RecapCallTriggerInput {
+  utterances: Array<{ speaker_role?: "agent" | "customer"; text: string; offset_s?: number; duration_s?: number }>;
+  pack_id?: string;
+  call_duration_s?: number;
+  call_direction?: "inbound" | "outbound";
+  customer_name?: string;
+  crm_fields?: Record<string, unknown>;
+}
+
 const RETRYABLE = new Set([429, 500, 502, 503, 504]);
 
 export class PyAI {
@@ -155,6 +1081,28 @@ export class PyAI {
     return (await res.json()) as T;
   }
 
+  private async postJson<T>(path: string, payload: unknown, extraHeaders: Record<string, string> = {}): Promise<T> {
+    const res = await this.request(path, {
+      method: "POST",
+      headers: this.authHeaders({ "Content-Type": "application/json", ...extraHeaders }),
+      body: JSON.stringify(payload),
+    });
+    return (await res.json()) as T;
+  }
+
+  private async putJson<T>(path: string, payload: unknown): Promise<T> {
+    const res = await this.request(path, {
+      method: "PUT",
+      headers: this.authHeaders({ "Content-Type": "application/json" }),
+      body: JSON.stringify(payload),
+    });
+    return (await res.json()) as T;
+  }
+
+  private deleteReq(path: string): Promise<Response> {
+    return this.request(path, { method: "DELETE", headers: this.authHeaders() });
+  }
+
   // --- models -------------------------------------------------------------
 
   models = {
@@ -209,10 +1157,23 @@ export class PyAI {
         file: Blob;
         filename?: string;
         model?: string;
+        language?: string;
+        response_format?: "json" | "text" | "verbose_json";
+        /**
+         * Deterministic seed for reproducible eval runs. Forward-compatible:
+         * honored once the engine supports it, otherwise ignored.
+         */
+        seed?: number;
+        /** Sampling temperature. Forward-compatible (honored when supported). */
+        temperature?: number;
       }): Promise<{ text: string; [k: string]: unknown }> => {
         const form = new FormData();
         form.set("file", params.file, params.filename ?? "audio.wav");
         form.set("model", params.model ?? "pyai-hear");
+        if (params.language) form.set("language", params.language);
+        if (params.response_format) form.set("response_format", params.response_format);
+        if (params.seed !== undefined) form.set("seed", String(params.seed));
+        if (params.temperature !== undefined) form.set("temperature", String(params.temperature));
         const res = await this.request("/v1/audio/transcriptions", {
           method: "POST",
           headers: this.authHeaders(),
@@ -220,6 +1181,14 @@ export class PyAI {
         });
         return (await res.json()) as { text: string };
       },
+      /**
+       * Open a live streaming-STT WebSocket (Hear). Hides the frame protocol
+       * behind `onPartial`/`onFinal`/`onError`; stream audio with `sendAudio`,
+       * force-finalize with `commit()`, flush+close with `close()`. Set
+       * `grounding: true` for Cue (turn detection + KB context).
+       */
+      stream: (opts: HearStreamOptions = {}): HearStream =>
+        new HearStream(this.hearStreamURL(opts), this.realtimeSubprotocol(), opts),
     },
   };
 
@@ -247,6 +1216,229 @@ export class PyAI {
     },
   };
 
+  // --- key introspection --------------------------------------------------
+
+  /**
+   * Introspect the calling key: scopes, environment, and limits. Useful for a
+   * preflight/doctor check. (New route; older deployments may 404 — handle it.)
+   */
+  me = (): Promise<MeResponse> => this.getJson<MeResponse>("/v1/me");
+
+  // --- voice clones -------------------------------------------------------
+
+  clones = {
+    /** List the org's cloned voices. */
+    list: (): Promise<ListResponse<Voice>> => this.getJson("/v1/voice/clones"),
+    /** Enroll a custom voice from reference audio (>= ~10s). Scope `voice:clone`. */
+    create: async (params: { name: string; file: Blob; filename?: string }): Promise<Voice> => {
+      const form = new FormData();
+      form.set("name", params.name);
+      form.set("file", params.file, params.filename ?? "sample.wav");
+      const res = await this.request("/v1/voice/clones", { method: "POST", headers: this.authHeaders(), body: form });
+      return (await res.json()) as Voice;
+    },
+    /**
+     * Fetch a single cloned voice by id. The API exposes no GET-by-id for
+     * clones, so this filters `list()` client-side and throws a 404 `PyAIError`
+     * when the id isn't found.
+     */
+    get: async (id: string): Promise<Voice> => {
+      const { data } = await this.clones.list();
+      const match = data.find((v) => v.id === id);
+      if (!match) throw new PyAIError(404, `No cloned voice ${id}`, ErrorCode.NotFound);
+      return match;
+    },
+    /** Delete a cloned voice (tenant-isolated). Scope `voice:clone`. */
+    delete: async (id: string): Promise<void> => {
+      await this.deleteReq(`/v1/voice/clones/${encodeURIComponent(id)}`);
+    },
+  };
+
+  // --- telephony (managed numbers) ---------------------------------------
+
+  telephony = {
+    numbers: {
+      /** Search the carrier's available US local numbers. */
+      available: (
+        params: { areaCode?: string; contains?: string; limit?: number } = {},
+      ): Promise<ListResponse<TelephonyAvailableNumber>> => {
+        const q = new URLSearchParams();
+        if (params.areaCode) q.set("area_code", params.areaCode);
+        if (params.contains) q.set("contains", params.contains);
+        if (params.limit !== undefined) q.set("limit", String(params.limit));
+        const qs = q.toString();
+        return this.getJson(`/v1/telephony/available${qs ? `?${qs}` : ""}`);
+      },
+      /** List the org's managed numbers (active only unless `includeReleased`). */
+      list: (params: { includeReleased?: boolean } = {}): Promise<ListResponse<TelephonyNumber>> => {
+        const qs = params.includeReleased ? "?include_released=true" : "";
+        return this.getJson(`/v1/telephony/numbers${qs}`);
+      },
+      /** Provision (buy) a specific available number, optionally bound to an agent. */
+      buy: (params: { phone_number: string; agent_id?: string | null }): Promise<TelephonyNumber> =>
+        this.postJson("/v1/telephony/numbers", params),
+      /** Route a number to an agent (`agentId: null` to unassign). */
+      assign: (id: string, agentId: string | null): Promise<TelephonyNumber> =>
+        this.postJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/assign`, { agent_id: agentId }),
+      /** Release a number back to the carrier (idempotent). */
+      release: async (id: string): Promise<TelephonyNumber> => {
+        const res = await this.deleteReq(`/v1/telephony/numbers/${encodeURIComponent(id)}`);
+        return (await res.json()) as TelephonyNumber;
+      },
+    },
+  };
+
+  // --- trace (compliance) -------------------------------------------------
+
+  trace = {
+    interactions: {
+      /** List scanned interactions (scorecards), newest first. Scope `trace:read`. */
+      list: (
+        params: { verdict?: TraceVerdict; agentId?: string; limit?: number; cursor?: string } = {},
+      ): Promise<ListResponse<TraceInteraction>> => {
+        const q = new URLSearchParams();
+        if (params.verdict) q.set("verdict", params.verdict);
+        if (params.agentId) q.set("agent_id", params.agentId);
+        if (params.limit !== undefined) q.set("limit", String(params.limit));
+        if (params.cursor) q.set("cursor", params.cursor);
+        const qs = q.toString();
+        return this.getJson(`/v1/trace/interactions${qs ? `?${qs}` : ""}`);
+      },
+      /** The full per-call evidence view (findings, redactions, audit hash). */
+      get: (id: string): Promise<TraceInteractionDetail> =>
+        this.getJson(`/v1/trace/interactions/${encodeURIComponent(id)}`),
+    },
+    violations: {
+      /** Drill-down of every fired Tier-0 rule across scorecards. Scope `trace:read`. */
+      list: (
+        params: { ruleId?: string; severity?: TraceSeverity; interactionId?: string; limit?: number; cursor?: string } = {},
+      ): Promise<ListResponse<TraceViolation>> => {
+        const q = new URLSearchParams();
+        if (params.ruleId) q.set("rule_id", params.ruleId);
+        if (params.severity) q.set("severity", params.severity);
+        if (params.interactionId) q.set("interaction_id", params.interactionId);
+        if (params.limit !== undefined) q.set("limit", String(params.limit));
+        if (params.cursor) q.set("cursor", params.cursor);
+        const qs = q.toString();
+        return this.getJson(`/v1/trace/violations${qs ? `?${qs}` : ""}`);
+      },
+    },
+    findings: {
+      /** List Tier-2 (async semantic) findings — advisory, non-blocking. Scope `trace:read`. */
+      list: (
+        params: {
+          checkId?: string;
+          action?: "flag" | "preempt_next" | "escalate";
+          severity?: TraceSeverity;
+          interactionId?: string;
+          limit?: number;
+          cursor?: string;
+        } = {},
+      ): Promise<ListResponse<TraceFinding>> => {
+        const q = new URLSearchParams();
+        if (params.checkId) q.set("check_id", params.checkId);
+        if (params.action) q.set("action", params.action);
+        if (params.severity) q.set("severity", params.severity);
+        if (params.interactionId) q.set("interaction_id", params.interactionId);
+        if (params.limit !== undefined) q.set("limit", String(params.limit));
+        if (params.cursor) q.set("cursor", params.cursor);
+        const qs = q.toString();
+        return this.getJson(`/v1/trace/findings${qs ? `?${qs}` : ""}`);
+      },
+    },
+    config: {
+      /** Read per-agent Trace config (omit `agentId` for the org default). Scope `trace:configure`. */
+      get: (agentId?: string): Promise<TraceConfig> =>
+        this.getJson(`/v1/trace/config${agentId ? `?agent_id=${encodeURIComponent(agentId)}` : ""}`),
+      /** Upsert per-agent Trace config. Scope `trace:configure`. */
+      set: (input: TraceConfigInput): Promise<TraceConfig> => this.putJson("/v1/trace/config", input),
+    },
+    rulePacks: {
+      /** List built-in + custom rule packs. Scope `trace:configure`. */
+      list: (): Promise<ListResponse<TraceRulePack>> => this.getJson("/v1/trace/rule-packs"),
+      /** Upload a custom rule pack (Trace DSL). Scope `trace:configure`. */
+      create: (spec: TraceRulePackSpec): Promise<TraceRulePack> => this.postJson("/v1/trace/rule-packs", spec),
+      /** Resolve a rule pack by id (latest active, or pin `version`). */
+      get: (id: string, version?: string): Promise<TraceRulePack> =>
+        this.getJson(`/v1/trace/rule-packs/${encodeURIComponent(id)}${version ? `?version=${encodeURIComponent(version)}` : ""}`),
+    },
+    /** Compliance exposure summary over a trailing window. Scope `trace:read`. */
+    exposure: (windowDays?: number): Promise<TraceExposure> =>
+      this.getJson(`/v1/trace/exposure${windowDays !== undefined ? `?window_days=${windowDays}` : ""}`),
+    /**
+     * Convenience: the per-call operational timeline (eval scorecard-v1). A thin
+     * wrapper over `interactions.get(id)` that returns the `timeline` array, or
+     * `[]` when the engine hasn't emitted one yet (forward-compatible). Scope
+     * `trace:read`.
+     */
+    callTimeline: async (id: string): Promise<TraceTimelineTurn[]> => {
+      const detail = await this.trace.interactions.get(id);
+      return detail.timeline ?? [];
+    },
+  };
+
+  // --- recap (conversation intelligence) --------------------------------
+
+  recap = {
+    config: {
+      get: (): Promise<RecapConfig> => this.getJson("/v1/recap/config"),
+      set: (input: RecapConfigInput): Promise<RecapConfig> => this.putJson("/v1/recap/config", input),
+    },
+    calls: {
+      list: (params: { limit?: number; cursor?: string; status?: string } = {}): Promise<ListResponse<RecapCallSummary>> => {
+        const q = new URLSearchParams();
+        if (params.limit !== undefined) q.set("limit", String(params.limit));
+        if (params.cursor) q.set("cursor", params.cursor);
+        if (params.status) q.set("status", params.status);
+        const qs = q.toString();
+        return this.getJson(`/v1/recap/calls${qs ? `?${qs}` : ""}`);
+      },
+      get: (callId: string): Promise<RecapCall> =>
+        this.getJson(`/v1/recap/calls/${encodeURIComponent(callId)}`),
+      trigger: (callId: string, input: RecapCallTriggerInput): Promise<RecapCallSummary> =>
+        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: 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. */
@@ -254,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();
@@ -272,6 +1466,21 @@ export class PyAI {
     return `pyai-key.${this.apiKey}`;
   }
 
+  /** Build the Hear streaming-STT WebSocket URL (`/v1/audio/transcriptions/stream`). */
+  hearStreamURL(opts: HearStreamOptions = {}): string {
+    const wsBase = this.baseURL.replace(/^http/, "ws");
+    const q = new URLSearchParams(opts.query ?? {});
+    if (opts.model) q.set("model", opts.model);
+    if (opts.language) q.set("language", opts.language);
+    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}` : ""}`;
+  }
+
   /**
    * Open a realtime WebSocket. Uses the global WebSocket (browser, Node 22+).
    * The key travels as a subprotocol so it works from the browser without