@backbay/glia 0.2.0-alpha.6 → 0.2.0-alpha.8

package/dist/audio/index.js

@@ -1,7 +1,1147 @@
-export { DEFAULT_RUN_SPEECH_CUES, useCognitionSpeech, useRunSpeechCues } from '../chunk-TPK4BYCO.js';
-import '../chunk-Z2S54IZX.js';
-import '../chunk-Q2XDMV7U.js';
-import '../chunk-OBZD2M3C.js';
-import '../chunk-TM6AOUSD.js';
+export * from '@backbay/glia-agent/audio';
+import { createContext, useRef, useEffect, useCallback, useState, useMemo, useContext } from 'react';
+import 'react/jsx-runtime';
+import { z } from 'zod';
+
+// src/audio/index.ts
+var BBContext = createContext(null);
+function useBBContext() {
+  const context = useContext(BBContext);
+  if (!context) {
+    throw new Error("useBBContext must be used within a BBProvider");
+  }
+  return context;
+}
+
+// src/hooks/useRunStream.ts
+function useRunStream(runId, options = {}) {
+  const { pollInterval = 4e3, preferPolling = false, onEvent, onComplete, onError } = options;
+  const { config } = useBBContext();
+  const [events, setEvents] = useState([]);
+  const [latestEvent, setLatestEvent] = useState(null);
+  const [status, setStatus] = useState("idle");
+  const [isConnected, setIsConnected] = useState(false);
+  const [run, setRun] = useState(null);
+  const eventSourceRef = useRef(null);
+  const pollingIntervalRef = useRef(null);
+  const isActiveRef = useRef(true);
+  const handleEvent = useCallback(
+    (event) => {
+      if (!isActiveRef.current) return;
+      setEvents((prev) => [...prev, event]);
+      setLatestEvent(event);
+      onEvent?.(event);
+      if (event.data?.status) {
+        setStatus(event.data.status);
+      }
+      if (event.type === "completed" || event.type === "failed" || event.type === "cancelled") {
+        const finalStatus = event.type === "completed" ? "completed" : event.type === "failed" ? "failed" : "cancelled";
+        setStatus(finalStatus);
+        if (event.data?.run) {
+          setRun(event.data.run);
+          if (event.type === "completed") {
+            onComplete?.(event.data.run);
+          }
+        }
+      }
+    },
+    [onEvent, onComplete]
+  );
+  const setupEventSource = useCallback(() => {
+    if (!runId || preferPolling) return;
+    const url = `${config.apiBaseUrl}/runs/${runId}/events`;
+    const eventSource = new EventSource(url);
+    eventSource.onopen = () => {
+      setIsConnected(true);
+      handleEvent({
+        type: "connected",
+        runId,
+        timestamp: Date.now()
+      });
+    };
+    eventSource.onmessage = (e) => {
+      try {
+        const data = JSON.parse(e.data);
+        handleEvent({
+          type: data.type ?? "status",
+          runId,
+          timestamp: Date.now(),
+          data
+        });
+      } catch (err) {
+        console.error("Failed to parse event:", err);
+      }
+    };
+    eventSource.onerror = () => {
+      setIsConnected(false);
+      startPolling();
+    };
+    eventSourceRef.current = eventSource;
+  }, [runId, config.apiBaseUrl, preferPolling, handleEvent]);
+  const startPolling = useCallback(() => {
+    if (!runId || pollingIntervalRef.current) return;
+    const poll = async () => {
+      if (!isActiveRef.current || !runId) return;
+      try {
+        const response = await fetch(`${config.apiBaseUrl}/runs/${runId}`, {
+          headers: config.headers
+        });
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`);
+        }
+        const data = await response.json();
+        handleEvent({
+          type: "status",
+          runId,
+          timestamp: Date.now(),
+          data: {
+            status: data.status,
+            output: data.output,
+            run: data
+          }
+        });
+        if (data.status === "completed" || data.status === "failed" || data.status === "cancelled") {
+          stopPolling();
+          handleEvent({
+            type: data.status,
+            runId,
+            timestamp: Date.now(),
+            data: { run: data }
+          });
+        }
+      } catch (err) {
+        if (err instanceof Error) {
+          onError?.(err);
+        }
+      }
+    };
+    poll();
+    pollingIntervalRef.current = setInterval(poll, pollInterval);
+  }, [runId, config, pollInterval, handleEvent, onError]);
+  const stopPolling = useCallback(() => {
+    if (pollingIntervalRef.current) {
+      clearInterval(pollingIntervalRef.current);
+      pollingIntervalRef.current = null;
+    }
+  }, []);
+  const disconnect = useCallback(() => {
+    isActiveRef.current = false;
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+      eventSourceRef.current = null;
+    }
+    stopPolling();
+    setIsConnected(false);
+  }, [stopPolling]);
+  const reconnect = useCallback(() => {
+    disconnect();
+    isActiveRef.current = true;
+    setEvents([]);
+    setLatestEvent(null);
+    setStatus("idle");
+    if (preferPolling) {
+      startPolling();
+    } else {
+      setupEventSource();
+    }
+  }, [disconnect, preferPolling, startPolling, setupEventSource]);
+  useEffect(() => {
+    if (!runId) {
+      disconnect();
+      return;
+    }
+    isActiveRef.current = true;
+    setEvents([]);
+    setLatestEvent(null);
+    setStatus("running");
+    if (preferPolling) {
+      startPolling();
+    } else {
+      setupEventSource();
+      setTimeout(() => {
+        if (isActiveRef.current && !isConnected) {
+          startPolling();
+        }
+      }, 2e3);
+    }
+    return () => {
+      disconnect();
+    };
+  }, [runId]);
+  return {
+    events,
+    latestEvent,
+    status,
+    isConnected,
+    run,
+    disconnect,
+    reconnect
+  };
+}
+
+// src/audio/hooks/useRunSpeechCues.ts
+var DEFAULT_RUN_SPEECH_CUES = {
+  onStart: "hold",
+  onComplete: "done",
+  onFail: "error",
+  onCancel: "warning"
+};
+function useRunSpeechCues(options) {
+  const { runId, enabled = true, emit, cues, cooldownMs = 800 } = options;
+  const { status } = useRunStream(runId);
+  const prevStatusRef = useRef(null);
+  const lastEmitAtRef = useRef(0);
+  useEffect(() => {
+    if (!enabled) return;
+    if (!runId) return;
+    const prev = prevStatusRef.current;
+    prevStatusRef.current = status;
+    if (prev === status) return;
+    const now = Date.now();
+    if (now - lastEmitAtRef.current < cooldownMs) return;
+    const cueMap = { ...DEFAULT_RUN_SPEECH_CUES, ...cues ?? {} };
+    let token = null;
+    if (status === "running") token = cueMap.onStart;
+    if (status === "completed") token = cueMap.onComplete;
+    if (status === "failed") token = cueMap.onFail;
+    if (status === "cancelled") token = cueMap.onCancel;
+    if (!token) return;
+    lastEmitAtRef.current = now;
+    void emit(token, { runId, status });
+  }, [enabled, runId, status, emit, cues, cooldownMs]);
+}
+
+// src/cognition/types.ts
+function clamp01(value) {
+  return Math.max(0, Math.min(1, value));
+}
+var DEFAULT_AVO = { arousal: 0.25, valence: 0.6, openness: 0.35 };
+function createInitialCognitionState(overrides) {
+  return {
+    mode: "idle",
+    attention: 0.3,
+    workload: 0,
+    timePressure: 0,
+    planDrift: 0,
+    costPressure: 0,
+    risk: 0,
+    uncertainty: 0.2,
+    confidence: 0.8,
+    errorStress: 0,
+    personaAnchor: 1,
+    personaDriftRisk: 0,
+    moodAVO: { ...DEFAULT_AVO },
+    emotionAVO: { ...DEFAULT_AVO },
+    ...overrides
+  };
+}
+
+// src/cognition/reducers.ts
+var MODE_TRANSITION_MAP = {
+  "ui.input_received": "listening",
+  "ui.user_idle": "idle",
+  "ui.interrupt": "listening",
+  "run.started": "deliberating",
+  "run.completed": "idle",
+  "run.event": "deliberating"
+};
+function reduceSignals(state, signals) {
+  return {
+    ...state,
+    attention: signals.attention !== void 0 ? clamp01(signals.attention) : state.attention,
+    workload: signals.workload !== void 0 ? clamp01(signals.workload) : state.workload,
+    risk: signals.risk !== void 0 ? clamp01(signals.risk) : state.risk,
+    timePressure: signals.timePressure !== void 0 ? clamp01(signals.timePressure) : state.timePressure,
+    errorStress: signals.errorStress !== void 0 ? clamp01(signals.errorStress) : state.errorStress,
+    planDrift: signals.planDrift !== void 0 ? clamp01(signals.planDrift) : state.planDrift,
+    costPressure: signals.costPressure !== void 0 ? clamp01(signals.costPressure) : state.costPressure,
+    uncertainty: signals.uncertainty !== void 0 ? clamp01(signals.uncertainty) : state.uncertainty,
+    confidence: signals.confidence !== void 0 ? clamp01(signals.confidence) : state.confidence
+  };
+}
+function reduceDynamicsUpdate(state, dynamics) {
+  return {
+    ...state,
+    dynamics
+  };
+}
+function reducePolicyUpdate(state, policy, personality) {
+  return {
+    ...state,
+    policy: policy ?? state.policy,
+    personality: personality ?? state.personality
+  };
+}
+function reduceModeTransition(state, event) {
+  const trigger = event.type;
+  const newMode = MODE_TRANSITION_MAP[trigger];
+  if (!newMode) {
+    return state;
+  }
+  let focusRunId = state.focusRunId;
+  let errorStress = state.errorStress;
+  let mode = newMode;
+  if (event.type === "run.started") {
+    focusRunId = event.runId;
+  } else if (event.type === "run.completed") {
+    focusRunId = void 0;
+    if (!event.success) {
+      errorStress = clamp01(state.errorStress + 0.2);
+      mode = "recovering";
+    }
+  } else if (event.type === "run.event") {
+    focusRunId = event.runId;
+  }
+  return {
+    ...state,
+    mode,
+    focusRunId,
+    errorStress
+  };
+}
+function reduceDecay(state, deltaMs) {
+  const deltaSec = deltaMs / 1e3;
+  const errorStress = clamp01(
+    state.errorStress * Math.exp(-0.1 * deltaSec)
+  );
+  const timePressure = clamp01(
+    state.timePressure * Math.exp(-0.05 * deltaSec)
+  );
+  const planDrift = clamp01(
+    state.planDrift * Math.exp(-0.08 * deltaSec)
+  );
+  return {
+    ...state,
+    errorStress,
+    timePressure,
+    planDrift
+  };
+}
+function reduceEvent(state, event) {
+  switch (event.type) {
+    case "signals.update":
+      return reduceSignals(state, event.signals);
+    case "intensity.update":
+      return reduceSignals(state, event.values);
+    case "dynamics.update":
+      return reduceDynamicsUpdate(state, event.dynamics);
+    case "policy.update":
+      return reducePolicyUpdate(state, event.policy, event.personality);
+    case "tick":
+      return reduceDecay(state, event.deltaMs);
+    case "ui.input_received":
+    case "ui.user_idle":
+    case "ui.interrupt":
+    case "run.started":
+    case "run.completed":
+    case "run.event":
+      return reduceModeTransition(state, event);
+    case "text.user_message": {
+      const categories = event.categories ?? [];
+      const driftRisk = categories.includes("meta_reflection") ? 0.3 : categories.includes("vulnerable_disclosure") ? 0.4 : 0;
+      const newPersonaDriftRisk = clamp01(
+        state.personaDriftRisk * 0.7 + driftRisk * 0.3
+      );
+      return {
+        ...state,
+        mode: "listening",
+        personaDriftRisk: newPersonaDriftRisk
+      };
+    }
+    default: {
+      return state;
+    }
+  }
+}
+
+// src/cognition/controller.ts
+var MODE_TO_ANCHOR = {
+  idle: "idle",
+  listening: "listening",
+  deliberating: "thinking",
+  acting: "focused",
+  explaining: "explaining",
+  recovering: "recovering",
+  blocked: "concerned"
+};
+var MODE_TO_AVO = {
+  idle: { arousal: 0.25, valence: 0.6, openness: 0.35 },
+  listening: { arousal: 0.45, valence: 0.7, openness: 0.05 },
+  deliberating: { arousal: 0.6, valence: 0.6, openness: 0.4 },
+  acting: { arousal: 0.7, valence: 0.7, openness: 0.5 },
+  explaining: { arousal: 0.55, valence: 0.8, openness: 0.85 },
+  recovering: { arousal: 0.4, valence: 0.45, openness: 0.4 },
+  blocked: { arousal: 0.55, valence: 0.3, openness: 0.3 }
+};
+var CognitionController = class {
+  _state;
+  _listeners = /* @__PURE__ */ new Map();
+  _disposed = false;
+  constructor(options = {}) {
+    this._state = createInitialCognitionState(options.initial);
+  }
+  /**
+   * Get current cognition state
+   */
+  getState() {
+    return { ...this._state };
+  }
+  /**
+   * Get the emotion target for the current cognitive state
+   * Returns anchor state and AVO values adjusted by signals
+   */
+  getEmotionTarget() {
+    const anchor = MODE_TO_ANCHOR[this._state.mode];
+    const baseAVO = MODE_TO_AVO[this._state.mode];
+    const avo = this._adjustAVOBySignals(baseAVO);
+    return { anchor, avo };
+  }
+  /**
+   * Get emotion bridge - derives anchor and AVO from cognitive state
+   * @deprecated Use getEmotionTarget() instead
+   */
+  getEmotionBridge() {
+    const target = this.getEmotionTarget();
+    return { anchor: target.anchor, avo: target.avo };
+  }
+  /**
+   * Handle a cognition event and update state
+   */
+  handleEvent(event) {
+    if (this._disposed) return;
+    const prevMode = this._state.mode;
+    this._state = reduceEvent(this._state, event);
+    if (this._state.mode !== prevMode) {
+      this._emitEvent("modeChange", { from: prevMode, to: this._state.mode });
+    }
+    this._emitEvent("change", this._state);
+  }
+  /**
+   * Process an event and update state
+   * @deprecated Use handleEvent() instead
+   */
+  emit(event) {
+    this.handleEvent(event);
+  }
+  /**
+   * Update tick - call each frame with delta time in milliseconds
+   * Applies time-based decay to stress signals
+   */
+  tick(deltaMs) {
+    if (this._disposed) return;
+    const prevState = this._state;
+    this._state = reduceDecay(this._state, deltaMs);
+    if (prevState.errorStress !== this._state.errorStress || prevState.timePressure !== this._state.timePressure || prevState.planDrift !== this._state.planDrift) {
+      this._emitEvent("change", this._state);
+    }
+  }
+  /**
+   * Subscribe to controller events
+   * Returns unsubscribe function
+   */
+  on(event, handler) {
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this._listeners.get(event).add(handler);
+    return () => {
+      this._listeners.get(event)?.delete(handler);
+    };
+  }
+  /**
+   * Dispose controller and clean up resources
+   */
+  dispose() {
+    this._disposed = true;
+    this._listeners.clear();
+  }
+  /**
+   * Adjust AVO values based on current signal levels
+   */
+  _adjustAVOBySignals(baseAVO) {
+    const { errorStress, workload, timePressure, uncertainty, confidence, personaDriftRisk } = this._state;
+    const arousalBoost = workload * 0.2 + timePressure * 0.15 + errorStress * 0.1;
+    const valenceDrops = errorStress * 0.3 + uncertainty * 0.15;
+    const valenceBoost = (confidence - 0.5) * 0.2;
+    const opennessDrop = personaDriftRisk * 0.3;
+    return {
+      arousal: Math.max(0, Math.min(1, baseAVO.arousal + arousalBoost)),
+      valence: Math.max(0, Math.min(1, baseAVO.valence - valenceDrops + valenceBoost)),
+      openness: Math.max(0, Math.min(1, baseAVO.openness - opennessDrop))
+    };
+  }
+  _emitEvent(event, data) {
+    this._listeners.get(event)?.forEach((handler) => handler(data));
+  }
+};
+
+// src/cognition/hooks/useCognition.ts
+function useCognition(options = {}) {
+  const { initial, onChange, autoTick = true } = options;
+  const controllerRef = useRef(null);
+  if (!controllerRef.current) {
+    controllerRef.current = new CognitionController({ initial });
+  }
+  const controller = controllerRef.current;
+  const [state, setState] = useState(controller.getState());
+  const [emotion, setEmotion] = useState(
+    controller.getEmotionTarget()
+  );
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  useEffect(() => {
+    const unsub = controller.on("change", (newState) => {
+      setState({ ...newState });
+      setEmotion(controller.getEmotionTarget());
+      onChangeRef.current?.(newState);
+    });
+    return () => {
+      unsub();
+    };
+  }, [controller]);
+  useEffect(() => {
+    if (!autoTick) return;
+    let lastTime = performance.now();
+    let rafId;
+    const tickFn = (time) => {
+      const delta = time - lastTime;
+      lastTime = time;
+      controller.tick(delta);
+      rafId = requestAnimationFrame(tickFn);
+    };
+    rafId = requestAnimationFrame(tickFn);
+    return () => {
+      cancelAnimationFrame(rafId);
+    };
+  }, [controller, autoTick]);
+  useEffect(() => {
+    return () => {
+      controller.dispose();
+    };
+  }, [controller]);
+  const handleEvent = useCallback(
+    (event) => {
+      controller.handleEvent(event);
+    },
+    [controller]
+  );
+  const tick = useCallback(
+    (deltaMs) => {
+      controller.tick(deltaMs);
+    },
+    [controller]
+  );
+  const emit = handleEvent;
+  return {
+    state,
+    emotion,
+    handleEvent,
+    tick,
+    emit
+  };
+}
+
+// src/audio/types.ts
+var DEFAULT_TARGET_AVO = {
+  // Match the emotion system's "idle" anchor for a stable neutral baseline.
+  arousal: 0.25,
+  valence: 0.6,
+  openness: 0.35
+};
+function clamp012(value) {
+  return Math.max(0, Math.min(1, value));
+}
+function createTraceId() {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return crypto.randomUUID();
+  }
+  return `trace_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+}
+
+// src/audio/planner.ts
+function pickFirstAllowedVoiceId(voices, allowedVoiceIds) {
+  const list = voices.list();
+  for (const entry of list) {
+    if (!allowedVoiceIds || allowedVoiceIds.includes(entry.voiceId)) {
+      return entry.voiceId;
+    }
+  }
+  return null;
+}
+function pickVoiceId(args) {
+  const { voices, allowedVoiceIds, preferredVoiceId, requiredTag } = args;
+  if (preferredVoiceId) {
+    const entry = voices.get(preferredVoiceId);
+    if (entry && (!allowedVoiceIds || allowedVoiceIds.includes(entry.voiceId))) {
+      if (!requiredTag || (entry.tags ?? []).includes(requiredTag)) {
+        return entry.voiceId;
+      }
+    }
+  }
+  for (const entry of voices.list()) {
+    if (allowedVoiceIds && !allowedVoiceIds.includes(entry.voiceId)) continue;
+    if (requiredTag && !(entry.tags ?? []).includes(requiredTag)) continue;
+    return entry.voiceId;
+  }
+  return null;
+}
+function stripExcessPunctuation(text) {
+  return text.replace(/[!?]{2,}/g, (m) => m[0] ?? "!").replace(/\.{3,}/g, "\u2026");
+}
+function clampTextForSafetyMode(text) {
+  return stripExcessPunctuation(text).replace(/!/g, ".");
+}
+function planSpeech(input) {
+  const {
+    text,
+    language,
+    runId,
+    targetAffect,
+    policy,
+    voices,
+    signals,
+    defaults
+  } = input;
+  const personaDriftRisk = clamp012(signals?.personaDriftRisk ?? 0);
+  const confidence = clamp012(signals?.confidence ?? 0.8);
+  const risk = clamp012(signals?.risk ?? 1 - confidence);
+  const groundedVoiceTag = defaults?.groundedVoiceTag ?? "grounded";
+  const defaultVoiceTag = defaults?.defaultVoiceTag ?? "default";
+  const requireGrounded = policy.safetyMode || personaDriftRisk >= 0.6 || risk >= 0.7 && confidence <= 0.5;
+  const voiceId = (requireGrounded ? pickVoiceId({
+    voices,
+    allowedVoiceIds: policy.allowedVoiceIds,
+    preferredVoiceId: defaults?.voiceId,
+    requiredTag: groundedVoiceTag
+  }) : pickVoiceId({
+    voices,
+    allowedVoiceIds: policy.allowedVoiceIds,
+    preferredVoiceId: defaults?.voiceId,
+    requiredTag: defaultVoiceTag
+  })) ?? pickVoiceId({
+    voices,
+    allowedVoiceIds: policy.allowedVoiceIds,
+    preferredVoiceId: defaults?.voiceId
+  }) ?? pickFirstAllowedVoiceId(voices, policy.allowedVoiceIds);
+  if (!voiceId) {
+    throw new Error("No available voices (voice catalog is empty or policy blocks all voices)");
+  }
+  const baseTemperature = clamp012(defaults?.temperature ?? 0.65);
+  const temperature = requireGrounded ? Math.min(baseTemperature, 0.25) : baseTemperature;
+  const controls = {
+    temperature
+  };
+  const plannedText = policy.safetyMode || personaDriftRisk >= 0.7 ? clampTextForSafetyMode(text) : stripExcessPunctuation(text);
+  return {
+    traceId: createTraceId(),
+    runId,
+    text: plannedText,
+    language,
+    voiceId,
+    targetAffect: targetAffect ?? DEFAULT_TARGET_AVO,
+    controls,
+    policy: {
+      safetyMode: policy.safetyMode,
+      trustTier: policy.trustTier,
+      voiceCloningAllowed: policy.voiceCloningAllowed
+    }
+  };
+}
+function planSpeechFromCognition(input) {
+  const { cognition, ...rest } = input;
+  const signals = {
+    mode: cognition.mode,
+    personaDriftRisk: cognition.personaDriftRisk,
+    confidence: cognition.confidence,
+    risk: cognition.risk
+  };
+  const targetAffect = rest.targetAffect ?? cognition.emotionAVO;
+  return planSpeech({
+    ...rest,
+    targetAffect,
+    signals
+  });
+}
+var AudioProofVersionSchema = z.enum(["1.0"]);
+var AudioFormatSchema = z.enum(["wav", "pcm_s16le", "opus", "mp3", "flac"]);
+var VoiceLicenseCategorySchema = z.enum(["cc0", "cc-by", "cc-by-nc", "custom", "unknown"]);
+var AvoSchema = z.object({
+  valence: z.number().min(0).max(1),
+  arousal: z.number().min(0).max(1),
+  openness: z.number().min(0).max(1)
+});
+var AudioArtifactSchema = z.object({
+  id: z.string().min(1),
+  uri: z.string().optional(),
+  format: AudioFormatSchema,
+  sha256: z.string().min(32),
+  sampleRateHz: z.number().int().min(8e3).optional(),
+  channels: z.number().int().min(1).max(8).optional(),
+  durationMs: z.number().int().min(1)
+});
+var AudioGateResultSchema = z.object({
+  passed: z.boolean(),
+  metrics: z.record(z.string(), z.unknown()).optional(),
+  reason: z.string().optional()
+});
+var AudioGatesSchema = z.object({
+  quality: AudioGateResultSchema,
+  semantic: AudioGateResultSchema,
+  affect: AudioGateResultSchema,
+  multimodalConsistency: AudioGateResultSchema.optional(),
+  watermark: AudioGateResultSchema.optional(),
+  speakerConsistency: AudioGateResultSchema.optional(),
+  antiSpoof: AudioGateResultSchema.optional(),
+  mos: AudioGateResultSchema.optional(),
+  safetyText: AudioGateResultSchema.optional(),
+  safetyAudio: AudioGateResultSchema.optional()
+});
+var EvidenceRefSchema = z.object({
+  type: z.enum(["run", "run_receipt", "artifact", "ui"]),
+  runId: z.string().optional(),
+  receiptHash: z.string().optional(),
+  path: z.string().optional(),
+  digest: z.string().optional(),
+  componentId: z.string().optional(),
+  note: z.string().optional()
+});
+var AudioProofSchema = z.object({
+  version: AudioProofVersionSchema,
+  createdAt: z.string().datetime(),
+  manifest: z.object({
+    traceId: z.string().optional(),
+    runId: z.string().optional(),
+    text: z.string().min(1),
+    language: z.string().optional(),
+    targetAffect: AvoSchema,
+    policy: z.object({
+      safetyMode: z.boolean(),
+      trustTier: z.string().optional(),
+      voiceCloningAllowed: z.boolean()
+    }),
+    cognitionSnapshot: z.record(z.string(), z.unknown()).optional()
+  }),
+  proof: z.object({
+    synthesis: z.object({
+      providerId: z.string().min(1),
+      model: z.object({
+        id: z.string().min(1),
+        revision: z.string().optional(),
+        sha256: z.string().optional()
+      }),
+      voice: z.object({
+        voiceId: z.string().min(1),
+        licenseCategory: VoiceLicenseCategorySchema,
+        licenseText: z.string().optional(),
+        source: z.string().optional()
+      }),
+      controls: z.record(z.string(), z.unknown()).optional(),
+      seed: z.number().int().min(0).optional()
+    }),
+    attempts: z.array(
+      z.object({
+        attempt: z.number().int().min(1),
+        artifactRef: z.string().min(1),
+        notes: z.string().optional(),
+        gates: AudioGatesSchema
+      })
+    ).optional(),
+    artifacts: z.array(AudioArtifactSchema).min(1),
+    gates: AudioGatesSchema,
+    evidence: z.array(EvidenceRefSchema).optional()
+  }),
+  verdict: z.object({
+    passed: z.boolean(),
+    reason: z.string().optional(),
+    score: z.number().optional()
+  })
+});
+function validateAudioProof(audioProof) {
+  const result = AudioProofSchema.safeParse(audioProof);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  return { success: false, errors: result.error };
+}
+function useAudioPlayer(options = {}) {
+  const { volume = 1, onEnded, onError } = options;
+  const audioRef = useRef(null);
+  const objectUrlRef = useRef(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [error, setError] = useState(null);
+  if (!audioRef.current && typeof Audio !== "undefined") {
+    audioRef.current = new Audio();
+  }
+  const stop = useCallback(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    try {
+      audio.pause();
+      audio.currentTime = 0;
+    } catch {
+    } finally {
+      setIsPlaying(false);
+    }
+  }, []);
+  const play = useCallback(
+    async (source) => {
+      const audio = audioRef.current;
+      if (!audio) {
+        throw new Error("Audio playback not supported in this environment");
+      }
+      setError(null);
+      if (objectUrlRef.current) {
+        URL.revokeObjectURL(objectUrlRef.current);
+        objectUrlRef.current = null;
+      }
+      const src = typeof source === "string" ? source : URL.createObjectURL(source);
+      if (typeof source !== "string") {
+        objectUrlRef.current = src;
+      }
+      audio.volume = volume;
+      audio.src = src;
+      try {
+        await audio.play();
+        setIsPlaying(true);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Failed to play audio";
+        setIsPlaying(false);
+        setError(message);
+        onError?.(err instanceof Error ? err : new Error(message));
+        throw err instanceof Error ? err : new Error(message);
+      }
+    },
+    [volume, onError]
+  );
+  useEffect(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    const handleEnded = () => {
+      setIsPlaying(false);
+      onEnded?.();
+    };
+    const handleError = () => {
+      setIsPlaying(false);
+      const message = "Audio element error";
+      setError(message);
+      onError?.(new Error(message));
+    };
+    audio.addEventListener("ended", handleEnded);
+    audio.addEventListener("error", handleError);
+    return () => {
+      audio.removeEventListener("ended", handleEnded);
+      audio.removeEventListener("error", handleError);
+    };
+  }, [onEnded, onError]);
+  useEffect(() => {
+    return () => {
+      stop();
+      if (objectUrlRef.current) {
+        URL.revokeObjectURL(objectUrlRef.current);
+        objectUrlRef.current = null;
+      }
+    };
+  }, [stop]);
+  return {
+    isPlaying,
+    error,
+    play,
+    stop,
+    audioElement: audioRef.current
+  };
+}
+function useBargeIn(options) {
+  const { stream, enabled = true, threshold = 0.02, hangoverMs = 250, onBargeIn } = options;
+  const [isUserSpeaking, setIsUserSpeaking] = useState(false);
+  const [levelRms, setLevelRms] = useState(0);
+  const rafRef = useRef(null);
+  const lastAboveRef = useRef(0);
+  const prevSpeakingRef = useRef(false);
+  useEffect(() => {
+    if (!enabled || !stream) {
+      setIsUserSpeaking(false);
+      setLevelRms(0);
+      return;
+    }
+    if (typeof AudioContext === "undefined") {
+      return;
+    }
+    const audioContext = new AudioContext();
+    const source = audioContext.createMediaStreamSource(stream);
+    const analyser = audioContext.createAnalyser();
+    analyser.fftSize = 2048;
+    source.connect(analyser);
+    const buffer = new Float32Array(analyser.fftSize);
+    const tick = () => {
+      analyser.getFloatTimeDomainData(buffer);
+      let sum = 0;
+      for (let i = 0; i < buffer.length; i++) {
+        const x = buffer[i];
+        sum += x * x;
+      }
+      const rms = Math.sqrt(sum / buffer.length);
+      setLevelRms(rms);
+      const now = performance.now();
+      if (rms >= threshold) {
+        lastAboveRef.current = now;
+      }
+      const speaking = rms >= threshold || now - lastAboveRef.current <= hangoverMs;
+      setIsUserSpeaking(speaking);
+      if (!prevSpeakingRef.current && speaking) {
+        onBargeIn?.();
+      }
+      prevSpeakingRef.current = speaking;
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => {
+      if (rafRef.current) cancelAnimationFrame(rafRef.current);
+      rafRef.current = null;
+      try {
+        source.disconnect();
+        analyser.disconnect();
+      } catch {
+      }
+      audioContext.close().catch(() => {
+      });
+    };
+  }, [stream, enabled, threshold, hangoverMs, onBargeIn]);
+  return { isUserSpeaking, levelRms };
+}
+
+// src/audio/hooks/useSpeechSynthesis.ts
+function useSpeechSynthesis(options) {
+  const {
+    provider,
+    verifier,
+    voices,
+    policy,
+    signals,
+    defaults,
+    bargeIn,
+    volume = 1,
+    verificationMode,
+    onProof,
+    onBargeIn,
+    onError
+  } = options;
+  const effectiveVerificationMode = useMemo(() => {
+    if (verificationMode) return verificationMode;
+    if (policy.requireProofBeforePlayback) return "before_playback";
+    if (verifier) return "after_playback";
+    return "never";
+  }, [verificationMode, policy.requireProofBeforePlayback, verifier]);
+  const abortRef = useRef(null);
+  const [isSynthesizing, setIsSynthesizing] = useState(false);
+  const [error, setError] = useState(null);
+  const [lastRequest, setLastRequest] = useState(null);
+  const [lastResult, setLastResult] = useState(null);
+  const [lastProof, setLastProof] = useState(null);
+  const player = useAudioPlayer({
+    volume,
+    onError: (err) => {
+      setError(err.message);
+      onError?.(err);
+    }
+  });
+  const bargeInState = useBargeIn({
+    stream: bargeIn?.stream ?? null,
+    enabled: !!bargeIn?.stream,
+    threshold: bargeIn?.threshold,
+    hangoverMs: bargeIn?.hangoverMs,
+    onBargeIn: () => {
+      onBargeIn?.();
+    }
+  });
+  const cancel = useCallback(() => {
+    abortRef.current?.abort();
+    abortRef.current = null;
+    setIsSynthesizing(false);
+    player.stop();
+  }, [player]);
+  useEffect(() => {
+    if (!bargeIn?.stream) return;
+    if (!bargeInState.isUserSpeaking) return;
+    cancel();
+  }, [bargeIn?.stream, bargeInState.isUserSpeaking, cancel]);
+  const speak = useCallback(
+    async (text, speakOptions) => {
+      cancel();
+      setError(null);
+      setIsSynthesizing(true);
+      const controller = new AbortController();
+      abortRef.current = controller;
+      try {
+        const request = planSpeech({
+          text,
+          language: speakOptions?.language,
+          runId: speakOptions?.runId,
+          targetAffect: speakOptions?.targetAffect,
+          policy,
+          voices,
+          signals,
+          defaults
+        });
+        setLastRequest(request);
+        const result = await provider.synthesizeSpeech(request, { signal: controller.signal });
+        setLastResult(result);
+        let proof = result.proof;
+        if (proof) {
+          const parsed = validateAudioProof(proof);
+          if (!parsed.success) {
+            throw new Error("Provider returned invalid AudioProof");
+          }
+          proof = parsed.data;
+        }
+        const verifyNow = effectiveVerificationMode === "before_playback" && (!proof || !proof.verdict?.passed) && !!verifier;
+        if (verifyNow && verifier) {
+          proof = await verifier.verifySpeech({ request, result, policy });
+          const parsed = validateAudioProof(proof);
+          if (!parsed.success) {
+            throw new Error("Verifier returned invalid AudioProof");
+          }
+          proof = parsed.data;
+        }
+        if (policy.requireProofBeforePlayback && (!proof || proof.verdict.passed !== true)) {
+          throw new Error("Playback blocked by policy: missing or failing AudioProof");
+        }
+        await player.play(result.audio);
+        if (effectiveVerificationMode === "after_playback" && verifier && !proof) {
+          void (async () => {
+            try {
+              const p = await verifier.verifySpeech({ request, result, policy });
+              const parsed = validateAudioProof(p);
+              if (!parsed.success) return;
+              setLastProof(parsed.data);
+              onProof?.(parsed.data);
+            } catch {
+            }
+          })();
+        }
+        if (proof) {
+          setLastProof(proof);
+          onProof?.(proof);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Speech synthesis failed";
+        setError(message);
+        onError?.(err instanceof Error ? err : new Error(message));
+        throw err instanceof Error ? err : new Error(message);
+      } finally {
+        setIsSynthesizing(false);
+        abortRef.current = null;
+      }
+    },
+    [
+      cancel,
+      policy,
+      voices,
+      signals,
+      defaults,
+      provider,
+      verifier,
+      effectiveVerificationMode,
+      player,
+      onProof,
+      onError
+    ]
+  );
+  return {
+    isSynthesizing,
+    isSpeaking: player.isPlaying,
+    error,
+    lastRequest,
+    lastResult,
+    lastProof,
+    speak,
+    cancel
+  };
+}
+
+// src/audio/hooks/useCognitionSpeech.ts
+function useCognitionSpeech(options) {
+  const {
+    provider,
+    verifier,
+    voices,
+    policy,
+    volume,
+    verificationMode,
+    initialCognition,
+    autoTick = true,
+    onCognitionChange,
+    bargeIn,
+    defaults,
+    onProof,
+    onBargeIn,
+    onError
+  } = options;
+  const cognitionResult = useCognition({
+    initial: initialCognition,
+    autoTick,
+    onChange: onCognitionChange
+  });
+  const speechResult = useSpeechSynthesis({
+    provider,
+    verifier,
+    voices,
+    policy,
+    volume,
+    verificationMode,
+    signals: {
+      mode: cognitionResult.state.mode,
+      personaDriftRisk: cognitionResult.state.personaDriftRisk,
+      confidence: cognitionResult.state.confidence,
+      risk: cognitionResult.state.risk
+    },
+    defaults,
+    bargeIn,
+    onProof,
+    onBargeIn: () => {
+      cognitionResult.handleEvent({ type: "ui.interrupt" });
+      onBargeIn?.();
+    },
+    onError
+  });
+  const speak = useCallback(
+    async (text, speakOptions) => {
+      const request = planSpeechFromCognition({
+        text,
+        language: speakOptions?.language,
+        runId: speakOptions?.runId,
+        targetAffect: speakOptions?.targetAffect,
+        cognition: cognitionResult.state,
+        policy,
+        voices,
+        defaults
+      });
+      await speechResult.speak(text, {
+        ...speakOptions,
+        targetAffect: request.targetAffect
+      });
+    },
+    [cognitionResult.state, policy, voices, defaults, speechResult]
+  );
+  return {
+    // Cognition
+    cognition: cognitionResult.state,
+    emotion: cognitionResult.emotion,
+    handleCognition: cognitionResult.handleEvent,
+    emitCognition: cognitionResult.handleEvent,
+    // deprecated alias
+    tickCognition: cognitionResult.tick,
+    // Speech
+    isSynthesizing: speechResult.isSynthesizing,
+    isSpeaking: speechResult.isSpeaking,
+    error: speechResult.error,
+    lastRequest: speechResult.lastRequest,
+    lastResult: speechResult.lastResult,
+    lastProof: speechResult.lastProof,
+    speak,
+    cancel: speechResult.cancel
+  };
+}
+
+export { DEFAULT_RUN_SPEECH_CUES, useCognitionSpeech, useRunSpeechCues };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map