agents 0.22.0 → 0.24.0

package/dist/voice/client.d.ts

@@ -0,0 +1,226 @@
+import {
+  C as VoiceTransport,
+  D as VoiceTurnSource,
+  E as VoiceTurnOutcome,
+  S as VoiceStatus,
+  T as VoiceTurnMetrics,
+  _ as VoiceErrorStage,
+  b as VoiceRole,
+  c as VoiceAudioFormat,
+  d as VoiceCompletionOutcome,
+  f as VoiceCompletionOutcomeCode,
+  g as VoiceErrorCode,
+  h as VoiceError,
+  l as VoiceAudioInput,
+  m as VoiceDiagnosticsOptions,
+  o as TranscriptMessage,
+  p as VoiceDiagnosticEvent,
+  s as VOICE_PROTOCOL_VERSION,
+  v as VoiceModelFinishReason,
+  w as VoiceTransportCloseInfo,
+  y as VoicePipelineMetrics
+} from "../types-_Faxb570.js";
+
+//#region src/voice/client.d.ts
+interface VoiceClientOptions {
+  /** Agent name (matches the server-side Durable Object class). */
+  agent: string;
+  /** Instance name for the agent. @default "default" */
+  name?: string;
+  /** Host to connect to. @default window.location.host */
+  host?: string;
+  /** Query parameters appended to the WebSocket URL. */
+  query?: Record<string, string | null | undefined>;
+  /**
+   * Custom transport for sending/receiving data.
+   * Defaults to a WebSocket transport via PartySocket.
+   * Provide a custom implementation for WebRTC, SFU, or other transports.
+   */
+  transport?: VoiceTransport;
+  /**
+   * Custom audio input source. When provided, VoiceClient does NOT
+   * use its built-in AudioWorklet mic capture. The audio input is
+   * responsible for capturing and routing audio to the server.
+   * It must report audio levels via `onAudioLevel` for silence and
+   * interrupt detection to work.
+   */
+  audioInput?: VoiceAudioInput;
+  /**
+   * Preferred audio format for server responses. Sent in `start_call`
+   * as a hint — the server may ignore it if it cannot produce that format.
+   * The actual format is declared in the server's `audio_config` message.
+   */
+  preferredFormat?: VoiceAudioFormat;
+  /** RMS threshold below which audio is considered silence. @default 0.04 */
+  silenceThreshold?: number;
+  /** How long silence must last before sending end_of_speech (ms). @default 500 */
+  silenceDurationMs?: number;
+  /** RMS threshold for detecting user speech during agent playback. @default 0.05 */
+  interruptThreshold?: number;
+  /** Consecutive high-RMS chunks needed to trigger an interrupt. @default 2 */
+  interruptChunks?: number;
+  /** Maximum transcript messages to keep in memory. @default 200 */
+  maxTranscriptMessages?: number;
+  /**
+   * Preferred audio output device for assistant playback.
+   * Pass a MediaDeviceInfo.deviceId from an audiooutput device.
+   * Unsupported browsers continue playing through the default output.
+   * @default "default"
+   */
+  outputDeviceId?: string;
+}
+/**
+ * Low-level browser transport information for diagnosing connection failures.
+ * Error causes stay as the raw `unknown` value because browsers do not
+ * guarantee useful fields on WebSocket error events. The SDK does not
+ * serialize or log this local event; consumers must narrow it before use.
+ */
+type VoiceConnectionDiagnostic =
+  | {
+      type: "error";
+      cause: unknown;
+    }
+  | ({
+      type: "close";
+    } & VoiceTransportCloseInfo);
+/** Maps each event name to the data type passed to its listeners. */
+interface VoiceClientEventMap {
+  statuschange: VoiceStatus;
+  transcriptchange: TranscriptMessage[];
+  interimtranscript: string | null;
+  metricschange: VoicePipelineMetrics | null;
+  turnmetrics: VoiceTurnMetrics;
+  audiolevelchange: number;
+  connectionchange: boolean;
+  connectiondiagnostic: VoiceConnectionDiagnostic;
+  voiceerror: VoiceError;
+  completionoutcome: VoiceCompletionOutcome;
+  error: string | null;
+  outputdeviceerror: string | null;
+  mutechange: boolean;
+  custommessage: unknown;
+}
+type VoiceClientEvent = keyof VoiceClientEventMap;
+/**
+ * Default VoiceTransport backed by PartySocket (reconnecting WebSocket).
+ * Created automatically when no custom transport is provided.
+ */
+declare class WebSocketVoiceTransport implements VoiceTransport {
+  #private;
+  onopen: (() => void) | null;
+  onclose: ((info?: VoiceTransportCloseInfo) => void) | null;
+  onerror: ((error?: unknown) => void) | null;
+  onmessage: ((data: string | ArrayBuffer | Blob) => void) | null;
+  constructor(options: {
+    agent: string;
+    name?: string;
+    host?: string;
+    query?: Record<string, string | null | undefined>;
+  });
+  get connected(): boolean;
+  sendJSON(data: Record<string, unknown>): void;
+  sendBinary(data: ArrayBuffer): void;
+  connect(): void;
+  disconnect(): void;
+}
+declare class VoiceClient {
+  #private;
+  constructor(options: VoiceClientOptions);
+  get status(): VoiceStatus;
+  get transcript(): TranscriptMessage[];
+  get metrics(): VoicePipelineMetrics | null;
+  /** Last stable terminal summary received for any speech or text turn. */
+  get turnMetrics(): VoiceTurnMetrics | null;
+  get audioLevel(): number;
+  get isMuted(): boolean;
+  get connected(): boolean;
+  get error(): string | null;
+  get outputDeviceError(): string | null;
+  /**
+   * The current interim (partial) transcript from streaming STT.
+   * Updates in real time as the user speaks. Cleared when the final
+   * transcript is produced or the call reaches a terminal reset.
+   * null when no interim text is available.
+   */
+  get interimTranscript(): string | null;
+  /**
+   * The protocol version reported by the server.
+   * null until the server sends its welcome message.
+   */
+  get serverProtocolVersion(): number | null;
+  addEventListener<K extends VoiceClientEvent>(
+    event: K,
+    listener: (data: VoiceClientEventMap[K]) => void
+  ): void;
+  removeEventListener<K extends VoiceClientEvent>(
+    event: K,
+    listener: (data: VoiceClientEventMap[K]) => void
+  ): void;
+  connect(): void;
+  disconnect(): void;
+  startCall(): Promise<void>;
+  endCall(): void;
+  toggleMute(): void;
+  /**
+   * Send a text message to the agent. The agent processes it through
+   * `onTurn()` (bypassing STT) and responds with text transcript and
+   * TTS audio (if in a call) or text-only (if not).
+   */
+  sendText(text: string): void;
+  /**
+   * Send arbitrary JSON to the agent. Use this for app-level messages
+   * that are not part of the voice protocol (e.g. `{ type: "kick_speaker" }`).
+   * The server receives these in the consumer's `onMessage()` handler.
+   */
+  sendJSON(data: Record<string, unknown>): void;
+  /**
+   * Set the preferred audio output device for assistant playback.
+   * Unsupported browsers continue playing through the default output.
+   */
+  setOutputDevice(outputDeviceId?: string): Promise<void>;
+  /**
+   * The last custom (non-voice-protocol) message received from the server.
+   * Listen for the `"custommessage"` event to be notified when this changes.
+   */
+  get lastCustomMessage(): unknown;
+  /**
+   * The audio format the server declared for binary payloads.
+   * Set when the server sends `audio_config` at call start.
+   */
+  get audioFormat(): VoiceAudioFormat | null;
+  /**
+   * The sample rate (Hz) the server declared for raw pcm16 payloads.
+   * Set when the server sends `audio_config` at call start. Defaults to 16000.
+   */
+  get sampleRate(): number;
+}
+//#endregion
+export {
+  type TranscriptMessage,
+  VOICE_PROTOCOL_VERSION,
+  type VoiceAudioFormat,
+  type VoiceAudioInput,
+  VoiceClient,
+  VoiceClientEvent,
+  VoiceClientEventMap,
+  VoiceClientOptions,
+  type VoiceCompletionOutcome,
+  type VoiceCompletionOutcomeCode,
+  VoiceConnectionDiagnostic,
+  type VoiceDiagnosticEvent,
+  type VoiceDiagnosticsOptions,
+  type VoiceError,
+  type VoiceErrorCode,
+  type VoiceErrorStage,
+  type VoiceModelFinishReason,
+  type VoicePipelineMetrics,
+  type VoiceRole,
+  type VoiceStatus,
+  type VoiceTransport,
+  type VoiceTransportCloseInfo,
+  type VoiceTurnMetrics,
+  type VoiceTurnOutcome,
+  type VoiceTurnSource,
+  WebSocketVoiceTransport
+};
+//# sourceMappingURL=client.d.ts.map