@mastra/voice-aws-nova-sonic 0.0.0-studio-cli-20260504022012

package/dist/index.js

@@ -0,0 +1,1615 @@
+import { randomUUID } from 'crypto';
+import { PassThrough } from 'stream';
+import { BedrockRuntimeClient, InvokeModelWithBidirectionalStreamCommand } from '@aws-sdk/client-bedrock-runtime';
+import { MastraVoice } from '@mastra/core/voice';
+import { NodeHttp2Handler } from '@smithy/node-http-handler';
+import { defaultProvider } from '@aws-sdk/credential-provider-node';
+
+// src/index.ts
+
+// src/types.ts
+var NovaSonicErrorCode = /* @__PURE__ */ ((NovaSonicErrorCode2) => {
+  NovaSonicErrorCode2["CONNECTION_FAILED"] = "connection_failed";
+  NovaSonicErrorCode2["CONNECTION_NOT_ESTABLISHED"] = "connection_not_established";
+  NovaSonicErrorCode2["AUTHENTICATION_FAILED"] = "authentication_failed";
+  NovaSonicErrorCode2["CREDENTIALS_MISSING"] = "credentials_missing";
+  NovaSonicErrorCode2["REGION_INVALID"] = "region_invalid";
+  NovaSonicErrorCode2["WEBSOCKET_ERROR"] = "websocket_error";
+  NovaSonicErrorCode2["AUDIO_PROCESSING_ERROR"] = "audio_processing_error";
+  NovaSonicErrorCode2["AUDIO_STREAM_ERROR"] = "audio_stream_error";
+  NovaSonicErrorCode2["SPEAKER_STREAM_ERROR"] = "speaker_stream_error";
+  NovaSonicErrorCode2["TRANSCRIPTION_TIMEOUT"] = "transcription_timeout";
+  NovaSonicErrorCode2["TRANSCRIPTION_FAILED"] = "transcription_failed";
+  NovaSonicErrorCode2["TOOL_EXECUTION_ERROR"] = "tool_execution_error";
+  NovaSonicErrorCode2["TOOL_NOT_FOUND"] = "tool_not_found";
+  NovaSonicErrorCode2["SESSION_CONFIG_UPDATE_FAILED"] = "session_config_update_failed";
+  NovaSonicErrorCode2["INVALID_AUDIO_FORMAT"] = "invalid_audio_format";
+  NovaSonicErrorCode2["NOT_CONNECTED"] = "not_connected";
+  NovaSonicErrorCode2["INVALID_STATE"] = "invalid_state";
+  NovaSonicErrorCode2["VALIDATION_ERROR"] = "validation_error";
+  NovaSonicErrorCode2["UNKNOWN_ERROR"] = "unknown_error";
+  return NovaSonicErrorCode2;
+})(NovaSonicErrorCode || {});
+
+// src/utils/errors.ts
+var NovaSonicError = class extends Error {
+  code;
+  details;
+  timestamp;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "NovaSonicError";
+    this.code = code;
+    this.details = details;
+    this.timestamp = Date.now();
+  }
+  toEventData() {
+    return {
+      message: this.message,
+      code: this.code,
+      details: this.details,
+      timestamp: this.timestamp
+    };
+  }
+};
+
+// src/utils/auth.ts
+async function getAwsCredentials(explicitCredentials, debug) {
+  if (explicitCredentials) {
+    if (debug) {
+      console.info("[getAwsCredentials] Using explicit credentials provided in config");
+    }
+    return explicitCredentials;
+  }
+  try {
+    if (debug) {
+      console.info("[getAwsCredentials] Using default credential provider chain");
+    }
+    const credentials = await defaultProvider()();
+    if (debug) {
+      console.info("[getAwsCredentials] Credentials retrieved successfully");
+    }
+    return credentials;
+  } catch (error) {
+    if (error instanceof NovaSonicError) {
+      throw error;
+    }
+    throw new NovaSonicError(
+      "authentication_failed" /* AUTHENTICATION_FAILED */,
+      `Failed to load AWS credentials: ${error instanceof Error ? error.message : "Unknown error"}`,
+      error
+    );
+  }
+}
+
+// src/index.ts
+var DEFAULT_MODEL = "amazon.nova-2-sonic-v1:0";
+var DEFAULT_REGION = "us-east-1";
+var NovaSonicVoice = class extends MastraVoice {
+  client;
+  stream;
+  inputStream;
+  // Input stream for sending events to AWS
+  _eventQueue;
+  _signalQueue;
+  _closeSignal;
+  _promptName;
+  state = "disconnected";
+  events;
+  instructions;
+  tools;
+  requestContext;
+  debug;
+  region;
+  model;
+  credentials;
+  speakerStreams;
+  currentResponseId;
+  processingStream = false;
+  streamRestartAttempted = false;
+  // Prevent multiple restart attempts
+  sessionConfig;
+  promptStarted = false;
+  // Track if promptStart was sent (now sent during connection)
+  audioContentName;
+  audioContentStarted = false;
+  hasSentContentEnd = false;
+  // Track if contentEnd has been sent for current turn
+  turnCompleted = false;
+  // Track if turn has been completed (to prevent sending contentEnd after turn completion)
+  turnCompleteTimeout;
+  // Timeout for fallback turn completion
+  isReceivingAssistantAudio = false;
+  // Track if we're currently receiving assistant audio output
+  currentTextGenerationStage;
+  // Track generationStage (SPECULATIVE|FINAL) for current text content block
+  /**
+   * Creates a new instance of NovaSonicVoice.
+   *
+   * @param config - Configuration options for the voice instance
+   * @param config.region - AWS region (defaults to us-east-1)
+   * @param config.model - The model ID to use (defaults to amazon.nova-2-sonic-v1:0)
+   * @param config.credentials - AWS credentials (optional, uses default credential chain)
+   * @param config.speaker - Voice name/identifier
+   * @param config.languageCode - Language code for the voice
+   * @param config.debug - Enable debug mode
+   *
+   * @example
+   * ```typescript
+   * const voice = new NovaSonicVoice({
+   *   region: 'us-east-1',
+   *   model: 'amazon.nova-2-sonic-v1:0',
+   *   speaker: 'default',
+   * });
+   * ```
+   */
+  constructor(config = {}) {
+    let normalizedConfig;
+    if ("realtimeConfig" in config || "speechModel" in config || "listeningModel" in config) {
+      normalizedConfig = config;
+    } else {
+      const configOptions = config;
+      normalizedConfig = {
+        realtimeConfig: {
+          model: configOptions.model || DEFAULT_MODEL,
+          apiKey: void 0,
+          // AWS doesn't use API keys
+          options: configOptions
+        },
+        speaker: typeof configOptions.speaker === "string" ? configOptions.speaker : "matthew"
+      };
+    }
+    super(normalizedConfig);
+    const options = normalizedConfig.realtimeConfig?.options || config;
+    this.region = options.region || DEFAULT_REGION;
+    this.model = options.model || DEFAULT_MODEL;
+    this.credentials = options.credentials;
+    this.debug = options.debug || false;
+    this.sessionConfig = options.sessionConfig;
+    this.events = {};
+    this.speakerStreams = /* @__PURE__ */ new Map();
+    const validRegions = ["us-east-1", "us-west-2", "ap-northeast-1"];
+    if (!validRegions.includes(this.region)) {
+      throw new NovaSonicError(
+        "region_invalid" /* REGION_INVALID */,
+        `Invalid region: ${this.region}. Supported regions: ${validRegions.join(", ")}`
+      );
+    }
+  }
+  /**
+   * Returns a list of available voice speakers.
+   *
+   * Nova 2 Sonic provides expressive voices across multiple languages.
+   * Tiffany (en-US, feminine) and Matthew (en-US, masculine) are polyglot
+   * voices that can speak all supported languages.
+   *
+   * @returns Promise resolving to an array of voice objects
+   */
+  async getSpeakers() {
+    return Promise.resolve([
+      // English (US) - Polyglot voices
+      { voiceId: "tiffany", name: "Tiffany", language: "English", locale: "en-US", gender: "feminine", polyglot: true },
+      {
+        voiceId: "matthew",
+        name: "Matthew",
+        language: "English",
+        locale: "en-US",
+        gender: "masculine",
+        polyglot: true
+      },
+      // English (UK)
+      { voiceId: "amy", name: "Amy", language: "English", locale: "en-GB", gender: "feminine", polyglot: false },
+      // English (Australia)
+      { voiceId: "olivia", name: "Olivia", language: "English", locale: "en-AU", gender: "feminine", polyglot: false },
+      // English (Indian)
+      { voiceId: "kiara", name: "Kiara", language: "English", locale: "en-IN", gender: "feminine", polyglot: false },
+      { voiceId: "arjun", name: "Arjun", language: "English", locale: "en-IN", gender: "masculine", polyglot: false },
+      // French
+      { voiceId: "ambre", name: "Ambre", language: "French", locale: "fr-FR", gender: "feminine", polyglot: false },
+      {
+        voiceId: "florian",
+        name: "Florian",
+        language: "French",
+        locale: "fr-FR",
+        gender: "masculine",
+        polyglot: false
+      },
+      // Italian
+      {
+        voiceId: "beatrice",
+        name: "Beatrice",
+        language: "Italian",
+        locale: "it-IT",
+        gender: "feminine",
+        polyglot: false
+      },
+      {
+        voiceId: "lorenzo",
+        name: "Lorenzo",
+        language: "Italian",
+        locale: "it-IT",
+        gender: "masculine",
+        polyglot: false
+      },
+      // German
+      { voiceId: "tina", name: "Tina", language: "German", locale: "de-DE", gender: "feminine", polyglot: false },
+      {
+        voiceId: "lennart",
+        name: "Lennart",
+        language: "German",
+        locale: "de-DE",
+        gender: "masculine",
+        polyglot: false
+      },
+      // Spanish (US)
+      { voiceId: "lupe", name: "Lupe", language: "Spanish", locale: "es-US", gender: "feminine", polyglot: false },
+      { voiceId: "carlos", name: "Carlos", language: "Spanish", locale: "es-US", gender: "masculine", polyglot: false },
+      // Portuguese
+      {
+        voiceId: "carolina",
+        name: "Carolina",
+        language: "Portuguese",
+        locale: "pt-BR",
+        gender: "feminine",
+        polyglot: false
+      },
+      { voiceId: "leo", name: "Leo", language: "Portuguese", locale: "pt-BR", gender: "masculine", polyglot: false },
+      // Hindi
+      { voiceId: "kiara", name: "Kiara", language: "Hindi", locale: "hi-IN", gender: "feminine", polyglot: false },
+      { voiceId: "arjun", name: "Arjun", language: "Hindi", locale: "hi-IN", gender: "masculine", polyglot: false }
+    ]);
+  }
+  /**
+   * Establishes a connection to the AWS Bedrock bidirectional streaming service.
+   * Must be called before using speak, listen, or send functions.
+   *
+   * @throws {NovaSonicError} If connection fails or credentials are missing
+   *
+   * @example
+   * ```typescript
+   * await voice.connect();
+   * // Now ready for voice interactions
+   * ```
+   */
+  async connect({ requestContext } = {}) {
+    if (this.state === "connected" || this.state === "connecting") {
+      this.log("Already connected or connecting");
+      return;
+    }
+    this.state = "connecting";
+    this.requestContext = requestContext;
+    this.streamRestartAttempted = false;
+    try {
+      await this.createBedrockClient();
+      const asyncIterable = this.createEventQueue();
+      this.enqueueInitialSessionEvents();
+      await this.sendInitialConnectCommand(asyncIterable);
+      this.processStream().catch((error) => {
+        this.log("Error in stream processing:", error);
+        this.emit("error", {
+          message: error instanceof Error ? error.message : "Stream processing error",
+          code: "STREAM_PROCESSING_ERROR",
+          details: error
+        });
+      });
+      this.log("Connected to AWS Bedrock Nova 2 Sonic");
+    } catch (error) {
+      this.state = "disconnected";
+      if (this.client) {
+        if (typeof this.client.destroy === "function") {
+          this.client.destroy();
+        }
+        this.client = void 0;
+      }
+      this.log("Connection error:", error);
+      const errorMessage = error instanceof Error ? error.message : "Unknown error during connection";
+      throw new NovaSonicError("connection_failed" /* CONNECTION_FAILED */, `Failed to connect to AWS Bedrock: ${errorMessage}`, error);
+    }
+  }
+  /**
+   * Resolve credentials and initialize the Bedrock Runtime client over HTTP/2.
+   */
+  async createBedrockClient() {
+    this.log("Getting AWS credentials...");
+    const credentials = await getAwsCredentials(this.credentials, this.debug);
+    if (!credentials) {
+      throw new NovaSonicError(
+        "credentials_missing" /* CREDENTIALS_MISSING */,
+        "AWS credentials are required. Please configure AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables or provide credentials in the config."
+      );
+    }
+    this.log("Credentials retrieved:", {
+      hasAccessKeyId: !!credentials.accessKeyId,
+      hasSecretAccessKey: !!credentials.secretAccessKey,
+      hasSessionToken: !!credentials.sessionToken,
+      accessKeyIdPrefix: credentials.accessKeyId ? `${credentials.accessKeyId.substring(0, 6)}...` : "missing",
+      expiration: credentials.expiration ? credentials.expiration.toISOString() : "no expiration"
+    });
+    this.log(`Initializing Bedrock Runtime client for region: ${this.region}, model: ${this.model}`);
+    const nodeHttp2Handler = new NodeHttp2Handler({
+      requestTimeout: 3e5,
+      // 5 minutes
+      sessionTimeout: 3e5,
+      // 5 minutes
+      disableConcurrentStreams: false,
+      maxConcurrentStreams: 20
+    });
+    this.client = new BedrockRuntimeClient({
+      region: this.region,
+      credentials,
+      requestHandler: nodeHttp2Handler
+    });
+  }
+  /**
+   * Build the async-iterable event queue used as the request body for the
+   * bidirectional stream. Returns the iterable and wires up internal queue
+   * helpers (_eventQueue, _signalQueue, _closeSignal) used by sendClientEvent.
+   */
+  createEventQueue() {
+    this.log("Creating bidirectional stream command...");
+    const voiceInstance = this;
+    const eventQueue = [];
+    const pendingResolvers = [];
+    let closeSignal = false;
+    const signalQueue = () => {
+      if (pendingResolvers.length > 0) {
+        voiceInstance.log(`[AsyncIterable] Signaling queue - resolving ${pendingResolvers.length} pending Promise(s)`);
+        const resolvers = [...pendingResolvers];
+        pendingResolvers.length = 0;
+        resolvers.forEach((resolve) => resolve());
+      } else {
+        voiceInstance.log("[AsyncIterable] signalQueue called but no pending Promise");
+      }
+    };
+    const asyncIterable = {
+      [Symbol.asyncIterator]: () => {
+        voiceInstance.log("[AsyncIterable] Iterator requested");
+        return {
+          next: async () => {
+            try {
+              if (closeSignal || voiceInstance.state === "disconnected") {
+                voiceInstance.log(`[AsyncIterable] Stream closed (state: ${voiceInstance.state}), done = true`);
+                return { value: void 0, done: true };
+              }
+              if (eventQueue.length === 0) {
+                try {
+                  voiceInstance.log("[AsyncIterable] Queue empty, waiting for signal...");
+                  await new Promise((resolve) => {
+                    pendingResolvers.push(resolve);
+                    voiceInstance.log(
+                      `[AsyncIterable] Promise created, waiting for signal (${pendingResolvers.length} pending)...`
+                    );
+                    setImmediate(() => {
+                      if (eventQueue.length > 0) {
+                        voiceInstance.log("[AsyncIterable] Data arrived before wait, resolving immediately");
+                        const index = pendingResolvers.indexOf(resolve);
+                        if (index !== -1) {
+                          pendingResolvers.splice(index, 1);
+                          resolve();
+                        }
+                        return;
+                      }
+                      if (closeSignal || voiceInstance.state === "disconnected") {
+                        voiceInstance.log("[AsyncIterable] Closed before wait, resolving");
+                        const index = pendingResolvers.indexOf(resolve);
+                        if (index !== -1) {
+                          pendingResolvers.splice(index, 1);
+                          resolve();
+                        }
+                        return;
+                      }
+                    });
+                  });
+                  voiceInstance.log("[AsyncIterable] Promise resolved, checking queue...");
+                } catch (error) {
+                  if (error instanceof Error && error.message === "Stream closed") {
+                    voiceInstance.log("[AsyncIterable] Stream closed during wait");
+                    return { value: void 0, done: true };
+                  }
+                  voiceInstance.log("[AsyncIterable] Error during wait:", error);
+                }
+              }
+              if (closeSignal) {
+                voiceInstance.log("[AsyncIterable] Stream closed (closeSignal)");
+                return { value: void 0, done: true };
+              }
+              if (voiceInstance.state === "disconnected") {
+                voiceInstance.log("[AsyncIterable] Stream closed (disconnected state)");
+                return { value: void 0, done: true };
+              }
+              while (eventQueue.length === 0 && !closeSignal) {
+                if (voiceInstance.state === "disconnected") {
+                  voiceInstance.log("[AsyncIterable] Stream closed before wait loop");
+                  return { value: void 0, done: true };
+                }
+                voiceInstance.log("[AsyncIterable] Queue still empty, waiting again...");
+                await new Promise((resolve) => {
+                  pendingResolvers.push(resolve);
+                  setImmediate(() => {
+                    if (eventQueue.length > 0 || closeSignal || voiceInstance.state === "disconnected") {
+                      const index = pendingResolvers.indexOf(resolve);
+                      if (index !== -1) {
+                        pendingResolvers.splice(index, 1);
+                        resolve();
+                      }
+                    }
+                  });
+                });
+                if (closeSignal || voiceInstance.state === "disconnected") {
+                  voiceInstance.log("[AsyncIterable] Stream closed during wait loop");
+                  return { value: void 0, done: true };
+                }
+              }
+              const nextEvent = eventQueue.shift();
+              const eventJson = JSON.stringify(nextEvent);
+              const eventBytes = Buffer.from(eventJson, "utf-8");
+              voiceInstance.log(`[AsyncIterable] Yielding event of size: ${eventBytes.length}`);
+              return {
+                value: {
+                  chunk: {
+                    bytes: eventBytes
+                  }
+                },
+                done: false
+              };
+            } catch (error) {
+              voiceInstance.log("[AsyncIterable] Error in iterator:", error);
+              closeSignal = true;
+              return { value: void 0, done: true };
+            }
+          },
+          return: async () => {
+            voiceInstance.log("[AsyncIterable] Iterator return() called");
+            closeSignal = true;
+            signalQueue();
+            return { value: void 0, done: true };
+          },
+          throw: async (error) => {
+            voiceInstance.log("[AsyncIterable] Iterator throw() called:", error);
+            closeSignal = true;
+            signalQueue();
+            throw error;
+          }
+        };
+      }
+    };
+    this._eventQueue = eventQueue;
+    this._signalQueue = signalQueue;
+    this._closeSignal = () => {
+      closeSignal = true;
+      signalQueue();
+    };
+    return asyncIterable;
+  }
+  /**
+   * Pre-populate the event queue with the AWS Nova Sonic connection
+   * handshake events: sessionStart, promptStart, then a SYSTEM text content
+   * block carrying the configured instructions. AUDIO contentStart is NOT
+   * sent here; it is deferred to the first send() call.
+   */
+  enqueueInitialSessionEvents() {
+    const eventQueue = this._eventQueue;
+    if (!eventQueue) {
+      throw new NovaSonicError(
+        "connection_failed" /* CONNECTION_FAILED */,
+        "Event queue must be initialized before enqueueing session events"
+      );
+    }
+    this.log("Pre-populating queue with sessionStart and promptStart events...");
+    const promptName = randomUUID();
+    this._promptName = promptName;
+    const sessionStartEvent = {};
+    if (this.sessionConfig) {
+      if (this.sessionConfig.inferenceConfiguration) {
+        sessionStartEvent.inferenceConfiguration = {
+          maxTokens: this.sessionConfig.inferenceConfiguration.maxTokens || 4096,
+          topP: this.sessionConfig.inferenceConfiguration.topP || 0.9,
+          temperature: this.sessionConfig.inferenceConfiguration.temperature || 0.7,
+          ...this.sessionConfig.inferenceConfiguration.topK !== void 0 && {
+            topK: this.sessionConfig.inferenceConfiguration.topK
+          },
+          ...this.sessionConfig.inferenceConfiguration.stopSequences && {
+            stopSequences: this.sessionConfig.inferenceConfiguration.stopSequences
+          }
+        };
+      } else {
+        sessionStartEvent.inferenceConfiguration = {
+          maxTokens: 4096,
+          topP: 0.9,
+          temperature: 0.7
+        };
+      }
+      if (this.sessionConfig.turnDetectionConfiguration) {
+        sessionStartEvent.turnDetectionConfiguration = {
+          ...this.sessionConfig.turnDetectionConfiguration.endpointingSensitivity && {
+            endpointingSensitivity: this.sessionConfig.turnDetectionConfiguration.endpointingSensitivity
+          }
+        };
+      }
+    } else {
+      sessionStartEvent.inferenceConfiguration = {
+        maxTokens: 4096,
+        topP: 0.9,
+        temperature: 0.7
+      };
+    }
+    eventQueue.push({
+      event: {
+        sessionStart: sessionStartEvent
+      }
+    });
+    let voiceId = "matthew";
+    if (this.sessionConfig?.voice) {
+      if (typeof this.sessionConfig.voice === "string") {
+        voiceId = this.sessionConfig.voice;
+      } else if (this.sessionConfig.voice.name) {
+        voiceId = this.sessionConfig.voice.name;
+      }
+    } else if (this.speaker && this.speaker !== "default") {
+      if (typeof this.speaker === "string") {
+        voiceId = this.speaker;
+      } else {
+        const speakerObj = this.speaker;
+        if (speakerObj && typeof speakerObj === "object" && speakerObj.name) {
+          voiceId = speakerObj.name;
+        }
+      }
+    }
+    const promptStartEvent = {
+      promptName,
+      textOutputConfiguration: {
+        mediaType: "text/plain"
+      },
+      // AWS REQUIRES this - cannot be omitted
+      audioOutputConfiguration: {
+        mediaType: "audio/lpcm",
+        sampleRateHertz: 24e3,
+        sampleSizeBits: 16,
+        channelCount: 1,
+        voiceId,
+        encoding: "base64",
+        audioType: "SPEECH"
+      }
+    };
+    if (this.sessionConfig?.tools && this.sessionConfig.tools.length > 0) {
+      promptStartEvent.toolConfiguration = {
+        tools: this.sessionConfig.tools.map((tool) => {
+          let inputSchemaJson;
+          if (typeof tool.inputSchema === "string") {
+            inputSchemaJson = tool.inputSchema;
+          } else {
+            inputSchemaJson = JSON.stringify(tool.inputSchema);
+          }
+          return {
+            toolSpec: {
+              name: tool.name,
+              description: tool.description,
+              inputSchema: {
+                json: inputSchemaJson
+              }
+            }
+          };
+        }),
+        // toolChoice goes inside toolConfiguration for Nova 2 Sonic
+        ...this.sessionConfig?.toolChoice && { toolChoice: this.sessionConfig.toolChoice }
+      };
+    } else if (this.sessionConfig?.toolChoice) {
+      promptStartEvent.toolConfiguration = {
+        toolChoice: this.sessionConfig.toolChoice
+      };
+    }
+    eventQueue.push({
+      event: {
+        promptStart: promptStartEvent
+      }
+    });
+    this.promptStarted = true;
+    const systemContentName = randomUUID();
+    eventQueue.push({
+      event: {
+        contentStart: {
+          promptName,
+          contentName: systemContentName,
+          type: "TEXT",
+          interactive: false,
+          role: "SYSTEM",
+          textInputConfiguration: {
+            mediaType: "text/plain"
+          }
+        }
+      }
+    });
+    eventQueue.push({
+      event: {
+        textInput: {
+          promptName,
+          contentName: systemContentName,
+          content: this.instructions || ""
+        }
+      }
+    });
+    eventQueue.push({
+      event: {
+        contentEnd: {
+          promptName,
+          contentName: systemContentName
+        }
+      }
+    });
+    this.audioContentStarted = false;
+    this.log(`Queue pre-populated with ${eventQueue.length} event(s)`);
+  }
+  /**
+   * Issue the InvokeModelWithBidirectionalStreamCommand to AWS Bedrock with
+   * a 5-second abort timeout that tears down the client on hang to avoid
+   * leaked HTTP/2 sessions. On success the response stream is stored and the
+   * voice transitions to 'connected'.
+   */
+  async sendInitialConnectCommand(asyncIterable) {
+    if (!this.client) {
+      throw new NovaSonicError(
+        "connection_failed" /* CONNECTION_FAILED */,
+        "Bedrock client must be created before sending the initial command"
+      );
+    }
+    const command = new InvokeModelWithBidirectionalStreamCommand({
+      modelId: this.model,
+      body: asyncIterable
+      // Type assertion needed as SDK types may be strict
+    });
+    const sendStartTime = Date.now();
+    const abortController = new AbortController();
+    const timeoutId = setTimeout(() => {
+      this.log("[DEBUG] client.send() timeout after 5 seconds - aborting request");
+      abortController.abort();
+    }, 5e3);
+    let response;
+    try {
+      response = await this.client.send(command, { abortSignal: abortController.signal });
+    } catch (error) {
+      const sendDuration2 = Date.now() - sendStartTime;
+      if (abortController.signal.aborted) {
+        this.log(`[DEBUG] client.send() aborted after ${sendDuration2}ms`);
+        this._closeSignal?.();
+        this.client.destroy();
+        throw new Error("client.send() timeout");
+      }
+      this.log(`[DEBUG] client.send() error after ${sendDuration2}ms:`, error);
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    const sendDuration = Date.now() - sendStartTime;
+    this.log(`[DEBUG] client.send() completed in ${sendDuration}ms`);
+    this.log("Received response from AWS Bedrock");
+    this.stream = response.body;
+    this.log(
+      `[DEBUG] Response stream is async iterable: ${this.stream && typeof this.stream[Symbol.asyncIterator] === "function"}`
+    );
+    this.state = "connected";
+    this.log(`[STATE] State set to 'connected'`);
+  }
+  /**
+   * Process the bidirectional stream from AWS Bedrock
+   */
+  async processStream() {
+    if (!this.stream) {
+      this.log("[Stream] No stream available, cannot process");
+      return;
+    }
+    if (this.processingStream) {
+      this.log("[Stream] Already processing stream, skipping");
+      return;
+    }
+    this.processingStream = true;
+    this.log("[Stream] Starting stream processing");
+    let eventCount = 0;
+    let lastEventTime = Date.now();
+    try {
+      for await (const chunk of this.stream) {
+        if (chunk.chunk) {
+          const textResponse = Buffer.from(chunk.chunk.bytes || []).toString("utf-8");
+          eventCount++;
+          const now = Date.now();
+          const timeSinceLastEvent = now - lastEventTime;
+          lastEventTime = now;
+          this.log(
+            `[Stream] Received chunk #${eventCount}, length: ${textResponse.length}, time since last: ${timeSinceLastEvent}ms`
+          );
+          try {
+            const jsonResponse = JSON.parse(textResponse);
+            this.log(`[Stream] ========================================`);
+            this.log(`[Stream] Parsed JSON response, keys: ${Object.keys(jsonResponse).join(", ")}`);
+            if (jsonResponse.event) {
+              const eventKeys = Object.keys(jsonResponse.event);
+              this.log(`[Stream] Event keys: ${eventKeys.join(", ")}`);
+              if (jsonResponse.event.contentStart) {
+                this.log(`[Stream] \u2192 Handling contentStart`);
+                this.handleServerEvent({ contentStart: jsonResponse.event.contentStart });
+              } else if (jsonResponse.event.textOutput) {
+                this.log(
+                  `[Stream] \u2192 Handling textOutput, content length: ${jsonResponse.event.textOutput?.content?.length ?? 0}`
+                );
+                this.handleServerEvent({ textOutput: jsonResponse.event.textOutput });
+              } else if (jsonResponse.event.audioOutput) {
+                this.handleServerEvent({ audioOutput: jsonResponse.event.audioOutput });
+              } else if (jsonResponse.event.toolUse) {
+                this.handleServerEvent({ toolUse: jsonResponse.event.toolUse });
+              } else if (jsonResponse.event.contentEnd && jsonResponse.event.contentEnd.type === "TOOL") {
+                this.handleServerEvent({ contentEnd: jsonResponse.event.contentEnd });
+              } else if (jsonResponse.event.contentEnd) {
+                this.log(
+                  `[Stream] Found contentEnd, type: ${jsonResponse.event.contentEnd.type}, stopReason: ${jsonResponse.event.contentEnd.stopReason}`
+                );
+                this.handleServerEvent({ contentEnd: jsonResponse.event.contentEnd });
+              } else if (jsonResponse.event.completionStart) {
+                this.log(
+                  "[Stream] Found completionStart inside event object:",
+                  JSON.stringify(jsonResponse.event.completionStart, null, 2)
+                );
+                this.emit("completionStart", jsonResponse.event.completionStart);
+              } else if (jsonResponse.event.completionEnd) {
+                this.log(
+                  "[Stream] Found completionEnd inside event object:",
+                  JSON.stringify(jsonResponse.event.completionEnd, null, 2)
+                );
+                this.handleServerEvent({ completionEnd: jsonResponse.event.completionEnd });
+              } else {
+                const eventKeys2 = Object.keys(jsonResponse.event || {});
+                this.log(`[Stream] Event keys for other events: ${eventKeys2.join(", ")}`);
+                if (eventKeys2.length > 0) {
+                  if (eventKeys2.includes("completionEnd")) {
+                    this.log("[Stream] Found completionEnd in other events, handling explicitly");
+                    this.handleServerEvent({ completionEnd: jsonResponse.event.completionEnd });
+                  } else {
+                    const eventKey = eventKeys2[0];
+                    this.log(`[Stream] Dispatching other event: ${eventKey}`);
+                    const eventValue = jsonResponse.event[eventKey];
+                    if (eventValue !== void 0) {
+                      if (eventKey === "completionEnd") {
+                        this.handleServerEvent({ completionEnd: eventValue });
+                      } else {
+                        this.handleServerEvent({ [eventKey]: eventValue });
+                      }
+                    }
+                  }
+                } else if (Object.keys(jsonResponse).length > 0) {
+                  this.log(`[Stream] Unknown event structure, keys:`, Object.keys(jsonResponse).join(", "));
+                }
+              }
+            } else {
+              if (this.debug) {
+                this.log(
+                  '[Stream] Received event without "event" wrapper, keys:',
+                  Object.keys(jsonResponse).join(", ")
+                );
+              }
+              if (jsonResponse.usageEvent) {
+                this.emit("usage", {
+                  inputTokens: jsonResponse.usageEvent.totalInputTokens || 0,
+                  outputTokens: jsonResponse.usageEvent.totalOutputTokens || 0,
+                  totalTokens: jsonResponse.usageEvent.totalTokens || 0
+                });
+              }
+              if (jsonResponse.completionEnd) {
+                this.log(
+                  "[Stream] Found completionEnd at top level:",
+                  JSON.stringify(jsonResponse.completionEnd, null, 2)
+                );
+                this.handleServerEvent({ completionEnd: jsonResponse.completionEnd });
+              }
+              if (!jsonResponse.event && !jsonResponse.completionEnd && !jsonResponse.usageEvent) {
+                this.log(
+                  "[Stream] Received response without event wrapper, keys:",
+                  Object.keys(jsonResponse).join(", ")
+                );
+              }
+              if (jsonResponse.completionStart || jsonResponse.event?.completionStart) {
+                const completionStart = jsonResponse.completionStart || jsonResponse.event.completionStart;
+                this.log("[Stream] Found completionStart:", JSON.stringify(completionStart, null, 2));
+                this.emit("completionStart", completionStart);
+              }
+            }
+          } catch (parseError) {
+            this.log("[Stream] Failed to parse JSON response:", textResponse.substring(0, 200));
+            this.emit("error", {
+              message: "Failed to parse stream response",
+              code: "PARSE_ERROR",
+              details: parseError
+            });
+          }
+        } else if (chunk.internalServerException) {
+          this.emit("error", {
+            message: "Internal server error",
+            code: "INTERNAL_SERVER_ERROR",
+            details: chunk.internalServerException
+          });
+        } else if (chunk.modelStreamErrorException) {
+          this.emit("error", {
+            message: "Model stream error",
+            code: "MODEL_STREAM_ERROR",
+            details: chunk.modelStreamErrorException
+          });
+        } else if (chunk.modelTimeoutException) {
+          this.emit("error", {
+            message: "Model timeout",
+            code: "MODEL_TIMEOUT",
+            details: chunk.modelTimeoutException
+          });
+        } else if (chunk.serviceUnavailableException) {
+          this.emit("error", {
+            message: "Service unavailable",
+            code: "SERVICE_UNAVAILABLE",
+            details: chunk.serviceUnavailableException
+          });
+        } else if (chunk.throttlingException) {
+          this.emit("error", {
+            message: "Request throttled",
+            code: "THROTTLING",
+            details: chunk.throttlingException
+          });
+        } else if (chunk.validationException) {
+          this.emit("error", {
+            message: "Validation error",
+            code: "VALIDATION_ERROR",
+            details: chunk.validationException
+          });
+        }
+      }
+    } catch (streamError) {
+      this.log("[Stream] Error in processStream:", streamError);
+      this.emit("error", {
+        message: "Stream processing error",
+        code: "STREAM_ERROR",
+        details: streamError instanceof Error ? streamError.message : String(streamError)
+      });
+    } finally {
+      this.processingStream = false;
+      this.log(
+        `[Stream] processStream finished, processingStream set to false. Total events received: ${eventCount || 0}`
+      );
+      this.log(`[Stream] Stream state: state=${this.state}, stream exists=${!!this.stream}`);
+      if (!this.turnCompleted && this.audioContentStarted) {
+        this.log("[Stream] Stream ended but turn not completed - signaling turn completion as fallback");
+        this.log(
+          `[Stream] State: turnCompleted=${this.turnCompleted}, audioContentStarted=${this.audioContentStarted}, hasSentContentEnd=${this.hasSentContentEnd}`
+        );
+        this.turnCompleted = true;
+        this.emit("turnComplete", { timestamp: Date.now() });
+        if (this.currentResponseId) {
+          const stream = this.speakerStreams.get(this.currentResponseId);
+          if (stream) {
+            stream.end();
+          }
+          this.speakerStreams.delete(this.currentResponseId);
+          this.currentResponseId = void 0;
+        }
+        this.hasSentContentEnd = false;
+        this.log("[Stream] Turn completion signaled, ready for next turn");
+      } else if (this.turnCompleted) {
+        this.log("[Stream] Stream ended and turn was already completed");
+      } else {
+        this.log(
+          `[Stream] Stream ended but turn not completed - audioContentStarted=${this.audioContentStarted}, turnCompleted=${this.turnCompleted}`
+        );
+      }
+      if (this.stream && this.state === "connected" && !this.processingStream && !this.streamRestartAttempted) {
+        this.log("[Stream] Stream still open but processing stopped - will restart stream processing");
+        this.streamRestartAttempted = true;
+        setImmediate(() => {
+          if (this.stream && this.state === "connected" && !this.processingStream) {
+            this.log("[Stream] Restarting stream processing for subsequent turns");
+            this.processStream().catch((error) => {
+              this.log("[Stream] Error restarting stream processing:", error);
+              this.streamRestartAttempted = false;
+            });
+          } else {
+            this.streamRestartAttempted = false;
+          }
+        });
+      } else {
+        if (this.streamRestartAttempted) {
+          this.log("[Stream] Stream restart already attempted, skipping");
+        }
+      }
+    }
+  }
+  /**
+   * Handle server events from AWS Bedrock
+   */
+  handleServerEvent(event) {
+    if (this.debug) {
+      this.log("Received event, keys:", Object.keys(event).join(", "));
+    }
+    if (event.contentStart) {
+      this.handleContentStart(event.contentStart);
+    }
+    if (event.textOutput) {
+      this.handleTextOutput(event.textOutput);
+    }
+    if (event.audioOutput?.content) {
+      this.handleAudioOutput(event.audioOutput);
+    }
+    if (event.toolUse) {
+      this.handleToolUse(event.toolUse);
+    }
+    if (event.contentEnd) {
+      this.handleContentEnd(event.contentEnd);
+    }
+    if (event.completionEnd) {
+      this.handleCompletionEnd(event.completionEnd);
+    }
+    if (event.error) {
+      this.emit("error", {
+        message: event.error.message || "Unknown error",
+        code: event.error.code || "UNKNOWN_ERROR",
+        details: event.error
+      });
+    }
+  }
+  /**
+   * Handle a contentStart event. Tracks generationStage for text content
+   * blocks so the corresponding 'writing' events can be tagged
+   * SPECULATIVE/FINAL for the client.
+   */
+  handleContentStart(contentStart) {
+    const role = contentStart.role?.toLowerCase();
+    const contentType = contentStart.type;
+    this.log(`[Event] contentStart: type=${contentType || "unknown"}, role=${role}`);
+    this.emit("contentStart", contentStart);
+    if (contentType === "TEXT" && contentStart.additionalModelFields) {
+      try {
+        const additionalFields = JSON.parse(contentStart.additionalModelFields);
+        this.currentTextGenerationStage = additionalFields.generationStage;
+        this.log(`[Event] Text content generationStage: ${this.currentTextGenerationStage}`);
+      } catch {
+        this.currentTextGenerationStage = void 0;
+      }
+    } else if (contentType === "TEXT") {
+      this.currentTextGenerationStage = void 0;
+    }
+  }
+  /**
+   * Handle a textOutput event. Detects interruption (barge-in) markers in
+   * the payload, otherwise emits a 'writing' event with the text and
+   * current generationStage.
+   */
+  handleTextOutput(textOutput) {
+    const text = textOutput.content || "";
+    const role = textOutput.role?.toLowerCase() || "assistant";
+    this.log(`[Event] textOutput received: role=${role}, text length=${text.length}`);
+    let isInterrupted = false;
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && parsed.interrupted === true) {
+        isInterrupted = true;
+      }
+    } catch {
+      if (/interrupted/i.test(text)) {
+        isInterrupted = true;
+      }
+    }
+    if (isInterrupted) {
+      this.log(`[Event] Interrupt detected, emitting interrupt event`);
+      this.emit("interrupt", { type: "user", timestamp: Date.now() });
+      return;
+    }
+    const generationStage = this.currentTextGenerationStage;
+    this.log(`[Event] Emitting 'writing': role=${role}, generationStage=${generationStage}, length=${text.length}`);
+    this.emit("writing", { text, role, generationStage });
+  }
+  /**
+   * Handle an audioOutput event. Decodes the base64 LPCM payload, emits
+   * 'speaking' with both the base64 string and an Int16Array view, and
+   * forwards bytes to any active speaker stream.
+   */
+  handleAudioOutput(audioOutput) {
+    try {
+      const content = audioOutput.content;
+      const audioBytes = Buffer.from(content, "base64");
+      this.log(`[Event] Audio output: ${audioBytes.length} bytes`);
+      this.isReceivingAssistantAudio = true;
+      const audioData = new Int16Array(audioBytes.buffer, audioBytes.byteOffset, audioBytes.byteLength / 2);
+      this.emit("speaking", {
+        audio: content,
+        audioData,
+        response_id: this.currentResponseId
+      });
+      if (this.currentResponseId) {
+        const stream = this.speakerStreams.get(this.currentResponseId);
+        if (stream) {
+          stream.write(audioBytes);
+        }
+      }
+    } catch (error) {
+      this.log("[Event] Error decoding audio:", error);
+      this.emit("error", {
+        message: "Failed to decode audio",
+        code: "AUDIO_DECODE_ERROR",
+        details: error
+      });
+    }
+  }
+  /**
+   * Handle a toolUse event. Emits 'toolCall' and dispatches to the
+   * configured tool's execute() function via handleToolCall().
+   */
+  handleToolUse(toolUse) {
+    const toolUseId = toolUse.toolUseId || "";
+    const toolName = toolUse.toolName || "";
+    const toolInput = toolUse.input || {};
+    this.emit("toolCall", {
+      name: toolName,
+      args: toolInput,
+      id: toolUseId
+    });
+    if (this.tools && toolName in this.tools) {
+      void this.handleToolCall(toolName, toolInput, toolUseId);
+    }
+  }
+  /**
+   * Handle a contentEnd event. Forwards it to clients, then routes by
+   * stopReason / type:
+   *   - INTERRUPTED: emit 'interrupt' and tear down the active speaker stream
+   *   - TOOL: end the active speaker stream
+   *   - AUDIO with END_TURN: signal turnComplete (assistant audio finished)
+   *   - AUDIO with PARTIAL_TURN while receiving assistant audio: schedule
+   *     fallback turnComplete in case completionEnd never arrives
+   *   - AUDIO otherwise: user input ended, reset turn flags
+   */
+  handleContentEnd(contentEnd) {
+    this.log(`[Event] contentEnd received: type=${contentEnd.type}, stopReason=${contentEnd.stopReason}`);
+    this.emit("contentEnd", contentEnd);
+    if (contentEnd.stopReason === "INTERRUPTED") {
+      this.log("[Event] Content interrupted by user (barge-in)");
+      this.emit("interrupt", { type: "user", timestamp: Date.now() });
+      if (this.currentResponseId) {
+        const stream = this.speakerStreams.get(this.currentResponseId);
+        if (stream) {
+          stream.destroy();
+        }
+        this.speakerStreams.delete(this.currentResponseId);
+      }
+      this.currentResponseId = void 0;
+      this.log("[Event] After interruption, keeping audioContentStarted=true for continued streaming");
+    } else if (contentEnd.type === "TOOL" && this.currentResponseId) {
+      const stream = this.speakerStreams.get(this.currentResponseId);
+      if (stream) {
+        stream.end();
+      }
+    } else if (contentEnd.type === "AUDIO") {
+      if (contentEnd.stopReason === "END_TURN") {
+        this.log(`[Event] contentEnd (AUDIO) with stopReason END_TURN - signaling turn complete`);
+        if (this.currentResponseId) {
+          const stream = this.speakerStreams.get(this.currentResponseId);
+          if (stream) {
+            stream.end();
+          }
+          this.speakerStreams.delete(this.currentResponseId);
+          this.currentResponseId = void 0;
+        }
+        if (!this.turnCompleted) {
+          this.turnCompleted = true;
+          this.emit("turnComplete", { timestamp: Date.now() });
+          this.hasSentContentEnd = false;
+          this.log(
+            `[Event] Turn complete (from contentEnd AUDIO with END_TURN), ready for next turn. audioContentStarted: ${this.audioContentStarted}, audioContentName: ${this.audioContentName}`
+          );
+        } else {
+          this.log(
+            `[Event] contentEnd (AUDIO) with END_TURN received but turn already completed - skipping duplicate turnComplete emission`
+          );
+        }
+        if (!this.turnCompleteTimeout) {
+          this.turnCompleteTimeout = setTimeout(() => {
+            this.log(`[Event] Timeout: completionEnd not received, but turn already completed from contentEnd`);
+            this.turnCompleteTimeout = void 0;
+          }, 1e3);
+        }
+      } else {
+        if (this.isReceivingAssistantAudio && contentEnd.stopReason === "PARTIAL_TURN") {
+          this.isReceivingAssistantAudio = false;
+          if (!this.turnCompleteTimeout && !this.turnCompleted) {
+            this.log(
+              `[Event] contentEnd (AUDIO) with PARTIAL_TURN for assistant output - waiting for completionEnd, setting fallback timeout`
+            );
+            this.turnCompleteTimeout = setTimeout(() => {
+              if (!this.turnCompleted) {
+                this.log(
+                  `[Event] Fallback: completionEnd not received after contentEnd (AUDIO) with PARTIAL_TURN, signaling turn complete`
+                );
+                this.turnCompleted = true;
+                this.emit("turnComplete", { timestamp: Date.now() });
+                if (this.currentResponseId) {
+                  const stream = this.speakerStreams.get(this.currentResponseId);
+                  if (stream) {
+                    stream.end();
+                  }
+                  this.speakerStreams.delete(this.currentResponseId);
+                  this.currentResponseId = void 0;
+                }
+                this.hasSentContentEnd = false;
+                this.turnCompleteTimeout = void 0;
+              }
+            }, 2e3);
+          }
+        } else {
+          this.hasSentContentEnd = false;
+          this.turnCompleted = false;
+          this.log(
+            `[Event] contentEnd (AUDIO) - user input ended, stopReason: ${contentEnd.stopReason}. Keeping audioContentStarted=true for next turn. Reset hasSentContentEnd=false, turnCompleted=false.`
+          );
+        }
+      }
+    } else if (contentEnd.type === "TEXT") {
+      this.currentTextGenerationStage = void 0;
+      this.log(
+        `[Event] contentEnd (TEXT) received, stopReason: ${contentEnd.stopReason}. Turn completion handled by completionEnd/contentEnd(AUDIO).`
+      );
+      if (contentEnd.stopReason === "END_TURN") {
+        this.hasSentContentEnd = false;
+      }
+    }
+  }
+  /**
+   * Handle a completionEnd event. AWS uses this as the definitive signal
+   * that a turn (and all audio output) has finished. Tears down the active
+   * speaker stream, clears any fallback timer, emits 'turnComplete' once,
+   * and forwards token usage if reported.
+   */
+  handleCompletionEnd(completionEnd) {
+    this.log(`[Event] completionEnd received, stopReason: ${completionEnd.stopReason}`);
+    if (this.turnCompleteTimeout) {
+      clearTimeout(this.turnCompleteTimeout);
+      this.turnCompleteTimeout = void 0;
+    }
+    if (this.currentResponseId) {
+      const stream = this.speakerStreams.get(this.currentResponseId);
+      if (stream) {
+        stream.end();
+      }
+      this.speakerStreams.delete(this.currentResponseId);
+      this.currentResponseId = void 0;
+    }
+    this.isReceivingAssistantAudio = false;
+    if (!this.turnCompleted) {
+      this.log(
+        `[Event] completionEnd - signaling turn complete (stopReason: ${completionEnd.stopReason || "undefined"})`
+      );
+      this.turnCompleted = true;
+      this.emit("turnComplete", { timestamp: Date.now() });
+      this.hasSentContentEnd = false;
+    } else {
+      this.log(`[Event] completionEnd received but turn already completed - skipping duplicate turnComplete emission`);
+    }
+    if (completionEnd.usage) {
+      this.emit("usage", {
+        inputTokens: completionEnd.usage.inputTokens || 0,
+        outputTokens: completionEnd.usage.outputTokens || 0,
+        totalTokens: (completionEnd.usage.inputTokens || 0) + (completionEnd.usage.outputTokens || 0)
+      });
+    }
+  }
+  /**
+   * Handle tool execution
+   */
+  async handleToolCall(toolName, args, toolUseId) {
+    const tool = this.tools?.[toolName];
+    if (!tool || !tool.execute) {
+      this.emit("error", {
+        message: `Tool ${toolName} not found or has no execute function`,
+        code: "TOOL_NOT_FOUND"
+      });
+      return;
+    }
+    try {
+      const result = await tool.execute(
+        { context: args, requestContext: this.requestContext },
+        {
+          toolCallId: toolUseId,
+          messages: []
+        }
+      );
+      await this.sendClientEvent({
+        toolResult: {
+          toolUseId,
+          content: [
+            {
+              json: typeof result === "object" ? result : { result }
+            }
+          ]
+        }
+      });
+    } catch (error) {
+      this.emit("error", {
+        message: `Error executing tool ${toolName}: ${error instanceof Error ? error.message : "Unknown error"}`,
+        code: "TOOL_EXECUTION_ERROR",
+        details: error
+      });
+      await this.sendClientEvent({
+        toolResult: {
+          toolUseId,
+          content: [
+            {
+              text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+            }
+          ]
+        }
+      });
+    }
+  }
+  /**
+   * Send a client event to AWS Bedrock
+   * Events are sent through the input stream that was passed to the bidirectional stream command
+   */
+  async sendClientEvent(event) {
+    if (this.state !== "connected") {
+      throw new NovaSonicError("not_connected" /* NOT_CONNECTED */, "Not connected to AWS Bedrock. Call connect() first.");
+    }
+    try {
+      const eventQueue = this._eventQueue;
+      const signalQueue = this._signalQueue;
+      if (!eventQueue || !signalQueue) {
+        throw new NovaSonicError(
+          "not_connected" /* NOT_CONNECTED */,
+          "Event queue not initialized. Connection may not be fully established."
+        );
+      }
+      this.log(`[sendClientEvent] Adding event to queue (queue size: ${eventQueue.length})`);
+      eventQueue.push({ event });
+      this.log(`[sendClientEvent] Event added, queue size now: ${eventQueue.length}, signaling...`);
+      signalQueue();
+      this.log(`[sendClientEvent] Signal sent`);
+      if (this.debug) {
+        this.log("Sent client event, keys:", Object.keys(event).join(", "));
+      }
+    } catch (error) {
+      throw new NovaSonicError(
+        "websocket_error" /* WEBSOCKET_ERROR */,
+        `Failed to send client event: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
+  /**
+   * Disconnects from the AWS Bedrock session and cleans up resources.
+   *
+   * Pushes a `sessionEnd` event to the queue before signalling close,
+   * then schedules client destruction on the next tick so the async
+   * iterator has a chance to yield the event to the SDK.
+   */
+  close() {
+    if (this.state === "disconnected") {
+      return;
+    }
+    this.state = "disconnected";
+    this.processingStream = false;
+    if (this.turnCompleteTimeout) {
+      clearTimeout(this.turnCompleteTimeout);
+      this.turnCompleteTimeout = void 0;
+    }
+    const eventQueue = this._eventQueue;
+    const signalQueue = this._signalQueue;
+    if (eventQueue && signalQueue) {
+      eventQueue.push({ event: { sessionEnd: {} } });
+      signalQueue();
+    }
+    const closeSignal = this._closeSignal;
+    if (closeSignal) {
+      closeSignal();
+    }
+    if (this.inputStream) {
+      this.inputStream.end();
+      this.inputStream = void 0;
+    }
+    for (const stream of this.speakerStreams.values()) {
+      stream.end();
+    }
+    this.speakerStreams.clear();
+    const client = this.client;
+    this.client = void 0;
+    this.stream = void 0;
+    if (client) {
+      setImmediate(() => {
+        if (typeof client.destroy === "function") {
+          client.destroy();
+        }
+      });
+    }
+    this.log("Disconnected from AWS Bedrock Nova 2 Sonic");
+  }
+  /**
+   * Equips the voice instance with a set of instructions.
+   */
+  addInstructions(instructions) {
+    this.instructions = instructions;
+  }
+  /**
+   * Equips the voice instance with a set of tools.
+   */
+  addTools(tools) {
+    this.tools = tools || {};
+  }
+  /**
+   * Convert text to speech
+   */
+  async speak(input, _options) {
+    if (this.state !== "connected") {
+      throw new NovaSonicError("not_connected" /* NOT_CONNECTED */, "Not connected. Call connect() first.");
+    }
+    let text = "";
+    if (typeof input !== "string") {
+      const chunks = [];
+      for await (const chunk of input) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+      }
+      text = Buffer.concat(chunks).toString("utf-8");
+    } else {
+      text = input;
+    }
+    if (text.trim().length === 0) {
+      throw new NovaSonicError("validation_error" /* VALIDATION_ERROR */, "Input text is empty");
+    }
+    this.currentResponseId = `response-${Date.now()}`;
+    const speakerStream = new PassThrough();
+    speakerStream.id = this.currentResponseId;
+    this.speakerStreams.set(this.currentResponseId, speakerStream);
+    this.emit("speaker", speakerStream);
+    const promptName = this._promptName;
+    if (!promptName) {
+      throw new NovaSonicError(
+        "not_connected" /* NOT_CONNECTED */,
+        "Prompt name not initialized. Connection may not be fully established."
+      );
+    }
+    if (!this.promptStarted) {
+      throw new NovaSonicError(
+        "invalid_state" /* INVALID_STATE */,
+        "Prompt not started. This should not happen - prompt should be started during connection."
+      );
+    }
+    const contentName = randomUUID();
+    await this.sendClientEvent({
+      contentStart: {
+        promptName,
+        contentName,
+        type: "TEXT",
+        interactive: true,
+        role: "USER",
+        textInputConfiguration: {
+          mediaType: "text/plain"
+        }
+      }
+    });
+    await this.sendClientEvent({
+      textInput: {
+        promptName,
+        contentName,
+        content: text
+      }
+    });
+    await this.sendClientEvent({
+      contentEnd: {
+        promptName,
+        contentName
+      }
+    });
+  }
+  /**
+   * Convert speech to text (transcription)
+   * For Nova Sonic, this is the same as send() - both stream audio input
+   */
+  async listen(audioStream, _options) {
+    if (audioStream && typeof audioStream === "object" && "read" in audioStream) {
+      await this.send(audioStream);
+    } else {
+      throw new NovaSonicError("invalid_audio_format" /* INVALID_AUDIO_FORMAT */, "Unsupported audio stream format for listen()");
+    }
+  }
+  /**
+   * Streams audio data in real-time to the AWS Bedrock service.
+   * Following AWS Nova 2 Sonic event sequence:
+   * 1. contentStart (AUDIO, USER) - if not already sent
+   * 2. audioInput events (one per chunk)
+   * 3. contentEnd - when audio stream ends (handled separately via endAudioInput)
+   */
+  async send(audioData) {
+    this.log(`[send] Current state: ${this.state}`);
+    if (this.state !== "connected") {
+      this.log(`[send] ERROR: State is '${this.state}', expected 'connected'`);
+      throw new NovaSonicError(
+        "not_connected" /* NOT_CONNECTED */,
+        `Not connected. Current state: ${this.state}. Call connect() first.`
+      );
+    }
+    this.log(`[send] State check passed, proceeding with send`);
+    if (!(audioData instanceof Int16Array) && !(audioData && typeof audioData === "object" && "read" in audioData)) {
+      throw new NovaSonicError("invalid_audio_format" /* INVALID_AUDIO_FORMAT */, "Unsupported audio data format");
+    }
+    if (this.turnCompleted || this.hasSentContentEnd) {
+      this.log(
+        `[send] Starting new turn - resetting flags. turnCompleted=${this.turnCompleted}, hasSentContentEnd=${this.hasSentContentEnd}.`
+      );
+      const needNewContent = this.hasSentContentEnd;
+      this.turnCompleted = false;
+      this.hasSentContentEnd = false;
+      this.streamRestartAttempted = false;
+      if (needNewContent) {
+        this.audioContentStarted = false;
+        this.log(`[send] contentEnd was previously sent - will create new audio content container`);
+      }
+      this.log(
+        `[send] State reset: turnCompleted=false, hasSentContentEnd=false, audioContentStarted=${this.audioContentStarted}`
+      );
+    }
+    if (!this.promptStarted) {
+      this.promptStarted = true;
+    }
+    const promptName = this._promptName;
+    if (!promptName) {
+      throw new NovaSonicError(
+        "not_connected" /* NOT_CONNECTED */,
+        "Prompt name not initialized. Connection may not be fully established."
+      );
+    }
+    if (!this.audioContentStarted) {
+      const audioContentId = randomUUID();
+      this.audioContentName = audioContentId;
+      this.log(`[send] First audio send - sending AUDIO contentStart with contentName: ${audioContentId}`);
+      await this.sendClientEvent({
+        contentStart: {
+          promptName,
+          contentName: audioContentId,
+          type: "AUDIO",
+          interactive: true,
+          role: "USER",
+          audioInputConfiguration: {
+            mediaType: "audio/lpcm",
+            sampleRateHertz: 16e3,
+            sampleSizeBits: 16,
+            channelCount: 1,
+            encoding: "base64",
+            audioType: "SPEECH"
+          }
+        }
+      });
+      this.audioContentStarted = true;
+      this.log(`[send] AUDIO contentStart sent, ready to stream audio`);
+    } else {
+      this.log(`[send] AUDIO contentStart already sent, sending audioInput chunks directly`);
+    }
+    if (!this.audioContentName) {
+      throw new NovaSonicError("invalid_state" /* INVALID_STATE */, "Audio content name not initialized. This should not happen.");
+    }
+    const contentName = this.audioContentName;
+    if (audioData instanceof Int16Array) {
+      const buffer = Buffer.from(audioData.buffer, audioData.byteOffset, audioData.byteLength);
+      const base64Audio = buffer.toString("base64");
+      this.log(
+        `[send] Sending audioInput chunk, size: ${buffer.length} bytes, contentName: ${contentName}, turnCompleted: ${this.turnCompleted}, hasSentContentEnd: ${this.hasSentContentEnd}, audioContentStarted: ${this.audioContentStarted}, state: ${this.state}`
+      );
+      if (this.state !== "connected") {
+        this.log(`[send] ERROR: State changed to '${this.state}' during send!`);
+        throw new NovaSonicError("not_connected" /* NOT_CONNECTED */, `Connection lost during send. State: ${this.state}`);
+      }
+      await this.sendClientEvent({
+        audioInput: {
+          promptName,
+          contentName,
+          content: base64Audio
+        }
+      });
+      this.log(`[send] audioInput chunk sent successfully`);
+    } else if (audioData && typeof audioData === "object" && "read" in audioData) {
+      const stream = audioData;
+      for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        const base64Audio = buffer.toString("base64");
+        this.log(
+          `[send] Sending audioInput chunk from stream, size: ${buffer.length} bytes, contentName: ${contentName}, turnCompleted: ${this.turnCompleted}, hasSentContentEnd: ${this.hasSentContentEnd}`
+        );
+        await this.sendClientEvent({
+          audioInput: {
+            promptName,
+            contentName,
+            content: base64Audio
+          }
+        });
+      }
+    } else {
+      throw new NovaSonicError("invalid_audio_format" /* INVALID_AUDIO_FORMAT */, "Unsupported audio data format");
+    }
+  }
+  /**
+   * End audio input stream (sends contentEnd for audio)
+   * Call this when done sending audio chunks
+   */
+  async endAudioInput() {
+    if (this.hasSentContentEnd) {
+      this.log("[endAudioInput] contentEnd already sent for this turn, skipping");
+      return;
+    }
+    if (this.turnCompleted) {
+      this.log(
+        "[endAudioInput] Turn already completed by AWS, skipping contentEnd. Resetting turnCompleted flag for next turn."
+      );
+      this.turnCompleted = false;
+      this.hasSentContentEnd = false;
+      return;
+    }
+    if (this.audioContentStarted && this.audioContentName && this._promptName) {
+      const promptName = this._promptName;
+      this.log("[endAudioInput] Sending contentEnd for audio input");
+      await this.sendClientEvent({
+        contentEnd: {
+          promptName,
+          contentName: this.audioContentName
+        }
+      });
+      this.hasSentContentEnd = true;
+    } else {
+      this.log(
+        "[endAudioInput] Cannot send contentEnd: audioContentStarted=" + this.audioContentStarted + ", audioContentName=" + this.audioContentName
+      );
+    }
+  }
+  /**
+   * Register an event listener
+   */
+  on(event, callback) {
+    if (!this.events[event]) {
+      this.events[event] = [];
+    }
+    this.events[event].push(callback);
+  }
+  /**
+   * Remove an event listener
+   */
+  off(event, callback) {
+    if (!this.events[event]) {
+      return;
+    }
+    const index = this.events[event].indexOf(callback);
+    if (index !== -1) {
+      this.events[event].splice(index, 1);
+    }
+  }
+  /**
+   * Emit an event with arguments
+   */
+  emit(event, data) {
+    if (!this.events[event]) {
+      this.log(`[NovaSonic] emit('${event}'): No listeners registered for this event`);
+      return;
+    }
+    const listenerCount = this.events[event].length;
+    this.log(`[NovaSonic] emit('${event}'): Calling ${listenerCount} listener(s)`);
+    for (const callback of this.events[event]) {
+      try {
+        callback(data);
+        this.log(`[NovaSonic] emit('${event}'): Successfully called one listener`);
+      } catch (error) {
+        this.log(`Error in event handler for ${event}:`, error);
+      }
+    }
+    this.log(`[NovaSonic] emit('${event}'): Finished calling all ${listenerCount} listener(s)`);
+  }
+  /**
+   * Get listener status
+   */
+  async getListener() {
+    return { enabled: this.state === "connected" };
+  }
+  /**
+   * Log helper
+   */
+  log(...args) {
+    if (this.debug) {
+      console.info("[NovaSonicVoice]", ...args);
+    }
+  }
+};
+
+export { NovaSonicError, NovaSonicErrorCode, NovaSonicVoice };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map