@springbrand/chat-client 0.1.3-alpha.8 → 0.3.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/chat-client",
-  "version": "0.1.3-alpha.8",
+  "version": "0.3.0-alpha.1",
   "type": "module",
   "files": [
     "src",
@@ -13,7 +13,8 @@
     ".": "./src/index.ts"
   },
   "peerDependencies": {
-    "agents": "^0.20.1",
+    "@cloudflare/ai-chat": "^0.11.0",
+    "agents": "^0.22.0",
     "ai": "^7.0.0",
     "react": "^19.0.0"
   },
@@ -21,11 +22,12 @@
     "nanoid": "^5.1.16"
   },
   "devDependencies": {
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "react-dom": "^19.2.7",
+    "@cloudflare/ai-chat": "0.11.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "react-dom": "^19.2.8",
     "typescript": "^7.0.2",
-    "@springbrand/agent-runtime": "0.1.3-alpha.11"
+    "@springbrand/agent-runtime": "0.3.0-alpha.1"
   },
   "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,11 +1,24 @@
-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 { getAgentMessages, useAgentChat } from "@cloudflare/ai-chat/react";
 import { useAgent, useAgentToolEvents } from "agents/react";
 import {
+  type ApprovalDecision,
   type MessageDelivery,
   type MessageDispatchReceipt,
   type RequestedCapability,
@@ -13,15 +26,32 @@ import {
   type RuntimeConfigUpdateResult,
   type RuntimeQueuedSubmission,
   type RuntimeState,
+  type RuntimeTurnState,
 } from "@springbrand/agent-runtime/contracts";
 import { createSafeUIMessageAgentConnection } from "./ui-message-stream-guard";
 import { CURRENT_INBOX_AGENT_PATH } from "./chat-sessions";
 
 type ChatMessageMetadata = Record<string, unknown> & {
+  completedAt?: number;
+  error?: string;
+  interruptedByUser?: boolean;
+  // AI SDK keeps one assistant UIMessage for the live stream. This anchor is
+  // persisted in the user sidecar so live and hydrated presentation agree.
+  optimisticSteer?: {
+    assistantMessageId: string;
+    afterStep: number;
+  };
   requestedCapabilities?: readonly RequestedCapability[];
+  turnId?: string;
+  userMessageId?: string;
   turnStatus?: string;
 };
 type ChatMessage = UIMessage<ChatMessageMetadata>;
+export type ChatConnectionStatus =
+  | "connecting"
+  | "connected"
+  | "rejected"
+  | "error";
 type FailedDispatch = {
   message: ChatMessage;
   delivery: MessageDelivery;
@@ -62,35 +92,20 @@ type ChatApproval = {
   requestId: string;
 };
 
-type ChatQueuedSubmission = {
-  submissionId: string;
-  messageId: string;
-  preview: string;
-  position: number;
-  createdAt: number;
-};
-
-type ChatTurn = {
-  activeSubmissionId?: string;
-  activeRequestId?: string;
-  recoveryAttempt?: number;
-  recoveryMax?: number;
-  recoveryReason?: "no_meaningful_model_progress" | "transient_model_error";
-  steerable: boolean;
-  hasPendingSteer: boolean;
-  queued: ChatQueuedSubmission[];
-};
-
 export interface ChatRuntime {
   messages: ChatMessage[];
   status: ChatStatus;
+  connectionStatus: ChatConnectionStatus;
+  connectionError: AgentConnectionError | undefined;
   runtimeLoad: ChatRuntimeLoadState | undefined;
   isStreaming: boolean;
   error: string | Error | undefined;
+  /** Reusing messageId makes delivery idempotent across caller retries. */
   sendText: (
     text: string,
     files?: readonly FileUIPart[],
     capabilities?: readonly RequestedCapability[],
+    messageId?: string,
   ) => Promise<boolean>;
   steerText: (
     text: string,
@@ -115,6 +130,10 @@ export interface ChatRuntime {
     toolCallId: string,
     response: unknown,
   ) => Promise<boolean>;
+  decideApproval: (
+    executionId: string,
+    decision: ApprovalDecision,
+  ) => Promise<{ ok: boolean }>;
   /**
    * 读取该 Session facet 当前真正装配出来的 Runtime。
    *
@@ -124,6 +143,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>>;
@@ -136,7 +159,7 @@ export interface ChatRuntime {
   isToolContinuation: boolean;
   approvals: ChatApproval[] | undefined;
   approvalsLoaded: boolean;
-  turn: ChatTurn | undefined;
+  turn: RuntimeTurnState | undefined;
   turnActive: boolean;
   canSteer: boolean;
 }
@@ -145,8 +168,15 @@ 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;
+  /** Optional Agent RPC method injected by the Host to receive Turn timings. */
+  performanceRpc?: string;
 };
 
 export type ChatConnectionOptions = SharedChatConnectionOptions & (
@@ -154,9 +184,61 @@ 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;
+  submissionId?: string;
   baselineAssistantIds: Set<string>;
   click: number;
   rpcReceipt?: number;
@@ -165,6 +247,37 @@ type ChatTurnTiming = {
   ready?: number;
 };
 
+type ClientPerformanceMetrics = {
+  clickToRpcMs: number;
+  rpcToStreamMs: number;
+  streamToFirstTextMs?: number;
+  firstTextToReadyMs?: number;
+  ttftMs?: number;
+  totalMs: number;
+};
+
+export function clientPerformanceMetrics(
+  timing: ChatTurnTiming,
+): ClientPerformanceMetrics | null {
+  if (
+    timing.rpcReceipt === undefined ||
+    timing.streamStart === undefined ||
+    timing.ready === undefined
+  ) return null;
+  return {
+    clickToRpcMs: timing.rpcReceipt - timing.click,
+    rpcToStreamMs: timing.streamStart - timing.rpcReceipt,
+    ...(timing.firstText === undefined
+      ? {}
+      : {
+          streamToFirstTextMs: timing.firstText - timing.streamStart,
+          firstTextToReadyMs: timing.ready - timing.firstText,
+          ttftMs: timing.firstText - timing.click,
+        }),
+    totalMs: timing.ready - timing.click,
+  };
+}
+
 const CHAT_TURN_SEGMENTS = {
   rpcReceipt: ["click", "universal-agent.chat.click_to_rpc_receipt"],
   streamStart: [
@@ -210,6 +323,7 @@ function createChatMessage(
   text: string,
   files?: readonly FileUIPart[],
   capabilities: readonly RequestedCapability[] = [],
+  messageId?: string,
 ): ChatMessage | null {
   const normalizedText = text.trim();
   if (!normalizedText && !files?.length) return null;
@@ -222,7 +336,7 @@ function createChatMessage(
     return true;
   });
   return {
-    id: nanoid(),
+    id: messageId ?? nanoid(),
     role: "user",
     parts: [
       ...(files ?? []),
@@ -243,10 +357,204 @@ export function mergeOptimisticMessages<T extends UIMessage>(
   messages: T[],
   optimistic: T[],
 ): T[] {
-  if (optimistic.length === 0) return messages;
   const ids = new Set(messages.map(({ id }) => id));
   const pending = optimistic.filter(({ id }) => !ids.has(id));
-  return pending.length === 0 ? messages : [...messages, ...pending];
+  const assistantsByTurn = new Map<string, T[]>();
+  for (const message of messages) {
+    const turnId = (message.metadata as ChatMessageMetadata | undefined)?.turnId;
+    if (message.role !== "assistant" || typeof turnId !== "string") continue;
+    const assistants = assistantsByTurn.get(turnId) ?? [];
+    assistants.push(message);
+    assistantsByTurn.set(turnId, assistants);
+  }
+  const assistantPosition = new Map<string, {
+    assistantMessageId: string;
+    stepOffset: number;
+  }>();
+  for (const assistants of assistantsByTurn.values()) {
+    let stepOffset = 0;
+    for (const assistant of assistants) {
+      assistantPosition.set(assistant.id, {
+        assistantMessageId: assistants[0]!.id,
+        stepOffset,
+      });
+      stepOffset += assistant.parts.filter(
+        ({ type }) => type === "step-start",
+      ).length;
+    }
+  }
+  const normalizeAnchor = (anchor: NonNullable<
+    ChatMessageMetadata["optimisticSteer"]
+  >) => {
+    const position = assistantPosition.get(anchor.assistantMessageId);
+    return position
+      ? {
+          assistantMessageId: position.assistantMessageId,
+          afterStep: position.stepOffset + anchor.afterStep,
+        }
+      : anchor;
+  };
+  const logicalMessages: T[] = [];
+  const logicalAssistantIndex = new Map<string, number>();
+  for (const message of messages) {
+    const turnId = (message.metadata as ChatMessageMetadata | undefined)?.turnId;
+    if (message.role !== "assistant" || typeof turnId !== "string") {
+      logicalMessages.push(message);
+      continue;
+    }
+    const existingIndex = logicalAssistantIndex.get(turnId);
+    if (existingIndex === undefined) {
+      logicalAssistantIndex.set(turnId, logicalMessages.length);
+      logicalMessages.push(message);
+      continue;
+    }
+    const existing = logicalMessages[existingIndex]!;
+    logicalMessages[existingIndex] = {
+      ...existing,
+      parts: [...existing.parts, ...message.parts],
+      metadata: {
+        ...(existing.metadata as Record<string, unknown> | undefined),
+        ...(message.metadata as Record<string, unknown> | undefined),
+      },
+    } as T;
+  }
+  const authoritativeAnchors = messages.flatMap((message, messageIndex) => {
+    const anchor = (message.metadata as ChatMessageMetadata | undefined)
+      ?.optimisticSteer;
+    if (anchor) return [{ message, anchor: normalizeAnchor(anchor) }];
+    if (message.role !== "user") return [];
+    const turnId = (message.metadata as ChatMessageMetadata | undefined)?.turnId;
+    const assistants = typeof turnId === "string"
+      ? assistantsByTurn.get(turnId)
+      : undefined;
+    if (!assistants || assistants.length === 0) return [];
+    const openingMessageId = (assistants[0]!.metadata as
+      | ChatMessageMetadata
+      | undefined)?.userMessageId;
+    if (message.id === openingMessageId) return [];
+    const preceding = messages.slice(0, messageIndex).filter((candidate) =>
+      candidate.role === "assistant" &&
+      (candidate.metadata as ChatMessageMetadata | undefined)?.turnId === turnId
+    );
+    return [{
+      message,
+      anchor: {
+        assistantMessageId: assistants[0]!.id,
+        afterStep: preceding.reduce((total, assistant) =>
+          total + assistant.parts.filter(
+            ({ type }) => type === "step-start",
+          ).length, 0),
+      },
+    }];
+  });
+  const pendingAnchors = pending.flatMap((message) => {
+    const anchor = (message.metadata as ChatMessageMetadata | undefined)
+      ?.optimisticSteer;
+    return anchor ? [{ message, anchor: normalizeAnchor(anchor) }] : [];
+  });
+  const anchoredSteers = [...authoritativeAnchors, ...pendingAnchors];
+  if (pending.length === 0 && anchoredSteers.length === 0) return messages;
+  const anchoredIds = new Set(
+    anchoredSteers.map(({ message }) => message.id),
+  );
+  const pendingById = new Map(
+    pending
+      .filter(({ id }) => !anchoredIds.has(id))
+      .map((message) => [message.id, message]),
+  );
+  const withPrompts = logicalMessages
+    .filter(({ id }) => !anchoredIds.has(id))
+    .flatMap((message) => {
+      const userMessageId = message.role === "assistant"
+        ? (message.metadata as ChatMessageMetadata | undefined)?.userMessageId
+        : undefined;
+      if (typeof userMessageId !== "string") return [message];
+      const prompt = pendingById.get(userMessageId);
+      if (!prompt) return [message];
+      pendingById.delete(userMessageId);
+      return [prompt, message];
+    });
+  const unmatchedPrompts = pending.filter(({ id }) => pendingById.has(id));
+  if (anchoredSteers.length === 0) {
+    return [
+      ...withPrompts,
+      ...unmatchedPrompts,
+    ];
+  }
+  const targetAssistantIds = new Set(
+    anchoredSteers.map(({ anchor }) => anchor.assistantMessageId),
+  );
+  const firstTarget = withPrompts.findIndex(({ id, role }) =>
+    role === "assistant" && targetAssistantIds.has(id)
+  );
+  const base = firstTarget < 0
+    ? [...withPrompts, ...unmatchedPrompts]
+    : [
+        ...withPrompts.slice(0, firstTarget),
+        ...unmatchedPrompts,
+        ...withPrompts.slice(firstTarget),
+      ];
+  const byAssistant = new Map<string, typeof anchoredSteers>();
+  for (const anchored of anchoredSteers) {
+    const group = byAssistant.get(anchored.anchor.assistantMessageId) ?? [];
+    group.push(anchored);
+    byAssistant.set(anchored.anchor.assistantMessageId, group);
+  }
+  const placed = new Set<string>();
+  const merged = base.flatMap((message) => {
+    if (message.role !== "assistant") return [message];
+    const steers = byAssistant.get(message.id);
+    if (!steers) return [message];
+
+    const projected: T[] = [];
+    const stepStarts = message.parts.flatMap((part, index) =>
+      part.type === "step-start" ? [index] : []
+    );
+    let cursor = 0;
+    let minimumBoundary = 1;
+    for (let index = 0; index < steers.length;) {
+      const boundary = Math.max(
+        minimumBoundary,
+        steers[index]!.anchor.afterStep,
+      );
+      minimumBoundary = boundary;
+      let end = index + 1;
+      while (
+        end < steers.length &&
+        steers[end]!.anchor.afterStep <= boundary
+      ) {
+        end += 1;
+      }
+      const segmentEnd = stepStarts[boundary] ?? message.parts.length;
+      if (segmentEnd > cursor) {
+        projected.push({
+          ...message,
+          id: `${message.id}:segment:${projected.length}`,
+          parts: message.parts.slice(cursor, segmentEnd),
+        });
+      }
+      for (const anchored of steers.slice(index, end)) {
+        projected.push(anchored.message);
+        placed.add(anchored.message.id);
+      }
+      cursor = segmentEnd;
+      index = end;
+    }
+    if (cursor < message.parts.length) {
+      projected.push({
+        ...message,
+        id: `${message.id}:segment:${projected.length}`,
+        parts: message.parts.slice(cursor),
+      });
+    }
+    return projected;
+  });
+  return [
+    ...merged,
+    ...anchoredSteers
+      .filter(({ message }) => !placed.has(message.id))
+      .map(({ message }) => message),
+  ];
 }
 
 function queuedPreview(message: ChatMessage): string {
@@ -260,10 +568,12 @@ function queuedPreview(message: ChatMessage): string {
 function loadInitialMessages(
   url: string | undefined,
   credentials: RequestCredentials | undefined,
+  view: "hydration" | "full" = "hydration",
 ): Promise<ChatMessage[]> {
   if (!url) return Promise.resolve([]);
   const messagesUrl = new URL(url);
   messagesUrl.pathname = `${messagesUrl.pathname.replace(/\/$/, "")}/get-messages`;
+  if (view === "hydration") messagesUrl.searchParams.set("view", "hydration");
   return getAgentMessages({
     url: messagesUrl.toString(),
     ...(credentials === undefined ? {} : { credentials }),
@@ -281,10 +591,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] =
@@ -292,25 +604,7 @@ export function useUniversalAgentChat(
   const [dispatchError, setDispatchError] = useState<string>();
   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],
-  );
-
+  const stopRevisionRef = useRef(0);
   // 轮询→推送:这条 chat 连接连的是 UniversalAgent facet,`agent.state` 即 facet 的
   // AgentState 广播(useAgent 内部 useState,收到 cf_agent_state 即 re-render)。待批项
   // 随它推来 —— 审批读侧复用这条已开的连接,不另开第二条 WebSocket。三态(原则 VII):
@@ -326,27 +620,32 @@ export function useUniversalAgentChat(
     isStreaming,
     error,
     clearError,
+    setMessages,
+    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],
   );
-  const authoritativeTurn = facetState?.turn;
+  const reportedTurn = facetState?.turn;
   const stoppedByUser = error?.message === USER_STOP_REASON;
   const latestMessage = visibleMessages.at(-1);
   const latestTurnStatus = latestMessage?.role === "assistant"
@@ -356,15 +655,40 @@ export function useUniversalAgentChat(
     latestTurnStatus === "error" ||
     latestTurnStatus === "aborted" ||
     latestTurnStatus === "skipped";
+  // Messages and Agent state arrive in separate frames. A terminal message for
+  // the same Submission is newer than a still-active state projection; a
+  // different active ID belongs to the next Turn and must remain live.
+  const authoritativeTurn = reportedTurn &&
+      hasTerminalMessage &&
+      latestMessage?.metadata?.turnId === reportedTurn.activeSubmissionId
+    ? {
+        steerable: false,
+        hasPendingSteer: false,
+        queued: reportedTurn.queued,
+      }
+    : reportedTurn;
   const normalizedSdkStatus = sdkStatus === "error" &&
       (stoppedByUser || hasTerminalMessage)
     ? "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 = isServerStreaming || isRecovering ||
+      (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 =
-    normalizedSdkStatus === "ready" &&
+  const authoritativeStatus = isServerStreaming
+    ? "streaming"
+    : normalizedSdkStatus === "ready" &&
     !isRecovering &&
     approvals?.length === 0 &&
     authoritativeTurn?.activeSubmissionId
@@ -372,13 +696,57 @@ 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);
   messagesRef.current = messages;
+  // SDK callback identities can change without a new recovery request.
+  const replayActionsRef = useRef({ setMessages, clearError });
+  replayActionsRef.current = { setMessages, clearError };
+  useEffect(() => {
+    const activeMessageId = facetState?.turn?.activeMessageId;
+    if (
+      !activeMessageId ||
+      sdkStatus !== "error" ||
+      sdkIsRecovering ||
+      isServerStreaming
+    ) return;
+    const url = chatAgent.getHttpUrl();
+    if (!url) return;
+    const baseline = messagesRef.current;
+    let cancelled = false;
+    void loadInitialMessages(url, connection.credentials, "full")
+      .then((snapshot) => {
+        if (cancelled) return;
+        // The SDK protects its own snapshots while streaming. This HTTP
+        // fallback must also reject a response older than the current store.
+        const actions = replayActionsRef.current;
+        let applied = false;
+        actions.setMessages((current) => {
+          if (current !== baseline) return current;
+          applied = true;
+          return snapshot;
+        });
+        if (applied) actions.clearError();
+      })
+      .catch(() => undefined);
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    chatAgent,
+    connection.credentials,
+    facetState?.turn?.activeMessageId,
+    isServerStreaming,
+    sdkIsRecovering,
+    sdkStatus,
+  ]);
   const turnTimingRef = useRef<ChatTurnTiming | null>(null);
 
   useEffect(() => {
@@ -386,7 +754,8 @@ export function useUniversalAgentChat(
     if (!timing) return;
     const assistant = messages.find((message) =>
       message.role === "assistant" &&
-      !timing.baselineAssistantIds.has(message.id)
+      !timing.baselineAssistantIds.has(message.id) &&
+      (!timing.submissionId || message.metadata?.turnId === timing.submissionId)
     );
     if (assistant) markChatTurnPhase(timing, "streamStart");
     if (
@@ -398,9 +767,18 @@ export function useUniversalAgentChat(
     }
     if (status === "ready" && timing.streamStart !== undefined) {
       if (timing.firstText !== undefined) markChatTurnPhase(timing, "ready");
+      else timing.ready ??= now();
       turnTimingRef.current = null;
+      const metrics = clientPerformanceMetrics(timing);
+      if (connection.performanceRpc && timing.submissionId && metrics) {
+        void agentRef.current.call(connection.performanceRpc, [{
+          submissionId: timing.submissionId,
+          messageId: timing.messageId,
+          ...metrics,
+        }]).catch(() => {});
+      }
     }
-  }, [messages, status]);
+  }, [connection.performanceRpc, messages, status]);
 
   useEffect(() => {
     if (optimisticMessages.length === 0 || messages.length === 0) return;
@@ -466,7 +844,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 &&
@@ -485,17 +864,56 @@ 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,
     delivery: MessageDelivery,
     projection: "message" | "queue",
   ): Promise<boolean> => {
+    if (projection === "message" && delivery === "steer") {
+      const activeSubmissionId = authoritativeTurn?.activeSubmissionId;
+      const activeAssistants = messagesRef.current.filter((candidate) =>
+        candidate.role === "assistant" &&
+        candidate.metadata?.turnId === activeSubmissionId
+      );
+      const assistantMessageId = activeAssistants[0]?.id ??
+        authoritativeTurn?.activeMessageId;
+      if (assistantMessageId) {
+        message = {
+          ...message,
+          metadata: {
+            ...message.metadata,
+            optimisticSteer: {
+              assistantMessageId,
+              afterStep: activeAssistants.reduce((total, assistant) =>
+                total + assistant.parts.filter(
+                  ({ type }) => type === "step-start",
+                ).length, 0),
+            },
+          },
+        };
+      }
+    }
+    const stopRevision = stopRevisionRef.current;
     setDispatchError(undefined);
     clearError();
     failedDispatchRef.current = undefined;
@@ -513,7 +931,6 @@ export function useUniversalAgentChat(
       };
     }
     if (projection === "message") {
-      activeSubmissionIdRef.current = undefined;
       setOptimisticMessages((current) =>
         current.some(({ id }) => id === message.id)
           ? current
@@ -548,7 +965,7 @@ export function useUniversalAgentChat(
         markChatTurnPhase(turnTimingRef.current, "rpcReceipt");
       }
       if (receipt.kind === "rejected") {
-        if (projection === "queue") rollback();
+        rollback();
         if (turnTimingRef.current?.messageId === message.id) {
           turnTimingRef.current = null;
         }
@@ -558,9 +975,49 @@ export function useUniversalAgentChat(
         return false;
       }
       if (projection === "message") {
-        activeSubmissionIdRef.current = receipt.kind === "queued"
+        const submissionId = receipt.kind === "queued"
           ? receipt.submission.submissionId
           : receipt.submissionId;
+        if (stopRevision !== stopRevisionRef.current) {
+          await agentRef.current.call<{ ok: boolean }>(
+            "cancelSubmissionById",
+            [submissionId, USER_STOP_REASON],
+          );
+          rollback();
+          return true;
+        }
+        if (
+          delivery === "steer" && receipt.kind === "accepted" &&
+          !message.metadata?.optimisticSteer
+        ) {
+          const activeAssistant = messagesRef.current.findLast((candidate) =>
+            candidate.role === "assistant" &&
+            candidate.metadata?.turnId === submissionId
+          );
+          const assistantMessageId = activeAssistant?.id ??
+            (authoritativeTurn?.activeSubmissionId === submissionId
+              ? authoritativeTurn.activeMessageId
+              : undefined);
+          if (assistantMessageId) {
+            const afterStep = activeAssistant?.parts.filter(
+              ({ type }) => type === "step-start",
+            ).length ?? 0;
+            setOptimisticMessages((current) => current.map((optimistic) =>
+              optimistic.id === message.id
+                ? {
+                    ...optimistic,
+                    metadata: {
+                      ...optimistic.metadata,
+                      optimisticSteer: { assistantMessageId, afterStep },
+                    },
+                  }
+                : optimistic
+            ));
+          }
+        }
+        if (turnTimingRef.current?.messageId === message.id) {
+          turnTimingRef.current.submissionId = submissionId;
+        }
       }
       if (projection === "queue") {
         if (receipt.kind !== "queued" || receipt.position < 1) {
@@ -579,7 +1036,7 @@ export function useUniversalAgentChat(
       }
       return true;
     } catch (cause) {
-      if (projection === "queue") rollback();
+      rollback();
       if (turnTimingRef.current?.messageId === message.id) {
         turnTimingRef.current = null;
       }
@@ -590,14 +1047,21 @@ export function useUniversalAgentChat(
       );
       return false;
     }
-  }, [chatId, clearError, dispatchMessage]);
+  }, [
+    authoritativeTurn?.activeMessageId,
+    authoritativeTurn?.activeSubmissionId,
+    chatId,
+    clearError,
+    dispatchMessage,
+  ]);
 
   const sendText = useCallback(async (
     text: string,
     files?: readonly FileUIPart[],
     capabilities?: readonly RequestedCapability[],
+    messageId?: string,
   ): Promise<boolean> => {
-    const message = createChatMessage(text, files, capabilities);
+    const message = createChatMessage(text, files, capabilities, messageId);
     return message
       ? submitMessage(message, "enqueue", "message")
       : false;
@@ -678,29 +1142,49 @@ export function useUniversalAgentChat(
   }, []);
 
   const stop = useCallback(async () => {
+    stopRevisionRef.current += 1;
     const requestId = authoritativeTurn?.activeRequestId;
-    const submissionId = authoritativeTurn?.activeSubmissionId ??
-      activeSubmissionIdRef.current;
+    const submissionId = authoritativeTurn?.activeSubmissionId;
+    const beforeStop = messagesRef.current;
+    const userIndex = beforeStop.findLastIndex(({ role }) => role === "user");
+    const assistantIndex = beforeStop.findLastIndex(
+      ({ role }, index) => index > userIndex && role === "assistant",
+    );
+    const marker = {
+      completedAt: Date.now(),
+      interruptedByUser: true,
+      turnStatus: "aborted",
+    } as const;
+    setMessages(assistantIndex < 0
+      ? [...beforeStop, {
+          id: `optimistic-stop:${submissionId ?? requestId ?? crypto.randomUUID()}`,
+          role: "assistant",
+          metadata: marker,
+          parts: [],
+        }]
+      : beforeStop.map((message, index) =>
+          index === assistantIndex
+            ? { ...message, metadata: { ...message.metadata, ...marker } }
+            : message
+        ));
+    const rollback = () => setMessages(beforeStop);
     setDispatchError(undefined);
     try {
+      await agentRef.current.call<{ ok: boolean }>(
+        "stopAllSubmissions",
+        [USER_STOP_REASON],
+      );
+      setOptimisticMessages([]);
+      setOptimisticQueued([]);
       if (requestId) {
         agentRef.current.send(JSON.stringify({
           type: MessageType.CF_AGENT_CHAT_REQUEST_CANCEL,
           id: requestId,
         }));
-        return;
+        await stopChat();
       }
-      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) {
+      rollback();
       setDispatchError(
         cause instanceof Error ? cause.message : String(cause),
       );
@@ -708,6 +1192,7 @@ export function useUniversalAgentChat(
   }, [
     authoritativeTurn?.activeRequestId,
     authoritativeTurn?.activeSubmissionId,
+    stopChat,
   ]);
 
   const retry = useCallback(() => {
@@ -736,6 +1221,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 之后调用方要拿到的是新装配。
@@ -743,6 +1236,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>>(
@@ -761,15 +1272,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,