@springbrand/chat-client 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@springbrand/chat-client",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "agents": "^0.19.0",
+    "ai": "^7.0.0",
+    "react": "^19.0.0"
+  },
+  "dependencies": {
+    "nanoid": "^5.1.16",
+    "@springbrand/agent-runtime": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react-dom": "^19.2.7",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/chat-attachments.ts

@@ -0,0 +1,238 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { nanoid } from "nanoid";
+import type { FileUIPart } from "ai";
+
+const VISION_MAX_BYTES = 500 * 1024;
+const VISION_TYPES = /^image\/(png|jpe?g|webp|gif)$/i;
+
+export interface UploadReceipt {
+  path: string;
+  size: number;
+  mime: string;
+  markdownPath?: string | null;
+}
+
+export function isVisionFile(meta: { mediaType?: string; size?: number }): boolean {
+  return (
+    VISION_TYPES.test(meta.mediaType ?? "") && (meta.size ?? 0) <= VISION_MAX_BYTES
+  );
+}
+
+export async function uploadFileToWorkspace(
+  file: File,
+  chatId: string,
+): Promise<UploadReceipt> {
+  const form = new FormData();
+  form.append("file", file);
+  const query = new URLSearchParams({ chat: chatId });
+  const response = await fetch(`/api/files?${query.toString()}`, {
+    method: "POST",
+    body: form,
+  });
+  if (!response.ok) throw new Error(`upload failed: ${response.status}`);
+  return (await response.json()) as UploadReceipt;
+}
+
+interface VisionUploadPart {
+  filename?: string;
+  mediaType?: string;
+  url: string;
+}
+
+async function toDataUrl<T extends VisionUploadPart>(part: T): Promise<T> {
+  if (!part.url.startsWith("blob:")) return part;
+  try {
+    const blob = await (await fetch(part.url)).blob();
+    const dataUrl = await new Promise<string | null>((resolve) => {
+      const reader = new FileReader();
+      reader.onloadend = () => resolve(reader.result as string);
+      reader.onerror = () => resolve(null);
+      reader.readAsDataURL(blob);
+    });
+    return { ...part, url: dataUrl ?? part.url };
+  } catch {
+    return part;
+  }
+}
+
+export type AttachmentStatus = "uploading" | "ready" | "error";
+
+export type Attachment = {
+  id: string;
+  type: "file";
+  filename?: string;
+  mediaType?: string;
+  url: string;
+  size?: number;
+  isVision: boolean;
+  status: AttachmentStatus;
+  receipt?: UploadReceipt;
+};
+
+export async function prepareAttachmentParts(
+  files: readonly Attachment[],
+): Promise<FileUIPart[]> {
+  return Promise.all(files.map(async (file): Promise<FileUIPart> => {
+    if (file.isVision) {
+      const prepared = await toDataUrl({
+        filename: file.filename,
+        mediaType: file.mediaType,
+        url: file.url,
+      });
+      if (prepared.url.startsWith("blob:")) {
+        throw new Error(`${file.filename ?? "Image"} could not be prepared`);
+      }
+      return {
+        type: "file",
+        ...(prepared.filename ? { filename: prepared.filename } : {}),
+        mediaType: prepared.mediaType || "application/octet-stream",
+        url: prepared.url,
+      };
+    }
+    if (!file.receipt) {
+      throw new Error(`${file.filename ?? "Attachment"} is not uploaded`);
+    }
+    return {
+      type: "file",
+      ...(file.filename ? { filename: file.filename } : {}),
+      mediaType: file.receipt.mime,
+      url: file.receipt.path,
+    };
+  }));
+}
+
+/** 浏览器附件 module：公共 Composer 负责选择与展示，这里维护 Workspace 上传和提交状态。 */
+export function useWorkspaceAttachments(chatId: string | null) {
+  const [files, setFiles] = useState<Attachment[]>([]);
+  const rawRef = useRef(new Map<string, File>());
+
+  const patch = useCallback((id: string, value: Partial<Attachment>) => {
+    setFiles((current) =>
+      current.map((file) => (file.id === id ? { ...file, ...value } : file)),
+    );
+  }, []);
+
+  const startUpload = useCallback(
+    (id: string, file: File) => {
+      patch(id, { status: "uploading" });
+      if (!chatId) {
+        patch(id, { status: "error" });
+        return;
+      }
+      uploadFileToWorkspace(file, chatId)
+        .then((receipt) => patch(id, { status: "ready", receipt }))
+        .catch(() => patch(id, { status: "error" }));
+    },
+    [chatId, patch],
+  );
+
+  const add = useCallback(
+    (incoming: readonly File[]) => {
+      if (incoming.length === 0) return;
+      const entries = incoming.map((file) => {
+        const id = nanoid();
+        rawRef.current.set(id, file);
+        const isVision = isVisionFile({
+          mediaType: file.type,
+          size: file.size,
+        });
+        return {
+          id,
+          type: "file" as const,
+          filename: file.name,
+          mediaType: file.type,
+          size: file.size,
+          url: URL.createObjectURL(file),
+          isVision,
+          status: (isVision ? "ready" : "uploading") as AttachmentStatus,
+        };
+      });
+      setFiles((current) => [...current, ...entries]);
+      for (const entry of entries) {
+        if (!entry.isVision) {
+          const raw = rawRef.current.get(entry.id);
+          if (raw) startUpload(entry.id, raw);
+        }
+      }
+    },
+    [startUpload],
+  );
+
+  const retry = useCallback(
+    (id: string) => {
+      const raw = rawRef.current.get(id);
+      if (raw) startUpload(id, raw);
+    },
+    [startUpload],
+  );
+
+  const remove = useCallback((id: string) => {
+    rawRef.current.delete(id);
+    setFiles((current) => {
+      const found = current.find((file) => file.id === id);
+      if (found?.url.startsWith("blob:")) URL.revokeObjectURL(found.url);
+      return current.filter((file) => file.id !== id);
+    });
+  }, []);
+
+  const reorder = useCallback((fromIndex: number, toIndex: number) => {
+    setFiles((current) => {
+      if (
+        fromIndex < 0 ||
+        toIndex < 0 ||
+        fromIndex >= current.length ||
+        toIndex >= current.length
+      ) {
+        return current;
+      }
+      const next = [...current];
+      const [moved] = next.splice(fromIndex, 1);
+      next.splice(toIndex, 0, moved);
+      return next;
+    });
+  }, []);
+
+  const clear = useCallback(() => {
+    rawRef.current.clear();
+    setFiles((current) => {
+      for (const file of current) {
+        if (file.url.startsWith("blob:")) URL.revokeObjectURL(file.url);
+      }
+      return [];
+    });
+  }, []);
+
+  const allReady = useMemo(
+    () => files.every((file) => file.status === "ready"),
+    [files],
+  );
+
+  const toSubmit = useCallback(
+    () => prepareAttachmentParts(files),
+    [files],
+  );
+
+  const filesRef = useRef(files);
+  useEffect(() => {
+    filesRef.current = files;
+  }, [files]);
+  useEffect(
+    () => () => {
+      for (const file of filesRef.current) {
+        if (file.url.startsWith("blob:")) URL.revokeObjectURL(file.url);
+      }
+    },
+    [],
+  );
+
+  return {
+    files,
+    add,
+    remove,
+    retry,
+    reorder,
+    clear,
+    allReady,
+    toSubmit,
+  };
+}

package/src/chat-sessions.ts

@@ -0,0 +1,99 @@
+import { useCallback, useRef } from "react";
+import { useAgent } from "agents/react";
+import type { RuntimeActivity } from "@springbrand/agent-runtime/contracts";
+
+export interface ChatSessionSummary {
+  id: string;
+  userAgentId: string;
+  title: string;
+  titleSource: "default" | "generated" | "manual";
+  createdAt: number;
+  updatedAt: number;
+  pinned: boolean;
+  archived: boolean;
+  activity: RuntimeActivity;
+  usage?: {
+    totalTokens: number;
+    totalCost: number;
+  };
+}
+
+interface InboxState {
+  chats: ChatSessionSummary[];
+  workspaceRev?: number;
+}
+
+export const CURRENT_INBOX_AGENT_PATH = "api/agent-connections/inbox";
+
+/** Browser client for the user Inbox. Routing and presentation stay with the host UI. */
+export function useChatSessions() {
+  const inbox = useAgent<InboxState>({
+    agent: "Inbox",
+    basePath: CURRENT_INBOX_AGENT_PATH,
+  });
+  const creatingRef = useRef(false);
+
+  const createChat = useCallback(async (userAgentId?: string) => {
+    if (creatingRef.current) return undefined;
+    creatingRef.current = true;
+    try {
+      return await inbox.call<ChatSessionSummary>(
+        "createChat",
+        userAgentId ? [{ userAgentId }] : undefined,
+      );
+    } finally {
+      creatingRef.current = false;
+    }
+  }, [inbox]);
+
+  const forkChat = useCallback(
+    (sourceChatId: string, messageId: string) =>
+      inbox.call<ChatSessionSummary>("forkChat", [sourceChatId, messageId]),
+    [inbox],
+  );
+
+  const renameChat = useCallback(async (id: string, title: string) => {
+    const normalizedTitle = title.trim();
+    if (!normalizedTitle) return;
+    await inbox.call("renameChat", [id, normalizedTitle]);
+  }, [inbox]);
+
+  const deleteChat = useCallback(async (id: string) => {
+    await inbox.call("deleteChat", [id]);
+  }, [inbox]);
+
+  const pinChat = useCallback(async (id: string, pinned: boolean) => {
+    await inbox.call("pinChat", [id, pinned]);
+  }, [inbox]);
+
+  const archiveChat = useCallback(async (id: string, archived: boolean) => {
+    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 ?? [],
+    synced: inbox.state !== undefined,
+    workspaceRev: inbox.state?.workspaceRev ?? 0,
+    createChat,
+    forkChat,
+    renameChat,
+    deleteChat,
+    pinChat,
+    archiveChat,
+    reloadChatRuntime,
+  };
+}
+
+export type ChatSessions = ReturnType<typeof useChatSessions>;

package/src/chat-summary.ts

@@ -0,0 +1,119 @@
+import { isToolUIPart, type UIMessage } from "ai";
+
+export interface ChatSummarySource {
+  kind: "file" | "link";
+  label: string;
+  href?: string;
+}
+
+export interface ChatMessageSummary {
+  activityCount: number;
+  currentGoal: string;
+  sources: ChatSummarySource[];
+}
+
+export function extractUrls(output: unknown): string[] {
+  if (output == null) return [];
+  const text = typeof output === "string" ? output : JSON.stringify(output);
+  const matches = text.match(/https?:\/\/[^\s"'<>()[\]\\]+/g) ?? [];
+  return [...new Set(matches.map((url) => url.replace(/[.,;:!?]+$/, "")))];
+}
+
+function urlLabel(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.host}${parsed.pathname === "/" ? "" : parsed.pathname}`;
+  } catch {
+    return url;
+  }
+}
+
+function stringField(
+  record: Record<string, unknown>,
+  field: string,
+): string | undefined {
+  return typeof record[field] === "string" ? record[field] : undefined;
+}
+
+export function summarizeChatMessages(
+  messages: readonly UIMessage[],
+): ChatMessageSummary {
+  const sources: ChatSummarySource[] = [];
+  const seen = new Set<string>();
+  let activityCount = 0;
+  let currentGoal = "";
+
+  const add = (key: string, source: ChatSummarySource) => {
+    if (seen.has(key)) return;
+    seen.add(key);
+    sources.push(source);
+  };
+
+  const addUrls = (value: unknown) => {
+    for (const url of extractUrls(value)) {
+      add(`url:${url}`, {
+        kind: "link",
+        label: urlLabel(url),
+        href: url,
+      });
+    }
+  };
+
+  for (const message of messages) {
+    if (message.role === "user") {
+      const text = message.parts
+        .flatMap((part) =>
+          part.type === "text" && typeof part.text === "string"
+            ? [part.text]
+            : []
+        )
+        .join(" ")
+        .trim();
+      if (text) currentGoal = text;
+    }
+
+    for (const part of message.parts) {
+      const record = part as Record<string, unknown>;
+      if (part.type === "file") {
+        const url = part.url;
+        const label = part.filename ?? part.mediaType ?? "附件";
+        add(`file:${url || label}`, {
+          kind: "file",
+          label,
+          ...(url.startsWith("http") ? { href: url } : {}),
+        });
+      } else if (part.type === "source-document") {
+        const sourceId = stringField(record, "sourceId") ?? "";
+        add(`document:${sourceId}`, {
+          kind: "file",
+          label:
+            stringField(record, "filename") ??
+            stringField(record, "title") ??
+            "文档",
+        });
+      } else if (part.type === "source-url") {
+        const url = stringField(record, "url");
+        if (!url) continue;
+        add(`url:${url}`, {
+          kind: "link",
+          label: stringField(record, "title") || urlLabel(url),
+          href: url,
+        });
+      }
+    }
+
+    for (const part of message.parts) {
+      if (isToolUIPart(part)) {
+        activityCount += 1;
+        addUrls((part as Record<string, unknown>).output);
+      }
+    }
+
+    for (const part of message.parts) {
+      if (part.type === "text" || part.type === "reasoning") addUrls(part.text);
+    }
+    addUrls(message.metadata);
+  }
+
+  return { activityCount, currentGoal, sources: sources.slice(0, 5) };
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export {
+  useUniversalAgentChat,
+  type AgentToolRun,
+  type ChatRuntime,
+} from "./use-universal-agent-chat";
+export {
+  prepareAttachmentParts,
+  useWorkspaceAttachments,
+  type Attachment,
+  type AttachmentStatus,
+  type UploadReceipt,
+} from "./chat-attachments";
+export {
+  extractUrls,
+  summarizeChatMessages,
+  type ChatMessageSummary,
+  type ChatSummarySource,
+} from "./chat-summary";
+export {
+  useChatSessions,
+  type ChatSessionSummary,
+  type ChatSessions,
+} from "./chat-sessions";

package/src/ui-message-stream-guard.ts

@@ -0,0 +1,139 @@
+import type { UIMessageChunk } from "ai";
+
+type AgentListener = (event: MessageEvent) => void;
+
+interface AgentConnection {
+  addEventListener(
+    type: string,
+    listener: AgentListener,
+    options?: AddEventListenerOptions,
+  ): void;
+  removeEventListener(type: string, listener: AgentListener): void;
+}
+
+interface StreamState {
+  readonly text: Set<string>;
+  readonly reasoning: Set<string>;
+  readonly toolInput: Set<string>;
+}
+
+function createStreamState(): StreamState {
+  return {
+    text: new Set(),
+    reasoning: new Set(),
+    toolInput: new Set(),
+  };
+}
+
+function acceptsChunk(state: StreamState, chunk: UIMessageChunk): boolean {
+  switch (chunk.type) {
+    case "text-start":
+      state.text.add(chunk.id);
+      return true;
+    case "text-delta":
+      return state.text.has(chunk.id);
+    case "text-end":
+      return state.text.delete(chunk.id);
+    case "reasoning-start":
+      state.reasoning.add(chunk.id);
+      return true;
+    case "reasoning-delta":
+      return state.reasoning.has(chunk.id);
+    case "reasoning-end":
+      return state.reasoning.delete(chunk.id);
+    case "tool-input-start":
+      state.toolInput.add(chunk.toolCallId);
+      return true;
+    case "tool-input-delta":
+      return state.toolInput.has(chunk.toolCallId);
+    case "finish-step":
+      state.text.clear();
+      state.reasoning.clear();
+      return true;
+    default:
+      return true;
+  }
+}
+
+/** Drops orphan AI SDK streaming chunks so one malformed part cannot stop chat. */
+export function createSafeUIMessageAgentConnection<T extends AgentConnection>(
+  agent: T,
+): T {
+  const states = new Map<string, StreamState>();
+  const decisions = new WeakMap<MessageEvent, boolean>();
+  const listenerMaps = new Map<string, Map<AgentListener, AgentListener>>();
+  const bound = new Map<PropertyKey, unknown>();
+
+  const shouldForward = (event: MessageEvent): boolean => {
+    const decided = decisions.get(event);
+    if (decided !== undefined) return decided;
+
+    let forward = true;
+    try {
+      const frame = JSON.parse(event.data) as {
+        type?: unknown;
+        id?: unknown;
+        body?: unknown;
+        done?: unknown;
+      };
+      if (
+        frame.type === "cf_agent_use_chat_response" &&
+        typeof frame.id === "string"
+      ) {
+        if (typeof frame.body === "string" && frame.body.trim()) {
+          const chunk = JSON.parse(frame.body) as UIMessageChunk;
+          const state = chunk.type === "start"
+            ? createStreamState()
+            : states.get(frame.id) ?? createStreamState();
+          states.set(frame.id, state);
+          forward = acceptsChunk(state, chunk);
+        }
+        if (frame.done === true) states.delete(frame.id);
+      }
+    } catch {
+      // Leave unrelated or malformed frames to the owning SDK listener.
+    }
+    decisions.set(event, forward);
+    return forward;
+  };
+
+  const addEventListener = (
+    type: string,
+    listener: AgentListener,
+    options?: AddEventListenerOptions,
+  ) => {
+    if (type !== "message") {
+      agent.addEventListener(type, listener, options);
+      return;
+    }
+    const wrapped: AgentListener = (event) => {
+      if (typeof event.data !== "string" || shouldForward(event)) listener(event);
+    };
+    const listeners = listenerMaps.get(type) ?? new Map();
+    listeners.set(listener, wrapped);
+    listenerMaps.set(type, listeners);
+    options?.signal?.addEventListener(
+      "abort",
+      () => listeners.delete(listener),
+      { once: true },
+    );
+    agent.addEventListener(type, wrapped, options);
+  };
+
+  const removeEventListener = (type: string, listener: AgentListener) => {
+    const wrapped = listenerMaps.get(type)?.get(listener) ?? listener;
+    listenerMaps.get(type)?.delete(listener);
+    agent.removeEventListener(type, wrapped);
+  };
+
+  return new Proxy(agent, {
+    get(target, property) {
+      if (property === "addEventListener") return addEventListener;
+      if (property === "removeEventListener") return removeEventListener;
+      const value = Reflect.get(target, property, target) as unknown;
+      if (typeof value !== "function") return value;
+      if (!bound.has(property)) bound.set(property, value.bind(target));
+      return bound.get(property);
+    },
+  });
+}

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

@@ -0,0 +1,542 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { nanoid } from "nanoid";
+import type { FileUIPart, UIMessage } from "ai";
+import { useAgentChat } from "agents/chat/react";
+import { useAgent, useAgentToolEvents } from "agents/react";
+import {
+  USER_STOP_REASON,
+  type MessageDelivery,
+  type MessageDispatchReceipt,
+  type RuntimeQueuedSubmission,
+  type RuntimeState,
+} 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> & {
+  turnStatus?: string;
+};
+type ChatMessage = UIMessage<ChatMessageMetadata>;
+type FailedDispatch = {
+  message: ChatMessage;
+  delivery: MessageDelivery;
+  projection: "message" | "queue";
+};
+
+type ChatTurnTiming = {
+  chatId: string;
+  messageId: string;
+  baselineAssistantIds: Set<string>;
+  click: number;
+  rpcReceipt?: number;
+  streamStart?: number;
+  firstText?: number;
+  ready?: number;
+};
+
+const CHAT_TURN_SEGMENTS = {
+  rpcReceipt: ["click", "universal-agent.chat.click_to_rpc_receipt"],
+  streamStart: [
+    "rpcReceipt",
+    "universal-agent.chat.rpc_receipt_to_stream_start",
+  ],
+  firstText: [
+    "streamStart",
+    "universal-agent.chat.stream_start_to_first_text",
+  ],
+  ready: ["firstText", "universal-agent.chat.first_text_to_ready"],
+} as const;
+
+function now(): number {
+  return typeof performance === "undefined" ? Date.now() : performance.now();
+}
+
+function markChatTurnPhase(
+  timing: ChatTurnTiming,
+  phase: keyof typeof CHAT_TURN_SEGMENTS,
+): void {
+  if (timing[phase] !== undefined) return;
+  const timestamp = now();
+  timing[phase] = timestamp;
+  if (typeof performance === "undefined") return;
+  const [previous, name] = CHAT_TURN_SEGMENTS[phase];
+  const start = timing[previous];
+  if (start === undefined) return;
+  try {
+    performance.measure(name, {
+      start,
+      end: timestamp,
+      detail: { chatId: timing.chatId, messageId: timing.messageId },
+    });
+  } catch {
+    // Metrics must never interrupt message delivery.
+  }
+}
+
+function createChatMessage(
+  text: string,
+  files?: readonly FileUIPart[],
+): ChatMessage | null {
+  const normalizedText = text.trim();
+  if (!normalizedText && !files?.length) return null;
+  const createdAt = Date.now();
+  return {
+    id: nanoid(),
+    role: "user",
+    parts: [
+      ...(files ?? []),
+      ...(normalizedText
+        ? [{ type: "text" as const, text: normalizedText }]
+        : []),
+    ],
+    metadata: {
+      createdAt,
+      authorDisplayName: "You",
+      messageSource: "Web",
+    },
+  };
+}
+
+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];
+}
+
+function queuedPreview(message: ChatMessage): string {
+  return message.parts.flatMap((part) => {
+    if (part.type === "text") return [part.text];
+    if (part.type === "file" && part.filename) return [part.filename];
+    return [];
+  }).join(" ").trim().slice(0, 160) || "Queued message";
+}
+
+/**
+ * 薄适配层:把 useAgent + UIMessage chat + useAgentToolEvents
+ * 收敛成一个归一化 runtime,对外只暴露 messages / 发送 / 状态 / 子 agent 运行,
+ * 隐藏 SDK 细节。
+ *
+ * 多会话接线(官方 facet 模式):经父级 Inbox 连 UniversalAgent facet,
+ * URL = /api/agent-connections/inbox/sub/universal-agent/{chatId}；可信用户
+ * 由 Worker 从 Session 解析后再路由到真正的 Inbox。
+ * sub 数组由客户端 kebab 化;服务端按 ctx.exports 反解回 CamelCase className,
+ * 与 Inbox.onBeforeSubAgent 的严格门卫(hasSubAgent)对齐。
+ */
+export function useUniversalAgentChat(chatId: string) {
+  const [optimisticMessages, setOptimisticMessages] =
+    useState<ChatMessage[]>([]);
+  const [optimisticQueued, setOptimisticQueued] =
+    useState<RuntimeQueuedSubmission[]>([]);
+  const [dispatchError, setDispatchError] = useState<string>();
+  const [canRetry, setCanRetry] = useState(false);
+  const failedDispatchRef = useRef<FailedDispatch | undefined>(undefined);
+  const activeSubmissionIdRef = useRef<string | undefined>(undefined);
+  const agent = useAgent<RuntimeState>({
+    agent: "Inbox",
+    basePath: CURRENT_INBOX_AGENT_PATH,
+    sub: [{ agent: "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):
+  // approvals === undefined = 首帧未到(未加载),不可当「空」。
+  const facetState = agent.state;
+  const agentRef = useRef(agent);
+  agentRef.current = agent;
+  const approvals = facetState?.approvals;
+  const approvalsLoaded = facetState?.approvals !== undefined;
+  const {
+    messages,
+    status: sdkStatus,
+    isStreaming,
+    error,
+    // autonomous responses 纪律(CF 文档采纳 2026-07-05):框架已提供三个流态标志,
+    // 透出供 UI 区分「服务端主动流 vs 用户发起流」+「恢复态」(与 stall 看门狗配套)。
+    isServerStreaming,
+    isRecovering,
+    isToolContinuation,
+    connectionError,
+  } = useAgentChat<RuntimeState, ChatMessage>({
+    agent: chatAgent,
+    syncMessagesToServer: false,
+    throttle: 100,
+  });
+  const visibleMessages = useMemo(
+    () => mergeOptimisticMessages(messages, optimisticMessages),
+    [messages, optimisticMessages],
+  );
+  const authoritativeTurn = facetState?.turn;
+  const stoppedByUser = error?.message === USER_STOP_REASON;
+  const normalizedSdkStatus = stoppedByUser && sdkStatus === "error"
+    ? "ready"
+    : sdkStatus;
+  // 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" &&
+    !isRecovering &&
+    approvals?.length === 0 &&
+    authoritativeTurn?.activeSubmissionId
+      ? isServerStreaming
+        ? "streaming"
+        : "submitted"
+      : normalizedSdkStatus;
+  const status = dispatchError
+    ? "error"
+    : optimisticMessages.length > 0 && authoritativeStatus === "ready"
+      ? "submitted"
+      : authoritativeStatus;
+  const messagesRef = useRef(messages);
+  messagesRef.current = messages;
+  const turnTimingRef = useRef<ChatTurnTiming | null>(null);
+
+  useEffect(() => {
+    const timing = turnTimingRef.current;
+    if (!timing) return;
+    const assistant = messages.find((message) =>
+      message.role === "assistant" &&
+      !timing.baselineAssistantIds.has(message.id)
+    );
+    if (assistant) markChatTurnPhase(timing, "streamStart");
+    if (
+      assistant?.parts.some((part) =>
+        part.type === "text" && part.text.trim().length > 0
+      )
+    ) {
+      markChatTurnPhase(timing, "firstText");
+    }
+    if (status === "ready" && timing.streamStart !== undefined) {
+      if (timing.firstText !== undefined) markChatTurnPhase(timing, "ready");
+      turnTimingRef.current = null;
+    }
+  }, [messages, status]);
+
+  useEffect(() => {
+    if (optimisticMessages.length === 0 || messages.length === 0) return;
+    const acknowledged = new Set(messages.map(({ id }) => id));
+    setOptimisticMessages((current) => {
+      const next = current.filter(({ id }) => !acknowledged.has(id));
+      return next.length === current.length ? current : next;
+    });
+  }, [messages, optimisticMessages.length]);
+
+  useEffect(() => {
+    if (optimisticQueued.length === 0) return;
+    const acknowledged = new Set([
+      ...messages.map(({ id }) => id),
+      ...(authoritativeTurn?.queued.map(({ messageId }) => messageId) ?? []),
+    ]);
+    if (acknowledged.size === 0) return;
+    setOptimisticQueued((current) => {
+      const next = current.filter(({ messageId }) =>
+        !acknowledged.has(messageId)
+      );
+      return next.length === current.length ? current : next;
+    });
+  }, [authoritativeTurn?.queued, messages, optimisticQueued.length]);
+
+  const turn = useMemo(() => {
+    const visibleMessageIds = new Set(visibleMessages.map(({ id }) => id));
+    const authoritativeQueued = authoritativeTurn?.queued.filter(
+      ({ messageId }) => !visibleMessageIds.has(messageId),
+    ) ?? [];
+    const acknowledged = new Set([
+      ...visibleMessageIds,
+      ...(authoritativeTurn?.queued.map(({ messageId }) => messageId) ?? []),
+    ]);
+    const pending = optimisticQueued.filter(({ messageId }) =>
+      !acknowledged.has(messageId)
+    );
+    if (
+      pending.length === 0 &&
+      authoritativeQueued.length === (authoritativeTurn?.queued.length ?? 0)
+    ) {
+      return authoritativeTurn;
+    }
+    const queued = [
+      ...authoritativeQueued,
+      ...pending,
+    ].map((submission, index) => ({
+      ...submission,
+      position: index + 1,
+    }));
+    return {
+      ...authoritativeTurn,
+      steerable: authoritativeTurn?.steerable ?? false,
+      hasPendingSteer: authoritativeTurn?.hasPendingSteer ?? false,
+      queued,
+    };
+  }, [authoritativeTurn, visibleMessages, optimisticQueued]);
+  const turnActive = Boolean(turn?.activeSubmissionId) ||
+    status === "submitted" ||
+    status === "streaming" ||
+    isServerStreaming ||
+    isRecovering ||
+    isToolContinuation;
+  const canSteer = turnActive &&
+    (!turn?.activeSubmissionId || turn.steerable);
+
+  // 子 agent 运行(agentTool 前台 + runAgentTool detached 后台)的实时事件投影:
+  // 状态机 + progress snapshot + durable milestones(knowledge/upstream-adoption.csv F6)
+  const { runsById } = useAgentToolEvents({ agent });
+  const agentToolRuns = useMemo(
+    () => Object.values(runsById).sort((a, b) => a.order - b.order),
+    [runsById],
+  );
+
+  const dispatchMessage = useCallback(async (
+    message: ChatMessage,
+    delivery: MessageDelivery,
+  ): Promise<MessageDispatchReceipt> =>
+    agentRef.current.call<MessageDispatchReceipt>(
+      "dispatchMessage",
+      [message, delivery],
+    ), []);
+
+  const submitMessage = useCallback(async (
+    message: ChatMessage,
+    delivery: MessageDelivery,
+    projection: "message" | "queue",
+  ): Promise<boolean> => {
+    setDispatchError(undefined);
+    failedDispatchRef.current = undefined;
+    setCanRetry(false);
+    if (projection === "message" && delivery === "enqueue") {
+      turnTimingRef.current = {
+        chatId,
+        messageId: message.id,
+        baselineAssistantIds: new Set(
+          messagesRef.current
+            .filter(({ role }) => role === "assistant")
+            .map(({ id }) => id),
+        ),
+        click: now(),
+      };
+    }
+    if (projection === "message") {
+      setOptimisticMessages((current) =>
+        current.some(({ id }) => id === message.id)
+          ? current
+          : [...current, message]
+      );
+    } else {
+      setOptimisticQueued((current) => [
+        ...current,
+        {
+          submissionId: `optimistic:${message.id}`,
+          messageId: message.id,
+          preview: queuedPreview(message),
+          position: current.length + 1,
+          createdAt: Number(message.metadata?.createdAt ?? Date.now()),
+        },
+      ]);
+    }
+    const rollback = () => {
+      if (projection === "message") {
+        setOptimisticMessages((current) =>
+          current.filter(({ id }) => id !== message.id)
+        );
+      } else {
+        setOptimisticQueued((current) =>
+          current.filter(({ messageId }) => messageId !== message.id)
+        );
+      }
+    };
+    try {
+      const receipt = await dispatchMessage(message, delivery);
+      if (turnTimingRef.current?.messageId === message.id) {
+        markChatTurnPhase(turnTimingRef.current, "rpcReceipt");
+      }
+      if (receipt.kind === "rejected") {
+        if (projection === "queue") rollback();
+        if (turnTimingRef.current?.messageId === message.id) {
+          turnTimingRef.current = null;
+        }
+        failedDispatchRef.current = { message, delivery, projection };
+        setCanRetry(true);
+        setDispatchError(receipt.message);
+        return false;
+      }
+      if (projection === "message") {
+        activeSubmissionIdRef.current = receipt.kind === "queued"
+          ? receipt.submission.submissionId
+          : receipt.submissionId;
+      }
+      if (projection === "queue") {
+        if (receipt.kind !== "queued" || receipt.position < 1) {
+          rollback();
+        } else {
+          setOptimisticQueued((current) => current.map((queued) =>
+            queued.messageId === message.id
+              ? {
+                  ...queued,
+                  submissionId: receipt.submission.submissionId,
+                  position: receipt.position,
+                }
+              : queued
+          ));
+        }
+      }
+      return true;
+    } catch (cause) {
+      if (projection === "queue") rollback();
+      if (turnTimingRef.current?.messageId === message.id) {
+        turnTimingRef.current = null;
+      }
+      failedDispatchRef.current = { message, delivery, projection };
+      setCanRetry(true);
+      setDispatchError(
+        cause instanceof Error ? cause.message : String(cause),
+      );
+      return false;
+    }
+  }, [chatId, dispatchMessage]);
+
+  const sendText = useCallback(async (
+    text: string,
+    files?: readonly FileUIPart[],
+  ): Promise<boolean> => {
+    const message = createChatMessage(text, files);
+    return message
+      ? submitMessage(message, "enqueue", "message")
+      : false;
+  }, [submitMessage]);
+
+  const dispatchText = useCallback(async (
+    text: string,
+    files: readonly FileUIPart[] | undefined,
+    delivery: MessageDelivery,
+    projection: "message" | "queue",
+  ): Promise<boolean> => {
+    const message = createChatMessage(text, files);
+    return message ? submitMessage(message, delivery, projection) : false;
+  }, [submitMessage]);
+
+  const steerText = useCallback(
+    (text: string, files?: readonly FileUIPart[]) =>
+      dispatchText(text, files, "steer", "message"),
+    [dispatchText],
+  );
+  const enqueueText = useCallback(
+    (text: string, files?: readonly FileUIPart[]) =>
+      dispatchText(text, files, "enqueue", "queue"),
+    [dispatchText],
+  );
+  const steerQueued = useCallback(async (submissionId: string) => {
+    setDispatchError(undefined);
+    try {
+      const receipt = await agentRef.current.call<MessageDispatchReceipt>(
+        "steerQueuedSubmission",
+        [submissionId],
+      );
+      if (receipt.kind !== "steered") {
+        setDispatchError(
+          receipt.kind === "rejected"
+            ? receipt.message
+            : "The queued message could not be steered",
+        );
+        return false;
+      }
+      if (receipt.message) {
+        const message = receipt.message as ChatMessage;
+        setOptimisticMessages((current) =>
+          current.some(({ id }) => id === message.id)
+            ? current
+            : [...current, message]
+        );
+      }
+      setOptimisticQueued((current) =>
+        current.filter((queued) => queued.submissionId !== submissionId)
+      );
+      return true;
+    } catch (cause) {
+      setDispatchError(
+        cause instanceof Error ? cause.message : String(cause),
+      );
+      return false;
+    }
+  }, []);
+  const cancelQueued = useCallback(async (submissionId: string) => {
+    const result = await agentRef.current.call<{ ok: boolean }>(
+      "cancelSubmissionById",
+      [submissionId, "Cancelled from queue"],
+    );
+    if (result.ok) {
+      setOptimisticQueued((current) =>
+        current.filter((queued) => queued.submissionId !== submissionId)
+      );
+    }
+    return result.ok;
+  }, []);
+
+  const stop = useCallback(async () => {
+    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 (!result.ok) setDispatchError("The active Turn could not be stopped");
+    } catch (cause) {
+      setDispatchError(
+        cause instanceof Error ? cause.message : String(cause),
+      );
+    }
+  }, [authoritativeTurn?.activeSubmissionId]);
+
+  const retry = useCallback(() => {
+    const failed = failedDispatchRef.current;
+    if (!failed) return;
+    void submitMessage(
+      failed.message,
+      failed.delivery,
+      failed.projection,
+    );
+  }, [submitMessage]);
+
+  return {
+    messages: visibleMessages,
+    status,
+    runtimeLoad: facetState?.runtimeLoad,
+    isStreaming,
+    error: dispatchError ?? (stoppedByUser ? undefined : error) ??
+      connectionError ?? undefined,
+    sendText,
+    steerText,
+    enqueueText,
+    steerQueued,
+    cancelQueued,
+    stop,
+    regenerate: retry,
+    canRetry,
+    agentToolRuns,
+    // 流态标志:
+    // - isServerStreaming:服务端主动推流(子 agent 回投/续跑),非用户发起
+    // - isRecovering:durable turn 恢复中(被 deploy/eviction 或 stall 看门狗中断后重连)
+    // - isToolContinuation:工具续跑轮次(区分「用户刚发消息等首 token」)
+    isServerStreaming,
+    isRecovering,
+    isToolContinuation,
+    // facet 推送来的审批快照(会话级)。ApprovalsProvider 复用它,零轮询。
+    approvals,
+    approvalsLoaded,
+    turn,
+    turnActive,
+    canSteer,
+  };
+}
+
+export type ChatRuntime = ReturnType<typeof useUniversalAgentChat>;
+export type AgentToolRun = ChatRuntime["agentToolRuns"][number];