@athenaintel/react 0.20.0 → 0.21.0

package/dist/voice/use-athena-voice-session.cjs

@@ -0,0 +1,315 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const livekitClient = require("livekit-client");
+const auth = require("../runtime/auth.cjs");
+const toError = (value) => value instanceof Error ? value : new Error(String(value));
+const NO_BRIDGE = {
+  token: null,
+  statewireSyncUrl: null,
+  backendBaseUrl: null,
+  appUrl: null,
+  hostAnswered: false,
+  ready: true
+};
+const useNoBridge = () => NO_BRIDGE;
+const NO_VIEWER_TOKEN_MESSAGE = "useAthenaVoiceSession: no Athena viewer token. Either serve the app from a Marathon computer-asset URL (which mints one via /_athena/auth) or pass `createSession` to create the session through your own server.";
+const createAthenaVoiceSession = async ({
+  backendBaseUrl,
+  token,
+  session = {},
+  signal
+}) => {
+  const url = `${backendBaseUrl.replace(/\/+$/, "")}/api/orpheus/create-session`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`
+    },
+    body: JSON.stringify(session),
+    signal
+  });
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `Orpheus create-session failed (${response.status})${detail ? `: ${detail}` : ""}`
+    );
+  }
+  return await response.json();
+};
+const speakerOf = (participant, room) => participant !== void 0 && participant.identity === room.localParticipant.identity ? "user" : "agent";
+const useAthenaVoiceSession = (options = {}) => {
+  const {
+    createSession,
+    session,
+    onTranscript,
+    onInterimTranscript,
+    onError,
+    audioElement,
+    autoEnableMicrophone = true,
+    createRoom,
+    useBridge = createSession ? useNoBridge : auth.useParentBridge
+  } = options;
+  const bridge = useBridge();
+  const bridgeRef = react.useRef(bridge);
+  bridgeRef.current = bridge;
+  const bridgeReadyWaitersRef = react.useRef([]);
+  react.useEffect(() => {
+    if (!bridge.ready) return;
+    const waiters = bridgeReadyWaitersRef.current;
+    bridgeReadyWaitersRef.current = [];
+    for (const resolve of waiters) resolve();
+  }, [bridge.ready]);
+  const sessionRef = react.useRef(session);
+  sessionRef.current = session;
+  const createSessionAsViewer = react.useCallback(
+    async (signal) => {
+      if (!bridgeRef.current.ready) {
+        await new Promise((resolve) => {
+          bridgeReadyWaitersRef.current.push(resolve);
+          signal.addEventListener("abort", () => resolve(), { once: true });
+        });
+        if (signal.aborted) throw new Error("aborted");
+      }
+      const { token, backendBaseUrl } = bridgeRef.current;
+      if (!token || !backendBaseUrl) throw new Error(NO_VIEWER_TOKEN_MESSAGE);
+      return createAthenaVoiceSession({
+        backendBaseUrl,
+        token,
+        session: sessionRef.current,
+        signal
+      });
+    },
+    []
+  );
+  const [status, setStatus] = react.useState("idle");
+  const [activeSpeaker, setActiveSpeaker] = react.useState(
+    null
+  );
+  const [isMuted, setIsMuted] = react.useState(false);
+  const [transcript, setTranscript] = react.useState([]);
+  const [sessionId, setSessionId] = react.useState(null);
+  const [roomName, setRoomName] = react.useState(null);
+  const [error, setError] = react.useState(null);
+  const callbacksRef = react.useRef({
+    createSession: createSession ?? createSessionAsViewer,
+    onTranscript,
+    onInterimTranscript,
+    onError
+  });
+  callbacksRef.current = {
+    createSession: createSession ?? createSessionAsViewer,
+    onTranscript,
+    onInterimTranscript,
+    onError
+  };
+  const roomRef = react.useRef(null);
+  const abortRef = react.useRef(null);
+  const attachedElementsRef = react.useRef([]);
+  const ownedAudioRef = react.useRef(null);
+  const committedSegmentIdsRef = react.useRef(/* @__PURE__ */ new Set());
+  const startingRef = react.useRef(false);
+  const fail = react.useCallback((cause) => {
+    var _a, _b;
+    const err = toError(cause);
+    setError(err);
+    setStatus("error");
+    (_b = (_a = callbacksRef.current).onError) == null ? void 0 : _b.call(_a, err);
+  }, []);
+  const detachAudio = react.useCallback(() => {
+    for (const element of attachedElementsRef.current) {
+      element.srcObject = null;
+      if (element === ownedAudioRef.current) element.remove();
+    }
+    attachedElementsRef.current = [];
+    ownedAudioRef.current = null;
+  }, []);
+  const teardown = react.useCallback(async () => {
+    var _a;
+    (_a = abortRef.current) == null ? void 0 : _a.abort();
+    abortRef.current = null;
+    const room = roomRef.current;
+    roomRef.current = null;
+    startingRef.current = false;
+    detachAudio();
+    if (room) {
+      room.removeAllListeners();
+      await room.disconnect(true);
+    }
+  }, [detachAudio]);
+  const stop = react.useCallback(async () => {
+    const hadRoom = roomRef.current !== null || abortRef.current !== null;
+    await teardown();
+    setActiveSpeaker(null);
+    if (hadRoom) setStatus("ended");
+  }, [teardown]);
+  const attachTrack = react.useCallback(
+    (track) => {
+      if (track.kind !== livekitClient.Track.Kind.Audio) return;
+      if (audioElement) {
+        track.attach(audioElement);
+        attachedElementsRef.current.push(audioElement);
+        return;
+      }
+      const element = track.attach();
+      element.setAttribute("data-athena-voice-audio", "");
+      document.body.appendChild(element);
+      ownedAudioRef.current = element;
+      attachedElementsRef.current.push(element);
+    },
+    [audioElement]
+  );
+  const handleTranscription = react.useCallback(
+    (segments, participant, room) => {
+      var _a, _b, _c, _d;
+      const speaker = speakerOf(participant, room);
+      const committed = [];
+      for (const segment of segments) {
+        if (!segment.final) {
+          (_b = (_a = callbacksRef.current).onInterimTranscript) == null ? void 0 : _b.call(_a, speaker, segment.text);
+          continue;
+        }
+        if (committedSegmentIdsRef.current.has(segment.id)) continue;
+        committedSegmentIdsRef.current.add(segment.id);
+        committed.push({
+          id: segment.id,
+          speaker,
+          text: segment.text,
+          startTime: segment.startTime,
+          endTime: segment.endTime,
+          language: segment.language
+        });
+      }
+      if (committed.length === 0) return;
+      setTranscript((previous) => [...previous, ...committed]);
+      for (const turn of committed) (_d = (_c = callbacksRef.current).onTranscript) == null ? void 0 : _d.call(_c, turn);
+    },
+    []
+  );
+  const start = react.useCallback(async () => {
+    if (startingRef.current || roomRef.current) return;
+    startingRef.current = true;
+    setError(null);
+    setSessionId(null);
+    setRoomName(null);
+    setStatus("connecting");
+    const controller = new AbortController();
+    abortRef.current = controller;
+    let credentials;
+    try {
+      credentials = await callbacksRef.current.createSession(controller.signal);
+    } catch (cause) {
+      if (controller.signal.aborted) return;
+      abortRef.current = null;
+      startingRef.current = false;
+      fail(cause);
+      return;
+    }
+    if (controller.signal.aborted) return;
+    setSessionId(credentials.asset_id ?? null);
+    setRoomName(credentials.room_name ?? null);
+    const room = createRoom ? createRoom() : new livekitClient.Room();
+    roomRef.current = room;
+    room.on(livekitClient.RoomEvent.TrackSubscribed, attachTrack).on(livekitClient.RoomEvent.ActiveSpeakersChanged, (speakers) => {
+      const first = speakers[0];
+      setActiveSpeaker(first ? speakerOf(first, room) : null);
+    }).on(
+      livekitClient.RoomEvent.TranscriptionReceived,
+      (segments, participant) => handleTranscription(segments, participant, room)
+    ).on(livekitClient.RoomEvent.Reconnecting, () => setStatus("reconnecting")).on(livekitClient.RoomEvent.Reconnected, () => setStatus("connected")).on(livekitClient.RoomEvent.Disconnected, () => {
+      if (roomRef.current !== room) return;
+      roomRef.current = null;
+      startingRef.current = false;
+      detachAudio();
+      setActiveSpeaker(null);
+      setStatus("ended");
+    }).on(livekitClient.RoomEvent.MediaDevicesError, fail);
+    try {
+      await room.connect(credentials.server_url, credentials.token);
+      if (controller.signal.aborted) return;
+      if (autoEnableMicrophone) {
+        await room.localParticipant.setMicrophoneEnabled(true);
+        setIsMuted(false);
+      } else {
+        setIsMuted(true);
+      }
+      if (controller.signal.aborted) return;
+      abortRef.current = null;
+      startingRef.current = false;
+      setStatus("connected");
+    } catch (cause) {
+      if (controller.signal.aborted) return;
+      await teardown();
+      fail(cause);
+    }
+  }, [
+    attachTrack,
+    autoEnableMicrophone,
+    createRoom,
+    detachAudio,
+    fail,
+    handleTranscription,
+    teardown
+  ]);
+  const setMicrophone = react.useCallback(async (enabled) => {
+    const room = roomRef.current;
+    if (!room) return;
+    await room.localParticipant.setMicrophoneEnabled(enabled);
+    setIsMuted(!enabled);
+  }, []);
+  const mute = react.useCallback(() => setMicrophone(false), [setMicrophone]);
+  const unmute = react.useCallback(() => setMicrophone(true), [setMicrophone]);
+  const clearTranscript = react.useCallback(() => {
+    committedSegmentIdsRef.current.clear();
+    setTranscript([]);
+  }, []);
+  const unmountTimerRef = react.useRef(null);
+  react.useEffect(() => {
+    if (unmountTimerRef.current !== null) {
+      clearTimeout(unmountTimerRef.current);
+      unmountTimerRef.current = null;
+    }
+    return () => {
+      unmountTimerRef.current = setTimeout(() => {
+        unmountTimerRef.current = null;
+        void teardown();
+      }, 0);
+    };
+  }, [teardown]);
+  return react.useMemo(
+    () => ({
+      status,
+      isConnecting: status === "connecting",
+      isConnected: status === "connected" || status === "reconnecting",
+      activeSpeaker,
+      isMuted,
+      transcript,
+      sessionId,
+      roomName,
+      error,
+      start,
+      stop,
+      mute,
+      unmute,
+      clearTranscript
+    }),
+    [
+      status,
+      activeSpeaker,
+      isMuted,
+      transcript,
+      sessionId,
+      roomName,
+      error,
+      start,
+      stop,
+      mute,
+      unmute,
+      clearTranscript
+    ]
+  );
+};
+exports.createAthenaVoiceSession = createAthenaVoiceSession;
+exports.useAthenaVoiceSession = useAthenaVoiceSession;
+//# sourceMappingURL=use-athena-voice-session.cjs.map

package/dist/voice/use-athena-voice-session.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-athena-voice-session.cjs","sources":["../../src/voice/use-athena-voice-session.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport {\n  Room,\n  RoomEvent,\n  Track,\n  type Participant,\n  type RemoteTrack,\n  type TranscriptionSegment,\n} from 'livekit-client';\nimport { useParentBridge, type ParentBridgeState } from '../runtime/auth';\n\n/**\n * LiveKit connection details for one Athena voice session. This is the shape\n * Orpheus returns from `POST /api/orpheus/create-session`; the hook only reads\n * these fields, so any server that proxies that call can hand it straight back.\n */\nexport interface AthenaVoiceSessionCredentials {\n  /** LiveKit signalling URL (`wss://…`). */\n  server_url: string;\n  /** Short-lived LiveKit participant JWT scoped to `room_name`. */\n  token: string;\n  room_name?: string;\n  /**\n   * Athena session asset the voice run is persisted into. Use it with\n   * `GET /api/v0/sessions/{asset_id}/download` to retrieve the transcript\n   * after the call.\n   */\n  asset_id?: string;\n}\n\nexport type AthenaVoiceSessionStatus =\n  | 'idle'\n  | 'connecting'\n  | 'connected'\n  | 'reconnecting'\n  | 'ended'\n  | 'error';\n\nexport type AthenaVoiceSpeaker = 'user' | 'agent';\n\n/** One committed (final) transcription segment from either side of the call. */\nexport interface AthenaVoiceTranscriptTurn {\n  id: string;\n  speaker: AthenaVoiceSpeaker;\n  text: string;\n  /** Segment start, in ms since the LiveKit room's epoch. */\n  startTime: number;\n  endTime: number;\n  language: string;\n}\n\n/**\n * Orpheus agent configuration for a session the hook creates itself (see\n * `UseAthenaVoiceSessionOptions.session`). Mirrors the body of\n * `POST /api/orpheus/create-session`; every field is optional and falls back\n * to the server default.\n */\nexport interface AthenaVoiceSessionConfig {\n  /** Persona / instructions for the voice agent. */\n  system_prompt?: string;\n  /** Realtime provider, e.g. `'openai'` or `'google'`. */\n  provider?: string;\n  /** Provider model id, e.g. `'gpt-realtime-2'`. */\n  model?: string;\n  /** Provider voice id, e.g. `'marin'` (OpenAI) or `'Aoede'` (Google). */\n  voice?: string;\n  temperature?: number;\n  /** BCP-47 language tag; default `'en'`. */\n  language?: string;\n  /** Athena tool ids the agent may call; default none. */\n  enabled_tools?: string[];\n  /** IANA timezone of the speaker, e.g. `'America/New_York'`. */\n  timezone?: string;\n}\n\nexport interface UseAthenaVoiceSessionOptions {\n  /**\n   * Creates the LiveKit session. Omit it when the app is served from a\n   * Marathon computer-asset URL: the hook then calls\n   * `POST {backendBaseUrl}/api/orpheus/create-session` itself with the\n   * viewer's bearer token from `/_athena/auth`, so the session is created as\n   * — and shows up in the sessions of — whoever is using the app.\n   *\n   * Works for workspace members and external SSO viewers alike: the scoped\n   * `athview_` viewer credential is authorized for the Orpheus route and\n   * `agents/general/invoke` the same way it is for `/api/v0/sessions`.\n   *\n   * Supply it when the app runs anywhere else (standalone, custom auth): it\n   * should run on the caller's own server so the Athena API key never reaches\n   * the browser. The hook only reads the returned credentials.\n   *\n   * Decide once: switching between supplying and omitting it across renders\n   * of the same component is not supported.\n   */\n  createSession?: (\n    signal: AbortSignal,\n  ) => Promise<AthenaVoiceSessionCredentials>;\n  /**\n   * Agent configuration for sessions the hook creates itself. Ignored when\n   * `createSession` is supplied.\n   */\n  session?: AthenaVoiceSessionConfig;\n  /** Called once per committed transcript turn, in arrival order. */\n  onTranscript?: (turn: AthenaVoiceTranscriptTurn) => void;\n  /** Called with interim (non-final) transcript text as it streams in. */\n  onInterimTranscript?: (speaker: AthenaVoiceSpeaker, text: string) => void;\n  onError?: (error: Error) => void;\n  /**\n   * Where to play the agent's audio. Defaults to a detached `<audio>` element\n   * the hook creates and removes itself.\n   */\n  audioElement?: HTMLMediaElement | null;\n  /** Enable the microphone as soon as the room connects. Default `true`. */\n  autoEnableMicrophone?: boolean;\n  /** @internal Overrides `new Room()`; used by tests. */\n  createRoom?: () => Room;\n  /** @internal Overrides `useParentBridge()`; used by tests. */\n  useBridge?: () => ParentBridgeState;\n}\n\nexport interface UseAthenaVoiceSessionReturn {\n  status: AthenaVoiceSessionStatus;\n  /** True between `start()` resolving the session and the room connecting. */\n  isConnecting: boolean;\n  isConnected: boolean;\n  /** Who is speaking right now, or `null` when the room is quiet. */\n  activeSpeaker: AthenaVoiceSpeaker | null;\n  isMuted: boolean;\n  /** Committed transcript turns so far, in arrival order. */\n  transcript: AthenaVoiceTranscriptTurn[];\n  /** Athena session asset id, once the session has been created. */\n  sessionId: string | null;\n  roomName: string | null;\n  error: Error | null;\n  /** Creates a session and joins the room. No-op while a session is live. */\n  start: () => Promise<void>;\n  /** Leaves the room and stops local tracks. Safe to call at any time. */\n  stop: () => Promise<void>;\n  mute: () => Promise<void>;\n  unmute: () => Promise<void>;\n  /** Clears `transcript`; does not affect the live session. */\n  clearTranscript: () => void;\n}\n\nconst toError = (value: unknown): Error =>\n  value instanceof Error ? value : new Error(String(value));\n\nconst NO_BRIDGE: ParentBridgeState = {\n  token: null,\n  statewireSyncUrl: null,\n  backendBaseUrl: null,\n  appUrl: null,\n  hostAnswered: false,\n  ready: true,\n};\n// Stands in for `useParentBridge` when the caller creates sessions itself, so\n// the hook never fetches `/_athena/auth` it would not use.\nconst useNoBridge = (): ParentBridgeState => NO_BRIDGE;\n\nconst NO_VIEWER_TOKEN_MESSAGE =\n  'useAthenaVoiceSession: no Athena viewer token. Either serve the app from ' +\n  'a Marathon computer-asset URL (which mints one via /_athena/auth) or pass ' +\n  '`createSession` to create the session through your own server.';\n\n/**\n * `POST /api/orpheus/create-session` as the current viewer. Exported so apps\n * with their own bridge state (or a server proxy holding a user bearer) can\n * reuse the exact request the hook makes.\n */\nexport const createAthenaVoiceSession = async ({\n  backendBaseUrl,\n  token,\n  session = {},\n  signal,\n}: {\n  /** Bare Agora API base, e.g. `https://api.athenaintel.com`. */\n  backendBaseUrl: string;\n  /** Bearer token for the user the session belongs to. */\n  token: string;\n  session?: AthenaVoiceSessionConfig;\n  signal?: AbortSignal;\n}): Promise<AthenaVoiceSessionCredentials> => {\n  const url: string = `${backendBaseUrl.replace(/\\/+$/, '')}/api/orpheus/create-session`;\n  const response: Response = await fetch(url, {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${token}`,\n    },\n    body: JSON.stringify(session),\n    signal,\n  });\n  if (!response.ok) {\n    const detail: string = await response.text().catch(() => '');\n    throw new Error(\n      `Orpheus create-session failed (${response.status})${detail ? `: ${detail}` : ''}`,\n    );\n  }\n  return (await response.json()) as AthenaVoiceSessionCredentials;\n};\n\nconst speakerOf = (\n  participant: Participant | undefined,\n  room: Room,\n): AthenaVoiceSpeaker =>\n  participant !== undefined &&\n  participant.identity === room.localParticipant.identity\n    ? 'user'\n    : 'agent';\n\n/**\n * Runs one Athena voice session (Orpheus agent over LiveKit) from React.\n *\n * Owns the whole browser-side lifecycle the Orpheus API leaves to the caller:\n * creating the session through the app's own server, joining the LiveKit room,\n * publishing the microphone, playing the agent's audio, tracking who is\n * speaking, committing transcript turns from LiveKit transcription events, and\n * tearing everything down on `stop()` or unmount. A second `start()` while a\n * session is live (or still connecting) is ignored, so React StrictMode's\n * double-invoked effects cannot dispatch two agents into one room.\n */\nexport const useAthenaVoiceSession = (\n  options: UseAthenaVoiceSessionOptions = {},\n): UseAthenaVoiceSessionReturn => {\n  const {\n    createSession,\n    session,\n    onTranscript,\n    onInterimTranscript,\n    onError,\n    audioElement,\n    autoEnableMicrophone = true,\n    createRoom,\n    useBridge = createSession ? useNoBridge : useParentBridge,\n  } = options;\n\n  // Viewer identity minted by Marathon (`/_athena/auth`) or the Olympus iframe\n  // bridge. Only consulted when the caller did not supply `createSession`.\n  const bridge: ParentBridgeState = useBridge();\n  const bridgeRef = useRef<ParentBridgeState>(bridge);\n  bridgeRef.current = bridge;\n  const bridgeReadyWaitersRef = useRef<Array<() => void>>([]);\n  useEffect(() => {\n    if (!bridge.ready) return;\n    const waiters: Array<() => void> = bridgeReadyWaitersRef.current;\n    bridgeReadyWaitersRef.current = [];\n    for (const resolve of waiters) resolve();\n  }, [bridge.ready]);\n\n  const sessionRef = useRef<AthenaVoiceSessionConfig | undefined>(session);\n  sessionRef.current = session;\n\n  const createSessionAsViewer = useCallback(\n    async (signal: AbortSignal): Promise<AthenaVoiceSessionCredentials> => {\n      if (!bridgeRef.current.ready) {\n        await new Promise<void>((resolve) => {\n          bridgeReadyWaitersRef.current.push(resolve);\n          signal.addEventListener('abort', () => resolve(), { once: true });\n        });\n        if (signal.aborted) throw new Error('aborted');\n      }\n      const { token, backendBaseUrl } = bridgeRef.current;\n      if (!token || !backendBaseUrl) throw new Error(NO_VIEWER_TOKEN_MESSAGE);\n      return createAthenaVoiceSession({\n        backendBaseUrl,\n        token,\n        session: sessionRef.current,\n        signal,\n      });\n    },\n    [],\n  );\n\n  const [status, setStatus] = useState<AthenaVoiceSessionStatus>('idle');\n  const [activeSpeaker, setActiveSpeaker] = useState<AthenaVoiceSpeaker | null>(\n    null,\n  );\n  const [isMuted, setIsMuted] = useState<boolean>(false);\n  const [transcript, setTranscript] = useState<AthenaVoiceTranscriptTurn[]>([]);\n  const [sessionId, setSessionId] = useState<string | null>(null);\n  const [roomName, setRoomName] = useState<string | null>(null);\n  const [error, setError] = useState<Error | null>(null);\n\n  // Latest callbacks without re-subscribing room listeners on every render.\n  const callbacksRef = useRef({\n    createSession: createSession ?? createSessionAsViewer,\n    onTranscript,\n    onInterimTranscript,\n    onError,\n  });\n  callbacksRef.current = {\n    createSession: createSession ?? createSessionAsViewer,\n    onTranscript,\n    onInterimTranscript,\n    onError,\n  };\n\n  const roomRef = useRef<Room | null>(null);\n  const abortRef = useRef<AbortController | null>(null);\n  const attachedElementsRef = useRef<HTMLMediaElement[]>([]);\n  const ownedAudioRef = useRef<HTMLMediaElement | null>(null);\n  const committedSegmentIdsRef = useRef<Set<string>>(new Set());\n  // Guards `start()` against re-entry from the moment it is called, before any\n  // state update lands — a StrictMode double effect fires both calls\n  // synchronously in the same tick.\n  const startingRef = useRef<boolean>(false);\n\n  const fail = useCallback((cause: unknown) => {\n    const err: Error = toError(cause);\n    setError(err);\n    setStatus('error');\n    callbacksRef.current.onError?.(err);\n  }, []);\n\n  const detachAudio = useCallback(() => {\n    for (const element of attachedElementsRef.current) {\n      element.srcObject = null;\n      if (element === ownedAudioRef.current) element.remove();\n    }\n    attachedElementsRef.current = [];\n    ownedAudioRef.current = null;\n  }, []);\n\n  const teardown = useCallback(async () => {\n    abortRef.current?.abort();\n    abortRef.current = null;\n    const room: Room | null = roomRef.current;\n    roomRef.current = null;\n    startingRef.current = false;\n    detachAudio();\n    if (room) {\n      room.removeAllListeners();\n      await room.disconnect(true);\n    }\n  }, [detachAudio]);\n\n  const stop = useCallback(async () => {\n    const hadRoom: boolean =\n      roomRef.current !== null || abortRef.current !== null;\n    await teardown();\n    setActiveSpeaker(null);\n    if (hadRoom) setStatus('ended');\n  }, [teardown]);\n\n  const attachTrack = useCallback(\n    (track: RemoteTrack) => {\n      if (track.kind !== Track.Kind.Audio) return;\n      if (audioElement) {\n        track.attach(audioElement);\n        attachedElementsRef.current.push(audioElement);\n        return;\n      }\n      const element: HTMLMediaElement = track.attach();\n      element.setAttribute('data-athena-voice-audio', '');\n      document.body.appendChild(element);\n      ownedAudioRef.current = element;\n      attachedElementsRef.current.push(element);\n    },\n    [audioElement],\n  );\n\n  const handleTranscription = useCallback(\n    (\n      segments: TranscriptionSegment[],\n      participant: Participant | undefined,\n      room: Room,\n    ) => {\n      const speaker: AthenaVoiceSpeaker = speakerOf(participant, room);\n      const committed: AthenaVoiceTranscriptTurn[] = [];\n      for (const segment of segments) {\n        if (!segment.final) {\n          callbacksRef.current.onInterimTranscript?.(speaker, segment.text);\n          continue;\n        }\n        if (committedSegmentIdsRef.current.has(segment.id)) continue;\n        committedSegmentIdsRef.current.add(segment.id);\n        committed.push({\n          id: segment.id,\n          speaker,\n          text: segment.text,\n          startTime: segment.startTime,\n          endTime: segment.endTime,\n          language: segment.language,\n        });\n      }\n      if (committed.length === 0) return;\n      setTranscript((previous) => [...previous, ...committed]);\n      for (const turn of committed) callbacksRef.current.onTranscript?.(turn);\n    },\n    [],\n  );\n\n  const start = useCallback(async () => {\n    if (startingRef.current || roomRef.current) return;\n    startingRef.current = true;\n    setError(null);\n    setSessionId(null);\n    setRoomName(null);\n    setStatus('connecting');\n\n    const controller = new AbortController();\n    abortRef.current = controller;\n\n    let credentials: AthenaVoiceSessionCredentials;\n    try {\n      credentials = await callbacksRef.current.createSession(controller.signal);\n    } catch (cause) {\n      if (controller.signal.aborted) return;\n      abortRef.current = null;\n      startingRef.current = false;\n      fail(cause);\n      return;\n    }\n    if (controller.signal.aborted) return;\n\n    setSessionId(credentials.asset_id ?? null);\n    setRoomName(credentials.room_name ?? null);\n\n    const room: Room = createRoom ? createRoom() : new Room();\n    roomRef.current = room;\n\n    room\n      .on(RoomEvent.TrackSubscribed, attachTrack)\n      .on(RoomEvent.ActiveSpeakersChanged, (speakers: Participant[]) => {\n        const first: Participant | undefined = speakers[0];\n        setActiveSpeaker(first ? speakerOf(first, room) : null);\n      })\n      .on(RoomEvent.TranscriptionReceived, (segments, participant) =>\n        handleTranscription(segments, participant, room),\n      )\n      .on(RoomEvent.Reconnecting, () => setStatus('reconnecting'))\n      .on(RoomEvent.Reconnected, () => setStatus('connected'))\n      .on(RoomEvent.Disconnected, () => {\n        if (roomRef.current !== room) return;\n        roomRef.current = null;\n        startingRef.current = false;\n        detachAudio();\n        setActiveSpeaker(null);\n        setStatus('ended');\n      })\n      .on(RoomEvent.MediaDevicesError, fail);\n\n    try {\n      await room.connect(credentials.server_url, credentials.token);\n      if (controller.signal.aborted) return;\n      if (autoEnableMicrophone) {\n        await room.localParticipant.setMicrophoneEnabled(true);\n        setIsMuted(false);\n      } else {\n        setIsMuted(true);\n      }\n      if (controller.signal.aborted) return;\n      abortRef.current = null;\n      startingRef.current = false;\n      setStatus('connected');\n    } catch (cause) {\n      if (controller.signal.aborted) return;\n      await teardown();\n      fail(cause);\n    }\n  }, [\n    attachTrack,\n    autoEnableMicrophone,\n    createRoom,\n    detachAudio,\n    fail,\n    handleTranscription,\n    teardown,\n  ]);\n\n  const setMicrophone = useCallback(async (enabled: boolean) => {\n    const room: Room | null = roomRef.current;\n    if (!room) return;\n    await room.localParticipant.setMicrophoneEnabled(enabled);\n    setIsMuted(!enabled);\n  }, []);\n  const mute = useCallback(() => setMicrophone(false), [setMicrophone]);\n  const unmute = useCallback(() => setMicrophone(true), [setMicrophone]);\n\n  const clearTranscript = useCallback(() => {\n    committedSegmentIdsRef.current.clear();\n    setTranscript([]);\n  }, []);\n\n  // Unmount teardown is deferred one tick so StrictMode's synchronous\n  // unmount/remount of the same instance does not abort an in-flight\n  // `createSession` (which would dispatch a second Orpheus agent on remount).\n  const unmountTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  useEffect(() => {\n    if (unmountTimerRef.current !== null) {\n      clearTimeout(unmountTimerRef.current);\n      unmountTimerRef.current = null;\n    }\n    return () => {\n      unmountTimerRef.current = setTimeout(() => {\n        unmountTimerRef.current = null;\n        void teardown();\n      }, 0);\n    };\n  }, [teardown]);\n\n  return useMemo<UseAthenaVoiceSessionReturn>(\n    () => ({\n      status,\n      isConnecting: status === 'connecting',\n      isConnected: status === 'connected' || status === 'reconnecting',\n      activeSpeaker,\n      isMuted,\n      transcript,\n      sessionId,\n      roomName,\n      error,\n      start,\n      stop,\n      mute,\n      unmute,\n      clearTranscript,\n    }),\n    [\n      status,\n      activeSpeaker,\n      isMuted,\n      transcript,\n      sessionId,\n      roomName,\n      error,\n      start,\n      stop,\n      mute,\n      unmute,\n      clearTranscript,\n    ],\n  );\n};\n"],"names":["useParentBridge","useRef","useEffect","useCallback","useState","Track","Room","RoomEvent","useMemo"],"mappings":"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"}

package/dist/voice/use-athena-voice-session.d.ts

@@ -0,0 +1,145 @@
+import { Room } from 'livekit-client';
+import { type ParentBridgeState } from '../runtime/auth';
+/**
+ * LiveKit connection details for one Athena voice session. This is the shape
+ * Orpheus returns from `POST /api/orpheus/create-session`; the hook only reads
+ * these fields, so any server that proxies that call can hand it straight back.
+ */
+export interface AthenaVoiceSessionCredentials {
+    /** LiveKit signalling URL (`wss://…`). */
+    server_url: string;
+    /** Short-lived LiveKit participant JWT scoped to `room_name`. */
+    token: string;
+    room_name?: string;
+    /**
+     * Athena session asset the voice run is persisted into. Use it with
+     * `GET /api/v0/sessions/{asset_id}/download` to retrieve the transcript
+     * after the call.
+     */
+    asset_id?: string;
+}
+export type AthenaVoiceSessionStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'ended' | 'error';
+export type AthenaVoiceSpeaker = 'user' | 'agent';
+/** One committed (final) transcription segment from either side of the call. */
+export interface AthenaVoiceTranscriptTurn {
+    id: string;
+    speaker: AthenaVoiceSpeaker;
+    text: string;
+    /** Segment start, in ms since the LiveKit room's epoch. */
+    startTime: number;
+    endTime: number;
+    language: string;
+}
+/**
+ * Orpheus agent configuration for a session the hook creates itself (see
+ * `UseAthenaVoiceSessionOptions.session`). Mirrors the body of
+ * `POST /api/orpheus/create-session`; every field is optional and falls back
+ * to the server default.
+ */
+export interface AthenaVoiceSessionConfig {
+    /** Persona / instructions for the voice agent. */
+    system_prompt?: string;
+    /** Realtime provider, e.g. `'openai'` or `'google'`. */
+    provider?: string;
+    /** Provider model id, e.g. `'gpt-realtime-2'`. */
+    model?: string;
+    /** Provider voice id, e.g. `'marin'` (OpenAI) or `'Aoede'` (Google). */
+    voice?: string;
+    temperature?: number;
+    /** BCP-47 language tag; default `'en'`. */
+    language?: string;
+    /** Athena tool ids the agent may call; default none. */
+    enabled_tools?: string[];
+    /** IANA timezone of the speaker, e.g. `'America/New_York'`. */
+    timezone?: string;
+}
+export interface UseAthenaVoiceSessionOptions {
+    /**
+     * Creates the LiveKit session. Omit it when the app is served from a
+     * Marathon computer-asset URL: the hook then calls
+     * `POST {backendBaseUrl}/api/orpheus/create-session` itself with the
+     * viewer's bearer token from `/_athena/auth`, so the session is created as
+     * — and shows up in the sessions of — whoever is using the app.
+     *
+     * Works for workspace members and external SSO viewers alike: the scoped
+     * `athview_` viewer credential is authorized for the Orpheus route and
+     * `agents/general/invoke` the same way it is for `/api/v0/sessions`.
+     *
+     * Supply it when the app runs anywhere else (standalone, custom auth): it
+     * should run on the caller's own server so the Athena API key never reaches
+     * the browser. The hook only reads the returned credentials.
+     *
+     * Decide once: switching between supplying and omitting it across renders
+     * of the same component is not supported.
+     */
+    createSession?: (signal: AbortSignal) => Promise<AthenaVoiceSessionCredentials>;
+    /**
+     * Agent configuration for sessions the hook creates itself. Ignored when
+     * `createSession` is supplied.
+     */
+    session?: AthenaVoiceSessionConfig;
+    /** Called once per committed transcript turn, in arrival order. */
+    onTranscript?: (turn: AthenaVoiceTranscriptTurn) => void;
+    /** Called with interim (non-final) transcript text as it streams in. */
+    onInterimTranscript?: (speaker: AthenaVoiceSpeaker, text: string) => void;
+    onError?: (error: Error) => void;
+    /**
+     * Where to play the agent's audio. Defaults to a detached `<audio>` element
+     * the hook creates and removes itself.
+     */
+    audioElement?: HTMLMediaElement | null;
+    /** Enable the microphone as soon as the room connects. Default `true`. */
+    autoEnableMicrophone?: boolean;
+    /** @internal Overrides `new Room()`; used by tests. */
+    createRoom?: () => Room;
+    /** @internal Overrides `useParentBridge()`; used by tests. */
+    useBridge?: () => ParentBridgeState;
+}
+export interface UseAthenaVoiceSessionReturn {
+    status: AthenaVoiceSessionStatus;
+    /** True between `start()` resolving the session and the room connecting. */
+    isConnecting: boolean;
+    isConnected: boolean;
+    /** Who is speaking right now, or `null` when the room is quiet. */
+    activeSpeaker: AthenaVoiceSpeaker | null;
+    isMuted: boolean;
+    /** Committed transcript turns so far, in arrival order. */
+    transcript: AthenaVoiceTranscriptTurn[];
+    /** Athena session asset id, once the session has been created. */
+    sessionId: string | null;
+    roomName: string | null;
+    error: Error | null;
+    /** Creates a session and joins the room. No-op while a session is live. */
+    start: () => Promise<void>;
+    /** Leaves the room and stops local tracks. Safe to call at any time. */
+    stop: () => Promise<void>;
+    mute: () => Promise<void>;
+    unmute: () => Promise<void>;
+    /** Clears `transcript`; does not affect the live session. */
+    clearTranscript: () => void;
+}
+/**
+ * `POST /api/orpheus/create-session` as the current viewer. Exported so apps
+ * with their own bridge state (or a server proxy holding a user bearer) can
+ * reuse the exact request the hook makes.
+ */
+export declare const createAthenaVoiceSession: ({ backendBaseUrl, token, session, signal, }: {
+    /** Bare Agora API base, e.g. `https://api.athenaintel.com`. */
+    backendBaseUrl: string;
+    /** Bearer token for the user the session belongs to. */
+    token: string;
+    session?: AthenaVoiceSessionConfig;
+    signal?: AbortSignal;
+}) => Promise<AthenaVoiceSessionCredentials>;
+/**
+ * Runs one Athena voice session (Orpheus agent over LiveKit) from React.
+ *
+ * Owns the whole browser-side lifecycle the Orpheus API leaves to the caller:
+ * creating the session through the app's own server, joining the LiveKit room,
+ * publishing the microphone, playing the agent's audio, tracking who is
+ * speaking, committing transcript turns from LiveKit transcription events, and
+ * tearing everything down on `stop()` or unmount. A second `start()` while a
+ * session is live (or still connecting) is ignored, so React StrictMode's
+ * double-invoked effects cannot dispatch two agents into one room.
+ */
+export declare const useAthenaVoiceSession: (options?: UseAthenaVoiceSessionOptions) => UseAthenaVoiceSessionReturn;