@springbrand/chat-client 0.1.3-alpha.1 → 0.1.3-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/chat-client",
-  "version": "0.1.3-alpha.1",
+  "version": "0.1.3-alpha.11",
   "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.2"
+    "@springbrand/agent-runtime": "0.2.0-alpha.19"
   },
   "scripts": {
     "typecheck": "tsc --noEmit"

package/src/chat-sessions.ts

@@ -88,18 +88,6 @@ export function useChatSessions<Session>(options: ChatSessionsOptions = {}) {
     await inbox.call("archiveChat", [id, archived]);
   }, [inbox]);
 
-  const reloadChatRuntime = useCallback(
-    async (chatId: string, userAgentId: string) => {
-      const result = await inbox.call<{ userAgentId: string } | null>(
-        "chatReloadRuntime",
-        [chatId, userAgentId],
-      );
-      if (!result) throw new Error("Session is unavailable");
-      return result;
-    },
-    [inbox],
-  );
-
   return {
     chats: inbox.state?.chats ?? snapshot ?? [],
     synced: inbox.state !== undefined || snapshot !== undefined,
@@ -111,7 +99,6 @@ export function useChatSessions<Session>(options: ChatSessionsOptions = {}) {
     deleteChat,
     pinChat,
     archiveChat,
-    reloadChatRuntime,
   };
 }
 

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

@@ -8,6 +8,9 @@ import { useAgent, useAgentToolEvents } from "agents/react";
 import {
   type MessageDelivery,
   type MessageDispatchReceipt,
+  type RequestedCapability,
+  type RuntimeAssemblyView,
+  type RuntimeConfigUpdateResult,
   type RuntimeQueuedSubmission,
   type RuntimeState,
 } from "@springbrand/agent-runtime/contracts";
@@ -15,6 +18,8 @@ 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[];
   turnStatus?: string;
 };
 type ChatMessage = UIMessage<ChatMessageMetadata>;
@@ -28,7 +33,7 @@ type ChatRuntimeLoadState =
   | { status: "idle"; available: false }
   | {
       status: "loading";
-      phase: "config" | "plugins" | "mcp" | "pi";
+      phase: "config" | "assembly" | "mcp" | "pi";
       available: boolean;
       startedAt: number;
       updatedAt: number;
@@ -41,7 +46,7 @@ type ChatRuntimeLoadState =
     }
   | {
       status: "error";
-      phase: "config" | "plugins" | "mcp" | "pi";
+      phase: "config" | "assembly" | "mcp" | "pi";
       available: boolean;
       startedAt: number;
       failedAt: number;
@@ -83,12 +88,47 @@ export interface ChatRuntime {
   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>;
+  /**
+   * 把用户对某张交互卡片的操作回写成那次工具调用的结果。
+   *
+   * 走的是这条已开的 WS 连接（`agent.call`），不是 HTTP —— ack 与随后流下来的
+   * `tool-output-available` chunk 同序到达，UI 状态不会倒挂。
+   */
+  respondToolInteraction: (
+    toolCallId: string,
+    response: unknown,
+  ) => Promise<boolean>;
+  /**
+   * 读取该 Session facet 当前真正装配出来的 Runtime。
+   *
+   * 复用这条已开的 WS 连接，调用方不必为一个只读控制面方法另建 `useAgent`。
+   *
+   * 与其它动作不同，失败会原样抛出：这是读取而不是提交，调用方需要知道是
+   * 装配未就绪还是连接断了，收敛成 `undefined` 会让调试面板无从显示原因。
+   */
+  getRuntimeAssembly: () => Promise<RuntimeAssemblyView>;
+  updateConfig: <Change = unknown>(
+    command: unknown,
+  ) => Promise<RuntimeConfigUpdateResult<Change>>;
+  reloadRuntime: () => Promise<void>;
   regenerate: () => void;
   canRetry: boolean;
   agentToolRuns: AgentToolRunState<ChatMessage["parts"][number]>[];
@@ -170,10 +210,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",
@@ -187,6 +235,7 @@ function createChatMessage(
       createdAt,
       authorDisplayName: "You",
       messageSource: "Web",
+      ...(requestedCapabilities.length > 0 ? { requestedCapabilities } : {}),
     },
   };
 }
@@ -281,7 +330,7 @@ export function useUniversalAgentChat(
     // autonomous responses 纪律(CF 文档采纳 2026-07-05):框架已提供三个流态标志,
     // 透出供 UI 区分「服务端主动流 vs 用户发起流」+「恢复态」(与 stall 看门狗配套)。
     isServerStreaming,
-    isRecovering,
+    isRecovering: sdkIsRecovering,
     isToolContinuation,
     connectionError,
   } = useAgentChat<RuntimeState, ChatMessage>({
@@ -294,6 +343,9 @@ export function useUniversalAgentChat(
     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],
@@ -313,6 +365,14 @@ export function useUniversalAgentChat(
     ? "ready"
     : sdkStatus;
   const sdkError = stoppedByUser || hasTerminalMessage ? undefined : error;
+  const runtimeError = dispatchError ?? sdkError ?? connectionError ?? undefined;
+  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 =
@@ -547,8 +607,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;
@@ -557,21 +618,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) => {
@@ -664,13 +732,55 @@ export function useUniversalAgentChat(
     );
   }, [submitMessage]);
 
+  // 交互卡片的写回口。失败只返回 false —— 调用方（块组件）自己决定怎么提示；
+  // 权威状态永远来自 part 的 state，不来自这里的返回值。
+  const respondToolInteraction = useCallback(async (
+    toolCallId: string,
+    response: unknown,
+  ): Promise<boolean> => {
+    try {
+      const receipt = await agentRef.current.call<{ ok: boolean }>(
+        "respondToolInteraction",
+        [toolCallId, response],
+      );
+      return receipt.ok;
+    } catch {
+      return false;
+    }
+  }, []);
+
+  // 只读控制面：Runtime 尚未装配时由 Agent 侧 `ensureRuntimeReady` 负责等待，
+  // 这里不缓存结果 —— 换模型、加技能或 reload 之后调用方要拿到的是新装配。
+  const getRuntimeAssembly = useCallback(
+    () => agentRef.current.call<RuntimeAssemblyView>("getRuntimeAssembly", []),
+    [],
+  );
+  const updateConfig = useCallback(
+    <Change,>(command: unknown) =>
+      agentRef.current.call<RuntimeConfigUpdateResult<Change>>(
+        "updateConfig",
+        [command],
+      ),
+    [],
+  );
+  const reloadRuntime = useCallback(
+    () => agentRef.current.call<void>(
+      "reloadRuntime",
+      [undefined, { force: true }],
+    ),
+    [],
+  );
+
   return {
+    respondToolInteraction,
+    getRuntimeAssembly,
+    updateConfig,
+    reloadRuntime,
     messages: visibleMessages,
     status,
     runtimeLoad: facetState?.runtimeLoad,
     isStreaming,
-    error: dispatchError ?? sdkError ??
-      connectionError ?? undefined,
+    error: presentationError,
     sendText,
     steerText,
     enqueueText,