@m4trix/core 0.5.0

package/dist/index.js

@@ -0,0 +1,2656 @@
+import { useRef, useState, useCallback, useEffect } from 'react';
+import { io } from 'socket.io-client';
+import { css, LitElement, html } from 'lit';
+import { property, state, customElement } from 'lit/decorators.js';
+import { createRef, ref } from 'lit/directives/ref.js';
+import { createTimeline } from 'animejs';
+import { ToolMessage, AIMessage, HumanMessage } from '@langchain/core/messages';
+import { Effect, pipe } from 'effect';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp(target, key, result);
+  return result;
+};
+
+// src/utility/Logger.ts
+var _Logger = class _Logger {
+  constructor(namespace = "") {
+    this.namespace = namespace;
+  }
+  static enableGlobalLogging() {
+    _Logger.globalEnabled = true;
+  }
+  static disableGlobalLogging() {
+    _Logger.globalEnabled = false;
+  }
+  formatPrefix() {
+    return this.namespace ? `[${this.namespace}]` : "";
+  }
+  logIfEnabled(level, ...args) {
+    if (!_Logger.globalEnabled)
+      return;
+    const prefix = this.formatPrefix();
+    if (prefix) {
+      console[level](prefix, ...args);
+    } else {
+      console[level](...args);
+    }
+  }
+  log(...args) {
+    this.logIfEnabled("log", ...args);
+  }
+  debug(...args) {
+    this.logIfEnabled("debug", ...args);
+  }
+  info(...args) {
+    this.logIfEnabled("info", ...args);
+  }
+  warn(...args) {
+    this.logIfEnabled("warn", ...args);
+  }
+  error(...args) {
+    this.logIfEnabled("error", ...args);
+  }
+};
+_Logger.globalEnabled = false;
+var Logger = _Logger;
+
+// src/react/adapter/VoiceEndpointAdapter.ts
+var VoiceEndpointAdapter = class {
+  constructor(config) {
+    this.logger = new Logger("SuTr > EndpointAdapter");
+    this.config = config;
+  }
+};
+var BaseVoiceEndpointAdapter = class extends VoiceEndpointAdapter {
+  constructor(config) {
+    super(config);
+  }
+  /**
+   * Send a voice file to the API endpoint and return a Pump stream of audio chunks
+   */
+  async sendVoiceFile({
+    blob,
+    metadata
+  }) {
+    const formData = new FormData();
+    formData.append("audio", blob);
+    if (metadata) {
+      formData.append("metadata", JSON.stringify(metadata));
+    }
+    this.logger.debug("Sending voice file to", this.config.endpoint, formData);
+    const response = await fetch(
+      `${this.config.baseUrl || ""}${this.config.endpoint}`,
+      {
+        method: "POST",
+        headers: this.config.headers,
+        body: formData
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`API error: ${response.status} ${await response.text()}`);
+    }
+    if (!response.body) {
+      throw new Error("No response body");
+    }
+    return response;
+  }
+};
+
+// src/react/utility/audio/InputAudioController.ts
+var InputAudioController = class {
+  constructor() {
+    this.logger = new Logger("@m4trix/core > InputAudioController");
+  }
+};
+
+// src/react/utility/audio/WebAudioInputAudioController.ts
+var DEFAULT_SLICING_INTERVAL = 3e3;
+var WebAudioInputAudioController = class extends InputAudioController {
+  constructor(audioConfig = {}) {
+    super();
+    this.audioConfig = audioConfig;
+    // ─── Recording state ─────────────────────────────────────────────────────
+    this.audioContextState = {
+      context: null,
+      source: null,
+      analyser: null
+    };
+    this.mediaRecorder = null;
+    this.recordedChunks = [];
+    this.recordingStream = null;
+  }
+  get audioContext() {
+    return this.audioContextState.context;
+  }
+  async createAudioContext() {
+    const context = new AudioContext({
+      sampleRate: this.audioConfig.sampleRate || 16e3,
+      latencyHint: "interactive"
+    });
+    const analyser = context.createAnalyser();
+    analyser.fftSize = 2048;
+    return { context, source: null, analyser };
+  }
+  async cleanupAudioContext() {
+    this.logger.debug("Cleaning up audio context");
+    const { source, context } = this.audioContextState;
+    if (source)
+      source.disconnect();
+    if (context)
+      await context.close();
+    this.audioContextState = { context: null, source: null, analyser: null };
+  }
+  async startRecording({
+    onRecordedChunk,
+    onError
+  } = {}) {
+    try {
+      this.logger.debug("Starting recording");
+      this.recordedChunks = [];
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      this.recordingStream = stream;
+      if (!this.audioContextState.context) {
+        this.audioContextState = await this.createAudioContext();
+      }
+      this.mediaRecorder = new MediaRecorder(stream, {
+        mimeType: "audio/webm;codecs=opus"
+      });
+      this.mediaRecorder.ondataavailable = (e) => {
+        if (e.data.size > 0) {
+          this.recordedChunks.push(e.data);
+          onRecordedChunk?.(e.data);
+          this.logger.debug("Recorded chunk", e.data.size);
+        }
+      };
+      this.mediaRecorder.start(DEFAULT_SLICING_INTERVAL);
+      this.logger.debug("MediaRecorder started");
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to start recording");
+      this.logger.error(error);
+      onError?.(error);
+    }
+  }
+  async stopRecording({
+    onRecordingCompleted
+  } = {}) {
+    this.logger.debug("Stopping recording");
+    if (!this.mediaRecorder || this.mediaRecorder.state === "inactive")
+      return;
+    await new Promise((resolve) => {
+      this.mediaRecorder.onstop = async () => {
+        if (this.recordedChunks.length) {
+          const blob = new Blob(this.recordedChunks, { type: "audio/webm" });
+          onRecordingCompleted?.(blob);
+          this.logger.debug("Recording completed", blob.size);
+        }
+        this.recordingStream?.getTracks().forEach((t) => t.stop());
+        this.recordingStream = null;
+        await this.cleanupAudioContext();
+        resolve();
+      };
+      this.mediaRecorder.stop();
+    });
+  }
+  /**
+   * Cleans up all audio recording resources.
+   */
+  cleanup() {
+    this.cleanupAudioContext();
+    if (this.mediaRecorder && this.mediaRecorder.state !== "inactive") {
+      this.mediaRecorder.stop();
+    }
+    if (this.recordingStream) {
+      this.recordingStream.getTracks().forEach((t) => t.stop());
+      this.recordingStream = null;
+    }
+  }
+};
+
+// src/react/utility/audio/OutputAudioController.ts
+var OutputAudioController = class {
+  constructor(loggerName) {
+    this.logger = new Logger(loggerName);
+  }
+};
+
+// src/react/utility/audio/AudioElementOutputAudioController.ts
+var AudioElementOutputAudioController = class extends OutputAudioController {
+  constructor() {
+    super("@m4trix/core > WebApiOutputAudioController");
+    // ─── Playback state ──────────────────────────────────────────────────────
+    this.currentHtmlAudio = null;
+    this.currentAudioUrl = null;
+  }
+  // ─── One-shot playback ────────────────────────────────────────────────────
+  /**
+   * Play either a Blob or a URL string.
+   * Uses <audio> under the hood for maximum browser compatibility.
+   */
+  async playAudio({
+    source,
+    onComplete
+  }) {
+    if (this.currentHtmlAudio) {
+      this.currentHtmlAudio.pause();
+      this.currentHtmlAudio.src = "";
+      if (this.currentAudioUrl && source instanceof Blob) {
+        URL.revokeObjectURL(this.currentAudioUrl);
+      }
+    }
+    const audio = new Audio();
+    this.currentHtmlAudio = audio;
+    let url;
+    if (source instanceof Blob) {
+      url = URL.createObjectURL(source);
+      this.currentAudioUrl = url;
+      audio.onended = () => {
+        URL.revokeObjectURL(url);
+        onComplete?.();
+      };
+    } else {
+      url = source;
+    }
+    audio.src = url;
+    try {
+      await audio.play();
+    } catch (err) {
+      this.logger.error("Playback failed, user gesture may be required", err);
+    }
+  }
+  // ─── Streaming playback ──────────────────────────────────────────────────
+  /**
+   * Stream audio from a Response via MediaSource Extensions.
+   * @param params.response The fetch Response whose body is an audio stream
+   * @param params.mimeCodec MIME type+codec string, e.g. 'audio/mpeg'
+   * @param params.onComplete Optional callback once the stream ends
+   */
+  async playAudioStream({
+    response,
+    mimeCodec = "audio/mpeg",
+    onComplete
+  }) {
+    if (!response.ok || !response.body) {
+      throw new Error(`Invalid response (${response.status})`);
+    }
+    if (typeof MediaSource === "undefined" || !MediaSource.isTypeSupported(mimeCodec)) {
+      throw new Error(`Unsupported MIME type or codec: ${mimeCodec}`);
+    }
+    await this.stopPlayback();
+    const mediaSource = new MediaSource();
+    const url = URL.createObjectURL(mediaSource);
+    this.currentAudioUrl = url;
+    const audio = new Audio(url);
+    this.currentHtmlAudio = audio;
+    audio.autoplay = true;
+    audio.onended = () => {
+      URL.revokeObjectURL(url);
+      this.currentAudioUrl = null;
+      onComplete?.();
+    };
+    mediaSource.addEventListener(
+      "sourceopen",
+      () => {
+        const sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
+        const reader = response.body.getReader();
+        const pump = async () => {
+          const { done, value } = await reader.read();
+          if (done) {
+            mediaSource.endOfStream();
+            return;
+          }
+          if (value) {
+            sourceBuffer.appendBuffer(value);
+          }
+          if (sourceBuffer.updating) {
+            sourceBuffer.addEventListener("updateend", pump, { once: true });
+          } else {
+            pump();
+          }
+        };
+        pump();
+      },
+      { once: true }
+    );
+    try {
+      await audio.play();
+    } catch (err) {
+      this.logger.error(
+        "Streaming playback failed, user gesture may be required",
+        err
+      );
+    }
+  }
+  // ─── Chunk-based streaming playback ─────────────────────────────────────
+  /**
+   * Initialize a streaming audio context for chunk-based playback.
+   * This creates the necessary MediaSource and SourceBuffer for subsequent chunk additions.
+   * Returns functions to add chunks and end the stream, encapsulated in a closure.
+   *
+   * @param mimeCodec MIME type+codec string, e.g. 'audio/mpeg'
+   * @param onComplete Optional callback once the stream ends
+   * @returns Object containing functions to add chunks and end the stream
+   */
+  async initializeChunkStream({
+    onComplete,
+    mimeCodec = "audio/mpeg"
+  }) {
+    this.logger.debug(`Initializing chunk stream with codec: ${mimeCodec}`);
+    if (typeof MediaSource === "undefined") {
+      throw new Error("MediaSource API is not supported in this browser");
+    }
+    if (!MediaSource.isTypeSupported(mimeCodec)) {
+      this.logger.warn(
+        `Codec ${mimeCodec} not supported, falling back to standard audio/mpeg`
+      );
+      mimeCodec = "audio/mpeg";
+      if (!MediaSource.isTypeSupported(mimeCodec)) {
+        throw new Error(
+          "Neither the specified codec nor the fallback codec are supported"
+        );
+      }
+    }
+    await this.stopPlayback();
+    const mediaSource = new MediaSource();
+    let sourceBuffer = null;
+    const url = URL.createObjectURL(mediaSource);
+    this.currentAudioUrl = url;
+    const audio = new Audio(url);
+    this.currentHtmlAudio = audio;
+    audio.autoplay = false;
+    audio.controls = true;
+    audio.style.display = "none";
+    document.body.appendChild(audio);
+    let playbackStarted = false;
+    let hasReceivedFirstChunk = false;
+    let receivedChunksCount = 0;
+    const pendingChunks = [];
+    let isProcessingQueue = false;
+    this.logger.debug("Waiting for MediaSource to open...");
+    await new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("MediaSource failed to open (timeout)"));
+      }, 5e3);
+      mediaSource.addEventListener(
+        "sourceopen",
+        () => {
+          clearTimeout(timeout);
+          this.logger.debug("MediaSource open event received");
+          try {
+            sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
+            if (mediaSource.duration === Infinity || isNaN(mediaSource.duration)) {
+              mediaSource.duration = 1e3;
+            }
+            this.logger.debug("SourceBuffer created successfully");
+            resolve();
+          } catch (err) {
+            reject(new Error(`Failed to create SourceBuffer: ${err}`));
+          }
+        },
+        { once: true }
+      );
+    });
+    const logger = this.logger;
+    const processQueue = async () => {
+      if (!sourceBuffer || pendingChunks.length === 0 || isProcessingQueue) {
+        return;
+      }
+      isProcessingQueue = true;
+      try {
+        while (pendingChunks.length > 0) {
+          if (sourceBuffer.updating) {
+            await new Promise((resolve) => {
+              sourceBuffer.addEventListener("updateend", () => resolve(), {
+                once: true
+              });
+            });
+          }
+          const nextChunk = pendingChunks.shift();
+          if (!nextChunk)
+            continue;
+          try {
+            sourceBuffer.appendBuffer(nextChunk);
+            logger.debug(
+              `Processed queued chunk of size ${nextChunk.byteLength}`
+            );
+            if (!playbackStarted && hasReceivedFirstChunk) {
+              await tryStartPlayback();
+            }
+            await new Promise((resolve) => {
+              sourceBuffer.addEventListener("updateend", () => resolve(), {
+                once: true
+              });
+            });
+          } catch (err) {
+            logger.error("Error appending queued chunk to source buffer", err);
+          }
+        }
+      } finally {
+        isProcessingQueue = false;
+      }
+    };
+    const tryStartPlayback = async () => {
+      if (playbackStarted)
+        return;
+      playbackStarted = true;
+      logger.debug("Attempting to start audio playback...");
+      if (receivedChunksCount < 3 && audio.buffered.length > 0 && audio.buffered.end(0) < 0.5) {
+        logger.debug("Not enough data buffered yet, delaying playback");
+        return;
+      }
+      try {
+        if (audio.readyState === 0) {
+          logger.debug(
+            "Audio element not ready yet, waiting for canplay event"
+          );
+          await new Promise((resolve) => {
+            audio.addEventListener("canplay", () => resolve(), { once: true });
+          });
+        }
+        await audio.play();
+        logger.debug("Successfully started audio playback");
+      } catch (err) {
+        logger.error("Failed to start playback", err);
+        document.addEventListener(
+          "click",
+          async () => {
+            try {
+              await audio.play();
+              logger.debug("Started playback after user interaction");
+            } catch (innerErr) {
+              logger.error(
+                "Still failed to play after user interaction",
+                innerErr
+              );
+            }
+          },
+          { once: true }
+        );
+      }
+    };
+    const addChunkToStream = async (chunk) => {
+      if (!sourceBuffer) {
+        throw new Error(
+          "Streaming context was closed or not properly initialized."
+        );
+      }
+      let arrayBufferChunk;
+      if (chunk instanceof Blob) {
+        logger.debug("Converting Blob to ArrayBuffer");
+        arrayBufferChunk = await chunk.arrayBuffer();
+      } else {
+        arrayBufferChunk = chunk;
+      }
+      if (!arrayBufferChunk || arrayBufferChunk.byteLength === 0) {
+        logger.warn("Received empty chunk, skipping");
+        return;
+      }
+      if (!hasReceivedFirstChunk) {
+        hasReceivedFirstChunk = true;
+        logger.debug(
+          `First chunk received, size: ${arrayBufferChunk.byteLength} bytes`
+        );
+      }
+      receivedChunksCount++;
+      pendingChunks.push(arrayBufferChunk);
+      logger.debug(
+        `Added chunk #${receivedChunksCount} to queue (size: ${arrayBufferChunk.byteLength} bytes)`
+      );
+      await processQueue();
+      if (!playbackStarted && hasReceivedFirstChunk && receivedChunksCount >= 3) {
+        await tryStartPlayback();
+      }
+    };
+    const endChunkStream = () => {
+      if (mediaSource && mediaSource.readyState === "open") {
+        try {
+          if (pendingChunks.length > 0 || sourceBuffer && sourceBuffer.updating) {
+            logger.debug("Waiting for pending chunks before ending stream");
+            setTimeout(() => endChunkStream(), 200);
+            return;
+          }
+          if (hasReceivedFirstChunk) {
+            mediaSource.endOfStream();
+            logger.debug("MediaSource stream ended successfully");
+          } else {
+            logger.warn("Stream ended without receiving any chunks");
+          }
+        } catch (err) {
+          logger.error("Error ending MediaSource stream", err);
+        }
+      }
+      audio.onended = null;
+      if (audio.parentNode) {
+        audio.parentNode.removeChild(audio);
+      }
+      if (this.currentAudioUrl === url) {
+        this.currentAudioUrl = null;
+        URL.revokeObjectURL(url);
+      }
+      sourceBuffer = null;
+    };
+    audio.onended = () => {
+      logger.debug("Audio playback completed");
+      endChunkStream();
+      onComplete?.();
+    };
+    return {
+      addChunkToStream,
+      endChunkStream
+    };
+  }
+  /**
+   * Stop any ongoing HTMLAudioElement playback.
+   */
+  async stopPlayback() {
+    if (this.currentHtmlAudio) {
+      try {
+        this.currentHtmlAudio.pause();
+        this.currentHtmlAudio.src = "";
+      } catch (err) {
+        this.logger.error("Error stopping playback", err);
+      }
+      this.currentHtmlAudio = null;
+    }
+    if (this.currentAudioUrl) {
+      URL.revokeObjectURL(this.currentAudioUrl);
+      this.currentAudioUrl = null;
+    }
+  }
+  /**
+   * Cleans up all audio playback resources.
+   */
+  cleanup() {
+    this.stopPlayback();
+  }
+};
+
+// src/react/hooks/use-conversation/useConversation.ts
+Logger.enableGlobalLogging();
+function useConversation(endpoint, {
+  onStartRecording,
+  onStopRecording,
+  onReceive,
+  autoPlay = true,
+  downstreamMode = "STREAM",
+  onError,
+  audioConfig = {},
+  requestData = {},
+  endpointConfig = {}
+}) {
+  const { current: logger } = useRef(
+    new Logger("@m4trix/core > useConversation")
+  );
+  const inputAudioControllerRef = useRef(void 0);
+  const outputAudioControllerRef = useRef(
+    void 0
+  );
+  const endpointAdapterRef = useRef(
+    void 0
+  );
+  const [voiceAgentState, setVoiceAgentState] = useState("READY");
+  const [error, setError] = useState(null);
+  const handleError = useCallback(
+    (state2, err) => {
+      setError(err);
+      logger.error(`Error during ${state2}:`, err);
+      onError?.(state2, err);
+    },
+    [onError]
+  );
+  const startRecording = useCallback(() => {
+    if (inputAudioControllerRef.current) {
+      try {
+        logger.debug("Starting recording");
+        setVoiceAgentState("RECORDING");
+        inputAudioControllerRef.current.startRecording({
+          onError: (err) => {
+            handleError("RECORDING", err);
+          }
+        });
+        onStartRecording?.();
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("RECORDING", err);
+        }
+      }
+    }
+  }, [onStartRecording, handleError]);
+  const stopRecording = useCallback(async () => {
+    if (inputAudioControllerRef.current) {
+      try {
+        logger.debug("Stopping recording");
+        await inputAudioControllerRef.current.stopRecording({
+          onRecordingCompleted: async (allData) => {
+            setVoiceAgentState("PROCESSING");
+            try {
+              const response = await endpointAdapterRef.current?.sendVoiceFile({
+                blob: allData,
+                metadata: requestData
+              });
+              if (!response) {
+                throw new Error("No response received from endpoint");
+              }
+              setVoiceAgentState("RESPONDING");
+              if (autoPlay) {
+                if (downstreamMode === "STREAM") {
+                  await outputAudioControllerRef.current?.playAudioStream({
+                    response,
+                    onComplete: () => {
+                      setVoiceAgentState("READY");
+                    }
+                  });
+                } else if (downstreamMode === "DOWNLOAD") {
+                  const responseBlob = await response.blob();
+                  await outputAudioControllerRef.current?.playAudio({
+                    source: responseBlob,
+                    onComplete: () => {
+                      setVoiceAgentState("READY");
+                    }
+                  });
+                }
+              } else {
+                setVoiceAgentState("READY");
+              }
+              onReceive?.(
+                allData,
+                async () => {
+                  if (outputAudioControllerRef.current) {
+                    if (downstreamMode === "STREAM") {
+                      return outputAudioControllerRef.current.playAudioStream({
+                        response,
+                        onComplete: () => {
+                          setVoiceAgentState("READY");
+                        }
+                      });
+                    } else {
+                      const responseBlob = await response.blob();
+                      return outputAudioControllerRef.current.playAudio({
+                        source: responseBlob,
+                        onComplete: () => {
+                          setVoiceAgentState("READY");
+                        }
+                      });
+                    }
+                  }
+                },
+                async () => {
+                  if (outputAudioControllerRef.current) {
+                    return outputAudioControllerRef.current.stopPlayback();
+                  }
+                }
+              );
+            } catch (err) {
+              if (err instanceof Error) {
+                handleError("PROCESSING", err);
+              }
+              setVoiceAgentState("READY");
+            }
+          }
+        });
+        onStopRecording?.();
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("RECORDING", err);
+        }
+      }
+    }
+  }, [
+    onStopRecording,
+    requestData,
+    autoPlay,
+    downstreamMode,
+    handleError,
+    onReceive
+  ]);
+  useEffect(() => {
+    if (endpointAdapterRef.current) {
+      return;
+    }
+    try {
+      const endpointAdapter = endpointConfig.endpointAdapter ? endpointConfig.endpointAdapter : new BaseVoiceEndpointAdapter({
+        baseUrl: endpointConfig.baseUrl,
+        endpoint,
+        headers: endpointConfig.headers
+      });
+      endpointAdapterRef.current = endpointAdapter;
+      if (!inputAudioControllerRef.current) {
+        inputAudioControllerRef.current = new WebAudioInputAudioController(
+          audioConfig
+        );
+      }
+      if (!outputAudioControllerRef.current) {
+        outputAudioControllerRef.current = new AudioElementOutputAudioController();
+      }
+    } catch (err) {
+      if (err instanceof Error) {
+        handleError("READY", err);
+      }
+    }
+  }, [endpoint, endpointConfig, audioConfig, handleError]);
+  useEffect(() => {
+    return () => {
+      inputAudioControllerRef.current?.cleanup();
+      outputAudioControllerRef.current?.cleanup();
+    };
+  }, []);
+  return {
+    startRecording,
+    stopRecording,
+    voiceAgentState,
+    error,
+    audioContext: inputAudioControllerRef.current?.audioContext || null
+  };
+}
+
+// src/react/adapter/socket/VoiceSocketAdapter.ts
+var VoiceSocketAdapter = class {
+  constructor(config) {
+    this._isConnected = false;
+    this.logger = new Logger("@m4trix/core > VoiceSocketAdapter");
+    this.emitter = new Emitter();
+    this.config = config;
+  }
+  on(event, listener) {
+    this.emitter.on(event, listener);
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+  }
+  once(event, listener) {
+    this.emitter.once(event, listener);
+  }
+  emit(event, data) {
+    this.emitter.emit(event, data);
+  }
+  isConnected() {
+    return this._isConnected;
+  }
+};
+var Emitter = class {
+  constructor() {
+    this.target = new EventTarget();
+  }
+  on(type, listener) {
+    this.target.addEventListener(type, listener);
+  }
+  off(type, listener) {
+    this.target.removeEventListener(type, listener);
+  }
+  once(type, listener) {
+    const wrapper = (event) => {
+      this.off(type, wrapper);
+      listener(event.detail);
+    };
+    this.on(type, wrapper);
+  }
+  emit(type, detail) {
+    this.target.dispatchEvent(new CustomEvent(type, { detail }));
+  }
+};
+var VoiceSocketIOAdapter = class extends VoiceSocketAdapter {
+  constructor(config) {
+    super(config);
+    this.socket = null;
+  }
+  async connect() {
+    return new Promise((resolve, reject) => {
+      if (!this.socket) {
+        this.socket = io(this.config.baseUrl, {
+          extraHeaders: this.config.headers,
+          autoConnect: true
+        });
+      }
+      this.socket.on("connect", () => {
+        this._isConnected = true;
+        this.logger.debug("Connected to socket");
+        this.emit("connect");
+        resolve();
+      });
+      this.socket.on("disconnect", () => {
+        this._isConnected = false;
+        this.emit("disconnect");
+        this.logger.debug("Disconnected from socket");
+        if (this.config.autoReconnect)
+          this.connect();
+      });
+      this.socket.on("connect_error", (error) => {
+        this.logger.error("Error connecting to socket", error);
+        this.emit("error", error);
+        reject(error);
+      });
+      this.socket.on("voice:chunk_received", (chunk) => {
+        this.logger.debug("Received voice chunk", chunk.byteLength);
+        this.onVoiceChunkReceived(chunk);
+      });
+      this.socket.on("voice:received_end_of_response_stream", () => {
+        this.logger.debug("Received end of response stream");
+        this.onReceivedEndOfResponseStream();
+      });
+      this.socket.on("voice:file_received", (blob) => {
+        this.logger.debug("Received voice file");
+        this.onVoiceFileReceived(blob);
+      });
+      this.socket.on("control-message", (message) => {
+        this.logger.debug("Received control message", message);
+        this.emit("control-message", message);
+      });
+    });
+  }
+  disconnect() {
+    this.socket?.disconnect();
+    this.socket = null;
+    this._isConnected = false;
+  }
+  exposeSocket() {
+    return this.socket;
+  }
+  async sendVoiceChunk(chunk, metadata) {
+    this.logger.debug(
+      "Sending voice chunk %i",
+      chunk instanceof Blob ? chunk.size : chunk.byteLength
+    );
+    if (!this.socket || !this.isConnected)
+      throw new Error("Socket not connected");
+    let chunkToSend;
+    if (chunk instanceof Blob) {
+      chunkToSend = await chunk.arrayBuffer();
+    } else {
+      chunkToSend = chunk;
+    }
+    this.logger.debug("[Socket] Sending voice chunk", chunkToSend.byteLength);
+    this.socket.emit("voice:send_chunk", chunkToSend, metadata);
+    this.emit("chunk_sent", chunk);
+  }
+  sendVoiceFile(blob, metadata) {
+    this.logger.debug("Sending voice file", blob, metadata);
+    if (!this.socket || !this.isConnected)
+      throw new Error("Socket not connected");
+    this.socket.emit("voice:send_file", blob, metadata);
+    this.emit("file-sent", blob);
+  }
+  commitVoiceMessage() {
+    if (!this.socket || !this.isConnected)
+      throw new Error("Socket not connected");
+    this.socket.emit("voice:commit");
+  }
+  onVoiceChunkReceived(chunk) {
+    this.emit("chunk-received", chunk);
+  }
+  onVoiceFileReceived(blob) {
+    this.emit("file-received", blob);
+  }
+  onReceivedEndOfResponseStream() {
+    this.emit("received-end-of-response-stream");
+  }
+};
+
+// src/react/utility/audio/WebAudioOutputAudioController.ts
+var STREAM_SAMPLE_RATE = 24e3;
+var CHANNELS = 1;
+var SLICE_DURATION_S = 0.25;
+var FRAMES_PER_SLICE = Math.floor(STREAM_SAMPLE_RATE * SLICE_DURATION_S);
+var BYTES_PER_SLICE = FRAMES_PER_SLICE * 2;
+var SCHED_TOLERANCE = 0.05;
+var WebAudioOutputAudioController = class extends OutputAudioController {
+  constructor() {
+    super("@m4trix/core > WebAudioOutputAudioController");
+    this.audioCtx = new AudioContext();
+    this.gain = this.audioCtx.createGain();
+    this.nextPlayTime = 0;
+    this.activeSources = /* @__PURE__ */ new Set();
+    this.userGestureHookAttached = false;
+    this.gain.connect(this.audioCtx.destination);
+    this.resetScheduler();
+  }
+  // ─────────────────────────────────────────────────────────────────────
+  // One‑shot playback
+  // ─────────────────────────────────────────────────────────────────────
+  async playAudio({
+    source,
+    onComplete
+  }) {
+    await this.stopPlayback();
+    const buf = await this.sourceToArrayBuffer(source);
+    const decoded = await this.decode(buf);
+    await this.ensureContextRunning();
+    const src = this.createSource(decoded, this.audioCtx.currentTime);
+    src.onended = () => {
+      this.activeSources.delete(src);
+      onComplete?.();
+    };
+  }
+  async playAudioStream() {
+  }
+  // ─────────────────────────────────────────────────────────────────────
+  // PCM streaming
+  // ─────────────────────────────────────────────────────────────────────
+  async initializeChunkStream({
+    onComplete
+  }) {
+    await this.stopPlayback();
+    await this.ensureContextRunning();
+    this.resetScheduler();
+    let streamEnded = false;
+    let pending = new Uint8Array(0);
+    const addChunkToStream = async (pkt) => {
+      if (streamEnded) {
+        this.logger.warn("Attempt to add chunk after stream ended \u2013 ignoring.");
+        return;
+      }
+      const bytes = new Uint8Array(
+        pkt instanceof Blob ? await pkt.arrayBuffer() : pkt
+      );
+      if (bytes.length === 0)
+        return;
+      const merged = new Uint8Array(pending.length + bytes.length);
+      merged.set(pending);
+      merged.set(bytes, pending.length);
+      pending = merged;
+      if (pending.length % 2 === 1)
+        return;
+      while (pending.length >= BYTES_PER_SLICE) {
+        const sliceBytes = pending.slice(0, BYTES_PER_SLICE);
+        pending = pending.slice(BYTES_PER_SLICE);
+        const aligned = sliceBytes.buffer.slice(
+          sliceBytes.byteOffset,
+          sliceBytes.byteOffset + sliceBytes.byteLength
+        );
+        const int16 = new Int16Array(aligned);
+        const buf = this.audioCtx.createBuffer(
+          CHANNELS,
+          int16.length,
+          STREAM_SAMPLE_RATE
+        );
+        const data = buf.getChannelData(0);
+        for (let i = 0; i < int16.length; i++)
+          data[i] = int16[i] / 32768;
+        this.scheduleBuffer(buf);
+      }
+    };
+    const endChunkStream = () => {
+      if (streamEnded)
+        return;
+      streamEnded = true;
+      if (onComplete) {
+        if (this.activeSources.size === 0)
+          onComplete();
+        else {
+          const last = Array.from(this.activeSources).pop();
+          if (last) {
+            const prev = last.onended;
+            last.onended = (e) => {
+              if (prev)
+                prev.call(last, e);
+              onComplete();
+            };
+          }
+        }
+      }
+    };
+    return { addChunkToStream, endChunkStream };
+  }
+  // ─────────────────────────────────────────────────────────────────────
+  // Buffer scheduling helpers
+  // ─────────────────────────────────────────────────────────────────────
+  scheduleBuffer(buf) {
+    if (this.nextPlayTime < this.audioCtx.currentTime + SCHED_TOLERANCE) {
+      this.nextPlayTime = this.audioCtx.currentTime + SCHED_TOLERANCE;
+    }
+    this.createSource(buf, this.nextPlayTime);
+    this.nextPlayTime += buf.duration;
+  }
+  createSource(buf, when) {
+    const src = this.audioCtx.createBufferSource();
+    src.buffer = buf;
+    src.connect(this.gain);
+    src.start(when);
+    this.activeSources.add(src);
+    src.onended = () => {
+      this.activeSources.delete(src);
+    };
+    return src;
+  }
+  resetScheduler() {
+    this.nextPlayTime = this.audioCtx.currentTime;
+  }
+  // ─── External resource helpers ───────────────────────────────────────
+  sourceToArrayBuffer(src) {
+    return typeof src === "string" ? fetch(src).then((r) => {
+      if (!r.ok)
+        throw new Error(`${r.status}`);
+      return r.arrayBuffer();
+    }) : src.arrayBuffer();
+  }
+  decode(buf) {
+    return new Promise(
+      (res, rej) => this.audioCtx.decodeAudioData(buf, res, rej)
+    );
+  }
+  // ─── Lifecycle methods ───────────────────────────────────────────────
+  async stopPlayback() {
+    for (const src of this.activeSources) {
+      try {
+        src.stop();
+      } catch {
+      }
+      src.disconnect();
+    }
+    this.activeSources.clear();
+    this.resetScheduler();
+  }
+  cleanup() {
+    this.stopPlayback();
+    if (this.audioCtx.state !== "closed")
+      this.audioCtx.close();
+  }
+  // ─── Autoplay‑policy helper ──────────────────────────────────────────
+  async ensureContextRunning() {
+    if (this.audioCtx.state !== "suspended")
+      return;
+    try {
+      await this.audioCtx.resume();
+    } catch {
+    }
+    if (this.audioCtx.state === "running")
+      return;
+    if (!this.userGestureHookAttached) {
+      this.userGestureHookAttached = true;
+      const resume = async () => {
+        try {
+          await this.audioCtx.resume();
+        } catch {
+        }
+        if (this.audioCtx.state === "running")
+          document.removeEventListener("click", resume);
+      };
+      document.addEventListener("click", resume);
+    }
+  }
+};
+
+// src/react/hooks/use-conversation/useSocketConversation.ts
+Logger.enableGlobalLogging();
+function useSocketConversation({
+  scope,
+  onStartRecording,
+  onStopRecording,
+  onReceive,
+  upstreamMode = "STREAM_WHILE_TALK",
+  onError,
+  audioConfig = {},
+  socketConfig = {}
+}) {
+  const { current: logger } = useRef(
+    new Logger("SuTr > useSocketConversation")
+  );
+  const inputAudioControllerRef = useRef(void 0);
+  const outputAudioControllerRef = useRef(
+    void 0
+  );
+  const socketAdapterRef = useRef(void 0);
+  const [socket, setSocket] = useState(null);
+  const [voiceAgentState, setVoiceAgentState] = useState("READY");
+  const [error, setError] = useState(null);
+  const shouldStreamWhileTalk = upstreamMode === "STREAM_WHILE_TALK";
+  const handleError = useCallback(
+    (state2, err) => {
+      setError(err);
+      logger.error(`Error during ${state2}:`, err);
+      onError?.(state2, err);
+    },
+    [onError]
+  );
+  const subscribeToSocketEventsForChunkDownstreaming = useCallback(
+    async (socketAdapter) => {
+      logger.debug("Setting up audio stream for receiving chunks");
+      try {
+        const { addChunkToStream, endChunkStream } = await outputAudioControllerRef.current.initializeChunkStream({
+          mimeCodec: "audio/mpeg",
+          onComplete: () => {
+            logger.debug("Audio stream playback completed");
+            setVoiceAgentState("READY");
+          }
+        });
+        let chunkCount = 0;
+        const chunkReceivedEmitter = async (chunk) => {
+          if (chunk instanceof ArrayBuffer) {
+            chunkCount++;
+            logger.debug(
+              `Received voice chunk #${chunkCount} from socket, size: ${chunk.byteLength} bytes`
+            );
+            if (!chunk || chunk.byteLength === 0) {
+              logger.warn("Received empty chunk, skipping");
+              return;
+            }
+            try {
+              await addChunkToStream(chunk);
+              logger.debug(
+                `Successfully added chunk #${chunkCount} to audio stream`
+              );
+            } catch (err) {
+              logger.error(
+                `Failed to add chunk #${chunkCount} to audio stream`,
+                err
+              );
+              if (err instanceof Error) {
+                handleError("DOWNSTREAMING", err);
+              }
+            }
+          }
+        };
+        socketAdapter.on("chunk-received", chunkReceivedEmitter);
+        const endOfStreamEmitter = () => {
+          logger.debug(
+            `Received end of stream signal after ${chunkCount} chunks, ending chunk stream`
+          );
+          endChunkStream();
+          setVoiceAgentState("READY");
+        };
+        socketAdapter.on("received-end-of-response-stream", endOfStreamEmitter);
+        return () => {
+          logger.debug("Cleaning up socket event listeners");
+          socketAdapter.off("chunk-received", chunkReceivedEmitter);
+          socketAdapter.off(
+            "received-end-of-response-stream",
+            endOfStreamEmitter
+          );
+          endChunkStream();
+        };
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("DOWNSTREAMING", err);
+        }
+        return () => {
+        };
+      }
+    },
+    [handleError]
+  );
+  const hookupSocketAdapter = useCallback(
+    async (socketAdapter) => {
+      logger.debug("Connecting to socket...");
+      try {
+        await socketAdapter.connect();
+        socketAdapter.on("connect", () => {
+          logger.debug("Socket adapter connected");
+          setVoiceAgentState("READY");
+        });
+        socketAdapter.on("disconnect", () => {
+          logger.debug("Socket adapter disconnected");
+        });
+        socketAdapter.on("error", (err) => {
+          if (err instanceof Error) {
+            handleError(voiceAgentState, err);
+          } else {
+            handleError(voiceAgentState, new Error("Unknown error"));
+          }
+        });
+        setSocket(socketAdapter.exposeSocket());
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("READY", err);
+        }
+      }
+    },
+    [handleError, voiceAgentState]
+  );
+  const startRecording = useCallback(() => {
+    if (inputAudioControllerRef.current) {
+      try {
+        logger.debug("Starting recording");
+        setVoiceAgentState("RECORDING");
+        inputAudioControllerRef.current.startRecording({
+          onRecordedChunk: async (chunk) => {
+            if (shouldStreamWhileTalk) {
+              try {
+                await socketAdapterRef.current?.sendVoiceChunk(chunk);
+              } catch (err) {
+                if (err instanceof Error) {
+                  handleError("RECORDING", err);
+                }
+              }
+            }
+          }
+        });
+        onStartRecording?.();
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("RECORDING", err);
+        }
+      }
+    }
+  }, [onStartRecording, shouldStreamWhileTalk, handleError]);
+  const stopRecording = useCallback(async () => {
+    if (inputAudioControllerRef.current) {
+      try {
+        logger.debug("Stopping recording");
+        await inputAudioControllerRef.current.stopRecording({
+          onRecordingCompleted: async (allData) => {
+            setVoiceAgentState("PROCESSING");
+            try {
+              if (shouldStreamWhileTalk) {
+                logger.debug("Committing voice message");
+                await socketAdapterRef.current?.commitVoiceMessage();
+              } else {
+                await socketAdapterRef.current?.sendVoiceFile(allData);
+              }
+              setVoiceAgentState("DOWNSTREAMING");
+              await subscribeToSocketEventsForChunkDownstreaming(
+                socketAdapterRef.current
+              );
+              onReceive?.(
+                allData,
+                async () => {
+                  if (outputAudioControllerRef.current) {
+                    return outputAudioControllerRef.current.stopPlayback();
+                  }
+                },
+                async () => {
+                  if (outputAudioControllerRef.current) {
+                    return outputAudioControllerRef.current.stopPlayback();
+                  }
+                }
+              );
+            } catch (err) {
+              if (err instanceof Error) {
+                handleError("PROCESSING", err);
+              }
+            }
+          }
+        });
+        onStopRecording?.();
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("RECORDING", err);
+        }
+      }
+    }
+  }, [
+    onStopRecording,
+    handleError,
+    subscribeToSocketEventsForChunkDownstreaming,
+    onReceive
+  ]);
+  useEffect(() => {
+    if (socketAdapterRef.current) {
+      return;
+    }
+    try {
+      const socketAdapter = socketConfig.socketAdapter ? socketConfig.socketAdapter : new VoiceSocketIOAdapter({
+        scope,
+        baseUrl: socketConfig.baseUrl || "",
+        headers: socketConfig.headers
+      });
+      socketAdapterRef.current = socketAdapter;
+      if (!socketAdapter.isConnected()) {
+        hookupSocketAdapter(socketAdapter);
+      }
+      if (!inputAudioControllerRef.current) {
+        inputAudioControllerRef.current = new WebAudioInputAudioController(
+          audioConfig
+        );
+      }
+      if (!outputAudioControllerRef.current) {
+        outputAudioControllerRef.current = new WebAudioOutputAudioController();
+      }
+    } catch (err) {
+      if (err instanceof Error) {
+        handleError("READY", err);
+      }
+    }
+  }, [scope, socketConfig, hookupSocketAdapter, audioConfig, handleError]);
+  useEffect(() => {
+    return () => {
+      inputAudioControllerRef.current?.cleanup();
+      outputAudioControllerRef.current?.cleanup();
+      if (socketAdapterRef.current) {
+        socketAdapterRef.current.disconnect();
+        socketAdapterRef.current = void 0;
+      }
+    };
+  }, []);
+  return {
+    startRecording,
+    stopRecording,
+    voiceAgentState,
+    error,
+    audioContext: inputAudioControllerRef.current?.audioContext || null,
+    socket
+  };
+}
+var AiCursorComponentStyle = css`
+  :host {
+    --ai-local-cursor-size: var(--sk-ai-cursor-size, 1rem);
+    --ai-local-cursor-label-padding: var(
+      --sk-ai-cursor-label-padding,
+      0.25rem 0.25rem
+    );
+    --ai-local-cursor-border-radius: var(--sk-ai-cursor-border-radius, 0.25rem);
+    --ai-local-label-offset: var(--sk-ai-cursor-label-offset, 1rem);
+
+    --ai-local-label-font-size: var(--sk-ai-cursor-label-font-size, 12px);
+    --ai-local-label-font-weight: var(--sk-ai-cursor-label-font-weight, bold);
+    --ai-local-label-color: var(--sk-ai-cursor-label-color, white);
+    --ai-local-label-background-color: var(
+      --sk-ai-cursor-label-background-color,
+      black
+    );
+    --ai-local-label-border-color: var(
+      --sk-ai-cursor-label-border-color,
+      white
+    );
+    --ai-local-label-border-width: var(
+      --sk-ai-cursor-label-border-width,
+      0.1rem
+    );
+
+    color: black;
+    stroke: white;
+    position: absolute;
+    /* Insetting in the parent element (body) */
+    top: 0;
+    left: 0;
+    bottom: 0;
+    right: 0;
+    pointer-events: none;
+    width: var(--ai-local-cursor-size);
+    height: var(--ai-local-cursor-size);
+  }
+
+  #cursor-graphic-parent {
+    position: absolute;
+    top: 0;
+    left: 0;
+  }
+
+  #label-text {
+    position: absolute;
+    color: white;
+    font-size: 12px;
+    font-weight: bold;
+    padding: var(--ai-local-cursor-label-padding);
+    border-radius: var(--ai-local-cursor-border-radius);
+
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+
+    width: fit-content;
+    min-width: fit-content;
+    top: var(--ai-local-label-offset);
+    left: var(--ai-local-label-offset);
+
+    border: var(--ai-local-label-border-width) solid
+      var(--ai-local-label-border-color);
+    background-color: var(--ai-local-label-background-color);
+    color: var(--ai-local-label-color);
+    font-size: var(--ai-local-label-font-size);
+    font-weight: var(--ai-local-label-font-weight);
+  }
+`;
+
+// src/ui/ai-cursor/rendering/AiCursorComponent.ts
+var AiCursorComponent = class extends LitElement {
+  constructor() {
+    super();
+    this.eventHooks = {
+      defineSetPosition: () => {
+      },
+      defineAddPositionToQueue: () => {
+      },
+      definePlayQueue: () => {
+      },
+      defineSetShowCursor: () => {
+      }
+    };
+    this.isShowingCursor = true;
+    this.labelText = "AI Cursor";
+    this.cursorPosition = [0, 0];
+    this._cursorRef = createRef();
+    this._labelRef = createRef();
+  }
+  updated(_changedProperties) {
+    if (_changedProperties.has("_cursorRef")) {
+      if (this._cursorRef.value) {
+        this.hookUpCallbacks();
+      } else {
+        this._timeline?.pause();
+        this._timeline?.refresh();
+      }
+    }
+    super.updated(_changedProperties);
+  }
+  render() {
+    const cursorSvg = html`
+      <svg
+        width=${24}
+        height=${24}
+        viewBox="0 0 100 100"
+        fill="none"
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <g clip-path="url(#clip0_3576_285)">
+          <path
+            class="cursor-path"
+            d="M2.14849 7.04749C1.35153 4.07321 4.07319 1.35155 7.04747 2.14851L77.3148 20.9766C80.2891 21.7735 81.2853 25.4914 79.108 27.6687L27.6687 79.108C25.4914 81.2853 21.7735 80.2891 20.9766 77.3149L2.14849 7.04749Z"
+            fill="currentColor"
+          />
+        </g>
+        <defs>
+          <clipPath id="clip0_3576_285">
+            <rect width="100" height="100" fill="white" />
+          </clipPath>
+        </defs>
+      </svg>
+    `;
+    return html`
+      <span
+        id="cursor-graphic-parent"
+        ${ref(this._cursorRef)}
+        ?hidden=${!this.isShowingCursor}
+      >
+        ${cursorSvg}
+        <span
+          ${ref(this._labelRef)}
+          id="label-text"
+          ?hidden=${!this.isShowingCursor}
+          >${this.labelText}</span
+        >
+      </span>
+    `;
+  }
+  // private methods
+  /**
+   * The primary way to control the cursor is using an external API.
+   * This interface exposes controlling methods. The Lit Component itself is
+   * intended to be a controlled component.
+   */
+  hookUpCallbacks() {
+    const animationTarget = this._cursorRef.value;
+    if (!animationTarget) {
+      return;
+    }
+    this._timeline = createTimeline({ defaults: { duration: 750 } });
+    if (!this._timeline) {
+      return;
+    }
+    this.eventHooks.defineSetPosition((position) => {
+      this._timeline?.add(animationTarget, {
+        translateX: position[0],
+        translateY: position[1],
+        duration: 1
+      });
+      this._timeline?.play();
+    });
+    this.eventHooks.defineAddPositionToQueue((position) => {
+      this._timeline?.add(animationTarget, {
+        translateX: position[0],
+        translateY: position[1],
+        duration: 1e3
+      });
+    });
+    this.eventHooks.defineSetShowCursor((show) => {
+      this.isShowingCursor = show;
+    });
+    this.eventHooks.definePlayQueue(() => {
+      this._timeline?.play();
+    });
+  }
+  // Getters
+  get cursorRef() {
+    return this._cursorRef.value;
+  }
+  get labelRef() {
+    return this._labelRef.value;
+  }
+};
+// Define scoped styles right with your component, in plain CSS
+AiCursorComponent.styles = AiCursorComponentStyle;
+__decorateClass([
+  property({
+    type: Object
+  })
+], AiCursorComponent.prototype, "eventHooks", 2);
+__decorateClass([
+  property({ type: Boolean })
+], AiCursorComponent.prototype, "isShowingCursor", 2);
+__decorateClass([
+  property({ type: String })
+], AiCursorComponent.prototype, "labelText", 2);
+__decorateClass([
+  property({ type: Array })
+], AiCursorComponent.prototype, "cursorPosition", 2);
+__decorateClass([
+  state()
+], AiCursorComponent.prototype, "_cursorRef", 2);
+__decorateClass([
+  state()
+], AiCursorComponent.prototype, "_labelRef", 2);
+AiCursorComponent = __decorateClass([
+  customElement("ai-cursor")
+], AiCursorComponent);
+
+// src/ui/ai-cursor/rendering/index.ts
+var mountAiCursor = (aiCursorProps) => {
+  const root = document.body;
+  const cursor = document.createElement("ai-cursor");
+  cursor.eventHooks = aiCursorProps.eventHooks;
+  root.appendChild(cursor);
+};
+
+// src/ui/ai-cursor/AiCursor.ts
+var AiCursor = class _AiCursor {
+  constructor() {
+  }
+  // Static constructors
+  static spawn() {
+    const newCursor = new _AiCursor();
+    newCursor.mount();
+    return newCursor;
+  }
+  jumpTo(target) {
+    const position = targetToPosition(target);
+    if (position) {
+      this.setPosition?.(position);
+    }
+  }
+  moveTo(target) {
+    const position = targetToPosition(target);
+    if (position) {
+      this.addPositionToQueue?.(position);
+      this.playQueue?.();
+    }
+  }
+  scheduleMoves(targets) {
+    targets.forEach((target) => {
+      const position = targetToPosition(target);
+      if (position) {
+        this.addPositionToQueue?.(position);
+      }
+    });
+    this.playQueue?.();
+  }
+  show() {
+    this.setShowCursor?.(true);
+  }
+  hide() {
+    this.setShowCursor?.(false);
+  }
+  mount() {
+    mountAiCursor({
+      eventHooks: {
+        defineSetPosition: (callback) => {
+          this.setPosition = callback;
+        },
+        defineAddPositionToQueue: (callback) => {
+          this.addPositionToQueue = callback;
+        },
+        definePlayQueue: (callback) => {
+          this.playQueue = callback;
+        },
+        defineSetShowCursor: (callback) => {
+          this.setShowCursor = callback;
+        }
+      }
+    });
+  }
+};
+function calculateClickPositionFromElement(element) {
+  const rect = element.getBoundingClientRect();
+  return [rect.left + rect.width / 2, rect.top + rect.height / 2];
+}
+function targetToPosition(target) {
+  if (Array.isArray(target) && target.length === 2 && typeof target[0] === "number" && typeof target[1] === "number") {
+    return target;
+  } else if (target instanceof HTMLElement) {
+    return calculateClickPositionFromElement(target);
+  } else if (typeof target === "string") {
+    const element = document.querySelector(target);
+    if (element) {
+      return calculateClickPositionFromElement(element);
+    }
+  }
+  return void 0;
+}
+
+// src/stream/Pump.ts
+var Pump = class _Pump {
+  constructor(src) {
+    this.src = src;
+  }
+  /**
+   * Wrap an existing AsyncIterable or Readable stream into a Pump
+   *
+   * @template U The type of data in the source stream
+   * @param source The source stream to convert to a Pump (AsyncIterable, ReadableStream, or NodeJS.ReadableStream)
+   * @returns A new Pump instance that wraps the source
+   */
+  static from(source) {
+    async function* gen() {
+      let seq = 0;
+      function isAsyncIterable(obj) {
+        return Symbol.asyncIterator in obj;
+      }
+      function isWebReadableStream(obj) {
+        return "getReader" in obj && typeof obj.getReader === "function";
+      }
+      function isNodeReadableStream(obj) {
+        return "pipe" in obj && "on" in obj && typeof obj.pipe === "function" && typeof obj.on === "function";
+      }
+      if (isAsyncIterable(source)) {
+        const iterator = source[Symbol.asyncIterator]();
+        try {
+          while (true) {
+            const result = await iterator.next();
+            if (result.done)
+              break;
+            yield {
+              sequence: seq++,
+              data: result.value,
+              done: false
+            };
+          }
+        } finally {
+        }
+      } else if (isWebReadableStream(source)) {
+        const reader = source.getReader();
+        try {
+          while (true) {
+            const result = await reader.read();
+            if (result.done)
+              break;
+            yield {
+              sequence: seq++,
+              data: result.value,
+              done: false
+            };
+          }
+        } finally {
+          reader.releaseLock();
+        }
+      } else if (isNodeReadableStream(source)) {
+        try {
+          for await (const chunk of source) {
+            yield {
+              sequence: seq++,
+              data: chunk,
+              done: false
+            };
+          }
+        } catch (error) {
+          console.error("Error reading from Node.js stream:", error);
+          throw error;
+        }
+      }
+      yield { sequence: seq, data: void 0, done: true };
+    }
+    return new _Pump(gen());
+  }
+  /**
+   * Sync or async map over the data portion of each chunk
+   *
+   * @template U The output type after transformation
+   * @param fn The mapping function that transforms each chunk
+   * @returns A new Pump instance with the transformed data
+   */
+  map(fn) {
+    async function* gen() {
+      for await (const { sequence, data, done } of this.src) {
+        if (done) {
+          const out2 = data !== void 0 ? await fn(data) : void 0;
+          yield { sequence, data: out2, done };
+          break;
+        }
+        const out = await fn(data);
+        yield { sequence, data: out, done };
+      }
+    }
+    return new _Pump(gen.call(this));
+  }
+  /**
+   * Stateful map allows processing stream chunks with a persistent context object.
+   *
+   * The context is initialized when the first chunk arrives and can be updated with each chunk.
+   * This is useful for maintaining state across the stream processing.
+   *
+   * If you plan to use sockets you should rather opt for asyncStatefulMap.
+   *
+   * The pipe closes only after all processing is complete, including any final operations in onClose.
+   *
+   * TODO: Un-tested
+   *
+   * @param handlers Object containing callback functions for stream processing
+   * @param handlers.onFirstChunk Function called when the first chunk arrives, initializes the context
+   * @param handlers.onChunk Function called for each subsequent chunk, updates the context
+   * @param handlers.onClose Optional function called when the stream closes, allows final processing
+   * @returns A new Pump instance with transformed data
+   */
+  statefulMap(handlers) {
+    const { src } = this;
+    const gen = async function* () {
+      let context;
+      let initialized = false;
+      let lastChunk;
+      let seq = 0;
+      const queue = [];
+      const yieldData = (data) => {
+        queue.push(data);
+      };
+      for await (const { data, done } of src) {
+        if (done) {
+          if (context && handlers.onClose) {
+            await handlers.onClose(lastChunk, context, yieldData);
+          }
+          while (queue.length > 0) {
+            yield { sequence: seq++, data: queue.shift(), done: false };
+          }
+          yield {
+            sequence: seq++,
+            data: void 0,
+            done: true
+          };
+          break;
+        }
+        if (!initialized) {
+          context = await handlers.onFirstChunk(data, yieldData);
+          initialized = true;
+        } else if (context) {
+          context = await handlers.onChunk(data, context, yieldData);
+        }
+        lastChunk = data;
+        while (queue.length > 0) {
+          yield { sequence: seq++, data: queue.shift(), done: false };
+        }
+      }
+    };
+    return new _Pump(gen());
+  }
+  /**
+   * Async map means that each incoming chunk is causing an async operation that when it completes
+   * should yield a new chunk.
+   * The pipe closes only after you unlock the pipe by using the unlockCloseEvent callback.
+   *
+   * Stateful refers to the fact that you can create your own small context object that is passed in the subsequent callbacks.
+   * This allows you to keep track of things like a socket connection.
+   *
+   * Why is this nice? Well if you use things like a socket the pipe might have received the close event,
+   * before you got any or all of your socket responses. Sockets don't fit into the standard promise pattern,
+   * which makes it harder to wait for them.
+   *
+   * TODO: Un-tested
+   *
+   * @param handlers Object containing callback functions for stream processing
+   * @param handlers.onFirstChunk Function called when the first chunk arrives, initializes the context
+   * @param handlers.onChunk Function called for each subsequent chunk, updates the context
+   * @param handlers.onClose Optional function called when the stream closes, allows final processing
+   * @returns A new Pump instance with transformed data
+   */
+  asyncStatefulMap(handlers) {
+    const { src } = this;
+    const gen = async function* () {
+      let context;
+      let initialized = false;
+      let lastChunk;
+      let seq = 0;
+      let lockedCloseEvent = true;
+      const queue = [];
+      const yieldData = (data) => {
+        queue.push(data);
+      };
+      const unlockCloseEvent = () => {
+        lockedCloseEvent = false;
+      };
+      for await (const { data, done } of src) {
+        if (done) {
+          if (context && handlers.onClose) {
+            await handlers.onClose(
+              lastChunk,
+              context,
+              yieldData,
+              unlockCloseEvent
+            );
+          }
+          const timestamp = Date.now();
+          while (lockedCloseEvent && Date.now() - timestamp < 1e4) {
+            while (queue.length > 0) {
+              yield { sequence: seq++, data: queue.shift(), done: false };
+            }
+            await new Promise((resolve) => setTimeout(resolve, 5));
+          }
+          while (queue.length > 0) {
+            yield { sequence: seq++, data: queue.shift(), done: false };
+          }
+          yield {
+            sequence: seq++,
+            data: void 0,
+            done: true
+          };
+          break;
+        }
+        if (!initialized) {
+          context = await handlers.onFirstChunk(
+            data,
+            yieldData,
+            unlockCloseEvent
+          );
+          initialized = true;
+        } else if (context) {
+          context = await handlers.onChunk(
+            data,
+            context,
+            yieldData,
+            unlockCloseEvent
+          );
+        }
+        lastChunk = data;
+        while (queue.length > 0) {
+          yield { sequence: seq++, data: queue.shift(), done: false };
+        }
+      }
+    };
+    return new _Pump(gen());
+  }
+  /**
+   * Filter items based on a predicate
+   *
+   * @param predicate A function that determines whether to keep each chunk
+   * @returns A new Pump instance containing only chunks that passed the predicate
+   */
+  filter(predicate) {
+    async function* gen() {
+      for await (const { sequence, data, done } of this.src) {
+        if (done) {
+          yield { sequence, data, done: true };
+          break;
+        }
+        const keep = await predicate(data);
+        if (keep) {
+          yield { sequence, data, done: false };
+        }
+      }
+    }
+    return new _Pump(gen.call(this));
+  }
+  /**
+   * Bundles (accumulates) chunks together based on a condition rather than a fixed size.
+   *
+   * This is useful when you need to group chunks dynamically based on their content or other criteria.
+   *
+   * Example: Bundling text chunks with a maximum character limit
+   *
+   * Input chunks: ["Hello", " this", " is", " a few", " chunks", " of text"]
+   * With max size of 10 characters:
+   * - First bundle: ["Hello", " this"] (10 chars)
+   * - Second bundle: [" is", " a few"] (8 chars)
+   * - Third bundle: [" chunks", " of text"] (13 chars)
+   *
+   * @param closeBundleCondition - Function that determines when to close the current bundle
+   *                              Returns true when the current bundle should be emitted
+   *                              Parameters:
+   *                              - chunk: The current chunk being processed
+   *                              - accumulatedChunks: Array of chunks in the current bundle
+   *
+   * @returns A pump that emits arrays of bundled items
+   */
+  bundle(closeBundleCondition) {
+    async function* gen() {
+      let buffer = [];
+      let lastSequence = 0;
+      for await (const { sequence, data, done } of this.src) {
+        lastSequence = sequence;
+        if (done) {
+          if (buffer.length > 0) {
+            yield { sequence, data: [...buffer], done: false };
+          }
+          yield {
+            sequence: lastSequence,
+            data: void 0,
+            done: true
+          };
+          break;
+        }
+        const shouldClose = await closeBundleCondition(data, buffer);
+        buffer.push(data);
+        if (shouldClose) {
+          yield {
+            sequence: lastSequence,
+            data: [...buffer],
+            done: false
+          };
+          buffer = [];
+        }
+      }
+    }
+    return new _Pump(gen.call(this));
+  }
+  /**
+   * Tap into each chunk without altering it
+   *
+   * @param fn A function that receives each chunk but doesn't affect the stream
+   * @returns The same pump instance with unmodified data
+   */
+  onChunk(fn) {
+    async function* gen() {
+      for await (const chunk of this.src) {
+        if (chunk.data === void 0 && chunk.done) {
+          yield chunk;
+        }
+        await fn(chunk.data);
+        yield chunk;
+      }
+    }
+    return new _Pump(gen.call(this));
+  }
+  /**
+   * Collect all chunks in the stream and run a callback when the stream is done.
+   * The callback receives an array of all chunks that passed through.
+   *
+   * This is useful for analytics, logging, or processing the complete stream history
+   * after all chunks have been received.
+   *
+   * @param fn - Callback function that receives the array of all chunks when the stream is complete
+   * @returns The same pump, for chaining
+   */
+  onClose(fn) {
+    async function* gen() {
+      const history = [];
+      for await (const chunk of this.src) {
+        if (chunk.data !== void 0) {
+          history.push(chunk.data);
+        }
+        if (chunk.done) {
+          await fn(history);
+        }
+        yield chunk;
+      }
+    }
+    return new _Pump(gen.call(this));
+  }
+  /**
+   * Batch `n` chunks into arrays before emitting
+   *
+   * @param n The number of chunks to batch together
+   * @returns A new Pump instance that emits arrays of batched chunks
+   */
+  batch(n) {
+    async function* gen() {
+      let buffer = [];
+      for await (const chunk of this.src) {
+        if (chunk.done) {
+          if (chunk.data === void 0) {
+            yield {
+              sequence: buffer[0].sequence,
+              data: buffer.map((c) => c.data),
+              done: false
+            };
+            yield {
+              sequence: chunk.sequence,
+              data: void 0,
+              done: true
+            };
+            buffer = [];
+          } else {
+            buffer.push(chunk);
+            yield {
+              sequence: buffer[0].sequence,
+              data: buffer.map((c) => c.data),
+              done: true
+            };
+          }
+          break;
+        }
+        buffer.push(chunk);
+        if (buffer.length === n) {
+          yield {
+            sequence: buffer[0].sequence,
+            data: buffer.map((c) => c.data),
+            done: chunk.done
+          };
+          buffer = [];
+        }
+      }
+    }
+    return new _Pump(gen.call(this));
+  }
+  /**
+   * If you want to prevent chunk starvation, you can buffer the chunks.
+   * Chunks will not be bundled into arrays or object but kept as is,
+   * but the pipeline will not progress at that segment until the buffer is filled up.
+   * Once a buffer is filled up it will drain and never buffer again.
+   *
+   * @param n The number of chunks to buffer before processing continues
+   * @returns A new Pump instance with buffering behavior
+   */
+  buffer(n) {
+    async function* gen() {
+      let buffer = [];
+      let bufferFilled = false;
+      for await (const chunk of this.src) {
+        if (!bufferFilled) {
+          if (!chunk.done) {
+            buffer.push(chunk);
+          }
+          if (buffer.length >= n || chunk.done) {
+            bufferFilled = true;
+            for (const bufferedChunk of buffer) {
+              yield bufferedChunk;
+            }
+            if (chunk.done) {
+              yield {
+                sequence: chunk.sequence,
+                data: void 0,
+                done: true
+              };
+              break;
+            }
+            buffer = [];
+          }
+        } else {
+          yield chunk;
+        }
+      }
+      for (const bufferedChunk of buffer) {
+        yield bufferedChunk;
+      }
+    }
+    return new _Pump(gen.call(this));
+  }
+  /**
+   * Rechunk the stream: transform one chunk into zero, one, or many output chunks.
+   * The handler function receives the current buffer of chunks, a push function to emit new chunks,
+   * and a flag indicating if this is the last chunk in the stream.
+   *
+   * @param handler Function that transforms chunks and pushes new ones
+   * @returns A new Pump instance with rechunked data
+   */
+  rechunk(handler) {
+    async function* gen() {
+      let buffer = [];
+      let seq = 0;
+      const pending = [];
+      const push = (chunk) => {
+        pending.push(chunk);
+      };
+      for await (const { data, done } of this.src) {
+        if (!done) {
+          if (data !== void 0) {
+            buffer.push(data);
+          }
+          await handler({
+            buffer,
+            push,
+            lastChunk: false,
+            setBuffer: (b) => {
+              buffer = b;
+            }
+          });
+        } else {
+          await handler({
+            buffer,
+            push,
+            lastChunk: true,
+            setBuffer: (b) => {
+              buffer = b;
+            }
+          });
+        }
+        while (pending.length > 0) {
+          const out = pending.shift();
+          yield { sequence: seq++, data: out, done: false };
+        }
+        if (done) {
+          break;
+        }
+      }
+      yield { sequence: seq, data: void 0, done: true };
+    }
+    return new _Pump(gen.call(this));
+  }
+  slidingWindow(size, step, fn) {
+    async function* gen() {
+      const history = [];
+      let offset = 0;
+      let lastSeq = 0;
+      function buildWindow(_offset, _size, _history) {
+        const window = Array(_size).fill(void 0);
+        let windowIndex = 0;
+        for (let i = _offset; i > _offset - _size; i -= step) {
+          if (i >= history.length) {
+            windowIndex++;
+            continue;
+          }
+          if (i < 0) {
+            break;
+          }
+          window[windowIndex] = _history[i];
+          windowIndex++;
+        }
+        return window;
+      }
+      for await (const { sequence, data, done } of this.src) {
+        if (done) {
+          for (let i = 0; i < size - 1; i++) {
+            const window2 = buildWindow(offset + i, size, history);
+            yield { sequence: lastSeq, data: window2, done: false };
+          }
+          if (data === void 0) {
+            yield {
+              sequence: lastSeq,
+              data: void 0,
+              done: true
+            };
+          } else {
+            yield {
+              sequence: lastSeq,
+              data: [
+                history[history.length - 2] ?? void 0,
+                history[history.length - 3] ?? void 0,
+                history[history.length - 1]
+              ],
+              done: true
+            };
+          }
+          break;
+        }
+        lastSeq = sequence;
+        history.push(data);
+        const window = buildWindow(offset, size, history);
+        yield { sequence, data: window, done: false };
+        offset++;
+      }
+    }
+    const base = new _Pump(gen.call(this));
+    return fn ? base.map(fn) : base;
+  }
+  /**
+   * Sequentially flatten inner stream sources emitted by the pipeline.
+   * Works with any Source type (AsyncIterable or ReadableStream).
+   * This method is only available when the current Pump contains Source elements.
+   *
+   * @template U The type of data in the inner streams
+   * @template F The type of inner stream source (extends Source<U>)
+   * @returns A Pump instance with flattened stream data
+   */
+  sequenceStreams() {
+    async function* gen() {
+      let seq = 0;
+      for await (const { data: innerSource, done: outerDone } of this.src) {
+        if (outerDone)
+          break;
+        const innerPump = _Pump.from(innerSource);
+        for await (const { data, done } of innerPump.src) {
+          if (done)
+            break;
+          yield { sequence: seq++, data, done: false };
+        }
+      }
+      yield { sequence: seq, data: void 0, done: true };
+    }
+    return new _Pump(gen.call(this));
+  }
+  /**
+   * Fork the stream: two independent Pump<T> consumers
+   * Both resulting Pumps will receive the same data, allowing for divergent processing paths.
+   *
+   * @returns An array containing two independent Pump instances with the same source data
+   */
+  fork() {
+    const buffers = [[], []];
+    let done = false;
+    const srcIter = this.src[Symbol.asyncIterator]();
+    async function fill() {
+      const { value, done: streamDone } = await srcIter.next();
+      if (streamDone) {
+        done = true;
+        return;
+      }
+      buffers.forEach((q) => q.push(value));
+      if (value.done)
+        done = true;
+    }
+    function makeStream(buf) {
+      return {
+        [Symbol.asyncIterator]() {
+          return {
+            async next() {
+              while (buf.length === 0 && !done) {
+                await fill();
+              }
+              if (buf.length === 0)
+                return {
+                  done: true,
+                  value: void 0
+                };
+              return { done: false, value: buf.shift() };
+            }
+          };
+        }
+      };
+    }
+    return [new _Pump(makeStream(buffers[0])), new _Pump(makeStream(buffers[1]))];
+  }
+  /**
+   * Drain the pipeline, consuming all chunks.
+   * Returns a Promise that resolves when all chunks have been consumed.
+   *
+   * @returns A Promise that resolves when all chunks have been consumed
+   */
+  drain() {
+    return (async () => {
+      for await (const { done } of this.src) {
+        if (done)
+          break;
+      }
+    })();
+  }
+  /**
+   * Drain the pipeline to a StreamTransformer.
+   * Applies transform() to each data chunk, then closes the transformer,
+   * and returns its response (which can be of any type defined by the transformer).
+   *
+   * Example with httpStreamResponse:
+   * ```
+   * const { transform, response, close } = httpStreamResponse(options);
+   * return Pump.from(messageStream).drainTo({ transform, close, response });
+   * ```
+   *
+   * @template U The type of data expected by the transformer (extends T)
+   * @template R The response type produced by the transformer
+   * @param transformer The StreamTransformer to drain to
+   * @returns The response from the transformer
+   */
+  drainTo(transformer) {
+    (async () => {
+      for await (const { data, done } of this.src) {
+        if (done)
+          break;
+        transformer.transform(data);
+      }
+      transformer.close();
+    })();
+    return transformer.response;
+  }
+};
+
+// src/stream/utility/pipe-transformers/response.ts
+function httpStreamResponse(options = {}) {
+  const { init, encoder } = options;
+  const encodeFn = encoder ?? ((d) => {
+    if (d instanceof Uint8Array)
+      return d;
+    if (typeof d === "string")
+      return d;
+    return JSON.stringify(d);
+  });
+  const { readable, writable } = new TransformStream();
+  const writer = writable.getWriter();
+  const response = new Response(readable, init);
+  const transform = (chunk) => {
+    const encoded = encodeFn(chunk);
+    const bytes = typeof encoded === "string" ? new TextEncoder().encode(encoded) : encoded;
+    writer.write(bytes);
+    return chunk;
+  };
+  const close = () => {
+    writer.close();
+  };
+  return { transform, response, close };
+}
+
+// src/stream/utility/rechunker/ensure-full-words.ts
+async function ensureFullWords({
+  buffer,
+  push,
+  lastChunk
+}) {
+  const combined = buffer.join("");
+  const lastBoundary = Math.max(
+    combined.lastIndexOf(" "),
+    combined.lastIndexOf("\n"),
+    combined.lastIndexOf("	")
+  );
+  if (lastBoundary !== -1 || lastChunk) {
+    const emitPart = lastBoundary !== -1 ? combined.slice(0, lastBoundary + 1) : combined;
+    const leftoverPart = lastBoundary !== -1 ? combined.slice(lastBoundary + 1) : "";
+    if (emitPart.trim().length > 0) {
+      push(emitPart);
+    }
+    buffer.length = 0;
+    if (leftoverPart.length > 0) {
+      buffer.push(leftoverPart);
+    }
+  }
+}
+
+// src/api/socket-handler/SocketIoFactory.ts
+var SocketIoFactory = class _SocketIoFactory {
+  constructor(socket, prefix, hooks) {
+    this.socket = socket;
+    this.prefix = prefix;
+    this.hooks = hooks;
+  }
+  static setupSocketHandlers({
+    enableVoiceEvents,
+    enableChatEvents,
+    enableTranscriptEvents,
+    prefix = "",
+    socket,
+    hooks
+  }) {
+    const factory = new _SocketIoFactory(socket, prefix, hooks);
+    if (enableVoiceEvents) {
+      factory.setupVoiceEvents();
+    }
+    if (enableChatEvents) {
+      factory.setupChatEvents(socket);
+    }
+    if (enableTranscriptEvents) {
+      factory.setupTranscriptEvents(socket);
+    }
+  }
+  setupVoiceEvents() {
+    const {
+      onVoiceInputFile,
+      onVoiceInputChunk,
+      onVoiceInputCommit,
+      onVoiceOutputDelta,
+      onVoiceOutputCommit,
+      onVoiceOutputFile,
+      onVoiceOutputTranscriptDelta,
+      onVoiceOutputTranscriptFull
+    } = this.hooks;
+    const prefix = this.prefixEvent;
+    if (onVoiceInputFile) {
+      this.socket.on(prefix("voice:input_file"), onVoiceInputFile);
+    }
+    if (onVoiceInputChunk) {
+      this.socket.on(prefix("voice:input_chunk"), onVoiceInputChunk);
+    }
+    if (onVoiceInputCommit) {
+      this.socket.on(prefix("voice:input_commit"), onVoiceInputCommit);
+    }
+    if (onVoiceOutputDelta) {
+      this.socket.on(prefix("voice:output_delta"), onVoiceOutputDelta);
+    }
+    if (onVoiceOutputCommit) {
+      this.socket.on(prefix("voice:output_commit"), onVoiceOutputCommit);
+    }
+    if (onVoiceOutputFile) {
+      this.socket.on(prefix("voice:output_file"), onVoiceOutputFile);
+    }
+    if (onVoiceOutputTranscriptDelta) {
+      this.socket.on(
+        prefix("voice:output_transcript_delta"),
+        onVoiceOutputTranscriptDelta
+      );
+    }
+    if (onVoiceOutputTranscriptFull) {
+      this.socket.on(
+        prefix("voice:output_transcript_full"),
+        onVoiceOutputTranscriptFull
+      );
+    }
+  }
+  setupChatEvents(_socket) {
+  }
+  setupTranscriptEvents(_socket) {
+  }
+  prefixEvent(event) {
+    return this.prefix ? `${this.prefix}:${event}` : event;
+  }
+};
+var humanAndAI = (message) => message instanceof HumanMessage || message instanceof AIMessage;
+var humanOnly = (message) => message instanceof HumanMessage;
+var aiOnly = (message) => message instanceof AIMessage;
+var includingTags = (message, tags) => {
+  if (tags) {
+    return tags.some(
+      (tag) => Array.isArray(message.additional_kwargs?.tags) ? message.additional_kwargs?.tags.includes(tag) : false
+    );
+  }
+  return true;
+};
+var excludingTags = (message, tags) => {
+  if (tags) {
+    return !tags.some(
+      (tag) => Array.isArray(message.additional_kwargs?.tags) ? message.additional_kwargs?.tags.includes(tag) : false
+    );
+  }
+  return true;
+};
+var typeOnFilter = {
+  ["HumanAndAI" /* HumanAndAI */]: humanAndAI,
+  ["HumanOnly" /* HumanOnly */]: humanOnly,
+  ["AIOnly" /* AIOnly */]: aiOnly,
+  ["IncludingTags" /* IncludingTags */]: includingTags,
+  ["ExcludingTags" /* ExcludingTags */]: excludingTags
+};
+function concise(messages) {
+  return messages.map((message) => {
+    const prefix = message instanceof AIMessage ? "AI" : "Human";
+    return `${prefix}: ${message.content}`;
+  }).join("\n");
+}
+function verbose(messages) {
+  return messages.map((message) => {
+    const prefix = message instanceof AIMessage ? "AI" : "Human";
+    return `${prefix}:
+${message.content}`;
+  }).join("\n-------------------\n");
+}
+function redactAi(messages) {
+  return messages.map((message) => {
+    const prefix = message instanceof AIMessage ? "AI" : "Human";
+    const content = message instanceof AIMessage ? "[...]" : message.content;
+    return `${prefix}: ${content}`;
+  }).join("\n");
+}
+function redactHuman(messages) {
+  return messages.map((message) => {
+    const prefix = message instanceof AIMessage ? "AI" : "Human";
+    const content = message instanceof AIMessage ? "[...]" : message.content;
+    return `${prefix}: ${content}`;
+  }).join("\n");
+}
+var typeOnFormatter = {
+  ["concise" /* Concise */]: concise,
+  ["verbose" /* Verbose */]: verbose,
+  ["redact-ai" /* RedactAi */]: redactAi,
+  ["redact-human" /* RedactHuman */]: redactHuman
+};
+
+// src/helper/transform-messages/TransformMessages.ts
+var TransformMessages = class _TransformMessages {
+  constructor(effect) {
+    this.effect = effect;
+  }
+  /**
+   * Create a new TransformMessages from an array of messages.
+   */
+  static from(messages) {
+    return new _TransformMessages(Effect.succeed(messages));
+  }
+  /**
+   * Filter messages based on a predicate function
+   */
+  filter(predicate, tags) {
+    let finalPredicate;
+    if (typeof predicate === "string") {
+      finalPredicate = typeOnFilter[predicate];
+    } else {
+      finalPredicate = predicate;
+    }
+    return new _TransformMessages(
+      pipe(
+        this.effect,
+        Effect.map(
+          (messages) => messages.filter((message) => finalPredicate(message, tags))
+        )
+      )
+    );
+  }
+  /**
+   * Take only the last n messages, but safely.
+   * Tool calls should not be separated from the last human message.
+   * Ensures all tool call conversations in the last n messages are complete.
+   */
+  safelyTakeLast(n, pruneAfterNOvershootingMessages = 0) {
+    return new _TransformMessages(
+      pipe(
+        this.effect,
+        Effect.map((messages) => {
+          const total = messages.length;
+          if (n <= 0 || total === 0)
+            return [];
+          const start = Math.max(0, total - n);
+          const end = total;
+          const lastSlice = messages.slice(start, end);
+          if (lastSlice[0] instanceof ToolMessage && lastSlice[0].tool_call_id) {
+            let messagesToInclude = [];
+            const remainingMessages = messages.slice(0, start);
+            for (let i = remainingMessages.length - 1; i >= 0; i--) {
+              const msg = remainingMessages[i];
+              if (pruneAfterNOvershootingMessages > 0 && messagesToInclude.length - 1 >= pruneAfterNOvershootingMessages) {
+                messagesToInclude = [];
+                const filteredSlice = [];
+                let foundFirstNonToolMessage = false;
+                for (let i2 = 0; i2 < lastSlice.length; i2++) {
+                  const msg2 = lastSlice[i2];
+                  if (msg2 instanceof ToolMessage) {
+                    if (foundFirstNonToolMessage) {
+                      filteredSlice.push(msg2);
+                    }
+                  } else {
+                    foundFirstNonToolMessage = true;
+                    filteredSlice.push(msg2);
+                  }
+                }
+                return filteredSlice;
+              }
+              if (msg instanceof AIMessage && Array.isArray(msg.tool_calls)) {
+                messagesToInclude.push(msg);
+                break;
+              } else if (msg instanceof ToolMessage) {
+                messagesToInclude.push(msg);
+              } else {
+                throw new Error(
+                  "Messages array invalid no adjacent AI message found"
+                );
+              }
+            }
+            return [...messagesToInclude.reverse(), ...lastSlice];
+          } else {
+            return lastSlice;
+          }
+        })
+      )
+    );
+  }
+  /**
+   * Take only the last n messages
+   */
+  last(n) {
+    return new _TransformMessages(
+      pipe(
+        this.effect,
+        Effect.map((messages) => messages.slice(-n))
+      )
+    );
+  }
+  /**
+   * Take only the first n messages
+   */
+  first(n) {
+    return new _TransformMessages(
+      pipe(
+        this.effect,
+        Effect.map((messages) => messages.slice(0, n))
+      )
+    );
+  }
+  /**
+   * Skip the first n messages
+   */
+  skip(n) {
+    return new _TransformMessages(
+      pipe(
+        this.effect,
+        Effect.map((messages) => messages.slice(n))
+      )
+    );
+  }
+  /**
+   * Reverse the order of messages
+   */
+  reverse() {
+    return new _TransformMessages(
+      pipe(
+        this.effect,
+        Effect.map((messages) => [...messages].reverse())
+      )
+    );
+  }
+  /**
+   * Map over messages with a transformation function
+   */
+  map(fn) {
+    return new _TransformMessages(
+      pipe(
+        this.effect,
+        Effect.map((messages) => messages.map(fn))
+      )
+    );
+  }
+  /**
+   * Format messages according to the specified format type
+   */
+  format(formatType) {
+    return pipe(
+      this.effect,
+      Effect.map((messages) => {
+        if (formatType === "json" /* JSON */) {
+          return JSON.stringify(messages, null, 2);
+        }
+        const formatter = typeOnFormatter[formatType];
+        return formatter(messages);
+      })
+    );
+  }
+  // Sink methods
+  /**
+   * Convert to array - runs the effect and returns the result
+   */
+  toArray() {
+    return this.effect;
+  }
+  /**
+   * Convert to string - runs the effect and returns JSON string
+   */
+  toString() {
+    return pipe(
+      this.effect,
+      Effect.map((messages) => JSON.stringify(messages, null, 2))
+    );
+  }
+  /**
+   * Get the count of messages
+   */
+  count() {
+    return pipe(
+      this.effect,
+      Effect.map((messages) => messages.length)
+    );
+  }
+};
+
+export { AiCursor, BaseVoiceEndpointAdapter, Emitter, InputAudioController, Pump, SocketIoFactory, TransformMessages, VoiceEndpointAdapter, VoiceSocketAdapter, ensureFullWords, httpStreamResponse, useConversation, useSocketConversation };
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.js.map