@personaai/react 0.7.6 → 0.7.9

package/dist/index.d.cts

@@ -33,6 +33,11 @@ interface PersonaToolCall {
     seq?: number;
     /** Nested activity timeline — only present on `task` (subagent) tool calls. */
     subagentActivity?: PersonaSubagentActivityEntry[];
+    /** Present when this tool is backed by an interactive MCP Ext App. */
+    mcpApp?: {
+        resourceUri: string;
+        mcpId: string;
+    };
 }
 interface PersonaMessage {
     id: string;
@@ -268,6 +273,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 +310,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
@@ -335,6 +361,16 @@ interface UseVoiceOptions {
      * (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;
@@ -354,6 +390,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 {
@@ -545,6 +590,19 @@ declare function useMcpConnections(options?: UseMcpConnectionsOptions): {
     refetch: () => Promise<PersonaMcpConnection[]>;
 };
 
+interface UseMcpOptions {
+    /** Default MCP server ID for resource reads and tool calls */
+    mcpId?: string;
+}
+/**
+ * Hook for interacting with MCP servers connected via the Persona runtime.
+ * Provides helper functions for reading UI/data resources and calling server tools.
+ */
+declare function useMcp(options?: UseMcpOptions): {
+    readResource: (uri: string, mcpId?: string) => Promise<any>;
+    callTool: (name: string, args?: Record<string, unknown>, mcpId?: string) => Promise<any>;
+};
+
 /**
  * SSE transport for chat streams, with a React Native fallback.
  *
@@ -601,6 +659,6 @@ declare function supportsStreamingFetch(): boolean;
  */
 declare function openSSEStream(opts: OpenSSEOptions): Promise<SSEStream>;
 
-declare const VERSION = "0.7.3";
+declare const VERSION = "0.7.9";
 
-export { type OpenSSEOptions, type PersonaAgentSummary, type PersonaClarificationQuestion, type PersonaFileItem, type PersonaHealthInfo, type PersonaHitlActionRequest, type PersonaInterrupt, type PersonaMcpConnection, type PersonaMemoryAgentGroup, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, type PersonaPresentedFile, PersonaProvider, type PersonaProviderProps, type PersonaResumeValue, type PersonaRole, type PersonaStreamingEvent, type PersonaSubagentActivityEntry, type PersonaThread, type PersonaTodo, type PersonaToolCall, type PersonaVoiceEndReason, type PersonaVoiceState, type PersonaVoiceToolCall, type PersonaVoiceTranscriptLine, type PersonaWorkspaceFile, type SSEReader, type SSEStream, type SendMessageOverride, type UseChatOptions, type UseMcpConnectionsOptions, type UseVoiceOptions, type UseVoiceResult, VERSION, openSSEStream, supportsStreamingFetch, useAgents, useChat, useConnection, useFiles, useMcpConnections, useMemory, usePersonaContext, useThreads, useVoice };
+export { type OpenSSEOptions, type PersonaAgentSummary, type PersonaClarificationQuestion, type PersonaFileItem, type PersonaHealthInfo, type PersonaHitlActionRequest, type PersonaInterrupt, type PersonaMcpConnection, type PersonaMemoryAgentGroup, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, type PersonaPresentedFile, PersonaProvider, type PersonaProviderProps, type PersonaResumeValue, type PersonaRole, type PersonaStreamingEvent, type PersonaSubagentActivityEntry, type PersonaThread, type PersonaTodo, type PersonaToolCall, type PersonaVoiceEndReason, type PersonaVoiceState, type PersonaVoiceToolCall, type PersonaVoiceTranscriptLine, type PersonaWorkspaceFile, type SSEReader, type SSEStream, type SendMessageOverride, type UseChatOptions, type UseMcpConnectionsOptions, type UseMcpOptions, type UseVoiceOptions, type UseVoiceResult, VERSION, openSSEStream, supportsStreamingFetch, useAgents, useChat, useConnection, useFiles, useMcp, useMcpConnections, useMemory, usePersonaContext, useThreads, useVoice };

package/dist/index.d.ts

@@ -33,6 +33,11 @@ interface PersonaToolCall {
     seq?: number;
     /** Nested activity timeline — only present on `task` (subagent) tool calls. */
     subagentActivity?: PersonaSubagentActivityEntry[];
+    /** Present when this tool is backed by an interactive MCP Ext App. */
+    mcpApp?: {
+        resourceUri: string;
+        mcpId: string;
+    };
 }
 interface PersonaMessage {
     id: string;
@@ -268,6 +273,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 +310,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
@@ -335,6 +361,16 @@ interface UseVoiceOptions {
      * (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;
@@ -354,6 +390,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 {
@@ -545,6 +590,19 @@ declare function useMcpConnections(options?: UseMcpConnectionsOptions): {
     refetch: () => Promise<PersonaMcpConnection[]>;
 };
 
+interface UseMcpOptions {
+    /** Default MCP server ID for resource reads and tool calls */
+    mcpId?: string;
+}
+/**
+ * Hook for interacting with MCP servers connected via the Persona runtime.
+ * Provides helper functions for reading UI/data resources and calling server tools.
+ */
+declare function useMcp(options?: UseMcpOptions): {
+    readResource: (uri: string, mcpId?: string) => Promise<any>;
+    callTool: (name: string, args?: Record<string, unknown>, mcpId?: string) => Promise<any>;
+};
+
 /**
  * SSE transport for chat streams, with a React Native fallback.
  *
@@ -601,6 +659,6 @@ declare function supportsStreamingFetch(): boolean;
  */
 declare function openSSEStream(opts: OpenSSEOptions): Promise<SSEStream>;
 
-declare const VERSION = "0.7.3";
+declare const VERSION = "0.7.9";
 
-export { type OpenSSEOptions, type PersonaAgentSummary, type PersonaClarificationQuestion, type PersonaFileItem, type PersonaHealthInfo, type PersonaHitlActionRequest, type PersonaInterrupt, type PersonaMcpConnection, type PersonaMemoryAgentGroup, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, type PersonaPresentedFile, PersonaProvider, type PersonaProviderProps, type PersonaResumeValue, type PersonaRole, type PersonaStreamingEvent, type PersonaSubagentActivityEntry, type PersonaThread, type PersonaTodo, type PersonaToolCall, type PersonaVoiceEndReason, type PersonaVoiceState, type PersonaVoiceToolCall, type PersonaVoiceTranscriptLine, type PersonaWorkspaceFile, type SSEReader, type SSEStream, type SendMessageOverride, type UseChatOptions, type UseMcpConnectionsOptions, type UseVoiceOptions, type UseVoiceResult, VERSION, openSSEStream, supportsStreamingFetch, useAgents, useChat, useConnection, useFiles, useMcpConnections, useMemory, usePersonaContext, useThreads, useVoice };
+export { type OpenSSEOptions, type PersonaAgentSummary, type PersonaClarificationQuestion, type PersonaFileItem, type PersonaHealthInfo, type PersonaHitlActionRequest, type PersonaInterrupt, type PersonaMcpConnection, type PersonaMemoryAgentGroup, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, type PersonaPresentedFile, PersonaProvider, type PersonaProviderProps, type PersonaResumeValue, type PersonaRole, type PersonaStreamingEvent, type PersonaSubagentActivityEntry, type PersonaThread, type PersonaTodo, type PersonaToolCall, type PersonaVoiceEndReason, type PersonaVoiceState, type PersonaVoiceToolCall, type PersonaVoiceTranscriptLine, type PersonaWorkspaceFile, type SSEReader, type SSEStream, type SendMessageOverride, type UseChatOptions, type UseMcpConnectionsOptions, type UseMcpOptions, type UseVoiceOptions, type UseVoiceResult, VERSION, openSSEStream, supportsStreamingFetch, useAgents, useChat, useConnection, useFiles, useMcp, useMcpConnections, useMemory, usePersonaContext, useThreads, useVoice };

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
         });
@@ -860,6 +865,18 @@ function useChat(options = {}) {
                     ];
                     patchAssistant({});
                   }
+                } else if (event.name === "mcp_app") {
+                  const val = event.value;
+                  if (val?.toolCallId && val?.resourceUri && val?.mcpId) {
+                    const existing = toolCallsMap.get(val.toolCallId);
+                    if (existing) {
+                      existing.mcpApp = {
+                        resourceUri: val.resourceUri,
+                        mcpId: val.mcpId
+                      };
+                      patchAssistant({});
+                    }
+                  }
                 }
               } else if (event.type === "RUN_ERROR") {
                 chatLogger.warn("run error", {
@@ -1393,6 +1410,7 @@ function useVoice(options = {}) {
   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(
@@ -1665,7 +1683,8 @@ function useVoice(options = {}) {
     voiceLogger.debug("start() called", {
       agentId,
       threadId,
-      hasContextOverride: !!contextOverride
+      hasContextOverride: !!contextOverride,
+      hasContext: !!context
     });
     try {
       const res = await fetchWithAuth("/voice/sessions", {
@@ -1674,7 +1693,8 @@ function useVoice(options = {}) {
         body: JSON.stringify({
           agentId,
           ...threadId ? { threadId } : {},
-          ...contextOverride ? { contextOverride } : {}
+          ...contextOverride ? { contextOverride } : {},
+          ...context ? { context } : {}
         })
       });
       if (!res.ok) {
@@ -1710,7 +1730,7 @@ function useVoice(options = {}) {
       }
       teardownAudio();
     }
-  }, [agentId, threadId, contextOverride, fetchWithAuth, handleMessage, teardownAudio, voiceLogger]);
+  }, [agentId, threadId, contextOverride, context, fetchWithAuth, handleMessage, teardownAudio, voiceLogger]);
   const mute = useCallback4((muted) => {
     setIsMuted(muted);
     streamRef.current?.getAudioTracks().forEach((track) => {
@@ -1721,6 +1741,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,
@@ -1732,7 +1756,8 @@ function useVoice(options = {}) {
     start,
     stop,
     mute,
-    sendText
+    sendText,
+    updateContext
   };
 }
 
@@ -1962,6 +1987,47 @@ function useMcpConnections(options = {}) {
   };
 }
 
+// src/hooks/useMcp.ts
+import { useCallback as useCallback9 } from "react";
+function useMcp(options = {}) {
+  const { fetchWithAuth } = usePersonaContext();
+  const defaultMcpId = options.mcpId;
+  const readResource = useCallback9(
+    async (uri, mcpId) => {
+      const id = mcpId ?? defaultMcpId;
+      if (!id) throw new Error("MCP server ID is required to read resource");
+      const res = await fetchWithAuth(
+        `/mcps/${id}/resource?uri=${encodeURIComponent(uri)}`
+      );
+      if (!res.ok) {
+        throw new Error(`Failed to read MCP resource: ${res.statusText}`);
+      }
+      return await res.json();
+    },
+    [fetchWithAuth, defaultMcpId]
+  );
+  const callTool = useCallback9(
+    async (name, args, mcpId) => {
+      const id = mcpId ?? defaultMcpId;
+      if (!id) throw new Error("MCP server ID is required to call tool");
+      const res = await fetchWithAuth(`/mcps/${id}/call-tool`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name, arguments: args })
+      });
+      if (!res.ok) {
+        throw new Error(`Failed to call MCP tool: ${res.statusText}`);
+      }
+      return await res.json();
+    },
+    [fetchWithAuth, defaultMcpId]
+  );
+  return {
+    readResource,
+    callTool
+  };
+}
+
 // src/index.ts
 import {
   createLogger as createLogger2,
@@ -1970,7 +2036,7 @@ import {
   getLogLevel,
   isLevelEnabled
 } from "@personaai/logger";
-var VERSION = "0.7.3";
+var VERSION = "0.7.9";
 export {
   PersonaProvider,
   VERSION,
@@ -1985,6 +2051,7 @@ export {
   useChat,
   useConnection,
   useFiles,
+  useMcp,
   useMcpConnections,
   useMemory,
   usePersonaContext,