@springbrand/chat-client 0.1.3-alpha.0 → 0.1.3-alpha.10

package/package.json

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

package/src/chat-sessions.ts

@@ -1,35 +1,22 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useAgent } from "agents/react";
 
-export interface ChatSessionSummary {
-  id: string;
-  userAgentId: string;
-  title: string;
-  titleSource: "default" | "generated" | "manual";
-  createdAt: number;
-  updatedAt: number;
-  pinned: boolean;
-  archived: boolean;
-  activity: "idle" | "working" | "needs-input";
-  usage?: {
-    totalTokens: number;
-    totalCost: number;
-  };
-}
-
-interface InboxState {
-  chats: ChatSessionSummary[];
+interface InboxState<Session> {
+  chats: Session[];
   workspaceRev?: number;
 }
 
 export const CURRENT_INBOX_AGENT_PATH = "api/agent-connections/inbox";
 
 type Request = typeof fetch;
+export type ChatSessionsOptions = {
+  protocols?: string | string[];
+};
 
-export async function loadChatSessions(
+export async function loadChatSessions<Session>(
   signal?: AbortSignal,
   request: Request = fetch,
-): Promise<ChatSessionSummary[]> {
+): Promise<Session[]> {
   const response = await request("/api/chats", {
     cache: "no-store",
     headers: { Accept: "application/json" },
@@ -42,21 +29,22 @@ export async function loadChatSessions(
   if (!Array.isArray(body?.chats)) {
     throw new Error("Invalid chat sessions response");
   }
-  return body.chats as ChatSessionSummary[];
+  return body.chats as Session[];
 }
 
 /** Browser client for the user Inbox. Routing and presentation stay with the host UI. */
-export function useChatSessions() {
-  const inbox = useAgent<InboxState>({
+export function useChatSessions<Session>(options: ChatSessionsOptions = {}) {
+  const inbox = useAgent<InboxState<Session>>({
     agent: "Inbox",
     basePath: CURRENT_INBOX_AGENT_PATH,
+    ...(options.protocols === undefined ? {} : { protocols: options.protocols }),
   });
-  const [snapshot, setSnapshot] = useState<ChatSessionSummary[]>();
+  const [snapshot, setSnapshot] = useState<Session[]>();
   const creatingRef = useRef(false);
 
   useEffect(() => {
     const controller = new AbortController();
-    void loadChatSessions(controller.signal)
+    void loadChatSessions<Session>(controller.signal)
       .then(setSnapshot)
       .catch(() => undefined); // WebSocket state remains the fallback.
     return () => controller.abort();
@@ -67,7 +55,7 @@ export function useChatSessions() {
     creatingRef.current = true;
     try {
       await inbox.ready;
-      return await inbox.call<ChatSessionSummary>(
+      return await inbox.call<Session>(
         "createChat",
         userAgentId ? [{ userAgentId }] : undefined,
       );
@@ -78,7 +66,7 @@ export function useChatSessions() {
 
   const forkChat = useCallback(
     (sourceChatId: string, messageId: string) =>
-      inbox.call<ChatSessionSummary>("forkChat", [sourceChatId, messageId]),
+      inbox.call<Session>("forkChat", [sourceChatId, messageId]),
     [inbox],
   );
 
@@ -100,18 +88,6 @@ export function useChatSessions() {
     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,
@@ -123,8 +99,9 @@ export function useChatSessions() {
     deleteChat,
     pinChat,
     archiveChat,
-    reloadChatRuntime,
   };
 }
 
-export type ChatSessions = ReturnType<typeof useChatSessions>;
+export type ChatSessions<Session> = ReturnType<
+  typeof useChatSessions<Session>
+>;

package/src/index.ts

@@ -19,6 +19,6 @@ export {
 } from "./chat-summary";
 export {
   useChatSessions,
-  type ChatSessionSummary,
+  type ChatSessionsOptions,
   type ChatSessions,
 } from "./chat-sessions";

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

@@ -2,11 +2,15 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { nanoid } from "nanoid";
 import type { ChatStatus, FileUIPart, UIMessage } from "ai";
 import type { AgentToolRunState } from "agents";
+import { MessageType } from "agents/chat";
 import { getAgentMessages, useAgentChat } from "agents/chat/react";
 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";
@@ -14,6 +18,7 @@ import { createSafeUIMessageAgentConnection } from "./ui-message-stream-guard";
 import { CURRENT_INBOX_AGENT_PATH } from "./chat-sessions";
 
 type ChatMessageMetadata = Record<string, unknown> & {
+  requestedCapabilities?: readonly RequestedCapability[];
   turnStatus?: string;
 };
 type ChatMessage = UIMessage<ChatMessageMetadata>;
@@ -27,7 +32,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;
@@ -40,7 +45,7 @@ type ChatRuntimeLoadState =
     }
   | {
       status: "error";
-      phase: "config" | "plugins" | "mcp" | "pi";
+      phase: "config" | "assembly" | "mcp" | "pi";
       available: boolean;
       startedAt: number;
       failedAt: number;
@@ -67,6 +72,10 @@ type ChatQueuedSubmission = {
 
 type ChatTurn = {
   activeSubmissionId?: string;
+  activeRequestId?: string;
+  recoveryAttempt?: number;
+  recoveryMax?: number;
+  recoveryReason?: "no_meaningful_model_progress" | "transient_model_error";
   steerable: boolean;
   hasPendingSteer: boolean;
   queued: ChatQueuedSubmission[];
@@ -78,12 +87,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]>[];
@@ -100,6 +144,7 @@ export interface ChatRuntime {
 type SharedChatConnectionOptions = {
   host?: string;
   credentials?: RequestCredentials;
+  protocols?: string | string[];
   inboxAgent?: string;
   sessionAgent?: string;
 };
@@ -164,10 +209,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",
@@ -181,6 +234,7 @@ function createChatMessage(
       createdAt,
       authorDisplayName: "You",
       messageSource: "Web",
+      ...(requestedCapabilities.length > 0 ? { requestedCapabilities } : {}),
     },
   };
 }
@@ -246,6 +300,7 @@ export function useUniversalAgentChat(
       ? { 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,
@@ -270,10 +325,11 @@ export function useUniversalAgentChat(
     status: sdkStatus,
     isStreaming,
     error,
+    clearError,
     // autonomous responses 纪律(CF 文档采纳 2026-07-05):框架已提供三个流态标志,
     // 透出供 UI 区分「服务端主动流 vs 用户发起流」+「恢复态」(与 stall 看门狗配套)。
     isServerStreaming,
-    isRecovering,
+    isRecovering: sdkIsRecovering,
     isToolContinuation,
     connectionError,
   } = useAgentChat<RuntimeState, ChatMessage>({
@@ -286,15 +342,28 @@ 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],
   );
   const authoritativeTurn = facetState?.turn;
   const stoppedByUser = error?.message === USER_STOP_REASON;
-  const normalizedSdkStatus = stoppedByUser && sdkStatus === "error"
+  const latestMessage = visibleMessages.at(-1);
+  const latestTurnStatus = latestMessage?.role === "assistant"
+    ? latestMessage.metadata?.turnStatus
+    : undefined;
+  const hasTerminalMessage = latestTurnStatus === "completed" ||
+    latestTurnStatus === "error" ||
+    latestTurnStatus === "aborted" ||
+    latestTurnStatus === "skipped";
+  const normalizedSdkStatus = sdkStatus === "error" &&
+      (stoppedByUser || hasTerminalMessage)
     ? "ready"
     : sdkStatus;
+  const sdkError = stoppedByUser || hasTerminalMessage ? undefined : error;
   // RPC admissions bypass useChat's request lifecycle. Project the durable
   // Turn here so presentation stays correct without a second send path.
   const authoritativeStatus =
@@ -392,12 +461,17 @@ export function useUniversalAgentChat(
       queued,
     };
   }, [authoritativeTurn, visibleMessages, optimisticQueued]);
-  const turnActive = Boolean(turn?.activeSubmissionId) ||
+  const sdkTurnActive =
     status === "submitted" ||
     status === "streaming" ||
     isServerStreaming ||
     isRecovering ||
     isToolContinuation;
+  const pendingLocalTurn = optimisticMessages.length > 0 &&
+    (status === "submitted" || status === "streaming");
+  const turnActive = Boolean(turn?.activeSubmissionId) ||
+    pendingLocalTurn ||
+    (authoritativeTurn === undefined && sdkTurnActive);
   const canSteer = turnActive &&
     (!turn?.activeSubmissionId || turn.steerable);
 
@@ -426,6 +500,7 @@ export function useUniversalAgentChat(
     projection: "message" | "queue",
   ): Promise<boolean> => {
     setDispatchError(undefined);
+    clearError();
     failedDispatchRef.current = undefined;
     setCanRetry(false);
     if (projection === "message" && delivery === "enqueue") {
@@ -441,6 +516,7 @@ export function useUniversalAgentChat(
       };
     }
     if (projection === "message") {
+      activeSubmissionIdRef.current = undefined;
       setOptimisticMessages((current) =>
         current.some(({ id }) => id === message.id)
           ? current
@@ -517,13 +593,14 @@ export function useUniversalAgentChat(
       );
       return false;
     }
-  }, [chatId, dispatchMessage]);
+  }, [chatId, clearError, dispatchMessage]);
 
   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;
@@ -532,21 +609,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) => {
@@ -597,22 +681,37 @@ export function useUniversalAgentChat(
   }, []);
 
   const stop = useCallback(async () => {
+    const requestId = authoritativeTurn?.activeRequestId;
     const submissionId = authoritativeTurn?.activeSubmissionId ??
       activeSubmissionIdRef.current;
-    if (!submissionId) return;
     setDispatchError(undefined);
     try {
-      const result = await agentRef.current.call<{ ok: boolean }>(
-        "cancelSubmissionById",
-        [submissionId, USER_STOP_REASON],
-      );
+      if (requestId) {
+        agentRef.current.send(JSON.stringify({
+          type: MessageType.CF_AGENT_CHAT_REQUEST_CANCEL,
+          id: requestId,
+        }));
+        return;
+      }
+      const result = submissionId
+        ? await agentRef.current.call<{ ok: boolean }>(
+          "cancelSubmissionById",
+          [submissionId, USER_STOP_REASON],
+        )
+        : await 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),
       );
     }
-  }, [authoritativeTurn?.activeSubmissionId]);
+  }, [
+    authoritativeTurn?.activeRequestId,
+    authoritativeTurn?.activeSubmissionId,
+  ]);
 
   const retry = useCallback(() => {
     const failed = failedDispatchRef.current;
@@ -624,12 +723,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 ?? (stoppedByUser ? undefined : error) ??
+    error: dispatchError ?? sdkError ??
       connectionError ?? undefined,
     sendText,
     steerText,