@springbrand/chat-client 0.1.3-alpha.3 → 0.1.3-alpha.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/chat-client",
-  "version": "0.1.3-alpha.3",
+  "version": "0.1.3-alpha.31",
   "type": "module",
   "files": [
     "src",
@@ -13,7 +13,7 @@
     ".": "./src/index.ts"
   },
   "peerDependencies": {
-    "agents": "^0.19.0",
+    "agents": "^0.20.1",
     "ai": "^7.0.0",
     "react": "^19.0.0"
   },
@@ -25,7 +25,7 @@
     "@types/react-dom": "^19.2.3",
     "react-dom": "^19.2.7",
     "typescript": "^7.0.2",
-    "@springbrand/agent-runtime": "0.1.3-alpha.4"
+    "@springbrand/agent-runtime": "0.2.0-alpha.42"
   },
   "scripts": {
     "typecheck": "tsc --noEmit"

package/src/chat-sessions.ts

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useAgent } from "agents/react";
 
-interface InboxState<Session> {
+export interface InboxState<Session> {
   chats: Session[];
   workspaceRev?: number;
 }
@@ -33,8 +33,11 @@ export async function loadChatSessions<Session>(
 }
 
 /** Browser client for the user Inbox. Routing and presentation stay with the host UI. */
-export function useChatSessions<Session>(options: ChatSessionsOptions = {}) {
-  const inbox = useAgent<InboxState<Session>>({
+export function useChatSessions<
+  Session,
+  State extends InboxState<Session> = InboxState<Session>,
+>(options: ChatSessionsOptions = {}) {
+  const inbox = useAgent<State>({
     agent: "Inbox",
     basePath: CURRENT_INBOX_AGENT_PATH,
     ...(options.protocols === undefined ? {} : { protocols: options.protocols }),
@@ -93,6 +96,7 @@ export function useChatSessions<Session>(options: ChatSessionsOptions = {}) {
     synced: inbox.state !== undefined || snapshot !== undefined,
     connected: inbox.identified,
     workspaceRev: inbox.state?.workspaceRev ?? 0,
+    inboxState: inbox.state,
     createChat,
     forkChat,
     renameChat,

package/src/index.ts

@@ -1,6 +1,8 @@
 export {
+  UniversalAgentChatProvider,
   useUniversalAgentChat,
   type AgentToolRun,
+  type ChatConnectionStatus,
   type ChatConnectionOptions,
   type ChatRuntime,
 } from "./use-universal-agent-chat";
@@ -21,4 +23,5 @@ export {
   useChatSessions,
   type ChatSessionsOptions,
   type ChatSessions,
+  type InboxState,
 } from "./chat-sessions";

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

@@ -1,13 +1,27 @@
-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";
+import type { AgentConnectionError } from "agents/client";
 import { MessageType } from "agents/chat";
 import { getAgentMessages, useAgentChat } from "agents/chat/react";
 import { useAgent, useAgentToolEvents } from "agents/react";
 import {
+  type ApprovalDecision,
   type MessageDelivery,
   type MessageDispatchReceipt,
+  type RequestedCapability,
   type RuntimeAssemblyView,
   type RuntimeConfigUpdateResult,
   type RuntimeQueuedSubmission,
@@ -17,9 +31,17 @@ import { createSafeUIMessageAgentConnection } from "./ui-message-stream-guard";
 import { CURRENT_INBOX_AGENT_PATH } from "./chat-sessions";
 
 type ChatMessageMetadata = Record<string, unknown> & {
+  error?: string;
+  requestedCapabilities?: readonly RequestedCapability[];
+  turnId?: string;
   turnStatus?: string;
 };
 type ChatMessage = UIMessage<ChatMessageMetadata>;
+export type ChatConnectionStatus =
+  | "connecting"
+  | "connected"
+  | "rejected"
+  | "error";
 type FailedDispatch = {
   message: ChatMessage;
   delivery: MessageDelivery;
@@ -82,12 +104,26 @@ type ChatTurn = {
 export interface ChatRuntime {
   messages: ChatMessage[];
   status: ChatStatus;
+  connectionStatus: ChatConnectionStatus;
+  connectionError: AgentConnectionError | undefined;
   runtimeLoad: ChatRuntimeLoadState | undefined;
   isStreaming: boolean;
   error: string | Error | undefined;
-  sendText: (text: string, files?: readonly FileUIPart[]) => Promise<boolean>;
-  steerText: (text: string, files?: readonly FileUIPart[]) => Promise<boolean>;
-  enqueueText: (text: string, files?: readonly FileUIPart[]) => Promise<boolean>;
+  sendText: (
+    text: string,
+    files?: readonly FileUIPart[],
+    capabilities?: readonly RequestedCapability[],
+  ) => Promise<boolean>;
+  steerText: (
+    text: string,
+    files?: readonly FileUIPart[],
+    capabilities?: readonly RequestedCapability[],
+  ) => Promise<boolean>;
+  enqueueText: (
+    text: string,
+    files?: readonly FileUIPart[],
+    capabilities?: readonly RequestedCapability[],
+  ) => Promise<boolean>;
   steerQueued: (submissionId: string) => Promise<boolean>;
   cancelQueued: (submissionId: string) => Promise<boolean>;
   stop: () => Promise<void>;
@@ -101,6 +137,10 @@ export interface ChatRuntime {
     toolCallId: string,
     response: unknown,
   ) => Promise<boolean>;
+  decideApproval: (
+    executionId: string,
+    decision: ApprovalDecision,
+  ) => Promise<{ ok: boolean }>;
   /**
    * 读取该 Session facet 当前真正装配出来的 Runtime。
    *
@@ -110,6 +150,10 @@ export interface ChatRuntime {
    * 装配未就绪还是连接断了，收敛成 `undefined` 会让调试面板无从显示原因。
    */
   getRuntimeAssembly: () => Promise<RuntimeAssemblyView>;
+  getRuntimeBinding: <Binding = unknown>() => Promise<Binding>;
+  readChatMetadata: <Metadata = unknown>() => Promise<Metadata>;
+  renameChat: <Metadata = unknown>(title: string) => Promise<Metadata>;
+  rebindRuntime: <Input = unknown, Result = unknown>(input: Input) => Promise<Result>;
   updateConfig: <Change = unknown>(
     command: unknown,
   ) => Promise<RuntimeConfigUpdateResult<Change>>;
@@ -131,8 +175,13 @@ type SharedChatConnectionOptions = {
   host?: string;
   credentials?: RequestCredentials;
   protocols?: string | string[];
+  onMessage?: (message: MessageEvent) => void;
   inboxAgent?: string;
   sessionAgent?: string;
+  /** Skip history loading when the caller has just created this Chat. */
+  skipInitialMessages?: boolean;
+  /** Host projection used only until the selected Session sends its first state. */
+  initialTurnActive?: boolean;
 };
 
 export type ChatConnectionOptions = SharedChatConnectionOptions & (
@@ -140,6 +189,57 @@ export type ChatConnectionOptions = SharedChatConnectionOptions & (
   | { inboxName?: never; basePath?: string }
 );
 
+type SessionAgentConnection = ReturnType<typeof useAgent<RuntimeState>>;
+type UniversalAgentChatContextValue = {
+  chatId: string;
+  connection: ChatConnectionOptions;
+  agent: SessionAgentConnection;
+  chatAgent: 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 }),
+    ...(connection.onMessage === undefined ? {} : { onMessage: connection.onMessage }),
+    connectionTimeout: 6_000,
+    sub: [{
+      agent: connection.sessionAgent ?? "UniversalAgent",
+      name: chatId,
+    }],
+  });
+  const chatAgent = useMemo(
+    () => createSafeUIMessageAgentConnection(agent),
+    [agent],
+  );
+  const value = useMemo(
+    () => ({ chatId, connection, agent, chatAgent }),
+    [agent, chatAgent, chatId, connection],
+  );
+  return createElement(
+    UniversalAgentChatContext.Provider,
+    { value },
+    createElement(Suspense, { fallback }, children),
+  );
+}
+
 type ChatTurnTiming = {
   chatId: string;
   messageId: string;
@@ -195,10 +295,18 @@ function markChatTurnPhase(
 function createChatMessage(
   text: string,
   files?: readonly FileUIPart[],
+  capabilities: readonly RequestedCapability[] = [],
 ): ChatMessage | null {
   const normalizedText = text.trim();
   if (!normalizedText && !files?.length) return null;
   const createdAt = Date.now();
+  const seen = new Set<string>();
+  const requestedCapabilities = capabilities.filter((capability) => {
+    const key = `${capability.kind}:${capability.name}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
   return {
     id: nanoid(),
     role: "user",
@@ -212,6 +320,7 @@ function createChatMessage(
       createdAt,
       authorDisplayName: "You",
       messageSource: "Web",
+      ...(requestedCapabilities.length > 0 ? { requestedCapabilities } : {}),
     },
   };
 }
@@ -258,10 +367,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, chatAgent } = context;
   const [optimisticMessages, setOptimisticMessages] =
     useState<ChatMessage[]>([]);
   const [optimisticQueued, setOptimisticQueued] =
@@ -270,24 +381,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],
-  );
-
   // 轮询→推送:这条 chat 连接连的是 UniversalAgent facet,`agent.state` 即 facet 的
   // AgentState 广播(useAgent 内部 useState,收到 cf_agent_state 即 re-render)。待批项
   // 随它推来 —— 审批读侧复用这条已开的连接,不另开第二条 WebSocket。三态(原则 VII):
@@ -303,22 +396,27 @@ export function useUniversalAgentChat(
     isStreaming,
     error,
     clearError,
+    stop: stopChat,
     // autonomous responses 纪律(CF 文档采纳 2026-07-05):框架已提供三个流态标志,
     // 透出供 UI 区分「服务端主动流 vs 用户发起流」+「恢复态」(与 stall 看门狗配套)。
     isServerStreaming,
-    isRecovering,
+    isRecovering: sdkIsRecovering,
     isToolContinuation,
-    connectionError,
+    connectionError: sdkConnectionError,
   } = useAgentChat<RuntimeState, ChatMessage>({
     agent: chatAgent,
-    getInitialMessages: ({ url }) =>
-      loadInitialMessages(url, connection.credentials),
+    getInitialMessages: connection.skipInitialMessages
+      ? null
+      : ({ url }) => loadInitialMessages(url, connection.credentials),
     ...(connection.credentials === undefined
       ? {}
       : { credentials: connection.credentials }),
     syncMessagesToServer: false,
     throttle: 100,
   });
+  // The SDK keeps its advisory recovery flag until terminal settlement; a
+  // live server stream proves the recovered Turn is executing again.
+  const isRecovering = sdkIsRecovering && !isServerStreaming;
   const visibleMessages = useMemo(
     () => mergeOptimisticMessages(messages, optimisticMessages),
     [messages, optimisticMessages],
@@ -338,6 +436,18 @@ export function useUniversalAgentChat(
     ? "ready"
     : sdkStatus;
   const sdkError = stoppedByUser || hasTerminalMessage ? undefined : error;
+  const connectionError = sdkConnectionError ?? undefined;
+  const connectionStatus: ChatConnectionStatus = connectionError
+    ? connectionError.code === 1008 ? "rejected" : "error"
+    : agent.identified ? "connected" : "connecting";
+  const runtimeError = dispatchError ?? sdkError ?? connectionError;
+  const runtimeErrorMessage = runtimeError instanceof Error
+    ? runtimeError.message
+    : runtimeError;
+  const presentationError = latestTurnStatus === "error" &&
+      latestMessage?.metadata?.error === runtimeErrorMessage
+    ? undefined
+    : runtimeError;
   // RPC admissions bypass useChat's request lifecycle. Project the durable
   // Turn here so presentation stays correct without a second send path.
   const authoritativeStatus =
@@ -349,9 +459,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);
@@ -443,7 +556,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 &&
@@ -462,11 +576,25 @@ export function useUniversalAgentChat(
   const dispatchMessage = useCallback(async (
     message: ChatMessage,
     delivery: MessageDelivery,
-  ): Promise<MessageDispatchReceipt> =>
-    agentRef.current.call<MessageDispatchReceipt>(
+  ): Promise<MessageDispatchReceipt> => {
+    const dispatch = () => agentRef.current.call<MessageDispatchReceipt>(
       "dispatchMessage",
       [message, delivery],
-    ), []);
+    );
+    try {
+      return await dispatch();
+    } catch (error) {
+      // The server deduplicates dispatches by message.id, so replay only the
+      // transport failures that mean admission may already have succeeded.
+      const retryable = error instanceof Error && (
+        /^RPC call to dispatchMessage timed out after \d+ms$/u.test(error.message) ||
+        (error.message === "Connection closed" && agentRef.current.shouldReconnect)
+      );
+      if (!retryable) throw error;
+      await agentRef.current.ready;
+      return dispatch();
+    }
+  }, []);
 
   const submitMessage = useCallback(async (
     message: ChatMessage,
@@ -572,8 +700,9 @@ export function useUniversalAgentChat(
   const sendText = useCallback(async (
     text: string,
     files?: readonly FileUIPart[],
+    capabilities?: readonly RequestedCapability[],
   ): Promise<boolean> => {
-    const message = createChatMessage(text, files);
+    const message = createChatMessage(text, files, capabilities);
     return message
       ? submitMessage(message, "enqueue", "message")
       : false;
@@ -582,21 +711,28 @@ export function useUniversalAgentChat(
   const dispatchText = useCallback(async (
     text: string,
     files: readonly FileUIPart[] | undefined,
+    capabilities: readonly RequestedCapability[] | undefined,
     delivery: MessageDelivery,
     projection: "message" | "queue",
   ): Promise<boolean> => {
-    const message = createChatMessage(text, files);
+    const message = createChatMessage(text, files, capabilities);
     return message ? submitMessage(message, delivery, projection) : false;
   }, [submitMessage]);
 
   const steerText = useCallback(
-    (text: string, files?: readonly FileUIPart[]) =>
-      dispatchText(text, files, "steer", "message"),
+    (
+      text: string,
+      files?: readonly FileUIPart[],
+      capabilities?: readonly RequestedCapability[],
+    ) => dispatchText(text, files, capabilities, "steer", "message"),
     [dispatchText],
   );
   const enqueueText = useCallback(
-    (text: string, files?: readonly FileUIPart[]) =>
-      dispatchText(text, files, "enqueue", "queue"),
+    (
+      text: string,
+      files?: readonly FileUIPart[],
+      capabilities?: readonly RequestedCapability[],
+    ) => dispatchText(text, files, capabilities, "enqueue", "queue"),
     [dispatchText],
   );
   const steerQueued = useCallback(async (submissionId: string) => {
@@ -657,18 +793,18 @@ export function useUniversalAgentChat(
           type: MessageType.CF_AGENT_CHAT_REQUEST_CANCEL,
           id: requestId,
         }));
+        await stopChat();
         return;
       }
-      const result = submissionId
-        ? await agentRef.current.call<{ ok: boolean }>(
+      await (submissionId
+        ? agentRef.current.call<{ ok: boolean }>(
           "cancelSubmissionById",
           [submissionId, USER_STOP_REASON],
         )
-        : await agentRef.current.call<{ ok: boolean }>(
+        : agentRef.current.call<{ ok: boolean }>(
           "stopTurn",
           [undefined, USER_STOP_REASON],
-        );
-      if (!result.ok) setDispatchError("The active Turn could not be stopped");
+        ));
     } catch (cause) {
       setDispatchError(
         cause instanceof Error ? cause.message : String(cause),
@@ -677,6 +813,7 @@ export function useUniversalAgentChat(
   }, [
     authoritativeTurn?.activeRequestId,
     authoritativeTurn?.activeSubmissionId,
+    stopChat,
   ]);
 
   const retry = useCallback(() => {
@@ -705,6 +842,14 @@ export function useUniversalAgentChat(
       return false;
     }
   }, []);
+  const decideApproval = useCallback(
+    (executionId: string, decision: ApprovalDecision) =>
+      agentRef.current.call<{ ok: boolean }>(
+        "decideApproval",
+        [executionId, decision],
+      ),
+    [],
+  );
 
   // 只读控制面：Runtime 尚未装配时由 Agent 侧 `ensureRuntimeReady` 负责等待，
   // 这里不缓存结果 —— 换模型、加技能或 reload 之后调用方要拿到的是新装配。
@@ -712,6 +857,24 @@ export function useUniversalAgentChat(
     () => agentRef.current.call<RuntimeAssemblyView>("getRuntimeAssembly", []),
     [],
   );
+  const getRuntimeBinding = useCallback(
+    <Binding,>() => agentRef.current.call<Binding>("getRuntimeBinding", []),
+    [],
+  );
+  const readChatMetadata = useCallback(
+    <Metadata,>() => agentRef.current.call<Metadata>("readChatMetadata", []),
+    [],
+  );
+  const renameChat = useCallback(
+    <Metadata,>(title: string) =>
+      agentRef.current.call<Metadata>("renameChat", [title]),
+    [],
+  );
+  const rebindRuntime = useCallback(
+    <Input, Result,>(input: Input) =>
+      agentRef.current.call<Result>("rebindRuntime", [input]),
+    [],
+  );
   const updateConfig = useCallback(
     <Change,>(command: unknown) =>
       agentRef.current.call<RuntimeConfigUpdateResult<Change>>(
@@ -730,15 +893,21 @@ export function useUniversalAgentChat(
 
   return {
     respondToolInteraction,
+    decideApproval,
     getRuntimeAssembly,
+    getRuntimeBinding,
+    readChatMetadata,
+    renameChat,
+    rebindRuntime,
     updateConfig,
     reloadRuntime,
     messages: visibleMessages,
     status,
+    connectionStatus,
+    connectionError,
     runtimeLoad: facetState?.runtimeLoad,
     isStreaming,
-    error: dispatchError ?? sdkError ??
-      connectionError ?? undefined,
+    error: presentationError,
     sendText,
     steerText,
     enqueueText,