@springbrand/chat-client 0.1.1 → 0.1.2

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

@@ -1,542 +0,0 @@
-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];