@springbrand/chat-client 0.1.3-alpha.12 → 0.1.3-alpha.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/chat-client",
-  "version": "0.1.3-alpha.12",
+  "version": "0.1.3-alpha.15",
   "type": "module",
   "files": [
     "src",
@@ -25,7 +25,7 @@
     "@types/react-dom": "^19.2.3",
     "react-dom": "^19.2.7",
     "typescript": "^7.0.2",
-    "@springbrand/agent-runtime": "0.2.0-alpha.21"
+    "@springbrand/agent-runtime": "0.2.0-alpha.22"
   },
   "scripts": {
     "typecheck": "tsc --noEmit"

package/src/index.ts

@@ -1,4 +1,5 @@
 export {
+  UniversalAgentChatProvider,
   useUniversalAgentChat,
   type AgentToolRun,
   type ChatConnectionOptions,

package/src/use-universal-agent-chat.ts

@@ -1,4 +1,15 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  createContext,
+  createElement,
+  Suspense,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import { nanoid } from "nanoid";
 import type { ChatStatus, FileUIPart, UIMessage } from "ai";
 import type { AgentToolRunState } from "agents";
@@ -148,6 +159,8 @@ type SharedChatConnectionOptions = {
   protocols?: string | string[];
   inboxAgent?: string;
   sessionAgent?: string;
+  /** Host projection used only until the selected Session sends its first state. */
+  initialTurnActive?: boolean;
 };
 
 export type ChatConnectionOptions = SharedChatConnectionOptions & (
@@ -155,6 +168,51 @@ export type ChatConnectionOptions = SharedChatConnectionOptions & (
   | { inboxName?: never; basePath?: string }
 );
 
+type SessionAgentConnection = ReturnType<typeof useAgent<RuntimeState>>;
+type UniversalAgentChatContextValue = {
+  chatId: string;
+  connection: ChatConnectionOptions;
+  agent: SessionAgentConnection;
+};
+
+const UniversalAgentChatContext = createContext<UniversalAgentChatContextValue | null>(null);
+
+export function UniversalAgentChatProvider({
+  chatId,
+  connection = {},
+  fallback = null,
+  children,
+}: {
+  chatId: string;
+  connection?: ChatConnectionOptions;
+  fallback?: ReactNode;
+  children: ReactNode;
+}) {
+  const inboxAgent = connection.inboxAgent ?? "Inbox";
+  const agent = useAgent<RuntimeState>({
+    agent: inboxAgent,
+    ...(connection.inboxName === undefined
+      ? { basePath: connection.basePath ?? CURRENT_INBOX_AGENT_PATH }
+      : { name: connection.inboxName }),
+    ...(connection.host === undefined ? {} : { host: connection.host }),
+    ...(connection.protocols === undefined ? {} : { protocols: connection.protocols }),
+    connectionTimeout: 6_000,
+    sub: [{
+      agent: connection.sessionAgent ?? "UniversalAgent",
+      name: chatId,
+    }],
+  });
+  const value = useMemo(
+    () => ({ chatId, connection, agent }),
+    [agent, chatId, connection],
+  );
+  return createElement(
+    UniversalAgentChatContext.Provider,
+    { value },
+    createElement(Suspense, { fallback }, children),
+  );
+}
+
 type ChatTurnTiming = {
   chatId: string;
   messageId: string;
@@ -282,10 +340,12 @@ function loadInitialMessages(
  * sub 数组由客户端 kebab 化;服务端按 ctx.exports 反解回 CamelCase className,
  * 与 Inbox.onBeforeSubAgent 的严格门卫(hasSubAgent)对齐。
  */
-export function useUniversalAgentChat(
-  chatId: string,
-  connection: ChatConnectionOptions = {},
-): ChatRuntime {
+export function useUniversalAgentChat(): ChatRuntime {
+  const context = useContext(UniversalAgentChatContext);
+  if (!context) {
+    throw new Error("useUniversalAgentChat must be used within UniversalAgentChatProvider");
+  }
+  const { chatId, connection, agent } = context;
   const [optimisticMessages, setOptimisticMessages] =
     useState<ChatMessage[]>([]);
   const [optimisticQueued, setOptimisticQueued] =
@@ -294,19 +354,6 @@ export function useUniversalAgentChat(
   const [canRetry, setCanRetry] = useState(false);
   const failedDispatchRef = useRef<FailedDispatch | undefined>(undefined);
   const activeSubmissionIdRef = useRef<string | undefined>(undefined);
-  const inboxAgent = connection.inboxAgent ?? "Inbox";
-  const agent = useAgent<RuntimeState>({
-    agent: inboxAgent,
-    ...(connection.inboxName === undefined
-      ? { basePath: connection.basePath ?? CURRENT_INBOX_AGENT_PATH }
-      : { name: connection.inboxName }),
-    ...(connection.host === undefined ? {} : { host: connection.host }),
-    ...(connection.protocols === undefined ? {} : { protocols: connection.protocols }),
-    sub: [{
-      agent: connection.sessionAgent ?? "UniversalAgent",
-      name: chatId,
-    }],
-  });
   const chatAgent = useMemo(
     () => createSafeUIMessageAgentConnection(agent),
     [agent],
@@ -384,9 +431,12 @@ export function useUniversalAgentChat(
         ? "streaming"
         : "submitted"
       : normalizedSdkStatus;
+  const hydratingTurnActive = facetState === undefined &&
+    connection.initialTurnActive === true;
   const status = dispatchError
     ? "error"
-    : optimisticMessages.length > 0 && authoritativeStatus === "ready"
+    : (optimisticMessages.length > 0 || hydratingTurnActive) &&
+        authoritativeStatus === "ready"
       ? "submitted"
       : authoritativeStatus;
   const messagesRef = useRef(messages);
@@ -478,7 +528,8 @@ export function useUniversalAgentChat(
     isToolContinuation;
   const pendingLocalTurn = optimisticMessages.length > 0 &&
     (status === "submitted" || status === "streaming");
-  const turnActive = Boolean(turn?.activeSubmissionId) ||
+  const turnActive = hydratingTurnActive ||
+    Boolean(turn?.activeSubmissionId) ||
     pendingLocalTurn ||
     (authoritativeTurn === undefined && sdkTurnActive);
   const canSteer = turnActive &&