@pyai/sdk 0.2.3 → 0.4.0

package/src/index.ts

@@ -34,13 +34,35 @@ export class PyAIError extends Error {
 }
 
 export interface Voice {
+  /** Canonical catalog identifier returned by GET /v1/voices. */
+  voice_id: string;
+  /** SDK compatibility alias, always equal to voice_id. */
   id: string;
   name?: string;
   gender?: string;
   region?: string;
+  language?: string;
+  /** Customer-facing quality tier. */
+  tier?: "standard" | "natural";
+  /** Permanent convenience inputs accepted on the advertised surfaces. */
+  aliases?: string[];
+  /** Product surfaces on which this stock voice can be selected. */
+  available_on?: Array<"speak" | "omni">;
+  /** Accepted Speak delivery modes. Empty means the voice has no Speak surface. */
+  synthesis_modes?: Array<"streaming" | "async">;
+  /** Voice-specific amount on top of the selected product's base rate. */
+  pricing?: {
+    included_in_base_price: boolean;
+    additional_price_usd_per_minute: number;
+  };
   [k: string]: unknown;
 }
 
+function normalizeVoice(value: Record<string, unknown>): Voice {
+  const voiceId = String(value.voice_id ?? value.id ?? "");
+  return { ...value, voice_id: voiceId, id: voiceId } as Voice;
+}
+
 export interface ListResponse<T> {
   object: "list";
   data: T[];
@@ -62,13 +84,13 @@ 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
  * `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
+ * `wav`. 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` |
+ * | `wav` (default) | 8000/16000/24000/48000 | `audio/wav` |
+ * | `mp3` | 8000/16000/24000/48000 | `audio/mpeg` |
  * | `opus` | 8000/16000/24000/48000 | `audio/ogg` |
  * | `aac` | 8000/16000/24000/48000 | `audio/aac` |
  * | `flac` | 8000/16000/24000/48000 | `audio/flac` |
@@ -89,14 +111,24 @@ export const SPEECH_FORMATS = ["wav", "mp3", "opus", "aac", "flac", "pcm", "g711
 export const SPEECH_SAMPLE_RATES = [8000, 16000, 24000, 48000] as const;
 export type SpeechSampleRate = (typeof SPEECH_SAMPLE_RATES)[number];
 
+/** Canonical Speak model plus the intentional OpenAI drop-in aliases. */
+export type SpeakModel = "pyai-speak" | "tts-1" | "tts-1-hd";
+
 export interface SpeechParams {
   input: string;
   voice?: string;
-  model?: string;
+  model?: SpeakModel;
+  /**
+   * Delivery mode. The API defaults to true and every catalog voice accepts
+   * both values. Set false when you want one complete buffered body with a
+   * `Content-Length`. A voice whose serving fleet has no streaming lane is
+   * rendered buffered either way and says so with `x-pyai-stream: buffered`.
+   */
+  stream?: boolean;
   /**
    * Output container/codec, resampled+encoded server-side. One of
    * {@link SpeechFormat}, anything else is a `400 unsupported_format`. Omit for
-   * the default of `mp3`.
+   * the default of `wav`.
    *
    * `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
@@ -113,32 +145,91 @@ export interface SpeechParams {
    * telephony pipelines, most often with `response_format: "pcm"`.
    */
   sample_rate?: SpeechSampleRate;
+  /** Reserved; currently returns `400 unsupported_parameter` when provided. */
   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.
+   * Reserved; currently returns `400 unsupported_parameter` when provided.
    */
   seed?: number;
   /**
-   * Sampling temperature (lower = more deterministic). Forward-compatible, * honored once the engine supports it, otherwise ignored.
+   * Reserved; currently returns `400 unsupported_parameter` when provided.
    */
   temperature?: number;
 }
 
+function assertActiveSpeechParams(params: SpeechParams): void {
+  for (const field of ["speed", "seed", "temperature"] as const) {
+    if (params[field] !== undefined) {
+      throw new Error(`${field} is reserved but not active on Speak`);
+    }
+  }
+}
+
 export interface CreateJobParams {
   audio_url: string;
   model?: string;
   diarize?: boolean;
   channel?: boolean;
   numerals?: boolean;
+  smart_format?: boolean;
+  dictation?: boolean;
+  drop_fillers?: boolean;
+  /**
+   * Per-job names, brands, products, or distinctive terms. PyAI keeps up to
+   * five valid entries after trimming, deduplication, and common-word
+   * filtering.
+   */
+  vocabulary?: string[];
   output_formats?: Array<"json" | "srt" | "vtt">;
   webhook_url?: string;
+  call_id?: string;
+  pack_id?: string;
+  call_direction?: "inbound" | "outbound";
+  customer_name?: string;
+}
+
+export type HearVocabularyProfile = "batch" | "hear_stream";
+
+export interface HearVocabularyInput {
+  /** Organization-owned names, brands, products, or distinctive terms. */
+  terms: string[];
+  /** Stored terms remain inert unless a use case is selected here. */
+  enabledFor: HearVocabularyProfile[];
+}
+
+export interface HearVocabulary {
+  object: "hear.vocabulary";
+  /** Sanitized stored list, at most five terms. */
+  terms: string[];
+  /** Use cases that may add stored suggestions. */
+  enabled_for: HearVocabularyProfile[];
+  /** Unix milliseconds, or null before the first save. */
+  updated_at: number | null;
+}
+
+export interface AgentConfig {
+  name?: string;
+  persona_system_prompt?: string | null;
+  greeting?: string | null;
+  voice_id?: string | null;
+  language?: "en" | "fr" | "es" | "de" | "hi" | null;
+  /**
+   * Opt-in speech-recognition vocabulary. PyAI sanitizes and keeps at most
+   * five terms. An empty list or null turns it off.
+   */
+  vocabulary?: string[] | null;
+  [key: string]: unknown;
+}
+
+export interface Agent {
+  object: "agent";
+  agent_id: string;
+  name: string;
+  vocabulary: string[];
+  [key: string]: unknown;
 }
 
 export interface RealtimeOptions {
-  /** "omni" (agentic voice) or "flow" (legacy voice duplex). Default "omni". */
-  product?: "omni" | "flow";
   /**
    * 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
@@ -146,12 +237,10 @@ export interface RealtimeOptions {
    */
   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.
+   * Extra canonical query params (`format`, `rate`, or the intentional
+   * server-side `api_key` auth option). Retired connect aliases and model/token
+   * selectors are rejected.
    */
-  agentId?: string;
-  /** Extra query params (e.g. format, rate). */
   query?: Record<string, string>;
 }
 
@@ -195,6 +284,8 @@ export interface OmniSession {
 
 /** Frame `type`s emitted by the Hear streaming-STT WebSocket. */
 export const HearFrameType = {
+  /** Applied endpointing configuration and validation warnings. */
+  ConfigAck: "config_ack",
   /** Eager live hypothesis for the current utterance. */
   Partial: "partial",
   /** Partial whose prefix has stabilized (won't be revised). */
@@ -210,10 +301,16 @@ export const HearFrameType = {
 } as const;
 export type HearFrameType = (typeof HearFrameType)[keyof typeof HearFrameType];
 
-/** WebSocket close codes used across the PyAI realtime/streaming surfaces. */
+/**
+ * WebSocket close codes used across the PyAI realtime/streaming surfaces.
+ * Browser callers may initiate only Normal or values in 3000-4999; the
+ * standards-reserved values below are server close observations.
+ */
 export const WSCloseCode = {
   /** Normal closure. */
   Normal: 1000,
+  /** Browser-safe private application code for a malformed peer protocol frame. */
+  ProtocolViolation: 4002,
   /** Auth/policy: bad key, missing scope, or revoked token. */
   PolicyViolation: 1008,
   /** Engine/internal error. */
@@ -232,7 +329,7 @@ export const ErrorCode = {
   Unauthorized: "unauthorized",
   Forbidden: "forbidden",
   OriginNotAllowed: "origin_not_allowed",
-  InvalidAgentId: "invalid_agent_id",
+  InvalidSessionLabel: "invalid_session_label",
   CreditExhausted: "credit_exhausted",
   KeyBudgetExceeded: "key_budget_exceeded",
   InsufficientQuota: "insufficient_quota",
@@ -242,6 +339,7 @@ export const ErrorCode = {
   IdempotencyConflict: "idempotency_conflict",
   NotFound: "not_found",
   NumberInUse: "number_in_use",
+  UnsupportedToolTransport: "unsupported_tool_transport",
 } as const;
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 
@@ -255,6 +353,24 @@ export interface HearGroundingPassage {
   score: number;
 }
 
+/** One endpointing validation result echoed in a `config_ack` frame. */
+export interface HearConfigWarning {
+  field: string;
+  value: unknown;
+  effective?: number;
+  reason: "clamped_to_range" | "not_a_number" | "unknown_config_field" | (string & {});
+}
+
+/** Applied endpointing settings after connect-time or mid-session config. */
+export interface HearConfigAckFrame {
+  type: "config_ack";
+  endpointing_ms: number;
+  effective_floor_ms: number;
+  effective_ceiling_ms: number;
+  score_interval_ms: number;
+  warnings: HearConfigWarning[];
+}
+
 /** Live hypothesis frame (`partial` / `partial_stable`). */
 export interface HearPartialFrame {
   type: "partial" | "partial_stable";
@@ -269,6 +385,12 @@ export interface HearPartialFrame {
 }
 
 /** Finalized-utterance frame (`speech_final` / `final`). */
+export type HearEndpointReason =
+  | "peak_te_early"
+  | "silence_backstop"
+  | "commit"
+  | (string & {});
+
 export interface HearFinalFrame {
   type: "speech_final" | "final";
   text: string;
@@ -276,6 +398,8 @@ export interface HearFinalFrame {
   t_ms: number;
   /** Active-speech length of the utterance (the billed signal), ms. */
   audio_ms: number;
+  /** Why the utterance ended. Log this when tuning automatic endpointing. */
+  endpoint_reason: HearEndpointReason;
   /** Present only with Cue grounding enabled (top KB passages). */
   grounding?: HearGroundingPassage[];
 }
@@ -288,7 +412,7 @@ 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`). */
+  /** The billed meter (`hear.minutes` or `cue.minutes`). */
   meter: string;
   /** Summed active-speech audio billed for the session, in seconds. */
   audio_seconds: number;
@@ -303,7 +427,12 @@ export interface HearErrorFrame {
   message: string;
 }
 
-export type HearFrame = HearPartialFrame | HearFinalFrame | HearUsageFrame | HearErrorFrame;
+export type HearFrame =
+  | HearConfigAckFrame
+  | HearPartialFrame
+  | HearFinalFrame
+  | HearUsageFrame
+  | HearErrorFrame;
 
 /**
  * Minimal structural WebSocket, matches both the browser/Node global
@@ -319,36 +448,70 @@ export interface WebSocketLike {
   onclose: ((ev: { code: number; reason: string }) => void) | null;
 }
 
+/**
+ * The non-secret marker every PyAI realtime client offers ALONGSIDE its
+ * `pyai-key.<KEY>` credential token.
+ *
+ * A browser cannot set `Authorization` on a WebSocket, so the key rides in
+ * `Sec-WebSocket-Protocol`. RFC 6455 makes the server echo the subprotocol it
+ * SELECTS, so a server that selects the credential publishes the credential —
+ * which api.pyai.com did until 2026-09-07. The edge now echoes only this
+ * marker. Offering it is not optional for Node clients: `ws` throws
+ * "Server sent no subprotocol" when it offered subprotocols and the 101
+ * selected none, and RFC 6455 lets the server select only a value the client
+ * actually offered.
+ */
+export const REALTIME_SUBPROTOCOL_MARKER = "pyai.v1";
+
 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;
+  /** Omit or use auto for automatic detection; an explicit code pins recognition. */
+  language?: "auto" | "en" | "es" | "fr" | "de" | "hi" | "it" | "pt" | "nl";
   /** Input PCM sample rate in Hz. Default 16000 server-side. */
   sampleRate?: number;
   /** Audio frame encoding. Default "pcm16". */
-  encoding?: "pcm16" | "opus";
+  encoding?: "pcm16";
   /** 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.
+   * Tri-state number formatting on **final** transcripts. `true` forces digits,
+   * `false` keeps spoken form, omitted keeps the live engine default (ITN on).
+   * Never applied to interim partials. Independent of `smartFormat`.
    */
   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.
+   * Opt-in English punctuation and sentence capitalization on **final**
+   * transcripts only. Interim partials are never formatted. Default false.
+   */
+  smartFormat?: boolean;
+  /**
+   * Spoken punctuation commands (`period`, `comma`, `new paragraph`,
+   * `question mark`) on finals only. Separate from `smartFormat`. Off by default.
+   */
+  dictation?: boolean;
+  /**
+   * Strip `um` / `uh` / `umm` / `uhh` / `er` on finals. Off by default.
+   * Do not enable on legal or compliance audio by default.
+   */
+  dropFillers?: boolean;
+  /**
+   * Per-session names, brands, products, or other distinctive terms. PyAI
+   * sanitizes up to five effective terms. Request terms come first, then stored
+   * `hear_stream` suggestions fill remaining slots. The list is fixed at open.
+   */
+  vocabulary?: string[];
+  /**
+   * Minimum trailing-pause length before an utterance may end (50-5000 ms).
+   * Turn detection may wait longer, bounded at `max(endpointingMs, 1500)`.
+   * The server confirms the applied value through `onConfigAck`.
    */
   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.
+   * Reserved Cue grounding configuration. Grounding is not active on the
+   * serving Hear stream; do not rely on grounding frames or Cue metering yet.
    */
   grounding?: boolean;
   /** Cue: number of KB passages to retrieve per turn (1-20, default 3). */
@@ -360,8 +523,11 @@ export interface HearStreamOptions {
   groundingTimeoutMs?: number;
   /** Extra query params merged onto the connect URL. */
   query?: Record<string, string>;
-  /** Fired once the socket opens (after the optional grounding config). */
+  /** Fired once the socket opens. */
   onOpen?: () => void;
+  /** Fired after connect-time or mid-session endpointing config. Assert that
+   * `warnings` is empty before relying on the requested floor. */
+  onConfigAck?: (frame: HearConfigAckFrame) => void;
   /** Fired on `partial` / `partial_stable`. */
   onPartial?: (frame: HearPartialFrame) => void;
   /** Fired on `speech_final` / `final`. */
@@ -379,8 +545,10 @@ export interface HearStreamOptions {
 /**
  * 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()`.
+ * callbacks, update the silence floor with
+ * {@link HearStream.configureEndpointing}, 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;
@@ -389,25 +557,19 @@ export class HearStream {
 
   constructor(url: string, subprotocol: string, opts: HearStreamOptions) {
     this.opts = opts;
+    if (opts.grounding) {
+      throw new Error(
+        "Cue grounding is not active on the serving Hear stream; omit grounding until the API reference marks it active",
+      );
+    }
     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 = new WS(url, [REALTIME_SUBPROTOCOL_MARKER, 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);
@@ -429,6 +591,9 @@ export class HearStream {
       return;
     }
     switch (frame.type) {
+      case HearFrameType.ConfigAck:
+        this.opts.onConfigAck?.(frame);
+        break;
       case HearFrameType.Partial:
       case HearFrameType.PartialStable:
         this.opts.onPartial?.(frame);
@@ -454,6 +619,11 @@ export class HearStream {
     this.ws.send(chunk);
   }
 
+  /** Change the minimum trailing-pause floor without reconnecting. */
+  configureEndpointing(endpointingMs: number): void {
+    this.ws.send(JSON.stringify({ type: "config", endpointing_ms: endpointingMs }));
+  }
+
   /** Force-finalize the current utterance (e.g. on VAD end-of-turn). */
   commit(): void {
     this.ws.send(JSON.stringify({ type: "commit" }));
@@ -497,7 +667,7 @@ export class AmdStream {
         "No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to amd.stream()",
       );
     }
-    this.ws = new WS(url, [subprotocol]);
+    this.ws = new WS(url, [REALTIME_SUBPROTOCOL_MARKER, 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"));
@@ -573,6 +743,8 @@ export const OmniEvent = {
   Flush: "flush",
   /** Engine requests a client-loop tool invocation. */
   ToolCall: "tool_call",
+  /** A write tool is waiting for the caller to confirm; it has not run. */
+  ToolConfirmationRequired: "tool_confirmation_required",
   /** Session is closing; see close code. */
   SessionEnd: "session_end",
   /** Server fault frame. */
@@ -586,25 +758,23 @@ export interface OmniServerFrame {
   [k: string]: unknown;
 }
 
-/** Canonical, sanitized transcript delivered by the native Omni demux. */
+/** Canonical, sanitized transcript delivered by the native Omni demux.
+ * The live wire sends caller text deltas; the JSON fields are SDK-owned
+ * normalization so applications don't have to special-case the byte payload. */
 export interface OmniTranscriptFrame extends OmniServerFrame {
   event: "transcript";
   role: "user" | "assistant";
   text: string;
   final: boolean;
+  /** Live text frames append; legacy JSON frames replace unless they use `delta`. */
   mode: "delta" | "replace";
+  /** Optional ordering hint on legacy JSON frames. */
   sequence?: number;
 }
 
 const OMNI_TRANSCRIPT_MAX_BYTES = 16_384;
 const OMNI_TRANSCRIPT_MAX_CHARS = 4_000;
 
-function omniTranscriptRole(value: unknown): "user" | "assistant" | null {
-  if (value === "user" || value === "caller" || value === "human") return "user";
-  if (value === "assistant" || value === "agent") return "assistant";
-  return null;
-}
-
 function omniTranscriptText(value: unknown): string | null {
   return typeof value === "string"
     && value.length > 0
@@ -614,7 +784,13 @@ function omniTranscriptText(value: unknown): string | null {
     : null;
 }
 
-/** Normalize the live UTF-8 0x02 body and the documented direct-object legacy shape. */
+function omniTranscriptRole(value: unknown): "user" | "assistant" | null {
+  if (value === "user" || value === "caller" || value === "human") return "user";
+  if (value === "assistant" || value === "agent") return "assistant";
+  return null;
+}
+
+/** Normalize the live UTF-8 `0x02` text body and bounded legacy JSON bodies. */
 export function normalizeOmniTranscriptBody(bytes: Uint8Array): OmniTranscriptFrame | null {
   if (bytes.byteLength === 0 || bytes.byteLength > OMNI_TRANSCRIPT_MAX_BYTES) return null;
   let decoded: string;
@@ -623,12 +799,16 @@ export function normalizeOmniTranscriptBody(bytes: Uint8Array): OmniTranscriptFr
   } catch {
     return null;
   }
+  // The serving engine's canonical payload is plain UTF-8 caller text, not
+  // JSON. Each frame is a delta for the current caller turn.
   if (!decoded.trimStart().startsWith("{")) {
     const text = omniTranscriptText(decoded);
     return text
       ? { event: "transcript", role: "user", text, final: false, mode: "delta" }
       : null;
   }
+
+  // Keep accepting a bounded direct object for older bridges and recordings.
   let value: unknown;
   try {
     value = JSON.parse(decoded);
@@ -637,6 +817,8 @@ export function normalizeOmniTranscriptBody(bytes: Uint8Array): OmniTranscriptFr
   }
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const payload = value as Record<string, unknown>;
+  if (payload.type !== undefined
+    || (payload.event !== undefined && payload.event !== "transcript")) return null;
   const role = omniTranscriptRole(payload.role ?? payload.speaker);
   const mode = typeof payload.delta === "string" ? "delta" : "replace";
   const text = omniTranscriptText(
@@ -696,12 +878,10 @@ 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";
+  event: "tool_call";
   call_id: string;
   name: string;
   arguments?: Record<string, unknown>;
@@ -727,7 +907,7 @@ export interface OmniConfigure {
   /**
    * 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}`;
+   * applies automatically when `session_label` is the saved profile 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
@@ -735,7 +915,9 @@ export interface OmniConfigure {
    * staged, see the Language support reference.
    */
   language?: "en" | "fr" | "es" | "de" | "hi";
-  /** Function calling definitions (client-loop when `endpoint` is omitted). */
+  /** Function calling: hosted catalog names, client-loop schemas, or names of
+   * server tools already registered with POST /v1/tools. An inline `endpoint`
+   * is rejected with `unsupported_tool_transport`. */
   tools?: OmniToolDef[];
   /** Forward-compatible: any other key the engine honors. */
   [k: string]: unknown;
@@ -750,7 +932,11 @@ export interface OmniConnectOptions {
    * so a page never holds a secret key.
    */
   token?: string;
-  /** Connect-URL sample rate: 24000 browser, 16000 wideband telephony, 8000 G.711/Twilio. */
+  /**
+   * Caller-input sample rate. `24000` and `16000` sessions receive agent audio
+   * at 24 kHz; `8000` sessions receive 8 kHz. Read `hello.audio_out` rather than
+   * assuming output matches this value.
+   */
   rate?: 24000 | 16000 | 8000;
   /** Connect-URL audio format. Default `pcm16`. */
   format?: "pcm16";
@@ -773,7 +959,7 @@ export interface OmniConnectOptions {
   onSessionStarted?: (frame: OmniServerFrame) => void;
   /** Fired on `turn` boundaries. */
   onTurn?: (frame: OmniServerFrame) => void;
-  /** Fired on `transcript` text frames. */
+  /** Fired for each normalized caller-transcript delta (`0x02` plain UTF-8 live). */
   onTranscript?: (frame: OmniServerFrame) => void;
   /** Fired on `barge_in` / `flush` (user interrupted). */
   onBargeIn?: (frame: OmniServerFrame) => void;
@@ -824,7 +1010,7 @@ export class OmniConnection {
         "No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to omni.connect()",
       );
     }
-    this.ws = new WS(url, [subprotocol]);
+    this.ws = new WS(url, [REALTIME_SUBPROTOCOL_MARKER, subprotocol]);
     this.ws.onopen = () => {
       if (opts.configure) {
         try {
@@ -878,7 +1064,11 @@ export class OmniConnection {
       }
       if (tag === 0x03) {
         try {
-          const parsed = JSON.parse(new TextDecoder().decode(bytes.subarray(1))) as OmniServerFrame;
+          const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(1))) as OmniServerFrame;
+          if (parsed?.event === OmniEvent.Transcript) {
+            this.opts.onError?.(new Error("Omni transcript events must use a binary 0x02 frame"));
+            return;
+          }
           this.dispatchFrame(parsed);
         } catch {
           this.opts.onError?.(new Error("Unparseable Omni binary frame"));
@@ -889,23 +1079,16 @@ export class OmniConnection {
       this.opts.onError?.(new Error(`Ignored unknown Omni binary frame tag ${tagName}`));
       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)}`));
-    }
+    this.opts.onError?.(new Error("Unexpected Omni text frame; server frames must use binary 0x01/0x02/0x03 tags"));
   }
 
   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 });
+    const eventName = (frame as { event?: unknown }).event;
+    if (typeof eventName !== "string" || !eventName) {
+      this.opts.onError?.(new Error("Omni server control frame is missing its event key"));
+      return;
+    }
+    this.opts.onEvent?.(frame);
     switch (eventName) {
       case OmniEvent.Hello:
         this.opts.onHello?.(frame);
@@ -947,7 +1130,10 @@ export class OmniConnection {
    * `{"event":"configure"}` is acked but silently dropped by the engine.)
    */
   configure(cfg: OmniConfigure): void {
-    this.ws.send(omniControlFrame({ type: "configure", ...cfg }));
+    const payload: Record<string, unknown> = { ...cfg };
+    delete payload.type;
+    delete payload.event;
+    this.ws.send(omniControlFrame({ type: "configure", ...payload }));
   }
 
   /**
@@ -987,7 +1173,12 @@ export class OmniConnection {
    * never `event`.
    */
   send(frame: Record<string, unknown>): void {
-    this.ws.send(omniControlFrame(frame));
+    if (typeof frame.type !== "string" || !frame.type) {
+      throw new TypeError("Omni client control frames must have a non-empty type key");
+    }
+    const payload = { ...frame };
+    delete payload.event;
+    this.ws.send(omniControlFrame(payload));
   }
 
   /** Close the session. */
@@ -1284,8 +1475,41 @@ export interface RecapCallSummary {
   completed_at?: number | null;
 }
 
+export interface RecapActionItem {
+  owner?: string | null;
+  task: string;
+  due?: string | null;
+}
+
+export interface RecapTalkRatio {
+  agent: number;
+  customer: number;
+}
+
+export interface RecapSignal {
+  kind: string;
+  text: string;
+  at_s?: number | null;
+}
+
+export interface RecapRecord {
+  format: "recap.record.v1";
+  tldr: string | null;
+  summary: string | null;
+  action_items: RecapActionItem[];
+  disposition: string | null;
+  next_steps: string | null;
+  talk_ratio: RecapTalkRatio | null;
+  signals: RecapSignal[];
+  fields: Record<string, unknown>;
+  rep?: Record<string, unknown>;
+  manager?: Record<string, unknown>;
+  ops?: Record<string, unknown>;
+}
+
 export interface RecapCall extends RecapCallSummary {
-  record?: unknown;
+  record?: RecapRecord;
+  transcript?: { format: "utterances.v1"; utterances: Array<{ speaker_role: "agent" | "customer"; text: string; offset_s: number; duration_s: number }> };
   error?: string | null;
   crm_write_status?: string | null;
 }
@@ -1301,19 +1525,23 @@ export interface RecapCallTriggerInput {
 
 // --- AMD (answering-machine detection) -----------------------------------
 
-/** PyAI's richer answered-by vocabulary (superset of Twilio's enum). */
+/**
+ * The answered-by vocabulary on stored call records and the
+ * `amd.call.completed` webhook: the routing classes plus the machine subtypes.
+ */
 export type AmdAnsweredBy =
   | "human"
+  | "machine"
   | "voicemail"
-  | "live_voicemail"
   | "screening" // iPhone / Google Call Screen
   | "ivr"
-  | "human_gatekeeper"
+  | "music" // hold music
   | "sit_invalid" // dead / disconnected number
-  | "fax"
-  | "silence"
   | "unknown";
 
+/** The routing classes pushed on the mid-call wire event (`event: "amd"`). */
+export type AmdWireAnsweredBy = "human" | "machine" | "sit_invalid" | "unknown";
+
 /** Twilio's `AnsweredBy` enum, echoed for drop-in migration parity. */
 export type AmdTwilioAnsweredBy =
   | "human"
@@ -1363,11 +1591,16 @@ export interface AmdCall extends AmdCallSummary {
   error?: string | null;
 }
 
-/** A mid-call AMD decision event pushed on the stream (and to the webhook). */
+/**
+ * A mid-call AMD decision event pushed on the stream (and to the per-call
+ * TwiML `webhook`). Carries the coarse routing class; the machine subtype
+ * (`voicemail`/`ivr`/`screening`/`music`) is on the stored call record
+ * (`AmdCall`) and the `amd.call.completed` webhook instead.
+ */
 export interface AmdDecisionEvent {
   event?: "amd";
   call_id?: string;
-  answered_by?: AmdAnsweredBy;
+  answered_by?: AmdWireAnsweredBy;
   answered_by_twilio?: string | null;
   confidence?: number | null;
   decision_ms?: number | null;
@@ -1490,14 +1723,71 @@ export class PyAI {
   // --- voices -------------------------------------------------------------
 
   voices = {
-    list: (params: { gender?: string; region?: string } = {}): Promise<ListResponse<Voice>> => {
+    list: async (params: {
+      gender?: string;
+      region?: string;
+      language?: string;
+      tier?: "standard" | "natural";
+      q?: string;
+    } = {}): Promise<ListResponse<Voice>> => {
       const q = new URLSearchParams();
       if (params.gender) q.set("gender", params.gender);
       if (params.region) q.set("region", params.region);
+      if (params.language) q.set("language", params.language);
+      if (params.tier) q.set("tier", params.tier);
+      if (params.q) q.set("q", params.q);
       const qs = q.toString();
-      return this.getJson(`/v1/voices${qs ? `?${qs}` : ""}`);
+      const page = await this.getJson<ListResponse<Record<string, unknown>>>(
+        `/v1/voices${qs ? `?${qs}` : ""}`,
+      );
+      return { ...page, data: page.data.map(normalizeVoice) };
+    },
+    get: async (id: string): Promise<Voice> =>
+      normalizeVoice(
+        await this.getJson<Record<string, unknown>>(
+          `/v1/voices/${encodeURIComponent(id)}`,
+        ),
+      ),
+  };
+
+  // --- Hear organization settings ----------------------------------------
+
+  hear = {
+    vocabulary: {
+      /** Read organization-owned vocabulary. Scope `hear:configure`. */
+      get: (): Promise<HearVocabulary> =>
+        this.getJson("/v1/hear/vocabulary"),
+      /** Replace vocabulary and activation profiles. Scope `hear:configure`. */
+      set: (input: HearVocabularyInput): Promise<HearVocabulary> =>
+        this.putJson("/v1/hear/vocabulary", {
+          terms: input.terms,
+          enabled_for: input.enabledFor,
+        }),
+    },
+  };
+
+  // --- managed Agents ----------------------------------------------------
+
+  agents = {
+    list: (): Promise<ListResponse<Agent>> => this.getJson("/v1/agents"),
+    get: (agentId: string): Promise<Agent> =>
+      this.getJson(`/v1/agents/${encodeURIComponent(agentId)}`),
+    create: (input: AgentConfig & { name: string }): Promise<Agent> =>
+      this.postJson("/v1/agents", input),
+    update: (agentId: string, patch: AgentConfig): Promise<Agent> =>
+      this.postJson(`/v1/agents/${encodeURIComponent(agentId)}`, patch),
+    delete: async (
+      agentId: string,
+    ): Promise<{ object: "agent.deleted"; agent_id: string; deleted: boolean }> => {
+      const response = await this.deleteReq(
+        `/v1/agents/${encodeURIComponent(agentId)}`,
+      );
+      return (await response.json()) as {
+        object: "agent.deleted";
+        agent_id: string;
+        deleted: boolean;
+      };
     },
-    get: (id: string): Promise<Voice> => this.getJson(`/v1/voices/${encodeURIComponent(id)}`),
   };
 
   // --- audio --------------------------------------------------------------
@@ -1505,26 +1795,28 @@ export class PyAI {
   audio = {
     /** Text-to-speech. Returns the raw audio bytes (default WAV). */
     speech: async (params: SpeechParams): Promise<ArrayBuffer> => {
+      assertActiveSpeechParams(params);
       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-speak", ...params }),
       });
       return res.arrayBuffer();
     },
     /**
      * Text-to-speech, streamed. Resolves as soon as the response headers arrive
      * with the body as a `ReadableStream` of audio bytes, so you can start
-     * playback or forward the audio at the first chunk (the engine's
-     * time-to-first-byte is tens of ms) instead of buffering the whole clip.
-     * Use `mp3` for the smoothest progressive playback. Returns an async
-     * iterable of Uint8Array chunks.
+     * playback or forward the audio at the first chunk. Use `pcm`, `wav`,
+     * or G.711 for streaming; `mp3` and `opus` are buffered server-side.
+     * Consume the stream immediately and cancel its reader when stopping early.
+     * HTTP connection reuse and protocol negotiation are controlled by fetch.
      */
     speechStream: async (params: SpeechParams): Promise<ReadableStream<Uint8Array>> => {
+      assertActiveSpeechParams(params);
       const res = await this.request("/v1/audio/speech", {
         method: "POST",
         headers: this.authHeaders({ "Content-Type": "application/json" }),
-        body: JSON.stringify({ model: "pyai-voice", ...params, stream: true }),
+        body: JSON.stringify({ model: "pyai-speak", ...params, stream: true }),
       });
       if (!res.body) throw new PyAIError(res.status, "Response had no body to stream");
       return res.body as ReadableStream<Uint8Array>;
@@ -1535,7 +1827,13 @@ export class PyAI {
         file: Blob;
         filename?: string;
         model?: string;
-        language?: string;
+        /** Optional language hint. Omission enables automatic detection. */
+        language?: "en" | "es" | "fr" | "de" | "hi" | "it" | "pt" | "nl";
+        numerals?: boolean;
+        smart_format?: boolean;
+        dictation?: boolean;
+        drop_fillers?: boolean;
+        vocabulary?: string[];
         response_format?: "json" | "text" | "verbose_json";
         /**
          * Deterministic seed for reproducible eval runs. Forward-compatible:
@@ -1549,6 +1847,11 @@ export class PyAI {
         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.numerals !== undefined) form.set("numerals", String(params.numerals));
+        if (params.smart_format !== undefined) form.set("smart_format", String(params.smart_format));
+        if (params.dictation !== undefined) form.set("dictation", String(params.dictation));
+        if (params.drop_fillers !== undefined) form.set("drop_fillers", String(params.drop_fillers));
+        if (params.vocabulary?.length) form.set("vocabulary", params.vocabulary.join(","));
         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));
@@ -1607,7 +1910,7 @@ export class PyAI {
   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`. */
+    /** Enroll a custom voice from reference audio (>= ~10s). Scope `speak:clone`. */
     create: async (params: { name: string; file: Blob; filename?: string }): Promise<Voice> => {
       const form = new FormData();
       form.set("name", params.name);
@@ -1626,7 +1929,7 @@ export class PyAI {
       if (!match) throw new PyAIError(404, `No cloned voice ${id}`, ErrorCode.NotFound);
       return match;
     },
-    /** Delete a cloned voice (tenant-isolated). Scope `voice:clone`. */
+    /** Delete a cloned voice (tenant-isolated). Scope `speak:clone`. */
     delete: async (id: string): Promise<void> => {
       await this.deleteReq(`/v1/voice/clones/${encodeURIComponent(id)}`);
     },
@@ -1823,7 +2126,7 @@ export class PyAI {
      * 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
+     * `new WebSocket(session.url, ["pyai.v1", "pyai-key." + session.token])`. The token
      * expires after `ttlSeconds` (default 60s) and only works from
      * `allowedOrigins`. Scope `omni:session`.
      */
@@ -1847,7 +2150,7 @@ export class PyAI {
       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 url = this.realtimeURL({ sessionLabel: opts.sessionLabel, query });
       const sub = opts.token ? `pyai-key.${opts.token}` : this.realtimeSubprotocol();
       return new OmniConnection(url, sub, opts);
     },
@@ -1855,41 +2158,64 @@ export class PyAI {
 
   // --- realtime (WebSocket) ----------------------------------------------
 
-  /** Build the realtime WebSocket URL for the chosen product. */
+  /** Build the canonical Omni WebSocket URL. */
   realtimeURL(opts: RealtimeOptions = {}): string {
     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. 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();
-      return `${wsBase}/v1/omni${qs ? `?${qs}` : ""}`;
+    // format/rate are load-bearing on the connect URL, so default to
+    // browser-grade PCM16/24kHz.
+    for (const key of ["agent", "agent_id", "agentId", "model", "access_token"]) {
+      if (q.has(key)) {
+        throw new Error(
+          `Omni query parameter "${key}" is not supported; use sessionLabel, format/rate, or api_key`,
+        );
+      }
     }
-    q.set("model", "pyai-flow-realtime");
-    return `${wsBase}/v1/realtime?${q.toString()}`;
+    if (opts.sessionLabel) q.set("session_label", opts.sessionLabel);
+    if (!q.has("format")) q.set("format", "pcm16");
+    if (!q.has("rate")) q.set("rate", "24000");
+    const qs = q.toString();
+    return `${wsBase}/v1/omni${qs ? `?${qs}` : ""}`;
   }
 
-  /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */
+  /** The subprotocol token that carries the key on a WS upgrade. */
   realtimeSubprotocol(): string {
     return `pyai-key.${this.apiKey}`;
   }
 
+  /**
+   * The full subprotocol list to open a PyAI WebSocket with:
+   * `[marker, credential]`. Always pass BOTH — see
+   * {@link REALTIME_SUBPROTOCOL_MARKER}. Pass `token` to use an ephemeral
+   * session token (from `omni.createSession`) instead of the secret key.
+   */
+  realtimeSubprotocols(token?: string): string[] {
+    return [
+      REALTIME_SUBPROTOCOL_MARKER,
+      token ? `pyai-key.${token}` : this.realtimeSubprotocol(),
+    ];
+  }
+
   /** 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 ?? {});
+    // `context` is private to PyAI's adapter-to-server hop. Never expose or
+    // forward it from the public SDK escape hatch.
+    q.delete("context");
+    q.set("protocol", "pyai-hear-v1");
     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.smartFormat !== undefined) q.set("smart_format", String(opts.smartFormat));
+    if (opts.dictation !== undefined) q.set("dictation", String(opts.dictation));
+    if (opts.dropFillers !== undefined) q.set("drop_fillers", String(opts.dropFillers));
+    if (opts.vocabulary?.length) {
+      q.set("vocabulary", JSON.stringify(opts.vocabulary));
+    }
     if (opts.endpointingMs !== undefined) q.set("endpointing_ms", String(opts.endpointingMs));
     const qs = q.toString();
     return `${wsBase}/v1/audio/transcriptions/stream${qs ? `?${qs}` : ""}`;
@@ -1912,8 +2238,8 @@ export class PyAI {
    */
   connectRealtime(opts: RealtimeOptions = {}): WebSocket {
     const WS = (globalThis as { WebSocket?: typeof WebSocket }).WebSocket;
-    if (!WS) throw new Error("No global WebSocket; use realtimeURL()/realtimeSubprotocol() with a WS library");
-    return new WS(this.realtimeURL(opts), [this.realtimeSubprotocol()]);
+    if (!WS) throw new Error("No global WebSocket; use realtimeURL()/realtimeSubprotocols() with a WS library");
+    return new WS(this.realtimeURL(opts), this.realtimeSubprotocols());
   }
 }