@pyai/sdk 0.2.3 → 0.4.0

package/dist/index.d.ts

@@ -24,10 +24,27 @@ export declare class PyAIError extends Error {
     constructor(status: number, message: string, code?: string, type?: string, requestId?: string);
 }
 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;
 }
 export interface ListResponse<T> {
@@ -49,13 +66,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` |
@@ -73,14 +90,23 @@ export declare const SPEECH_FORMATS: readonly ["wav", "mp3", "opus", "aac", "fla
 /** Sample rates (Hz) the server accepts for `audio.speech` (`g711_*` is always 8 kHz). */
 export declare const SPEECH_SAMPLE_RATES: readonly [8000, 16000, 24000, 48000];
 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
@@ -97,15 +123,14 @@ 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;
 }
@@ -115,12 +140,59 @@ export interface CreateJobParams {
     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
@@ -128,12 +200,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>;
 }
 /** Parameters for minting an ephemeral browser Omni session token (server-side). */
@@ -167,6 +237,8 @@ export interface OmniSession {
 }
 /** Frame `type`s emitted by the Hear streaming-STT WebSocket. */
 export declare const HearFrameType: {
+    /** Applied endpointing configuration and validation warnings. */
+    readonly ConfigAck: "config_ack";
     /** Eager live hypothesis for the current utterance. */
     readonly Partial: "partial";
     /** Partial whose prefix has stabilized (won't be revised). */
@@ -181,10 +253,16 @@ export declare const HearFrameType: {
     readonly Error: "error";
 };
 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 declare const WSCloseCode: {
     /** Normal closure. */
     readonly Normal: 1000;
+    /** Browser-safe private application code for a malformed peer protocol frame. */
+    readonly ProtocolViolation: 4002;
     /** Auth/policy: bad key, missing scope, or revoked token. */
     readonly PolicyViolation: 1008;
     /** Engine/internal error. */
@@ -202,7 +280,7 @@ export declare const ErrorCode: {
     readonly Unauthorized: "unauthorized";
     readonly Forbidden: "forbidden";
     readonly OriginNotAllowed: "origin_not_allowed";
-    readonly InvalidAgentId: "invalid_agent_id";
+    readonly InvalidSessionLabel: "invalid_session_label";
     readonly CreditExhausted: "credit_exhausted";
     readonly KeyBudgetExceeded: "key_budget_exceeded";
     readonly InsufficientQuota: "insufficient_quota";
@@ -212,6 +290,7 @@ export declare const ErrorCode: {
     readonly IdempotencyConflict: "idempotency_conflict";
     readonly NotFound: "not_found";
     readonly NumberInUse: "number_in_use";
+    readonly UnsupportedToolTransport: "unsupported_tool_transport";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** A top-3 knowledge-base passage attached to Cue (grounded) finals. */
@@ -219,6 +298,22 @@ export interface HearGroundingPassage {
     content: string;
     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";
@@ -232,6 +327,7 @@ export interface HearPartialFrame {
     t_ms: number;
 }
 /** 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;
@@ -239,6 +335,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[];
 }
@@ -250,7 +348,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;
@@ -263,7 +361,7 @@ export interface HearErrorFrame {
     code?: string;
     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
  * `WebSocket` and the `ws` package, and lets tests inject a mock.
@@ -282,35 +380,68 @@ export interface WebSocketLike {
         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 declare 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). */
@@ -322,8 +453,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`. */
@@ -340,8 +474,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 declare class HearStream {
     private readonly ws;
@@ -351,6 +487,8 @@ export declare class HearStream {
     private handleMessage;
     /** Send a chunk of audio (PCM16 or opus per `encoding`). */
     sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void;
+    /** Change the minimum trailing-pause floor without reconnecting. */
+    configureEndpointing(endpointingMs: number): void;
     /** Force-finalize the current utterance (e.g. on VAD end-of-turn). */
     commit(): void;
     /** Close the socket; the server flushes a final for any buffered audio. */
@@ -409,6 +547,8 @@ export declare const OmniEvent: {
     readonly Flush: "flush";
     /** Engine requests a client-loop tool invocation. */
     readonly ToolCall: "tool_call";
+    /** A write tool is waiting for the caller to confirm; it has not run. */
+    readonly ToolConfirmationRequired: "tool_confirmation_required";
     /** Session is closing; see close code. */
     readonly SessionEnd: "session_end";
     /** Server fault frame. */
@@ -420,16 +560,20 @@ export interface OmniServerFrame {
     event: string;
     [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;
 }
-/** Normalize the live UTF-8 0x02 body and the documented direct-object legacy shape. */
+/** Normalize the live UTF-8 `0x02` text body and bounded legacy JSON bodies. */
 export declare function normalizeOmniTranscriptBody(bytes: Uint8Array): OmniTranscriptFrame | null;
 /** A binary agent-audio chunk delivered to {@link OmniConnectOptions.onAudio}. */
 export type OmniAudioChunk = ArrayBuffer | ArrayBufferView | Blob;
@@ -437,11 +581,9 @@ 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>;
@@ -466,7 +608,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
@@ -474,7 +616,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;
@@ -488,7 +632,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";
@@ -511,7 +659,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;
@@ -836,8 +984,45 @@ export interface RecapCallSummary {
     created_at?: number;
     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;
 }
@@ -854,8 +1039,13 @@ export interface RecapCallTriggerInput {
     customer_name?: string;
     crm_fields?: Record<string, unknown>;
 }
-/** PyAI's richer answered-by vocabulary (superset of Twilio's enum). */
-export type AmdAnsweredBy = "human" | "voicemail" | "live_voicemail" | "screening" | "ivr" | "human_gatekeeper" | "sit_invalid" | "fax" | "silence" | "unknown";
+/**
+ * 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" | "screening" | "ivr" | "music" | "sit_invalid" | "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" | "machine_start" | "machine_end_beep" | "machine_end_silence" | "machine_end_other" | "fax" | "unknown";
 export interface AmdConfigInput {
@@ -893,11 +1083,16 @@ export interface AmdCall extends AmdCallSummary {
     meta?: Record<string, unknown> | null;
     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;
@@ -946,19 +1141,43 @@ export declare class PyAI {
         list: (params?: {
             gender?: string;
             region?: string;
+            language?: string;
+            tier?: "standard" | "natural";
+            q?: string;
         }) => Promise<ListResponse<Voice>>;
         get: (id: string) => Promise<Voice>;
     };
+    hear: {
+        vocabulary: {
+            /** Read organization-owned vocabulary. Scope `hear:configure`. */
+            get: () => Promise<HearVocabulary>;
+            /** Replace vocabulary and activation profiles. Scope `hear:configure`. */
+            set: (input: HearVocabularyInput) => Promise<HearVocabulary>;
+        };
+    };
+    agents: {
+        list: () => Promise<ListResponse<Agent>>;
+        get: (agentId: string) => Promise<Agent>;
+        create: (input: AgentConfig & {
+            name: string;
+        }) => Promise<Agent>;
+        update: (agentId: string, patch: AgentConfig) => Promise<Agent>;
+        delete: (agentId: string) => Promise<{
+            object: "agent.deleted";
+            agent_id: string;
+            deleted: boolean;
+        }>;
+    };
     audio: {
         /** Text-to-speech. Returns the raw audio bytes (default WAV). */
         speech: (params: SpeechParams) => Promise<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: (params: SpeechParams) => Promise<ReadableStream<Uint8Array>>;
         /** Synchronous speech-to-text (multipart upload). */
@@ -967,7 +1186,13 @@ export declare 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:
@@ -1007,7 +1232,7 @@ export declare class PyAI {
     clones: {
         /** List the org's cloned voices. */
         list: () => Promise<ListResponse<Voice>>;
-        /** Enroll a custom voice from reference audio (>= ~10s). Scope `voice:clone`. */
+        /** Enroll a custom voice from reference audio (>= ~10s). Scope `speak:clone`. */
         create: (params: {
             name: string;
             file: Blob;
@@ -1019,7 +1244,7 @@ export declare class PyAI {
          * when the id isn't found.
          */
         get: (id: string) => Promise<Voice>;
-        /** Delete a cloned voice (tenant-isolated). Scope `voice:clone`. */
+        /** Delete a cloned voice (tenant-isolated). Scope `speak:clone`. */
         delete: (id: string) => Promise<void>;
     };
     telephony: {
@@ -1148,7 +1373,7 @@ export declare 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`.
          */
@@ -1164,10 +1389,17 @@ export declare class PyAI {
          */
         connect: (opts?: OmniConnectOptions) => OmniConnection;
     };
-    /** Build the realtime WebSocket URL for the chosen product. */
+    /** Build the canonical Omni WebSocket URL. */
     realtimeURL(opts?: RealtimeOptions): string;
-    /** 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;
+    /**
+     * 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[];
     /** Build the Hear streaming-STT WebSocket URL (`/v1/audio/transcriptions/stream`). */
     hearStreamURL(opts?: HearStreamOptions): string;
     /** Build the AMD detection WebSocket URL (`/v1/amd/stream`). */