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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/chat-client",
-  "version": "0.1.3-alpha.0",
+  "version": "0.1.3-alpha.1",
   "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.1.3-alpha.1"
+    "@springbrand/agent-runtime": "0.1.3-alpha.2"
   },
   "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],
   );
 
@@ -127,4 +115,6 @@ export function useChatSessions() {
   };
 }
 
-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,6 +2,7 @@ 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 {
@@ -67,6 +68,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[];
@@ -100,6 +105,7 @@ export interface ChatRuntime {
 type SharedChatConnectionOptions = {
   host?: string;
   credentials?: RequestCredentials;
+  protocols?: string | string[];
   inboxAgent?: string;
   sessionAgent?: string;
 };
@@ -246,6 +252,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,6 +277,7 @@ export function useUniversalAgentChat(
     status: sdkStatus,
     isStreaming,
     error,
+    clearError,
     // autonomous responses 纪律(CF 文档采纳 2026-07-05):框架已提供三个流态标志,
     // 透出供 UI 区分「服务端主动流 vs 用户发起流」+「恢复态」(与 stall 看门狗配套)。
     isServerStreaming,
@@ -292,9 +300,19 @@ export function useUniversalAgentChat(
   );
   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 +410,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 +449,7 @@ export function useUniversalAgentChat(
     projection: "message" | "queue",
   ): Promise<boolean> => {
     setDispatchError(undefined);
+    clearError();
     failedDispatchRef.current = undefined;
     setCanRetry(false);
     if (projection === "message" && delivery === "enqueue") {
@@ -441,6 +465,7 @@ export function useUniversalAgentChat(
       };
     }
     if (projection === "message") {
+      activeSubmissionIdRef.current = undefined;
       setOptimisticMessages((current) =>
         current.some(({ id }) => id === message.id)
           ? current
@@ -517,7 +542,7 @@ export function useUniversalAgentChat(
       );
       return false;
     }
-  }, [chatId, dispatchMessage]);
+  }, [chatId, clearError, dispatchMessage]);
 
   const sendText = useCallback(async (
     text: string,
@@ -597,22 +622,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;
@@ -629,7 +669,7 @@ export function useUniversalAgentChat(
     status,
     runtimeLoad: facetState?.runtimeLoad,
     isStreaming,
-    error: dispatchError ?? (stoppedByUser ? undefined : error) ??
+    error: dispatchError ?? sdkError ??
       connectionError ?? undefined,
     sendText,
     steerText,