@personaai/react 0.7.0 → 0.7.2

package/README.md

@@ -49,12 +49,51 @@ function Chat() {
 | Hook            | Purpose                                                                    |
 | --------------- | -------------------------------------------------------------------------- |
 | `useChat`       | Streaming chat — messages, send, stop, reload, interrupts, workspace files |
+| `useVoice`      | Real-time voice calls (Gemini Live) — start/stop/mute, live transcript, tool calls |
 | `useThreads`    | Thread CRUD — list, create, delete, rename, reset, archive                 |
 | `useFiles`      | Upload management — list, upload, delete                                   |
 | `useMemory`     | Persistent memory — read, write, delete                                    |
 | `useAgents`     | Agent discovery — list available agents                                    |
 | `useConnection` | Health check — backend connectivity status                                 |
 
+## Voice
+
+Real-time voice calls with an Agent, powered by Gemini Live. Requires your backend to be running
+`@personaai/runtime@^0.7.0` (or a framework adapter on top of it) so `POST /voice/sessions` exists
+to mint tickets — see that package's README for why the actual call bypasses your backend and
+goes straight to Persona instead of relaying through it like `useChat` does.
+
+```tsx
+import { useVoice } from "@personaai/react";
+
+function VoiceCall() {
+  const { state, transcript, partial, toolCalls, start, stop, mute, isMuted } = useVoice();
+
+  return (
+    <div>
+      <p>State: {state}</p>
+      {state === "idle" ? (
+        <button onClick={start}>Start call</button>
+      ) : (
+        <>
+          <button onClick={() => mute(!isMuted)}>{isMuted ? "Unmute" : "Mute"}</button>
+          <button onClick={stop}>End call</button>
+        </>
+      )}
+      {transcript.map((line) => (
+        <p key={line.id}>
+          <b>{line.speaker}:</b> {line.text}
+        </p>
+      ))}
+      {partial && <p style={{ opacity: 0.6 }}>{partial.text}</p>}
+    </div>
+  );
+}
+```
+
+Requires a browser with `AudioWorklet` support (every current evergreen browser). Needs an HTTPS
+page in production — browsers refuse an insecure `ws://` connection from an `https:` page.
+
 ## Devtools
 
 Floating panel for local debugging — inspect hooks, messages and threads with zero runtime changes. Dev-only, not bundled to production unless imported.

package/dist/index.cjs

@@ -1347,10 +1347,19 @@ function playerWorkletUrl() {
 }
 
 // src/hooks/useVoice.ts
+function mergeTranscriptText(prev, next) {
+  if (!prev) return next;
+  if (!next) return prev;
+  if (next === prev || prev.endsWith(next)) return prev;
+  if (next.startsWith(prev)) return next;
+  const needSpace = !/\s$/.test(prev) && !/^\s/.test(next);
+  return prev + (needSpace ? " " : "") + next;
+}
 function useVoice(options = {}) {
   const { defaultAgentId, fetchWithAuth, logger } = usePersonaContext();
   const voiceLogger = (0, import_react5.useMemo)(() => logger.child("voice"), [logger]);
   const agentId = options.agentId || defaultAgentId;
+  const threadId = options.threadId;
   const [state, setState] = (0, import_react5.useState)("idle");
   const [isMuted, setIsMuted] = (0, import_react5.useState)(false);
   const [transcript, setTranscript] = (0, import_react5.useState)(
@@ -1372,6 +1381,9 @@ function useVoice(options = {}) {
   const playerNodeRef = (0, import_react5.useRef)(null);
   const acceptedTurnSeqRef = (0, import_react5.useRef)(0);
   const mountedRef = (0, import_react5.useRef)(true);
+  const lastFinalTurnRef = (0, import_react5.useRef)(
+    null
+  );
   (0, import_react5.useEffect)(() => {
     mountedRef.current = true;
     return () => {
@@ -1454,8 +1466,7 @@ function useVoice(options = {}) {
     (id, patch) => {
       setToolCalls((prev) => {
         const idx = prev.findIndex((t) => t.id === id);
-        if (idx === -1)
-          return [...prev, { id, status: "running", ...patch }];
+        if (idx === -1) return [...prev, { id, status: "running", ...patch }];
         const next = [...prev];
         next[idx] = { ...next[idx], ...patch };
         return next;
@@ -1463,21 +1474,28 @@ function useVoice(options = {}) {
     },
     []
   );
-  const handleTranscript = (0, import_react5.useCallback)(
-    (value) => {
-      const { speaker, text, isFinal } = value;
-      if (isFinal) {
-        setPartial((prev) => prev?.speaker === speaker ? null : prev);
-        setTranscript((prev) => [
-          ...prev,
-          { id: `${speaker}-${prev.length}`, speaker, text }
-        ]);
-      } else {
-        setPartial({ id: "partial", speaker, text });
+  const handleTranscript = (0, import_react5.useCallback)((value) => {
+    const { speaker, text, isFinal, turnSeq } = value;
+    if (!isFinal) {
+      setPartial({ id: "partial", speaker, text });
+      return;
+    }
+    setPartial((prev) => prev?.speaker === speaker ? null : prev);
+    const last = lastFinalTurnRef.current;
+    const sameUtterance = last && last.speaker === speaker && last.turnSeq === turnSeq;
+    setTranscript((prev) => {
+      const tail = prev[prev.length - 1];
+      if (sameUtterance && tail?.speaker === speaker) {
+        const merged = mergeTranscriptText(tail.text, text);
+        if (merged === tail.text) return prev;
+        return prev.map(
+          (l, i) => i === prev.length - 1 ? { ...l, text: merged } : l
+        );
       }
-    },
-    []
-  );
+      return [...prev, { id: `${speaker}-${prev.length}`, speaker, text }];
+    });
+    lastFinalTurnRef.current = { speaker, turnSeq };
+  }, []);
   const handleCustomEvent = (0, import_react5.useCallback)(
     (name, value) => {
       switch (name) {
@@ -1510,9 +1528,7 @@ function useVoice(options = {}) {
           }
           break;
         case "voice_transcript":
-          handleTranscript(
-            value
-          );
+          handleTranscript(value);
           break;
         case "voice_interrupted":
           acceptedTurnSeqRef.current = value.turnSeq;
@@ -1585,7 +1601,9 @@ function useVoice(options = {}) {
         }
         case "RUN_ERROR":
           voiceLogger.warn("RUN_ERROR", { message: msg.message });
-          setError(new Error(msg.message || "The agent run failed."));
+          setError(
+            new Error(msg.message || "The agent run failed.")
+          );
           setState("error");
           break;
         default:
@@ -1610,12 +1628,15 @@ function useVoice(options = {}) {
     setToolCalls([]);
     acceptedTurnSeqRef.current = 0;
     setState("connecting");
-    voiceLogger.debug("start() called", { agentId });
+    voiceLogger.debug("start() called", { agentId, threadId });
     try {
       const res = await fetchWithAuth("/voice/sessions", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ agentId })
+        body: JSON.stringify({
+          agentId,
+          ...threadId ? { threadId } : {}
+        })
       });
       if (!res.ok) {
         throw new Error(`Failed to start voice session: ${res.statusText}`);
@@ -1650,7 +1671,7 @@ function useVoice(options = {}) {
       }
       teardownAudio();
     }
-  }, [agentId, fetchWithAuth, handleMessage, teardownAudio, voiceLogger]);
+  }, [agentId, threadId, fetchWithAuth, handleMessage, teardownAudio, voiceLogger]);
   const mute = (0, import_react5.useCallback)((muted) => {
     setIsMuted(muted);
     streamRef.current?.getAudioTracks().forEach((track) => {
@@ -1904,7 +1925,7 @@ function useMcpConnections(options = {}) {
 
 // src/index.ts
 var import_logger2 = require("@personaai/logger");
-var VERSION = "0.7.0";
+var VERSION = "0.7.2";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PersonaProvider,