@m4trix/core 0.8.1 → 0.10.0

package/dist/index.js

@@ -1,25 +1,8 @@
-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 { Brand, Schema, Effect, pipe, PubSub, Queue, Cause } from 'effect';
+import { Brand, Schema, Tracer, Layer, Effect, pipe, Exit, PubSub, Queue, Cause } from 'effect';
 export { Schema as S } from 'effect';
 import { randomUUID } from 'crypto';
 
-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;
-};
 var __accessCheck = (obj, member, msg) => {
   if (!member.has(obj))
     throw TypeError("Cannot " + msg);
@@ -39,1608 +22,6 @@ var __privateSet = (obj, member, value, setter) => {
   return value;
 };
 
-// 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) {
@@ -2748,8 +1129,66 @@ var Channel = {
     };
   }
 };
+
+// src/helper/types/noop.ts
+var asyncNoop = async () => {
+};
+
+// src/matrix/agent-network/stores/inmemory-network-store.ts
+var createInMemoryNetworkStore = () => {
+  const store = /* @__PURE__ */ new Map();
+  return {
+    storeEvent: (contextId, runId, event) => {
+      let byRun = store.get(contextId);
+      if (!byRun) {
+        byRun = /* @__PURE__ */ new Map();
+        store.set(contextId, byRun);
+      }
+      let events = byRun.get(runId);
+      if (!events) {
+        events = [];
+        byRun.set(runId, events);
+      }
+      events.push(event);
+    },
+    getEvents: (contextId, runId) => {
+      const events = store.get(contextId)?.get(runId);
+      return events ? [...events] : [];
+    },
+    getContextEvents: (contextId) => {
+      const byRun = store.get(contextId);
+      const result = /* @__PURE__ */ new Map();
+      if (byRun) {
+        for (const [runId, events] of byRun) {
+          result.set(runId, [...events]);
+        }
+      }
+      return result;
+    },
+    getFullStore: () => {
+      const result = /* @__PURE__ */ new Map();
+      for (const [contextId, byRun] of store) {
+        const contextMap = /* @__PURE__ */ new Map();
+        for (const [runId, events] of byRun) {
+          contextMap.set(runId, [...events]);
+        }
+        result.set(contextId, contextMap);
+      }
+      return result;
+    },
+    persist: () => asyncNoop(),
+    load: () => asyncNoop()
+  };
+};
+
+// src/matrix/agent-network/event-plane.ts
 var DEFAULT_CAPACITY = 16;
-var createEventPlane = (network, capacity = DEFAULT_CAPACITY) => Effect.gen(function* () {
+var createEventPlane = (options) => Effect.gen(function* () {
+  const {
+    network,
+    capacity = DEFAULT_CAPACITY,
+    store = createInMemoryNetworkStore()
+  } = options;
   const channels = network.getChannels();
   const pubsubs = /* @__PURE__ */ new Map();
   for (const channel of channels.values()) {
@@ -2762,12 +1201,59 @@ var createEventPlane = (network, capacity = DEFAULT_CAPACITY) => Effect.gen(func
       throw new Error(`Channel not found: ${channel}`);
     return p;
   };
-  const publish = (channel, envelope) => PubSub.publish(getPubsub(channel), envelope);
-  const publishToChannels = (targetChannels, envelope) => Effect.all(
-    targetChannels.map((c) => publish(c.name, envelope)),
-    { concurrency: "unbounded" }
-  ).pipe(Effect.map((results) => results.every(Boolean)));
+  const recordEvent = (envelope) => {
+    const { contextId, runId } = envelope.meta;
+    store.storeEvent(contextId, runId, envelope);
+  };
+  const publishToPubSub = (channel, envelope) => PubSub.publish(getPubsub(channel), envelope);
+  const publish = (channel, envelope) => Effect.sync(() => recordEvent(envelope)).pipe(
+    Effect.flatMap(() => publishToPubSub(channel, envelope)),
+    Effect.withSpan("event.publish", {
+      attributes: {
+        "event.name": envelope.name,
+        "event.payload": payloadForSpan(envelope.payload),
+        channel,
+        runId: envelope.meta.runId,
+        contextId: envelope.meta.contextId
+      }
+    })
+  );
+  const publishToChannels = (targetChannels, envelope) => Effect.sync(() => recordEvent(envelope)).pipe(
+    Effect.flatMap(
+      () => Effect.all(
+        targetChannels.map((c) => publishToPubSub(c.name, envelope)),
+        { concurrency: "unbounded" }
+      )
+    ),
+    Effect.map((results) => results.every(Boolean)),
+    Effect.withSpan("event.publish", {
+      attributes: {
+        "event.name": envelope.name,
+        "event.payload": payloadForSpan(envelope.payload),
+        runId: envelope.meta.runId,
+        contextId: envelope.meta.contextId
+      }
+    })
+  );
   const subscribe = (channel) => PubSub.subscribe(getPubsub(channel));
+  const getRunEvents = (runId, contextId) => {
+    return store.getEvents(contextId, runId).slice();
+  };
+  const getContextEvents = (contextId) => {
+    const byRun = store.getContextEvents(contextId);
+    const map = /* @__PURE__ */ new Map();
+    const all = [];
+    for (const [runId, events] of byRun) {
+      const readonlyEvents = events.slice();
+      map.set(runId, readonlyEvents);
+      all.push(...readonlyEvents);
+    }
+    return {
+      all,
+      byRun: (runId) => map.get(runId) ?? [],
+      map
+    };
+  };
   const shutdown = Effect.all([...pubsubs.values()].map(PubSub.shutdown), {
     concurrency: "unbounded"
   }).pipe(Effect.asVoid);
@@ -2775,42 +1261,77 @@ var createEventPlane = (network, capacity = DEFAULT_CAPACITY) => Effect.gen(func
     publish,
     publishToChannels,
     subscribe,
+    getRunEvents,
+    getContextEvents,
     shutdown
   };
 });
-var runSubscriber = (agent, publishesTo, dequeue, plane, emitQueue) => Effect.gen(function* () {
+function payloadForSpan(payload, maxLen = 500) {
+  try {
+    const s = JSON.stringify(payload);
+    return s.length > maxLen ? `${s.slice(0, maxLen)}...` : s;
+  } catch {
+    return String(payload);
+  }
+}
+var runSubscriber = (agent, publishesTo, dequeue, plane, emitQueue, channelName) => Effect.gen(function* () {
   const listensTo = agent.getListensTo?.() ?? [];
+  const agentId = agent.getId();
   const processOne = () => Effect.gen(function* () {
     const envelope = yield* Queue.take(dequeue);
     if (listensTo.length > 0 && !listensTo.includes(envelope.name)) {
       return;
     }
-    yield* Effect.tryPromise({
-      try: () => agent.invoke({
-        triggerEvent: envelope,
-        emit: (userEvent) => {
-          const fullEnvelope = {
-            name: userEvent.name,
-            meta: envelope.meta,
-            payload: userEvent.payload
-          };
-          if (emitQueue) {
-            Effect.runPromise(
-              Queue.offer(emitQueue, {
-                channels: publishesTo,
-                envelope: fullEnvelope
-              })
-            ).catch(() => {
-            });
-          } else {
-            Effect.runFork(
-              plane.publishToChannels(publishesTo, fullEnvelope)
-            );
-          }
+    const runEvents = plane.getRunEvents(
+      envelope.meta.runId,
+      envelope.meta.contextId
+    );
+    const contextEvents = plane.getContextEvents(envelope.meta.contextId);
+    yield* Effect.withSpan("agent.listen", {
+      attributes: {
+        agentId,
+        "event.name": envelope.name,
+        "event.payload": payloadForSpan(envelope.payload),
+        ...channelName !== void 0 && { channel: channelName }
+      }
+    })(
+      Effect.withSpan("agent.invoke", {
+        attributes: {
+          agentId,
+          "event.name": envelope.name,
+          "event.payload": payloadForSpan(envelope.payload)
         }
-      }),
-      catch: (e) => e
-    });
+      })(
+        Effect.tryPromise({
+          try: () => agent.invoke({
+            triggerEvent: envelope,
+            emit: (userEvent) => {
+              const fullEnvelope = {
+                name: userEvent.name,
+                meta: envelope.meta,
+                payload: userEvent.payload
+              };
+              if (emitQueue) {
+                Effect.runPromise(
+                  Queue.offer(emitQueue, {
+                    channels: publishesTo,
+                    envelope: fullEnvelope
+                  })
+                ).catch(() => {
+                });
+              } else {
+                Effect.runFork(
+                  plane.publishToChannels(publishesTo, fullEnvelope)
+                );
+              }
+            },
+            runEvents,
+            contextEvents
+          }),
+          catch: (e) => e
+        })
+      )
+    );
   }).pipe(
     Effect.catchAllCause(
       (cause) => Cause.isInterrupted(cause) ? Effect.void : Effect.sync(() => {
@@ -2832,7 +1353,8 @@ var run = (network, plane, options) => Effect.gen(function* () {
         reg.publishesTo,
         dequeue,
         plane,
-        emitQueue
+        emitQueue,
+        channel.name
       );
     }
   }
@@ -2901,7 +1423,16 @@ function streamFromDequeue(take, signal, eventFilter) {
   };
 }
 function expose(network, options) {
-  const { auth, select, plane: providedPlane, onRequest, startEventName = "request" } = options;
+  const {
+    auth,
+    select,
+    plane: providedPlane,
+    onRequest,
+    triggerEvents,
+    tracingLayer
+  } = options;
+  const triggerEventDef = triggerEvents?.[0];
+  const triggerEventName = triggerEventDef?.name ?? "request";
   const channels = resolveChannels(network, select);
   const eventFilter = select?.events;
   const mainChannel = network.getMainChannel();
@@ -2912,7 +1443,7 @@ function expose(network, options) {
     const payload = await extractPayload(req);
     const signal = req.request?.signal;
     const program = Effect.gen(function* () {
-      const plane = providedPlane ?? (yield* createEventPlane(network));
+      const plane = providedPlane ?? (yield* createEventPlane({ network, store: network.getStore() }));
       if (!providedPlane) {
         const emitQueue = yield* Queue.unbounded();
         yield* Effect.fork(
@@ -2928,25 +1459,46 @@ function expose(network, options) {
         yield* Effect.sleep("10 millis");
       }
       const targetChannel = mainChannel?.name ?? channels[0];
-      const emitStartEvent = (p) => {
-        const pld = p ?? payload;
+      let runId = req.runId ?? crypto.randomUUID();
+      let contextId = req.contextId ?? crypto.randomUUID();
+      const setRunId = (id) => {
+        runId = id;
+      };
+      const setContextId = (id) => {
+        contextId = id;
+      };
+      const emitStartEvent = (opts) => {
+        const meta = {
+          runId: opts.runId,
+          contextId: opts.contextId
+        };
         const envelope = {
-          name: startEventName,
-          meta: { runId: crypto.randomUUID() },
-          payload: pld
+          name: opts.event.name,
+          meta,
+          payload: opts.event.payload
         };
-        Effect.runPromise(plane.publish(targetChannel, envelope)).catch(() => {
-        });
+        Effect.runPromise(plane.publish(targetChannel, envelope)).catch(
+          () => {
+          }
+        );
       };
       const dequeue = yield* plane.subscribe(channels[0]);
       if (onRequest) {
         yield* Effect.tryPromise(
-          () => Promise.resolve(onRequest({ emitStartEvent, req, payload }))
+          () => Promise.resolve(
+            onRequest({
+              setRunId,
+              setContextId,
+              emitStartEvent,
+              req,
+              payload
+            })
+          )
         );
       } else if (!providedPlane) {
         const envelope = {
-          name: startEventName,
-          meta: { runId: crypto.randomUUID() },
+          name: triggerEventName,
+          meta: { runId, contextId },
           payload
         };
         yield* plane.publish(targetChannel, envelope);
@@ -2959,7 +1511,8 @@ function expose(network, options) {
       }
       return stream;
     });
-    return Effect.runPromise(program.pipe(Effect.scoped));
+    const runnable = tracingLayer ? program.pipe(Effect.provide(tracingLayer), Effect.scoped) : program.pipe(Effect.scoped);
+    return Effect.runPromise(runnable);
   };
   return {
     protocol: "sse",
@@ -2991,6 +1544,7 @@ var AgentNetwork = class _AgentNetwork {
     this.channels = /* @__PURE__ */ new Map();
     this.agentRegistrations = /* @__PURE__ */ new Map();
     this.spawnerRegistrations = [];
+    this._store = createInMemoryNetworkStore();
   }
   /* ─── Public Static Factory ─── */
   static setup(callback) {
@@ -3078,6 +1632,10 @@ var AgentNetwork = class _AgentNetwork {
   getSpawnerRegistrations() {
     return this.spawnerRegistrations;
   }
+  /** Store defined at network setup time. Shared across all event planes created for this network. */
+  getStore() {
+    return this._store;
+  }
   /**
    * Expose the network as a streamable API (e.g. SSE). Returns an ExposedAPI
    * that adapters (NextEndpoint, ExpressEndpoint) consume to produce streamed
@@ -3085,7 +1643,7 @@ var AgentNetwork = class _AgentNetwork {
    *
    * @example
    * const api = network.expose({ protocol: "sse", auth, select });
-   * export const GET = NextEndpoint.from(api).handler();
+   * export const GET = NextEndpoint.from(api, { requestToContextId, requestToRunId }).handler();
    */
   expose(options) {
     return expose(this, options);
@@ -3103,7 +1661,11 @@ var AgentNetwork = class _AgentNetwork {
   }
   runScoped(network, capacity) {
     return Effect.gen(function* () {
-      const plane = yield* createEventPlane(network, capacity);
+      const plane = yield* createEventPlane({
+        network,
+        capacity,
+        store: network.getStore()
+      });
       yield* Effect.fork(run(network, plane));
       return plane;
     });
@@ -3111,7 +1673,7 @@ var AgentNetwork = class _AgentNetwork {
 };
 var EventMetaSchema = Schema.Struct({
   runId: Schema.String,
-  contextId: Schema.optional(Schema.String),
+  contextId: Schema.String,
   correlationId: Schema.optional(Schema.String),
   causationId: Schema.optional(Schema.String),
   ts: Schema.optional(Schema.Number)
@@ -3134,9 +1696,7 @@ var AgentNetworkEvent = {
     const makeBound = (meta, payload2) => Effect.runSync(
       decodeEnvelope({ name, meta, payload: payload2 })
     );
-    const makeEffect = (payload2) => decodePayload(payload2).pipe(
-      Effect.map((p) => ({ name, payload: p }))
-    );
+    const makeEffect = (payload2) => decodePayload(payload2).pipe(Effect.map((p) => ({ name, payload: p })));
     const makeBoundEffect = (meta, payload2) => decodeEnvelope({ name, meta, payload: payload2 });
     const is = Schema.is(envelopeSchema);
     return {
@@ -3169,13 +1729,19 @@ var Agent = class {
     return __privateGet(this, _listensTo);
   }
   async invoke(options) {
-    const { triggerEvent, emit } = options ?? {};
+    const { triggerEvent, emit, runEvents, contextEvents } = options ?? {};
     const emitFn = emit ?? ((_event) => {
     });
     await __privateGet(this, _logic).call(this, {
       params: __privateGet(this, _params),
       triggerEvent: triggerEvent ?? void 0,
-      emit: emitFn
+      emit: emitFn,
+      runEvents: runEvents ?? [],
+      contextEvents: contextEvents ?? {
+        all: [],
+        byRun: () => [],
+        map: /* @__PURE__ */ new Map()
+      }
     });
   }
   getId() {
@@ -3288,14 +1854,19 @@ function toSSEStream(source, signal) {
 
 // src/matrix/io/adapters/next-endpoint.ts
 var NextEndpoint = {
-  from(api) {
+  from(api, options) {
     if (api.protocol !== "sse") {
       throw new Error(`NextEndpoint: unsupported protocol "${api.protocol}"`);
     }
+    const { requestToContextId, requestToRunId } = options;
     return {
       handler() {
         return async (request) => {
-          const req = { request };
+          const req = {
+            request,
+            contextId: requestToContextId(request),
+            runId: requestToRunId(request)
+          };
           try {
             const encoder = new TextEncoder();
             const { readable, writable } = new TransformStream();
@@ -3340,12 +1911,13 @@ var NextEndpoint = {
 
 // src/matrix/io/adapters/express-endpoint.ts
 var ExpressEndpoint = {
-  from(api) {
+  from(api, options) {
     if (api.protocol !== "sse") {
       throw new Error(
         `ExpressEndpoint: unsupported protocol "${api.protocol}"`
       );
     }
+    const { requestToContextId, requestToRunId } = options;
     return {
       handler() {
         return async (req, res) => {
@@ -3354,7 +1926,9 @@ var ExpressEndpoint = {
           const exposeReq = {
             request: { signal: controller.signal },
             req,
-            res
+            res,
+            contextId: requestToContextId(req),
+            runId: requestToRunId(req)
           };
           try {
             const encoder = new TextEncoder();
@@ -3386,7 +1960,79 @@ var ExpressEndpoint = {
     };
   }
 };
+var randomHexString = (length) => {
+  const chars = "abcdef0123456789";
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+};
+var ConsoleSpan = class {
+  constructor(name, parent, context, links, startTime, kind, depth) {
+    this.name = name;
+    this.parent = parent;
+    this.context = context;
+    this.startTime = startTime;
+    this.kind = kind;
+    this.depth = depth;
+    this._tag = "Span";
+    this.sampled = true;
+    this.attributes = /* @__PURE__ */ new Map();
+    this.links = [];
+    this.traceId = parent._tag === "Some" ? parent.value.traceId : randomHexString(32);
+    this.spanId = randomHexString(16);
+    this.links = Array.from(links);
+    this.status = { _tag: "Started", startTime };
+  }
+  end(endTime, exit) {
+    if (this.status._tag === "Ended")
+      return;
+    const startTime = this.status.startTime;
+    const durationNs = endTime - startTime;
+    const durationMs = Number(durationNs) / 1e6;
+    const indent = "  ".repeat(this.depth);
+    const attrs = Object.fromEntries(this.attributes);
+    const status = Exit.isSuccess(exit) ? "ok" : "error";
+    console.log(
+      `${indent}[trace] ${this.name} ${durationMs.toFixed(2)}ms (${status})`,
+      Object.keys(attrs).length > 0 ? attrs : ""
+    );
+    this.status = { _tag: "Ended", startTime, endTime, exit };
+  }
+  attribute(key, value) {
+    this.attributes.set(key, value);
+  }
+  event(_name, _startTime, _attributes) {
+  }
+  addLinks(links) {
+    this.links.push(...links);
+  }
+};
+function getDepth(parent) {
+  if (parent._tag === "None")
+    return 0;
+  const p = parent.value;
+  if (p._tag === "ExternalSpan")
+    return 0;
+  return 1 + getDepth(p.parent);
+}
+var consoleTracer = Tracer.make({
+  span: (name, parent, context, links, startTime, kind) => new ConsoleSpan(
+    name,
+    parent,
+    context,
+    links,
+    startTime,
+    kind,
+    getDepth(parent)
+  ),
+  context: (f) => f()
+});
+var consoleTracerLayer = Layer.setTracer(
+  consoleTracer
+);
 
-export { Agent, AgentFactory, AgentNetwork, AgentNetworkEvent, AiCursor, BaseVoiceEndpointAdapter, Channel, ChannelName, ConfiguredChannel, Emitter, EventMetaSchema, ExposeAuthError, ExpressEndpoint, InputAudioController, NextEndpoint, Pump, Sink, SocketIoFactory, TransformMessages, VoiceEndpointAdapter, VoiceSocketAdapter, ensureFullWords, formatSSE, httpStreamResponse, isHttpStreamSink, toSSEStream, useConversation, useSocketConversation };
+export { Agent, AgentFactory, AgentNetwork, AgentNetworkEvent, Channel, ChannelName, ConfiguredChannel, EventMetaSchema, ExposeAuthError, ExpressEndpoint, NextEndpoint, Pump, Sink, SocketIoFactory, TransformMessages, consoleTracer, consoleTracerLayer, ensureFullWords, formatSSE, httpStreamResponse, isHttpStreamSink, toSSEStream };
 //# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.js.map