@personaai/react 0.7.5 → 0.7.8

package/dist/index.d.cts

@@ -268,6 +268,20 @@ interface UseChatOptions {
      * host app still owns starting/stopping the call itself (e.g. `voice.start()`/`voice.stop()`).
      */
     voice?: UseVoiceResult;
+    /**
+     * Caller-supplied context — never shown to the model in any form, unlike
+     * `contextOverride` (see {@link SendMessageOverride.contextOverride}).
+     * Only ever read live by an RCP tool's resolver at the moment it's
+     * actually called. Accepts a plain object, or a getter (`() => object`)
+     * so `sendMessage()` always reads your app's *current* state at send
+     * time — no ref, no effect to keep it in sync as the value changes (e.g.
+     * the user navigates to a different page mid-conversation). Shallow-merged
+     * with any call-level `sendMessage(text, { context })` override, which
+     * wins on key collisions. Must be a flat object of string/number/boolean
+     * values only, capped at 2000 bytes serialized — a violation is rejected
+     * with a 400, not silently truncated or coerced.
+     */
+    context?: Record<string, unknown> | (() => Record<string, unknown>);
 }
 interface SendMessageOverride {
     agentId?: string;
@@ -291,6 +305,13 @@ interface SendMessageOverride {
      * `@personaai/sdk`'s `SendMessageOptions.contextOverride`.
      */
     contextOverride?: string;
+    /**
+     * One-off override for this send only — shallow-merged on top of
+     * `useChat`'s hook-level `context` option (this wins on key collisions).
+     * Same shape/cap/contract as the hook-level option; see
+     * {@link UseChatOptions.context}.
+     */
+    context?: Record<string, unknown>;
 }
 /**
  * `useVoice`'s call state, driven by `voice_activity` events from the
@@ -325,6 +346,26 @@ interface UseVoiceOptions {
      * leave undefined) to start a fresh conversation.
      */
     threadId?: string;
+    /**
+     * Caller-supplied context appended to the Agent's system instruction for
+     * this call — same field/cap/contract as `useChat`'s `sendMessage(text, {
+     * contextOverride })`. Unlike text chat, this is a **one-time append at
+     * connect**, not re-applied per turn: Gemini Live's system instruction is
+     * fixed for the whole call, so changing it means ending this call and
+     * starting a new `start()`. Capped at 4000 characters server-side
+     * (rejected with a 400, not truncated).
+     */
+    contextOverride?: string;
+    /**
+     * Caller-supplied context — never shown to the model, only ever read live
+     * by an RCP tool's resolver. This is the **at-connect seed only**, passed
+     * to `start()`'s ticket-mint call. To refresh it for the rest of an
+     * already-open call (a voice call can run up to 15 minutes — long enough
+     * for the caller's own context to change), use the returned
+     * `updateContext()` instead, which sends it live over the open WebSocket
+     * with no reconnect and no interruption to the audio.
+     */
+    context?: Record<string, unknown>;
 }
 interface UseVoiceResult {
     state: PersonaVoiceState;
@@ -344,6 +385,15 @@ interface UseVoiceResult {
     mute: (muted: boolean) => void;
     /** Sends a typed message mid-call instead of speaking — the agent may reply in either voice or text. */
     sendText: (text: string) => void;
+    /**
+     * Live-refreshes context for the rest of this already-open call — merged
+     * into, not replacing, whatever context is already set (from `start()`'s
+     * `context` option or a previous `updateContext()` call). Sent directly
+     * over the open WebSocket (`{ type: 'voice.context', context }`); a no-op
+     * if the call isn't currently active. No reconnect, no dropped audio —
+     * the next tool call in this session reads the new value.
+     */
+    updateContext: (context: Record<string, unknown>) => void;
 }
 
 interface PersonaContextValue {

package/dist/index.d.ts

@@ -268,6 +268,20 @@ interface UseChatOptions {
      * host app still owns starting/stopping the call itself (e.g. `voice.start()`/`voice.stop()`).
      */
     voice?: UseVoiceResult;
+    /**
+     * Caller-supplied context — never shown to the model in any form, unlike
+     * `contextOverride` (see {@link SendMessageOverride.contextOverride}).
+     * Only ever read live by an RCP tool's resolver at the moment it's
+     * actually called. Accepts a plain object, or a getter (`() => object`)
+     * so `sendMessage()` always reads your app's *current* state at send
+     * time — no ref, no effect to keep it in sync as the value changes (e.g.
+     * the user navigates to a different page mid-conversation). Shallow-merged
+     * with any call-level `sendMessage(text, { context })` override, which
+     * wins on key collisions. Must be a flat object of string/number/boolean
+     * values only, capped at 2000 bytes serialized — a violation is rejected
+     * with a 400, not silently truncated or coerced.
+     */
+    context?: Record<string, unknown> | (() => Record<string, unknown>);
 }
 interface SendMessageOverride {
     agentId?: string;
@@ -291,6 +305,13 @@ interface SendMessageOverride {
      * `@personaai/sdk`'s `SendMessageOptions.contextOverride`.
      */
     contextOverride?: string;
+    /**
+     * One-off override for this send only — shallow-merged on top of
+     * `useChat`'s hook-level `context` option (this wins on key collisions).
+     * Same shape/cap/contract as the hook-level option; see
+     * {@link UseChatOptions.context}.
+     */
+    context?: Record<string, unknown>;
 }
 /**
  * `useVoice`'s call state, driven by `voice_activity` events from the
@@ -325,6 +346,26 @@ interface UseVoiceOptions {
      * leave undefined) to start a fresh conversation.
      */
     threadId?: string;
+    /**
+     * Caller-supplied context appended to the Agent's system instruction for
+     * this call — same field/cap/contract as `useChat`'s `sendMessage(text, {
+     * contextOverride })`. Unlike text chat, this is a **one-time append at
+     * connect**, not re-applied per turn: Gemini Live's system instruction is
+     * fixed for the whole call, so changing it means ending this call and
+     * starting a new `start()`. Capped at 4000 characters server-side
+     * (rejected with a 400, not truncated).
+     */
+    contextOverride?: string;
+    /**
+     * Caller-supplied context — never shown to the model, only ever read live
+     * by an RCP tool's resolver. This is the **at-connect seed only**, passed
+     * to `start()`'s ticket-mint call. To refresh it for the rest of an
+     * already-open call (a voice call can run up to 15 minutes — long enough
+     * for the caller's own context to change), use the returned
+     * `updateContext()` instead, which sends it live over the open WebSocket
+     * with no reconnect and no interruption to the audio.
+     */
+    context?: Record<string, unknown>;
 }
 interface UseVoiceResult {
     state: PersonaVoiceState;
@@ -344,6 +385,15 @@ interface UseVoiceResult {
     mute: (muted: boolean) => void;
     /** Sends a typed message mid-call instead of speaking — the agent may reply in either voice or text. */
     sendText: (text: string) => void;
+    /**
+     * Live-refreshes context for the rest of this already-open call — merged
+     * into, not replacing, whatever context is already set (from `start()`'s
+     * `context` option or a previous `updateContext()` call). Sent directly
+     * over the open WebSocket (`{ type: 'voice.context', context }`); a no-op
+     * if the call isn't currently active. No reconnect, no dropped audio —
+     * the next tool call in this session reads the new value.
+     */
+    updateContext: (context: Record<string, unknown>) => void;
 }
 
 interface PersonaContextValue {

package/dist/index.js

@@ -642,10 +642,14 @@ function useChat(options = {}) {
         const resolvedThreadId = await (overrideOptions?.threadId ?? options.threadId);
         chatLogger.trace("resolved threadId", { threadId: resolvedThreadId });
         const token = getAuthToken ? await getAuthToken() : null;
+        const resolvedHookContext = typeof options.context === "function" ? options.context() : options.context;
+        const mergedContext = { ...resolvedHookContext, ...overrideOptions?.context };
+        const hasContext = Object.keys(mergedContext).length > 0;
         chatLogger.debug("opening SSE stream", {
           agentId: targetAgentId,
           hasToken: !!token,
-          hasThreadId: !!resolvedThreadId
+          hasThreadId: !!resolvedThreadId,
+          hasContext
         });
         const stream = await openSSEStream({
           url: `${baseUrl}/chat`,
@@ -658,7 +662,8 @@ function useChat(options = {}) {
             messages: payloadMessages,
             threadId: resolvedThreadId,
             resume: overrideOptions?.resume,
-            contextOverride: overrideOptions?.contextOverride
+            contextOverride: overrideOptions?.contextOverride,
+            ...hasContext ? { context: mergedContext } : {}
           }),
           signal: controller.signal
         });
@@ -1392,6 +1397,8 @@ function useVoice(options = {}) {
   const voiceLogger = useMemo3(() => logger.child("voice"), [logger]);
   const agentId = options.agentId || defaultAgentId;
   const threadId = options.threadId;
+  const contextOverride = options.contextOverride;
+  const context = options.context;
   const [state, setState] = useState4("idle");
   const [isMuted, setIsMuted] = useState4(false);
   const [transcript, setTranscript] = useState4(
@@ -1661,14 +1668,21 @@ function useVoice(options = {}) {
     setToolCalls([]);
     acceptedTurnSeqRef.current = 0;
     setState("connecting");
-    voiceLogger.debug("start() called", { agentId, threadId });
+    voiceLogger.debug("start() called", {
+      agentId,
+      threadId,
+      hasContextOverride: !!contextOverride,
+      hasContext: !!context
+    });
     try {
       const res = await fetchWithAuth("/voice/sessions", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
           agentId,
-          ...threadId ? { threadId } : {}
+          ...threadId ? { threadId } : {},
+          ...contextOverride ? { contextOverride } : {},
+          ...context ? { context } : {}
         })
       });
       if (!res.ok) {
@@ -1704,7 +1718,7 @@ function useVoice(options = {}) {
       }
       teardownAudio();
     }
-  }, [agentId, threadId, fetchWithAuth, handleMessage, teardownAudio, voiceLogger]);
+  }, [agentId, threadId, contextOverride, context, fetchWithAuth, handleMessage, teardownAudio, voiceLogger]);
   const mute = useCallback4((muted) => {
     setIsMuted(muted);
     streamRef.current?.getAudioTracks().forEach((track) => {
@@ -1715,6 +1729,10 @@ function useVoice(options = {}) {
     if (!text?.trim() || wsRef.current?.readyState !== WebSocket.OPEN) return;
     wsRef.current.send(JSON.stringify({ type: "voice.text", text }));
   }, []);
+  const updateContext = useCallback4((newContext) => {
+    if (wsRef.current?.readyState !== WebSocket.OPEN) return;
+    wsRef.current.send(JSON.stringify({ type: "voice.context", context: newContext }));
+  }, []);
   return {
     state,
     isMuted,
@@ -1726,7 +1744,8 @@ function useVoice(options = {}) {
     start,
     stop,
     mute,
-    sendText
+    sendText,
+    updateContext
   };
 }