@dtelecom/agents-js 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1201 @@
+import {
+  BaseSTTStream
+} from "./chunk-6OWWB2X7.mjs";
+import {
+  Embedder,
+  MemoryStore,
+  RoomMemory
+} from "./chunk-RQKGHAFV.mjs";
+import {
+  createLogger,
+  getLogLevel,
+  setLogLevel
+} from "./chunk-BN7PIFNJ.mjs";
+
+// src/core/voice-agent.ts
+import { EventEmitter as EventEmitter2 } from "events";
+
+// src/room/room-connection.ts
+import { Room, LocalAudioTrack, AudioSource, TrackSource } from "@dtelecom/server-sdk-node";
+var log = createLogger("RoomConnection");
+var RoomConnection = class {
+  room;
+  audioSource = null;
+  localTrack = null;
+  _connected = false;
+  constructor() {
+    this.room = new Room();
+  }
+  get connected() {
+    return this._connected;
+  }
+  /**
+   * Connect to a dTelecom room.
+   *
+   * 1. Create an Ed25519 JWT via AccessToken
+   * 2. Discover nearest SFU via getWsUrl()
+   * 3. Connect Room via WebRTC
+   * 4. Publish an audio track for the agent to speak through
+   */
+  async connect(options) {
+    const { room: roomName, apiKey, apiSecret, identity = "agent", name } = options;
+    log.info(`Connecting to room "${roomName}" as "${identity}"...`);
+    const { AccessToken } = await import("@dtelecom/server-sdk-js");
+    const token = new AccessToken(apiKey, apiSecret, {
+      identity,
+      name: name ?? identity
+    });
+    token.addGrant({
+      roomJoin: true,
+      room: roomName,
+      canPublish: true,
+      canSubscribe: true,
+      canPublishData: true
+    });
+    const wsUrl = await token.getWsUrl();
+    const jwt = token.toJwt();
+    log.info(`SFU URL: ${wsUrl}`);
+    await this.room.connect(wsUrl, jwt, { autoSubscribe: true });
+    this._connected = true;
+    log.info("Connected successfully");
+  }
+  /**
+   * Publish an audio track so the agent can speak.
+   * Returns the AudioSource to feed PCM16 audio into.
+   */
+  async publishAudioTrack() {
+    if (this.audioSource) return this.audioSource;
+    this.audioSource = new AudioSource(48e3, 1);
+    this.localTrack = LocalAudioTrack.createAudioTrack("agent-voice", this.audioSource);
+    await this.room.localParticipant.publishTrack(this.localTrack, {
+      name: "agent-voice",
+      source: TrackSource.MICROPHONE
+    });
+    log.info("Audio track published");
+    return this.audioSource;
+  }
+  /** Disconnect from the room and clean up resources. */
+  async disconnect() {
+    if (!this._connected) return;
+    if (this.localTrack) {
+      await this.room.localParticipant.unpublishTrack(this.localTrack);
+      this.localTrack = null;
+    }
+    if (this.audioSource) {
+      this.audioSource.destroy();
+      this.audioSource = null;
+    }
+    await this.room.disconnect();
+    this._connected = false;
+    log.info("Disconnected from room");
+  }
+};
+
+// src/room/audio-input.ts
+var log2 = createLogger("AudioInput");
+var AudioInput = class {
+  participantIdentity;
+  stream;
+  _closed = false;
+  frameCount = 0;
+  constructor(track, participantIdentity) {
+    this.participantIdentity = participantIdentity;
+    this.stream = track.createStream(16e3, 1);
+    log2.info(`AudioInput created for "${participantIdentity}" (trackSid=${track.sid})`);
+  }
+  get closed() {
+    return this._closed;
+  }
+  /**
+   * Async iterate over PCM16 buffers from this participant.
+   * Each yielded Buffer is 16kHz mono PCM16 LE.
+   */
+  async *frames() {
+    for await (const frame of this.stream) {
+      if (this._closed) break;
+      this.frameCount++;
+      if (this.frameCount === 1 || this.frameCount % 500 === 0) {
+        log2.info(`[${this.participantIdentity}] frame #${this.frameCount}`);
+      }
+      yield frame.toBuffer();
+    }
+    log2.info(`[${this.participantIdentity}] frame iterator ended (total: ${this.frameCount})`);
+  }
+  /** Async iterate over AudioFrame objects. */
+  async *audioFrames() {
+    for await (const frame of this.stream) {
+      if (this._closed) break;
+      yield frame;
+    }
+  }
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    this.stream.close();
+    log2.debug(`AudioInput closed for participant "${this.participantIdentity}"`);
+  }
+};
+
+// src/room/audio-output.ts
+import { AudioFrame } from "@dtelecom/server-sdk-node";
+import { writeFileSync, appendFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+var log3 = createLogger("AudioOutput");
+var SAMPLE_RATE = 16e3;
+var CHANNELS = 1;
+var FRAME_DURATION_MS = 20;
+var SAMPLES_PER_FRAME = SAMPLE_RATE * FRAME_DURATION_MS / 1e3;
+var SILENCE = new Int16Array(SAMPLES_PER_FRAME);
+var AudioOutput = class {
+  source;
+  _playing = false;
+  _responding = false;
+  _stopped = false;
+  silenceInterval = null;
+  /** When set, raw PCM from TTS is saved to this directory as WAV files for debugging. */
+  dumpDir = null;
+  dumpCounter = 0;
+  constructor(source) {
+    this.source = source;
+  }
+  get playing() {
+    return this._playing;
+  }
+  /**
+   * Mark the start of a multi-sentence response.
+   * Suppresses silence injection between sentences so partial frames
+   * in AudioSource's buffer don't get corrupted by interleaved silence.
+   */
+  beginResponse() {
+    this._responding = true;
+  }
+  /** Mark the end of a response — re-enable silence keepalive. */
+  endResponse() {
+    this._responding = false;
+  }
+  /**
+   * Start sparse silence keepalive to prevent the SFU from dropping the track.
+   * With Opus DTX enabled, the encoder handles silence natively — we only need
+   * an occasional packet to keep the SSRC alive.
+   */
+  startSilence() {
+    if (this.silenceInterval) return;
+    log3.debug("Starting silence keepalive (sparse, 3s interval)");
+    this.silenceInterval = setInterval(() => {
+      if (!this._playing && !this._responding && !this._stopped) {
+        const f = new AudioFrame(SILENCE, SAMPLE_RATE, CHANNELS, SAMPLES_PER_FRAME);
+        this.source.captureFrame(f).catch(() => {
+        });
+      }
+    }, 3e3);
+  }
+  /**
+   * Write a PCM16 buffer to the audio output.
+   * The buffer is split into 20ms frames and fed to AudioSource.
+   */
+  async writeBuffer(pcm16) {
+    this._playing = true;
+    try {
+      await this.writeFrames(pcm16);
+    } finally {
+      this._playing = false;
+    }
+  }
+  /**
+   * Write a stream of PCM16 buffers (from TTS) to the audio output.
+   * Supports cancellation via AbortSignal.
+   */
+  async writeStream(stream, signal) {
+    this._playing = true;
+    const streamStart = performance.now();
+    let chunkCount = 0;
+    let totalBytes = 0;
+    log3.debug("writeStream: started");
+    const rawChunks = this.dumpDir ? [] : null;
+    try {
+      for await (const chunk of stream) {
+        if (signal?.aborted) {
+          log3.debug(`writeStream: cancelled after ${chunkCount} chunks, ${(performance.now() - streamStart).toFixed(0)}ms`);
+          break;
+        }
+        chunkCount++;
+        totalBytes += chunk.byteLength;
+        rawChunks?.push(Buffer.from(chunk));
+        await this.writeFrames(chunk);
+      }
+    } finally {
+      this._playing = false;
+      const elapsed = performance.now() - streamStart;
+      const audioDurationMs = totalBytes / 2 / SAMPLE_RATE * 1e3;
+      log3.info(
+        `writeStream: done \u2014 ${chunkCount} chunks, ${totalBytes} bytes, audio=${audioDurationMs.toFixed(0)}ms, wall=${elapsed.toFixed(0)}ms`
+      );
+      if (rawChunks && rawChunks.length > 0 && this.dumpDir) {
+        try {
+          if (!existsSync(this.dumpDir)) mkdirSync(this.dumpDir, { recursive: true });
+          const filePath = join(this.dumpDir, `tts-raw-${++this.dumpCounter}.wav`);
+          writeWav(filePath, rawChunks, SAMPLE_RATE);
+          log3.info(`writeStream: saved raw TTS to ${filePath}`);
+        } catch (err) {
+          log3.warn("writeStream: failed to save WAV dump:", err);
+        }
+      }
+    }
+  }
+  /**
+   * Split a PCM16 buffer into 20ms frames and write them at real-time pace.
+   * Partial frames at the end are sent directly — AudioSource handles
+   * accumulation in its internal buffer.
+   */
+  async writeFrames(pcm16) {
+    const aligned = Buffer.alloc(pcm16.byteLength);
+    pcm16.copy(aligned);
+    const samples = new Int16Array(
+      aligned.buffer,
+      aligned.byteOffset,
+      aligned.byteLength / 2
+    );
+    let offset = 0;
+    while (offset < samples.length) {
+      const end = Math.min(offset + SAMPLES_PER_FRAME, samples.length);
+      const frameSamples = samples.subarray(offset, end);
+      const frame = new AudioFrame(
+        frameSamples,
+        SAMPLE_RATE,
+        CHANNELS,
+        frameSamples.length
+      );
+      await this.source.captureFrame(frame);
+      if (frameSamples.length === SAMPLES_PER_FRAME) {
+        await sleep(FRAME_DURATION_MS);
+      }
+      offset = end;
+    }
+  }
+  /**
+   * Write silence frames for the given duration.
+   * Used to pad the end of a response so the last Opus frame is fully flushed
+   * and the audio doesn't cut off abruptly.
+   */
+  async writeSilence(durationMs) {
+    const frameCount = Math.ceil(durationMs / FRAME_DURATION_MS);
+    for (let i = 0; i < frameCount; i++) {
+      const frame = new AudioFrame(SILENCE, SAMPLE_RATE, CHANNELS, SAMPLES_PER_FRAME);
+      await this.source.captureFrame(frame);
+      await sleep(FRAME_DURATION_MS);
+    }
+  }
+  /** Flush any buffered audio in AudioSource */
+  flush() {
+    this.source.flush();
+    this._playing = false;
+  }
+  /** Stop the silence keepalive */
+  stop() {
+    this._stopped = true;
+    if (this.silenceInterval) {
+      clearInterval(this.silenceInterval);
+      this.silenceInterval = null;
+    }
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function writeWav(filePath, pcmChunks, sampleRate) {
+  const dataSize = pcmChunks.reduce((sum, b) => sum + b.byteLength, 0);
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0);
+  header.writeUInt32LE(36 + dataSize, 4);
+  header.write("WAVE", 8);
+  header.write("fmt ", 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(1, 22);
+  header.writeUInt32LE(sampleRate, 24);
+  header.writeUInt32LE(sampleRate * 2, 28);
+  header.writeUInt16LE(2, 32);
+  header.writeUInt16LE(16, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(dataSize, 40);
+  writeFileSync(filePath, header);
+  for (const chunk of pcmChunks) {
+    appendFileSync(filePath, chunk);
+  }
+}
+
+// src/core/pipeline.ts
+import { EventEmitter } from "events";
+
+// src/core/context-manager.ts
+var log4 = createLogger("ContextManager");
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+var ContextManager = class {
+  instructions;
+  maxContextTokens;
+  recentTurnsToKeep;
+  turns = [];
+  summary = null;
+  constructor(options) {
+    this.instructions = options.instructions;
+    this.maxContextTokens = options.maxContextTokens ?? 5e3;
+    this.recentTurnsToKeep = options.recentTurnsToKeep ?? 4;
+  }
+  /** Add a user's speech turn to the conversation */
+  addUserTurn(speaker, text) {
+    this.turns.push({
+      speaker,
+      text,
+      isAgent: false,
+      timestamp: Date.now()
+    });
+  }
+  /** Add the agent's response to the conversation */
+  addAgentTurn(text) {
+    this.turns.push({
+      speaker: "assistant",
+      text,
+      isAgent: true,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Build the messages array for the LLM call.
+   *
+   * Structure:
+   * [system prompt]
+   * [memory context, if provided]
+   * [conversation summary, if any]
+   * [recent verbatim turns]
+   *
+   * @param memoryContext - Optional relevant context injected by the application
+   */
+  buildMessages(memoryContext) {
+    const messages = [];
+    messages.push({ role: "system", content: this.instructions });
+    if (memoryContext) {
+      messages.push({
+        role: "system",
+        content: `Relevant context from past conversations:
+${memoryContext}`
+      });
+    }
+    if (this.summary) {
+      messages.push({
+        role: "system",
+        content: `Conversation summary so far:
+${this.summary}`
+      });
+    }
+    const turnsToInclude = this.summary ? this.turns.slice(-this.recentTurnsToKeep) : this.turns;
+    for (const turn of turnsToInclude) {
+      if (turn.isAgent) {
+        messages.push({ role: "assistant", content: turn.text });
+      } else {
+        messages.push({
+          role: "user",
+          content: `[${turn.speaker}]: ${turn.text}`
+        });
+      }
+    }
+    return messages;
+  }
+  /** Check if summarization should be triggered */
+  shouldSummarize() {
+    const totalTokens = this.turns.reduce(
+      (acc, t) => acc + estimateTokens(t.text) + 10,
+      estimateTokens(this.instructions)
+    );
+    return totalTokens > this.maxContextTokens;
+  }
+  /**
+   * Summarize older turns using the LLM.
+   * Keeps the most recent turns verbatim.
+   */
+  async summarize(llm) {
+    if (this.turns.length <= this.recentTurnsToKeep) return;
+    const olderTurns = this.turns.slice(0, -this.recentTurnsToKeep);
+    const transcript = olderTurns.map((t) => `[${t.speaker}]: ${t.text}`).join("\n");
+    const summaryPrompt = [
+      {
+        role: "system",
+        content: "Summarize this conversation concisely, preserving key facts, decisions, and action items."
+      },
+      { role: "user", content: transcript }
+    ];
+    let summaryText = "";
+    for await (const chunk of llm.chat(summaryPrompt)) {
+      if (chunk.type === "token" && chunk.token) {
+        summaryText += chunk.token;
+      }
+    }
+    this.summary = this.summary ? `${this.summary}
+
+${summaryText}` : summaryText;
+    this.turns = this.turns.slice(-this.recentTurnsToKeep);
+    log4.info(`Summarized ${olderTurns.length} turns, ${this.turns.length} recent turns kept`);
+  }
+  /** Get the full transcript */
+  getFullTranscript() {
+    return this.turns.map((t) => `[${t.speaker}]: ${t.text}`).join("\n");
+  }
+  /** Reset the context */
+  reset() {
+    this.turns = [];
+    this.summary = null;
+  }
+};
+
+// src/core/sentence-splitter.ts
+var MIN_CHUNK = 20;
+var MAX_CHUNK = 150;
+var SentenceSplitter = class {
+  buffer = "";
+  /** Add a token and get back any speakable chunks */
+  push(token) {
+    this.buffer += token;
+    return this.extractChunks();
+  }
+  /** Flush any remaining text as a final chunk */
+  flush() {
+    const text = this.buffer.trim();
+    this.buffer = "";
+    return text.length > 0 ? text : null;
+  }
+  /** Reset the splitter */
+  reset() {
+    this.buffer = "";
+  }
+  extractChunks() {
+    const chunks = [];
+    while (true) {
+      const sentenceMatch = this.buffer.match(/[^.!?]*[.!?]\s*/);
+      if (sentenceMatch && sentenceMatch.index !== void 0) {
+        const end = sentenceMatch.index + sentenceMatch[0].length;
+        const chunk = this.buffer.slice(0, end).trim();
+        if (chunk.length >= MIN_CHUNK) {
+          chunks.push(chunk);
+          this.buffer = this.buffer.slice(end);
+          continue;
+        }
+      }
+      if (this.buffer.length >= MAX_CHUNK) {
+        const clauseMatch = this.buffer.match(/[,;:\u2014]\s*/);
+        if (clauseMatch && clauseMatch.index !== void 0 && clauseMatch.index >= MIN_CHUNK) {
+          const end = clauseMatch.index + clauseMatch[0].length;
+          const chunk = this.buffer.slice(0, end).trim();
+          chunks.push(chunk);
+          this.buffer = this.buffer.slice(end);
+          continue;
+        }
+        const spaceIdx = this.buffer.lastIndexOf(" ", MAX_CHUNK);
+        if (spaceIdx >= MIN_CHUNK) {
+          const chunk = this.buffer.slice(0, spaceIdx).trim();
+          chunks.push(chunk);
+          this.buffer = this.buffer.slice(spaceIdx);
+          continue;
+        }
+      }
+      break;
+    }
+    return chunks;
+  }
+};
+
+// src/core/turn-detector.ts
+var log5 = createLogger("TurnDetector");
+var TurnDetector = class {
+  silenceTimeoutMs;
+  silenceTimer = null;
+  _onTurnEnd = null;
+  lastFinalText = "";
+  constructor(options = {}) {
+    this.silenceTimeoutMs = options.silenceTimeoutMs ?? 800;
+  }
+  /** Set the callback for when a turn ends */
+  set onTurnEnd(cb) {
+    this._onTurnEnd = cb;
+  }
+  /**
+   * Feed a transcription result.
+   * Returns true if this result represents a completed turn.
+   */
+  handleTranscription(text, isFinal) {
+    this.clearTimer();
+    if (isFinal && text.trim().length > 0) {
+      this.lastFinalText = text;
+      this.silenceTimer = setTimeout(() => {
+        log5.debug(`Turn ended after ${this.silenceTimeoutMs}ms silence`);
+        this._onTurnEnd?.();
+      }, this.silenceTimeoutMs);
+      return false;
+    }
+    if (!isFinal && text.trim().length > 0) {
+      this.clearTimer();
+    }
+    return false;
+  }
+  /** Force-trigger turn end */
+  forceTurnEnd() {
+    this.clearTimer();
+    this._onTurnEnd?.();
+  }
+  /** Reset state */
+  reset() {
+    this.clearTimer();
+    this.lastFinalText = "";
+  }
+  clearTimer() {
+    if (this.silenceTimer) {
+      clearTimeout(this.silenceTimer);
+      this.silenceTimer = null;
+    }
+  }
+};
+
+// src/core/barge-in.ts
+var log6 = createLogger("BargeIn");
+var BargeIn = class {
+  abortController = null;
+  _interrupted = false;
+  _onInterrupt = null;
+  get interrupted() {
+    return this._interrupted;
+  }
+  /** Set the callback for when barge-in occurs */
+  set onInterrupt(cb) {
+    this._onInterrupt = cb;
+  }
+  /**
+   * Create a new AbortController for the current response cycle.
+   * Call this at the start of each STT->LLM->TTS cycle.
+   */
+  startCycle() {
+    this.abortController = new AbortController();
+    this._interrupted = false;
+    return this.abortController.signal;
+  }
+  /** Trigger barge-in. Called when STT detects speech during agent output. */
+  trigger() {
+    if (this._interrupted) return;
+    this._interrupted = true;
+    log6.info("Barge-in detected \u2014 cancelling current response");
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this._onInterrupt?.();
+  }
+  /** Reset after the interrupted cycle is cleaned up */
+  reset() {
+    this._interrupted = false;
+    this.abortController = null;
+  }
+};
+
+// src/core/pipeline.ts
+var log7 = createLogger("Pipeline");
+var AUDIO_DRAIN_MS = 800;
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var Pipeline = class extends EventEmitter {
+  stt;
+  llm;
+  tts;
+  audioOutput;
+  context;
+  turnDetector;
+  bargeIn;
+  splitter;
+  respondMode;
+  agentName;
+  nameVariants;
+  beforeRespond;
+  memory;
+  /** Active STT streams, keyed by participant identity */
+  sttStreams = /* @__PURE__ */ new Map();
+  _processing = false;
+  _running = false;
+  _agentState = "idle";
+  /** Queued turn while current one is still processing */
+  pendingTurn = null;
+  constructor(options) {
+    super();
+    this.stt = options.stt;
+    this.llm = options.llm;
+    this.tts = options.tts;
+    this.audioOutput = options.audioOutput;
+    this.respondMode = options.respondMode ?? "always";
+    this.agentName = (options.agentName ?? "assistant").toLowerCase();
+    this.nameVariants = (options.nameVariants ?? []).map((n) => n.toLowerCase());
+    this.beforeRespond = options.beforeRespond;
+    this.memory = options.memory;
+    this.context = new ContextManager({
+      instructions: options.instructions
+    });
+    this.turnDetector = new TurnDetector({
+      silenceTimeoutMs: options.silenceTimeoutMs
+    });
+    this.bargeIn = new BargeIn();
+    this.splitter = new SentenceSplitter();
+    this.turnDetector.onTurnEnd = () => {
+    };
+    this.bargeIn.onInterrupt = () => {
+      this.audioOutput.flush();
+      this.splitter.reset();
+      this.setAgentState("idle");
+    };
+    if (this.llm.warmup) {
+      this.llm.warmup(options.instructions).catch((err) => {
+        log7.warn("LLM warmup failed:", err);
+      });
+    }
+    if (this.tts?.warmup) {
+      this.tts.warmup().catch((err) => {
+        log7.warn("TTS warmup failed:", err);
+      });
+    }
+  }
+  get processing() {
+    return this._processing;
+  }
+  get running() {
+    return this._running;
+  }
+  get agentState() {
+    return this._agentState;
+  }
+  setAgentState(state) {
+    if (this._agentState !== state) {
+      this._agentState = state;
+      this.emit("agentState", state);
+    }
+  }
+  addParticipant(identity) {
+    const existing = this.sttStreams.get(identity);
+    if (existing) {
+      existing.close();
+      this.sttStreams.delete(identity);
+      log7.info(`Replacing STT stream for "${identity}"`);
+    }
+    const stream = this.stt.createStream();
+    this.sttStreams.set(identity, stream);
+    this._running = true;
+    stream.on("transcription", (result) => {
+      this.handleTranscription(identity, result);
+    });
+    stream.on("error", (error) => {
+      log7.error(`STT error for ${identity}:`, error);
+      this.emit("error", error);
+    });
+    log7.info(`STT stream started for participant "${identity}"`);
+    return stream;
+  }
+  async removeParticipant(identity) {
+    const stream = this.sttStreams.get(identity);
+    if (stream) {
+      await stream.close();
+      this.sttStreams.delete(identity);
+      log7.info(`STT stream removed for participant "${identity}"`);
+    }
+  }
+  async stop() {
+    this._running = false;
+    this.turnDetector.reset();
+    this.bargeIn.reset();
+    this.splitter.reset();
+    for (const [, stream] of this.sttStreams) {
+      await stream.close();
+    }
+    this.sttStreams.clear();
+    log7.info("Pipeline stopped");
+  }
+  getContextManager() {
+    return this.context;
+  }
+  lastFinalAt = 0;
+  lastSttDuration = 0;
+  async handleTranscription(speaker, result) {
+    this.emit("transcription", { ...result, speaker });
+    if (!result.isFinal && result.text.trim()) {
+      this.setAgentState("listening");
+    }
+    if (this.audioOutput.playing && result.text.trim().length > 0) {
+      this.bargeIn.trigger();
+    }
+    if (result.isFinal && result.text.trim()) {
+      const text = result.text.trim();
+      this.lastFinalAt = performance.now();
+      this.lastSttDuration = result.sttDuration ?? 0;
+      this.memory?.storeTurn(speaker, text, false);
+      if (await this.shouldRespond(speaker, text)) {
+        this.processTurn(speaker, text);
+      } else {
+        log7.info(`Not responding to "${speaker}": "${text.slice(0, 60)}" (mode=${this.respondMode})`);
+        this.setAgentState("idle");
+      }
+    } else if (result.isFinal) {
+      this.setAgentState("idle");
+    }
+  }
+  /**
+   * Determine if the agent should respond to this turn.
+   * In 'always' mode: responds to everything.
+   * In 'addressed' mode: only when agent name is mentioned + optional beforeRespond hook.
+   */
+  async shouldRespond(speaker, text) {
+    if (this.respondMode === "always") return true;
+    const lower = text.toLowerCase();
+    const nameMatch = lower.includes(this.agentName) || this.nameVariants.some((v) => lower.includes(v));
+    if (!nameMatch) return false;
+    if (this.beforeRespond) {
+      return this.beforeRespond(speaker, text);
+    }
+    return true;
+  }
+  async processTurn(speaker, text) {
+    if (this._processing) {
+      log7.info(`Queuing turn (current still processing): "${text}"`);
+      this.pendingTurn = { speaker, text };
+      this.bargeIn.trigger();
+      return;
+    }
+    this._processing = true;
+    const tSpeechEnd = this.lastFinalAt;
+    const sttDuration = this.lastSttDuration;
+    let tLlmFirstToken = 0;
+    let tFirstSentence = 0;
+    let tFirstAudioPlayed = 0;
+    log7.info(`Processing turn from "${speaker}": ${text}`);
+    try {
+      this.context.addUserTurn(speaker, text);
+      if (this.context.shouldSummarize()) {
+        await this.context.summarize(this.llm);
+      }
+      const signal = this.bargeIn.startCycle();
+      let memoryContext = "";
+      if (this.memory) {
+        try {
+          memoryContext = await this.memory.searchRelevant(text);
+        } catch (err) {
+          log7.warn("Memory search failed:", err);
+        }
+      }
+      const messages = this.context.buildMessages(memoryContext || void 0);
+      let fullResponse = "";
+      this.setAgentState("thinking");
+      const sentenceQueue = [];
+      let producerDone = false;
+      let wakeConsumer = null;
+      const wake = () => {
+        wakeConsumer?.();
+      };
+      const producer = async () => {
+        let isFirstToken = true;
+        let isFirstSentence = true;
+        const llmStream = this.llm.chat(messages, signal);
+        try {
+          while (!signal.aborted) {
+            const { value: chunk, done } = await llmStream.next();
+            if (done || !chunk) break;
+            if (signal.aborted) break;
+            if (chunk.type === "token" && chunk.token) {
+              if (isFirstToken) {
+                tLlmFirstToken = performance.now();
+                isFirstToken = false;
+                log7.info(`llm_first_token: ${(tLlmFirstToken - tSpeechEnd).toFixed(0)}ms`);
+              }
+              fullResponse += chunk.token;
+              const sentences = this.splitter.push(chunk.token);
+              for (const sentence of sentences) {
+                if (signal.aborted) break;
+                if (isFirstSentence) {
+                  tFirstSentence = performance.now();
+                  isFirstSentence = false;
+                  log7.info(`first_sentence: ${(tFirstSentence - tSpeechEnd).toFixed(0)}ms \u2014 "${sentence.slice(0, 60)}"`);
+                }
+                sentenceQueue.push(sentence);
+                wake();
+              }
+            }
+          }
+        } finally {
+          await llmStream.return(void 0);
+        }
+        if (!signal.aborted) {
+          const remaining = this.splitter.flush();
+          if (remaining) {
+            if (isFirstSentence) {
+              tFirstSentence = performance.now();
+              isFirstSentence = false;
+              log7.info(`first_sentence (flush): ${(tFirstSentence - tSpeechEnd).toFixed(0)}ms \u2014 "${remaining.slice(0, 60)}"`);
+            }
+            sentenceQueue.push(remaining);
+            wake();
+          }
+        }
+        producerDone = true;
+        wake();
+      };
+      const consumer = async () => {
+        this.audioOutput.beginResponse();
+        try {
+          while (true) {
+            if (signal.aborted) break;
+            if (sentenceQueue.length > 0) {
+              const sentence = sentenceQueue.shift();
+              if (!/\w/.test(sentence)) {
+                log7.debug(`Skipping non-word sentence: "${sentence}"`);
+                continue;
+              }
+              await this.synthesizeAndPlay(sentence, signal, (t) => {
+                if (!tFirstAudioPlayed) {
+                  tFirstAudioPlayed = t;
+                  this.setAgentState("speaking");
+                }
+                this.emit("sentence", sentence);
+              });
+              continue;
+            }
+            if (producerDone) break;
+            await new Promise((resolve) => {
+              wakeConsumer = resolve;
+            });
+            wakeConsumer = null;
+          }
+        } finally {
+          if (!signal.aborted) {
+            await this.audioOutput.writeSilence(40);
+          }
+          this.audioOutput.endResponse();
+        }
+      };
+      await Promise.all([producer(), consumer()]);
+      const ttftMs = tLlmFirstToken ? tLlmFirstToken - tSpeechEnd : 0;
+      const llmMs = tFirstSentence ? tFirstSentence - tSpeechEnd : 0;
+      const ttsMs = tFirstAudioPlayed && tFirstSentence ? tFirstAudioPlayed - tFirstSentence : 0;
+      const overallMs = sttDuration + llmMs + ttsMs;
+      log7.info(
+        `LATENCY "${text.slice(0, 30)}": STT=${sttDuration.toFixed(0)}ms LLM=${llmMs.toFixed(0)}ms (TTFT=${ttftMs.toFixed(0)}ms) TTS=${ttsMs.toFixed(0)}ms Overall=${overallMs.toFixed(0)}ms`
+      );
+      if (fullResponse.trim()) {
+        this.context.addAgentTurn(fullResponse.trim());
+        this.memory?.storeTurn("assistant", fullResponse.trim(), true);
+        this.emit("response", fullResponse.trim());
+      }
+      await sleep2(AUDIO_DRAIN_MS);
+      this.setAgentState("idle");
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        log7.debug("Turn processing aborted (barge-in)");
+      } else {
+        log7.error("Error processing turn:", err);
+        this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      this._processing = false;
+      this.bargeIn.reset();
+      if (this.pendingTurn) {
+        const { speaker: nextSpeaker, text: nextText } = this.pendingTurn;
+        this.pendingTurn = null;
+        log7.info(`Processing queued turn from "${nextSpeaker}": ${nextText}`);
+        this.processTurn(nextSpeaker, nextText);
+      }
+    }
+  }
+  /**
+   * Speak text directly via TTS, bypassing the LLM.
+   * Supports barge-in — if the student speaks, the greeting is cut short.
+   * Adds the text to conversation context so the LLM knows what was said.
+   */
+  async say(text) {
+    if (this._processing) {
+      log7.warn("say() called while processing \u2014 skipping");
+      return;
+    }
+    this._processing = true;
+    log7.info(`say(): "${text.slice(0, 60)}"`);
+    try {
+      const signal = this.bargeIn.startCycle();
+      this.audioOutput.beginResponse();
+      this.setAgentState("thinking");
+      await this.synthesizeAndPlay(text, signal, () => {
+        this.setAgentState("speaking");
+        this.emit("sentence", text);
+      });
+      if (!signal.aborted) {
+        await this.audioOutput.writeSilence(40);
+        this.context.addAgentTurn(text);
+        this.memory?.storeTurn("assistant", text, true);
+        this.emit("response", text);
+      }
+      await sleep2(AUDIO_DRAIN_MS);
+      this.setAgentState("idle");
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        log7.debug("say() aborted (barge-in)");
+      } else {
+        log7.error("Error in say():", err);
+        this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      this._processing = false;
+      this.audioOutput.endResponse();
+      this.bargeIn.reset();
+      if (this.pendingTurn) {
+        const { speaker: nextSpeaker, text: nextText } = this.pendingTurn;
+        this.pendingTurn = null;
+        log7.info(`Processing queued turn from "${nextSpeaker}": ${nextText}`);
+        this.processTurn(nextSpeaker, nextText);
+      }
+    }
+  }
+  async synthesizeAndPlay(text, signal, onFirstAudio) {
+    if (!this.tts || signal.aborted) {
+      log7.info(`[Agent says]: ${text}`);
+      return;
+    }
+    try {
+      const ttsStart = performance.now();
+      let firstChunk = true;
+      let ttsChunkCount = 0;
+      const ttsStream = this.tts.synthesize(text, signal);
+      const measuredStream = async function* () {
+        for await (const chunk of ttsStream) {
+          ttsChunkCount++;
+          if (firstChunk) {
+            firstChunk = false;
+            const now = performance.now();
+            log7.info(`tts_first_audio: ${(now - ttsStart).toFixed(0)}ms for "${text.slice(0, 40)}"`);
+            onFirstAudio(now);
+          }
+          yield chunk;
+        }
+      };
+      await this.audioOutput.writeStream(measuredStream(), signal);
+      log7.info(`synthesizeAndPlay done: ${(performance.now() - ttsStart).toFixed(0)}ms, ${ttsChunkCount} chunks for "${text.slice(0, 40)}"`);
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") return;
+      throw err;
+    }
+  }
+};
+
+// src/core/voice-agent.ts
+var log8 = createLogger("VoiceAgent");
+var VoiceAgent = class extends EventEmitter2 {
+  config;
+  connection = null;
+  pipeline = null;
+  audioInputs = /* @__PURE__ */ new Map();
+  audioOutput = null;
+  memory = null;
+  _running = false;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  get running() {
+    return this._running;
+  }
+  get room() {
+    return this.connection?.room ?? null;
+  }
+  /** Enable saving raw TTS audio as WAV files to `dir` for debugging. */
+  enableAudioDump(dir) {
+    this._dumpDir = dir;
+    if (this.audioOutput) {
+      this.audioOutput.dumpDir = dir;
+    }
+  }
+  _dumpDir = null;
+  /**
+   * Speak text directly via TTS, bypassing the LLM.
+   * Use for greetings or announcements. Supports barge-in.
+   */
+  async say(text) {
+    if (!this.pipeline) {
+      throw new Error("Agent not started \u2014 call start() first");
+    }
+    await this.pipeline.say(text);
+  }
+  /** Start the agent — connect to room and begin listening. */
+  async start(options) {
+    if (this._running) {
+      throw new Error("Agent is already running");
+    }
+    log8.info(`Starting agent for room "${options.room}"...`);
+    if (this.config.memory?.enabled) {
+      const { RoomMemory: RoomMemory2 } = await import("./room-memory-VAREPHY6.mjs");
+      this.memory = new RoomMemory2({
+        dbPath: this.config.memory.dbPath ?? "./data/memory.db",
+        room: options.room
+      });
+      await this.memory.init();
+      this.memory.startSession();
+      log8.info("Memory initialized");
+    }
+    this.connection = new RoomConnection();
+    await this.connection.connect({
+      room: options.room,
+      apiKey: options.apiKey,
+      apiSecret: options.apiSecret,
+      identity: options.identity ?? "agent",
+      name: options.name ?? options.identity ?? "AI Agent"
+    });
+    const source = await this.connection.publishAudioTrack();
+    this.audioOutput = new AudioOutput(source);
+    if (this._dumpDir) this.audioOutput.dumpDir = this._dumpDir;
+    this.audioOutput.startSilence();
+    this.pipeline = new Pipeline({
+      stt: this.config.stt,
+      llm: this.config.llm,
+      tts: this.config.tts,
+      instructions: this.config.instructions,
+      audioOutput: this.audioOutput,
+      respondMode: this.config.respondMode,
+      agentName: this.config.agentName,
+      nameVariants: this.config.nameVariants,
+      memory: this.memory ?? void 0
+    });
+    this.pipeline.on("transcription", (result) => this.emit("transcription", result));
+    this.pipeline.on("sentence", (text) => this.emit("sentence", text));
+    this.pipeline.on("response", (text) => this.emit("response", text));
+    this.pipeline.on("agentState", (state) => this.emit("agentState", state));
+    this.pipeline.on("error", (error) => this.emit("error", error));
+    for (const participant of this.connection.room.remoteParticipants.values()) {
+      for (const [, pub] of participant.trackPublications) {
+        if (pub.track) {
+          this.handleTrackSubscribed(pub.track, pub, participant);
+        }
+      }
+    }
+    this.connection.room.on("trackSubscribed", (track, pub, participant) => {
+      this.handleTrackSubscribed(track, pub, participant);
+    });
+    this.connection.room.on("trackUnsubscribed", (track, _pub, participant) => {
+      this.handleTrackUnsubscribed(track, participant);
+    });
+    this.connection.room.on("participantDisconnected", (participant) => {
+      this.handleParticipantDisconnected(participant);
+    });
+    this.connection.room.on("disconnected", (reason) => {
+      log8.info(`Room disconnected: ${reason}`);
+      this.emit("disconnected", reason);
+    });
+    if (this.config.onDataMessage) {
+      this.setupDataChannel(this.config.onDataMessage);
+    }
+    this._running = true;
+    this.emit("connected");
+    log8.info("Agent started and listening");
+  }
+  /** Stop the agent — disconnect and clean up. */
+  async stop() {
+    if (!this._running) return;
+    log8.info("Stopping agent...");
+    this._running = false;
+    if (this.pipeline) {
+      await this.pipeline.stop();
+      this.pipeline = null;
+    }
+    if (this.memory) {
+      try {
+        await this.memory.endSession(this.config.llm);
+        await this.memory.close();
+      } catch (err) {
+        log8.error("Error closing memory:", err);
+      }
+      this.memory = null;
+    }
+    for (const [, input] of this.audioInputs) {
+      input.close();
+    }
+    this.audioInputs.clear();
+    if (this.audioOutput) {
+      this.audioOutput.stop();
+      this.audioOutput = null;
+    }
+    if (this.connection) {
+      await this.connection.disconnect();
+      this.connection = null;
+    }
+    this.emit("disconnected", "agent_stopped");
+    log8.info("Agent stopped");
+  }
+  setupDataChannel(handler) {
+    if (!this.connection) return;
+    this.connection.room.on("dataReceived", (payload, participant, _kind, topic) => {
+      const identity = participant?.identity ?? "unknown";
+      handler(payload, identity, topic);
+    });
+    log8.info("Data channel handler registered");
+  }
+  handleTrackSubscribed(track, _publication, participant) {
+    const identity = participant.identity;
+    log8.info(`Track subscribed from "${identity}" (sid=${track.sid})`);
+    this.memory?.addParticipant(identity);
+    const existing = this.audioInputs.get(identity);
+    if (existing) {
+      log8.info(`Closing old AudioInput for "${identity}" (re-subscription)`);
+      existing.close();
+    }
+    const audioInput = new AudioInput(track, identity);
+    this.audioInputs.set(identity, audioInput);
+    const sttStream = this.pipeline.addParticipant(identity);
+    this.pipeAudioToSTT(audioInput, sttStream, identity);
+  }
+  handleTrackUnsubscribed(_track, participant) {
+    const identity = participant.identity;
+    log8.info(`Track unsubscribed from "${identity}"`);
+    const input = this.audioInputs.get(identity);
+    if (input) {
+      input.close();
+      this.audioInputs.delete(identity);
+    }
+  }
+  handleParticipantDisconnected(participant) {
+    const identity = participant.identity;
+    log8.info(`Participant disconnected: "${identity}"`);
+    const input = this.audioInputs.get(identity);
+    if (input) {
+      input.close();
+      this.audioInputs.delete(identity);
+    }
+    this.pipeline?.removeParticipant(identity);
+  }
+  async pipeAudioToSTT(input, sttStream, identity) {
+    try {
+      for await (const buffer of input.frames()) {
+        if (!this._running) break;
+        sttStream.sendAudio(buffer);
+      }
+    } catch (err) {
+      if (this._running) {
+        log8.error(`Audio pipe error for "${identity}":`, err);
+      }
+    }
+  }
+};
+export {
+  AudioInput,
+  AudioOutput,
+  BargeIn,
+  BaseSTTStream,
+  ContextManager,
+  Embedder,
+  MemoryStore,
+  Pipeline,
+  RoomConnection,
+  RoomMemory,
+  SentenceSplitter,
+  TurnDetector,
+  VoiceAgent,
+  createLogger,
+  getLogLevel,
+  setLogLevel
+};
+//# sourceMappingURL=index.mjs.map