vocal-stack 1.0.0

package/dist/index.js

@@ -0,0 +1,1003 @@
+// src/errors.ts
+var VocalStackError = class extends Error {
+  constructor(message, code, context) {
+    super(message);
+    this.code = code;
+    this.context = context;
+    this.name = "VocalStackError";
+    Error.captureStackTrace(this, this.constructor);
+  }
+};
+var SanitizerError = class extends VocalStackError {
+  constructor(message, context) {
+    super(message, "SANITIZER_ERROR", context);
+    this.name = "SanitizerError";
+  }
+};
+var FlowControlError = class extends VocalStackError {
+  constructor(message, context) {
+    super(message, "FLOW_CONTROL_ERROR", context);
+    this.name = "FlowControlError";
+  }
+};
+var MonitorError = class extends VocalStackError {
+  constructor(message, context) {
+    super(message, "MONITOR_ERROR", context);
+    this.name = "MonitorError";
+  }
+};
+
+// src/sanitizer/rules/code-blocks.ts
+function codeBlocksRule(text, _config) {
+  let result = text;
+  result = result.replace(/```[\s\S]*?```/g, "");
+  result = result.replace(/^(?: {4}|\t).+$/gm, "");
+  return result;
+}
+
+// src/sanitizer/rules/markdown.ts
+function markdownRule(text, _config) {
+  let result = text;
+  result = result.replace(/^#{1,6}\s+/gm, "");
+  result = result.replace(/(\*\*|__)(.*?)\1/g, "$2");
+  result = result.replace(/(\*|_)(.*?)\1/g, "$2");
+  result = result.replace(/`([^`]+)`/g, "$1");
+  result = result.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+  result = result.replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1");
+  result = result.replace(/^>\s+/gm, "");
+  result = result.replace(/^[\-*_]{3,}$/gm, "");
+  result = result.replace(/^[\s]*[-*+]\s+/gm, "");
+  result = result.replace(/^[\s]*\d+\.\s+/gm, "");
+  result = result.replace(/~~(.*?)~~/g, "$1");
+  result = result.replace(/^[\s]*-\s+\[[ xX]\]\s+/gm, "");
+  return result;
+}
+
+// src/sanitizer/rules/punctuation.ts
+function punctuationRule(text, _config) {
+  let result = text;
+  result = result.replace(/!{2,}/g, "!");
+  result = result.replace(/\?{2,}/g, "?");
+  result = result.replace(/\.{3,}/g, ".");
+  result = result.replace(/-{2,}/g, " ");
+  result = result.replace(/[—–]/g, " ");
+  result = result.replace(/[()[\]{}]/g, "");
+  result = result.replace(/,{2,}/g, ",");
+  result = result.replace(/[;:]/g, ",");
+  result = result.replace(/["'"'`]/g, "");
+  result = result.replace(/[*_]/g, "");
+  result = result.replace(/[/\\]/g, " ");
+  result = result.replace(/[|&]/g, " ");
+  result = result.replace(/[@#$%]/g, "");
+  return result;
+}
+
+// src/sanitizer/rules/urls.ts
+function urlsRule(text, _config) {
+  let result = text;
+  const urlWithProtocol = /\b(https?:\/\/|ftp:\/\/|www\.)[^\s<>"{}|\\^`[\]]+/gi;
+  const emailPattern = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g;
+  result = result.replace(urlWithProtocol, "");
+  result = result.replace(emailPattern, "");
+  result = result.replace(/\b[a-z0-9-]+\.[a-z]{2,}\b/gi, "");
+  return result;
+}
+
+// src/sanitizer/rules/index.ts
+var ruleRegistry = /* @__PURE__ */ new Map([
+  ["markdown", markdownRule],
+  ["urls", urlsRule],
+  ["code-blocks", codeBlocksRule],
+  ["punctuation", punctuationRule]
+]);
+
+// src/sanitizer/sanitizer.ts
+var SpeechSanitizer = class {
+  config;
+  plugins;
+  constructor(config = {}) {
+    this.config = {
+      rules: config.rules ?? ["markdown", "urls", "code-blocks", "punctuation"],
+      plugins: config.plugins ?? [],
+      preserveLineBreaks: config.preserveLineBreaks ?? false,
+      customReplacements: config.customReplacements ?? /* @__PURE__ */ new Map()
+    };
+    this.plugins = [...this.config.plugins].sort((a, b) => a.priority - b.priority);
+  }
+  /**
+   * Sanitize a string synchronously
+   */
+  sanitize(text) {
+    if (!text || text.trim().length === 0) {
+      return "";
+    }
+    let result = text;
+    try {
+      for (const rule of this.config.rules) {
+        const ruleFunction = ruleRegistry.get(rule);
+        if (ruleFunction) {
+          result = ruleFunction(result, this.config);
+        }
+      }
+      for (const plugin of this.plugins) {
+        const transformed = plugin.transform(result);
+        if (transformed instanceof Promise) {
+          throw new SanitizerError(
+            `Plugin ${plugin.name} returned a Promise in sync sanitize(). Use sanitizeAsync() instead.`
+          );
+        }
+        result = transformed;
+      }
+      for (const [pattern, replacement] of this.config.customReplacements) {
+        if (typeof pattern === "string") {
+          result = result.replaceAll(pattern, replacement);
+        } else {
+          result = result.replace(pattern, replacement);
+        }
+      }
+      if (this.config.preserveLineBreaks) {
+        result = result.replace(/ +/g, " ").replace(/^\s+|\s+$/gm, "");
+      } else {
+        result = result.replace(/\s+/g, " ").trim();
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof SanitizerError) {
+        throw error;
+      }
+      throw new SanitizerError("Failed to sanitize text", {
+        originalText: text.substring(0, 100),
+        error
+      });
+    }
+  }
+  /**
+   * Sanitize with detailed result metadata
+   */
+  sanitizeWithMetadata(text) {
+    const original = text;
+    const sanitized = this.sanitize(text);
+    return {
+      original,
+      sanitized,
+      appliedRules: this.config.rules,
+      metadata: {
+        removedCount: original.length - sanitized.length,
+        transformedCount: this.config.rules.length + this.plugins.length
+      }
+    };
+  }
+  /**
+   * Sanitize a stream of text chunks (AsyncIterable)
+   */
+  async *sanitizeStream(input) {
+    let buffer = "";
+    const sentenceBoundary = /[.!?]\s+/;
+    for await (const chunk of input) {
+      buffer += chunk;
+      const sentences = buffer.split(sentenceBoundary);
+      buffer = sentences.pop() ?? "";
+      for (const sentence of sentences) {
+        if (sentence.trim()) {
+          yield `${this.sanitize(sentence)} `;
+        }
+      }
+    }
+    if (buffer.trim()) {
+      yield this.sanitize(buffer);
+    }
+  }
+};
+function sanitizeForSpeech(text, config) {
+  const sanitizer = new SpeechSanitizer(config);
+  return sanitizer.sanitize(text);
+}
+
+// src/monitor/exporters/csv.ts
+function exportToCsv(metrics) {
+  const headers = [
+    "id",
+    "timestamp",
+    "completed",
+    "timeToFirstToken",
+    "totalDuration",
+    "tokenCount",
+    "averageTokenLatency",
+    "tags"
+  ];
+  const rows = metrics.map((m) => [
+    m.id,
+    m.timestamp.toString(),
+    m.completed.toString(),
+    m.metrics.timeToFirstToken?.toString() ?? "",
+    m.metrics.totalDuration?.toString() ?? "",
+    m.metrics.tokenCount.toString(),
+    m.metrics.averageTokenLatency?.toString() ?? "",
+    JSON.stringify(m.tags)
+  ]);
+  const csvLines = [
+    headers.join(","),
+    ...rows.map(
+      (row) => row.map((cell) => {
+        if (cell.includes(",") || cell.includes('"') || cell.includes("\n")) {
+          return `"${cell.replace(/"/g, '""')}"`;
+        }
+        return cell;
+      }).join(",")
+    )
+  ];
+  return csvLines.join("\n");
+}
+
+// src/monitor/exporters/json.ts
+function exportToJson(metrics) {
+  return JSON.stringify(
+    {
+      exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      count: metrics.length,
+      metrics: metrics.map((m) => ({
+        id: m.id,
+        timestamp: m.timestamp,
+        completed: m.completed,
+        timeToFirstToken: m.metrics.timeToFirstToken,
+        totalDuration: m.metrics.totalDuration,
+        tokenCount: m.metrics.tokenCount,
+        averageTokenLatency: m.metrics.averageTokenLatency,
+        tags: m.tags
+      }))
+    },
+    null,
+    2
+  );
+}
+
+// src/monitor/metrics-collector.ts
+var MetricsCollector = class {
+  metrics = [];
+  addMetric(metric) {
+    this.metrics.push(metric);
+  }
+  getMetrics() {
+    return [...this.metrics];
+  }
+  getSummary() {
+    if (this.metrics.length === 0) {
+      return {
+        count: 0,
+        avgTimeToFirstToken: 0,
+        avgTotalDuration: 0,
+        p50TimeToFirstToken: 0,
+        p95TimeToFirstToken: 0,
+        p99TimeToFirstToken: 0,
+        minTimeToFirstToken: 0,
+        maxTimeToFirstToken: 0
+      };
+    }
+    const ttfts = this.metrics.map((m) => m.metrics.timeToFirstToken).filter((t) => t !== null).sort((a, b) => a - b);
+    const durations = this.metrics.map((m) => m.metrics.totalDuration).filter((d) => d !== null);
+    const percentile = (arr, p) => {
+      if (arr.length === 0) return 0;
+      const index = Math.ceil(arr.length * p) - 1;
+      return arr[index] ?? 0;
+    };
+    return {
+      count: this.metrics.length,
+      avgTimeToFirstToken: ttfts.reduce((a, b) => a + b, 0) / ttfts.length || 0,
+      avgTotalDuration: durations.reduce((a, b) => a + b, 0) / durations.length || 0,
+      p50TimeToFirstToken: percentile(ttfts, 0.5),
+      p95TimeToFirstToken: percentile(ttfts, 0.95),
+      p99TimeToFirstToken: percentile(ttfts, 0.99),
+      minTimeToFirstToken: ttfts.length > 0 ? Math.min(...ttfts) : 0,
+      maxTimeToFirstToken: ttfts.length > 0 ? Math.max(...ttfts) : 0
+    };
+  }
+  clear() {
+    this.metrics = [];
+  }
+};
+
+// src/monitor/voice-auditor.ts
+var VoiceAuditor = class {
+  config;
+  collector;
+  activeMetrics = /* @__PURE__ */ new Map();
+  constructor(config = {}) {
+    this.config = {
+      enableRealtime: config.enableRealtime ?? false,
+      onMetric: config.onMetric ?? (() => {
+      }),
+      tags: config.tags ?? {}
+    };
+    this.collector = new MetricsCollector();
+  }
+  /**
+   * Start tracking a new voice interaction
+   */
+  startTracking(id, tags) {
+    if (this.activeMetrics.has(id)) {
+      throw new MonitorError(`Metric with id ${id} is already being tracked`);
+    }
+    const metric = {
+      id,
+      timestamp: Date.now(),
+      startTime: Date.now(),
+      firstTokenReceivedTime: null,
+      lastTokenReceivedTime: null,
+      completed: false,
+      metrics: {
+        timeToFirstToken: null,
+        totalDuration: null,
+        tokenCount: 0,
+        averageTokenLatency: null
+      },
+      tags: { ...this.config.tags, ...tags }
+    };
+    this.activeMetrics.set(id, metric);
+    return metric;
+  }
+  /**
+   * Record first token received
+   */
+  recordFirstToken(id) {
+    const metric = this.activeMetrics.get(id);
+    if (!metric) {
+      throw new MonitorError(`No active metric found for id ${id}`);
+    }
+    if (metric.firstTokenReceivedTime === null) {
+      const updated = {
+        ...metric,
+        firstTokenReceivedTime: Date.now(),
+        metrics: {
+          ...metric.metrics,
+          timeToFirstToken: Date.now() - metric.startTime,
+          tokenCount: 1
+        }
+      };
+      this.activeMetrics.set(id, updated);
+      if (this.config.enableRealtime) {
+        this.config.onMetric(updated);
+      }
+    }
+  }
+  /**
+   * Record token received
+   */
+  recordToken(id) {
+    const metric = this.activeMetrics.get(id);
+    if (!metric) {
+      throw new MonitorError(`No active metric found for id ${id}`);
+    }
+    const updated = {
+      ...metric,
+      lastTokenReceivedTime: Date.now(),
+      metrics: {
+        ...metric.metrics,
+        tokenCount: metric.metrics.tokenCount + 1
+      }
+    };
+    this.activeMetrics.set(id, updated);
+  }
+  /**
+   * Complete tracking for a voice interaction
+   */
+  completeTracking(id) {
+    const metric = this.activeMetrics.get(id);
+    if (!metric) {
+      throw new MonitorError(`No active metric found for id ${id}`);
+    }
+    const lastTime = metric.lastTokenReceivedTime ?? Date.now();
+    const totalDuration = lastTime - metric.startTime;
+    const avgLatency = metric.metrics.tokenCount > 0 ? totalDuration / metric.metrics.tokenCount : null;
+    const completed = {
+      ...metric,
+      completed: true,
+      metrics: {
+        ...metric.metrics,
+        totalDuration,
+        averageTokenLatency: avgLatency
+      }
+    };
+    this.activeMetrics.delete(id);
+    this.collector.addMetric(completed);
+    if (this.config.enableRealtime) {
+      this.config.onMetric(completed);
+    }
+    return completed;
+  }
+  /**
+   * Wrap an async iterable with automatic tracking
+   */
+  async *track(id, input, tags) {
+    this.startTracking(id, tags);
+    let firstToken = true;
+    try {
+      for await (const chunk of input) {
+        if (firstToken) {
+          this.recordFirstToken(id);
+          firstToken = false;
+        } else {
+          this.recordToken(id);
+        }
+        yield chunk;
+      }
+    } finally {
+      this.completeTracking(id);
+    }
+  }
+  /**
+   * Get all collected metrics
+   */
+  getMetrics() {
+    return this.collector.getMetrics();
+  }
+  /**
+   * Get summary statistics
+   */
+  getSummary() {
+    return this.collector.getSummary();
+  }
+  /**
+   * Export metrics in specified format
+   */
+  export(format) {
+    const metrics = this.collector.getMetrics();
+    switch (format) {
+      case "json":
+        return exportToJson(metrics);
+      case "csv":
+        return exportToCsv(metrics);
+      default:
+        throw new MonitorError(`Unsupported export format: ${format}`);
+    }
+  }
+  /**
+   * Clear all collected metrics
+   */
+  clear() {
+    this.activeMetrics.clear();
+    this.collector.clear();
+  }
+};
+
+// src/flow/buffer-manager.ts
+var BufferManager = class {
+  buffer = [];
+  maxSize;
+  head = 0;
+  size = 0;
+  constructor(maxSize = 10) {
+    if (maxSize <= 0) {
+      throw new Error("Buffer size must be positive");
+    }
+    this.maxSize = maxSize;
+  }
+  /**
+   * Add chunk to buffer
+   */
+  add(chunk) {
+    if (this.size < this.maxSize) {
+      this.buffer.push(chunk);
+      this.size++;
+    } else {
+      this.buffer[this.head] = chunk;
+      this.head = (this.head + 1) % this.maxSize;
+    }
+  }
+  /**
+   * Get all buffered chunks in order
+   */
+  getAll() {
+    if (this.size < this.maxSize) {
+      return [...this.buffer];
+    }
+    return [...this.buffer.slice(this.head), ...this.buffer.slice(0, this.head)];
+  }
+  /**
+   * Clear all buffered chunks
+   */
+  clear() {
+    this.buffer = [];
+    this.head = 0;
+    this.size = 0;
+  }
+  /**
+   * Get current buffer size
+   */
+  getSize() {
+    return this.size;
+  }
+  /**
+   * Check if buffer is empty
+   */
+  isEmpty() {
+    return this.size === 0;
+  }
+  /**
+   * Check if buffer is full
+   */
+  isFull() {
+    return this.size === this.maxSize;
+  }
+};
+
+// src/flow/constants.ts
+var DEFAULT_STALL_THRESHOLD_MS = 700;
+var DEFAULT_FILLER_PHRASES = ["um", "let me think", "hmm"];
+var DEFAULT_MAX_FILLERS_PER_RESPONSE = 3;
+
+// src/flow/filler-injector.ts
+var FillerInjector = class {
+  phrases;
+  maxFillers;
+  fillersUsed = 0;
+  lastFillerIndex = -1;
+  constructor(phrases, maxFillers) {
+    this.phrases = phrases;
+    this.maxFillers = maxFillers;
+  }
+  /**
+   * Get next filler phrase (returns null if limit reached)
+   */
+  getFiller() {
+    if (this.fillersUsed >= this.maxFillers) {
+      return null;
+    }
+    this.lastFillerIndex = (this.lastFillerIndex + 1) % this.phrases.length;
+    this.fillersUsed++;
+    return this.phrases[this.lastFillerIndex] ?? null;
+  }
+  /**
+   * Reset filler state
+   */
+  reset() {
+    this.fillersUsed = 0;
+    this.lastFillerIndex = -1;
+  }
+  /**
+   * Check if more fillers can be injected
+   */
+  canInjectMore() {
+    return this.fillersUsed < this.maxFillers;
+  }
+  /**
+   * Get count of fillers used
+   */
+  getUsedCount() {
+    return this.fillersUsed;
+  }
+};
+
+// src/flow/stall-detector.ts
+var StallDetector = class {
+  lastChunkTime = null;
+  stallTimer = null;
+  thresholdMs;
+  onStall;
+  constructor(thresholdMs, onStall) {
+    this.thresholdMs = thresholdMs;
+    this.onStall = onStall;
+  }
+  /**
+   * Notify detector that a chunk was received
+   */
+  notifyChunk() {
+    this.lastChunkTime = Date.now();
+    this.clearTimer();
+    this.scheduleStallCheck();
+  }
+  /**
+   * Start monitoring for stalls
+   */
+  start() {
+    this.lastChunkTime = Date.now();
+    this.scheduleStallCheck();
+  }
+  /**
+   * Stop monitoring
+   */
+  stop() {
+    this.clearTimer();
+    this.lastChunkTime = null;
+  }
+  scheduleStallCheck() {
+    this.clearTimer();
+    this.stallTimer = setTimeout(() => {
+      if (this.lastChunkTime !== null) {
+        const elapsed = Date.now() - this.lastChunkTime;
+        if (elapsed >= this.thresholdMs) {
+          this.onStall(elapsed);
+          this.scheduleStallCheck();
+        }
+      }
+    }, this.thresholdMs);
+  }
+  clearTimer() {
+    if (this.stallTimer) {
+      clearTimeout(this.stallTimer);
+      this.stallTimer = null;
+    }
+  }
+};
+
+// src/flow/types.ts
+var ConversationState = /* @__PURE__ */ ((ConversationState2) => {
+  ConversationState2["IDLE"] = "idle";
+  ConversationState2["WAITING"] = "waiting";
+  ConversationState2["SPEAKING"] = "speaking";
+  ConversationState2["INTERRUPTED"] = "interrupted";
+  return ConversationState2;
+})(ConversationState || {});
+
+// src/flow/state-machine.ts
+var VALID_TRANSITIONS = /* @__PURE__ */ new Map([
+  ["idle" /* IDLE */, ["speaking" /* SPEAKING */, "waiting" /* WAITING */]],
+  [
+    "waiting" /* WAITING */,
+    ["speaking" /* SPEAKING */, "idle" /* IDLE */, "interrupted" /* INTERRUPTED */]
+  ],
+  ["speaking" /* SPEAKING */, ["interrupted" /* INTERRUPTED */, "idle" /* IDLE */]],
+  ["interrupted" /* INTERRUPTED */, ["idle" /* IDLE */, "waiting" /* WAITING */]]
+]);
+var ConversationStateMachine = class {
+  currentState = "idle" /* IDLE */;
+  listeners = /* @__PURE__ */ new Set();
+  /**
+   * Get current state
+   */
+  getState() {
+    return this.currentState;
+  }
+  /**
+   * Attempt to transition to new state
+   */
+  transition(to) {
+    const validTransitions = VALID_TRANSITIONS.get(this.currentState);
+    if (!validTransitions?.includes(to)) {
+      throw new FlowControlError(`Invalid state transition: ${this.currentState} -> ${to}`, {
+        from: this.currentState,
+        to
+      });
+    }
+    const from = this.currentState;
+    this.currentState = to;
+    for (const listener of this.listeners) {
+      listener(from, to);
+    }
+    return true;
+  }
+  /**
+   * Add state change listener
+   */
+  onStateChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * Reset to IDLE
+   */
+  reset() {
+    this.currentState = "idle" /* IDLE */;
+  }
+};
+
+// src/flow/flow-controller.ts
+var FlowController = class {
+  config;
+  stateMachine;
+  stallDetector;
+  fillerInjector;
+  bufferManager;
+  firstChunkEmitted = false;
+  stats = {
+    fillersInjected: 0,
+    stallsDetected: 0,
+    chunksProcessed: 0,
+    firstChunkTime: null,
+    totalDurationMs: 0
+  };
+  startTime = null;
+  constructor(config = {}) {
+    this.config = {
+      stallThresholdMs: config.stallThresholdMs ?? DEFAULT_STALL_THRESHOLD_MS,
+      fillerPhrases: config.fillerPhrases ?? DEFAULT_FILLER_PHRASES,
+      enableFillers: config.enableFillers ?? true,
+      maxFillersPerResponse: config.maxFillersPerResponse ?? DEFAULT_MAX_FILLERS_PER_RESPONSE,
+      onFillerInjected: config.onFillerInjected ?? (() => {
+      }),
+      onStallDetected: config.onStallDetected ?? (() => {
+      }),
+      onFirstChunk: config.onFirstChunk ?? (() => {
+      })
+    };
+    this.stateMachine = new ConversationStateMachine();
+    this.fillerInjector = new FillerInjector(
+      this.config.fillerPhrases,
+      this.config.maxFillersPerResponse
+    );
+    this.bufferManager = new BufferManager(10);
+    this.stallDetector = new StallDetector(
+      this.config.stallThresholdMs,
+      this.handleStall.bind(this)
+    );
+  }
+  /**
+   * Wrap an async iterable with flow control
+   */
+  async *wrap(input) {
+    this.reset();
+    this.startTime = Date.now();
+    this.stateMachine.transition("waiting" /* WAITING */);
+    this.stallDetector.start();
+    try {
+      for await (const chunk of input) {
+        if (this.stateMachine.getState() === "interrupted" /* INTERRUPTED */) {
+          break;
+        }
+        this.stallDetector.notifyChunk();
+        this.stats.chunksProcessed++;
+        this.bufferManager.add(chunk);
+        if (!this.firstChunkEmitted) {
+          this.firstChunkEmitted = true;
+          this.stats.firstChunkTime = Date.now() - (this.startTime ?? Date.now());
+          this.stateMachine.transition("speaking" /* SPEAKING */);
+          this.config.onFirstChunk();
+        }
+        yield chunk;
+      }
+      if (this.stateMachine.getState() !== "interrupted" /* INTERRUPTED */) {
+        this.stateMachine.transition("idle" /* IDLE */);
+      }
+    } catch (error) {
+      throw new FlowControlError("Flow control error during stream processing", { error });
+    } finally {
+      this.stallDetector.stop();
+      this.stats.totalDurationMs = Date.now() - (this.startTime ?? Date.now());
+    }
+  }
+  /**
+   * Interrupt the current flow (for barge-in)
+   */
+  interrupt() {
+    const currentState = this.stateMachine.getState();
+    if (currentState === "speaking" /* SPEAKING */ || currentState === "waiting" /* WAITING */) {
+      this.stateMachine.transition("interrupted" /* INTERRUPTED */);
+      this.stallDetector.stop();
+      this.fillerInjector.reset();
+      this.bufferManager.clear();
+    }
+  }
+  /**
+   * Get current conversation state
+   */
+  getState() {
+    return this.stateMachine.getState();
+  }
+  /**
+   * Get flow statistics
+   */
+  getStats() {
+    return { ...this.stats };
+  }
+  /**
+   * Get buffered chunks (for advanced barge-in scenarios)
+   */
+  getBufferedChunks() {
+    return this.bufferManager.getAll();
+  }
+  handleStall(durationMs) {
+    if (this.config.enableFillers && !this.firstChunkEmitted && this.stateMachine.getState() !== "interrupted" /* INTERRUPTED */) {
+      const filler = this.fillerInjector.getFiller();
+      if (filler) {
+        this.stats.fillersInjected++;
+        this.config.onFillerInjected(filler);
+      }
+    }
+    this.stats.stallsDetected++;
+    this.config.onStallDetected(durationMs);
+  }
+  reset() {
+    this.firstChunkEmitted = false;
+    this.fillerInjector.reset();
+    this.bufferManager.clear();
+    this.stats = {
+      fillersInjected: 0,
+      stallsDetected: 0,
+      chunksProcessed: 0,
+      firstChunkTime: null,
+      totalDurationMs: 0
+    };
+  }
+};
+function withFlowControl(input, config) {
+  const controller = new FlowController(config);
+  return controller.wrap(input);
+}
+
+// src/flow/flow-manager.ts
+var FlowManager = class {
+  config;
+  stateMachine;
+  stallDetector;
+  fillerInjector;
+  bufferManager;
+  listeners = /* @__PURE__ */ new Set();
+  firstChunkEmitted = false;
+  stats = {
+    fillersInjected: 0,
+    stallsDetected: 0,
+    chunksProcessed: 0,
+    firstChunkTime: null,
+    totalDurationMs: 0
+  };
+  startTime = null;
+  stateChangeUnsubscribe = null;
+  constructor(config = {}) {
+    this.config = {
+      stallThresholdMs: config.stallThresholdMs ?? DEFAULT_STALL_THRESHOLD_MS,
+      fillerPhrases: config.fillerPhrases ?? DEFAULT_FILLER_PHRASES,
+      enableFillers: config.enableFillers ?? true,
+      maxFillersPerResponse: config.maxFillersPerResponse ?? DEFAULT_MAX_FILLERS_PER_RESPONSE,
+      bufferSize: config.bufferSize ?? 10
+    };
+    this.stateMachine = new ConversationStateMachine();
+    this.fillerInjector = new FillerInjector(
+      this.config.fillerPhrases,
+      this.config.maxFillersPerResponse
+    );
+    this.bufferManager = new BufferManager(this.config.bufferSize);
+    this.stallDetector = new StallDetector(
+      this.config.stallThresholdMs,
+      this.handleStall.bind(this)
+    );
+  }
+  /**
+   * Add event listener
+   */
+  on(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * Start flow tracking
+   */
+  start() {
+    if (this.startTime !== null) {
+      throw new FlowControlError("FlowManager already started");
+    }
+    this.reset();
+    this.startTime = Date.now();
+    this.stateMachine.transition("waiting" /* WAITING */);
+    this.stallDetector.start();
+    this.stateChangeUnsubscribe = this.stateMachine.onStateChange((from, to) => {
+      this.emit({
+        type: "state-change",
+        from,
+        to
+      });
+    });
+  }
+  /**
+   * Process a chunk from the stream
+   */
+  processChunk(chunk) {
+    if (this.startTime === null) {
+      throw new FlowControlError("FlowManager not started. Call start() first.");
+    }
+    if (this.stateMachine.getState() === "interrupted" /* INTERRUPTED */) {
+      return;
+    }
+    this.stallDetector.notifyChunk();
+    this.stats.chunksProcessed++;
+    this.bufferManager.add(chunk);
+    if (!this.firstChunkEmitted) {
+      this.firstChunkEmitted = true;
+      this.stats.firstChunkTime = Date.now() - this.startTime;
+      this.stateMachine.transition("speaking" /* SPEAKING */);
+      this.emit({
+        type: "first-chunk",
+        chunk
+      });
+    }
+    this.emit({
+      type: "chunk-processed",
+      chunk
+    });
+  }
+  /**
+   * Complete the flow
+   */
+  complete() {
+    if (this.startTime === null) {
+      throw new FlowControlError("FlowManager not started");
+    }
+    this.stallDetector.stop();
+    this.stats.totalDurationMs = Date.now() - this.startTime;
+    if (this.stateMachine.getState() !== "interrupted" /* INTERRUPTED */) {
+      this.stateMachine.transition("idle" /* IDLE */);
+    }
+    this.emit({
+      type: "completed",
+      stats: this.getStats()
+    });
+    if (this.stateChangeUnsubscribe) {
+      this.stateChangeUnsubscribe();
+      this.stateChangeUnsubscribe = null;
+    }
+    this.startTime = null;
+  }
+  /**
+   * Interrupt the flow (for barge-in)
+   */
+  interrupt() {
+    const currentState = this.stateMachine.getState();
+    if (currentState === "speaking" /* SPEAKING */ || currentState === "waiting" /* WAITING */) {
+      this.stateMachine.transition("interrupted" /* INTERRUPTED */);
+      this.stallDetector.stop();
+      this.fillerInjector.reset();
+      this.bufferManager.clear();
+      this.emit({
+        type: "interrupted"
+      });
+    }
+  }
+  /**
+   * Get current conversation state
+   */
+  getState() {
+    return this.stateMachine.getState();
+  }
+  /**
+   * Get flow statistics
+   */
+  getStats() {
+    return { ...this.stats };
+  }
+  /**
+   * Get buffered chunks
+   */
+  getBufferedChunks() {
+    return this.bufferManager.getAll();
+  }
+  handleStall(durationMs) {
+    this.stats.stallsDetected++;
+    this.emit({
+      type: "stall-detected",
+      durationMs
+    });
+    if (this.config.enableFillers && !this.firstChunkEmitted && this.stateMachine.getState() !== "interrupted" /* INTERRUPTED */) {
+      const filler = this.fillerInjector.getFiller();
+      if (filler) {
+        this.stats.fillersInjected++;
+        this.emit({
+          type: "filler-injected",
+          filler
+        });
+      }
+    }
+  }
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error("Error in FlowManager event listener:", error);
+      }
+    }
+  }
+  reset() {
+    this.firstChunkEmitted = false;
+    this.fillerInjector.reset();
+    this.bufferManager.clear();
+    this.stats = {
+      fillersInjected: 0,
+      stallsDetected: 0,
+      chunksProcessed: 0,
+      firstChunkTime: null,
+      totalDurationMs: 0
+    };
+  }
+};
+
+export { BufferManager, ConversationState, ConversationStateMachine, DEFAULT_FILLER_PHRASES, DEFAULT_MAX_FILLERS_PER_RESPONSE, DEFAULT_STALL_THRESHOLD_MS, FillerInjector, FlowControlError, FlowController, FlowManager, MetricsCollector, MonitorError, SanitizerError, SpeechSanitizer, StallDetector, VocalStackError, VoiceAuditor, exportToCsv, exportToJson, ruleRegistry, sanitizeForSpeech, withFlowControl };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map