@springbrand/chat-client 0.1.0 → 0.1.2

package/dist/use-universal-agent-chat.js

@@ -0,0 +1,431 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { nanoid } from "nanoid";
+import { getAgentMessages, useAgentChat } from "agents/chat/react";
+import { useAgent, useAgentToolEvents } from "agents/react";
+import { createSafeUIMessageAgentConnection } from "./ui-message-stream-guard";
+import { CURRENT_INBOX_AGENT_PATH } from "./chat-sessions";
+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"],
+};
+const USER_STOP_REASON = "Stopped by user";
+function now() {
+    return typeof performance === "undefined" ? Date.now() : performance.now();
+}
+function markChatTurnPhase(timing, phase) {
+    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, files) {
+    const normalizedText = text.trim();
+    if (!normalizedText && !files?.length)
+        return null;
+    const createdAt = Date.now();
+    return {
+        id: nanoid(),
+        role: "user",
+        parts: [
+            ...(files ?? []),
+            ...(normalizedText
+                ? [{ type: "text", text: normalizedText }]
+                : []),
+        ],
+        metadata: {
+            createdAt,
+            authorDisplayName: "You",
+            messageSource: "Web",
+        },
+    };
+}
+export function mergeOptimisticMessages(messages, optimistic) {
+    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) {
+    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";
+}
+function loadInitialMessages(url, credentials) {
+    if (!url)
+        return Promise.resolve([]);
+    const messagesUrl = new URL(url);
+    messagesUrl.pathname = `${messagesUrl.pathname.replace(/\/$/, "")}/get-messages`;
+    return getAgentMessages({
+        url: messagesUrl.toString(),
+        ...(credentials === undefined ? {} : { credentials }),
+    });
+}
+/**
+ * 薄适配层:把 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, connection = {}) {
+    const [optimisticMessages, setOptimisticMessages] = useState([]);
+    const [optimisticQueued, setOptimisticQueued] = useState([]);
+    const [dispatchError, setDispatchError] = useState();
+    const [canRetry, setCanRetry] = useState(false);
+    const failedDispatchRef = useRef(undefined);
+    const activeSubmissionIdRef = useRef(undefined);
+    const inboxAgent = connection.inboxAgent ?? "Inbox";
+    const agent = useAgent({
+        agent: inboxAgent,
+        ...(connection.inboxName === undefined
+            ? { basePath: connection.basePath ?? CURRENT_INBOX_AGENT_PATH }
+            : { name: connection.inboxName }),
+        ...(connection.host === undefined ? {} : { host: connection.host }),
+        sub: [{
+                agent: connection.sessionAgent ?? "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({
+        agent: chatAgent,
+        getInitialMessages: ({ url }) => loadInitialMessages(url, connection.credentials),
+        ...(connection.credentials === undefined
+            ? {}
+            : { credentials: connection.credentials }),
+        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(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, delivery) => agentRef.current.call("dispatchMessage", [message, delivery]), []);
+    const submitMessage = useCallback(async (message, delivery, projection) => {
+        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, files) => {
+        const message = createChatMessage(text, files);
+        return message
+            ? submitMessage(message, "enqueue", "message")
+            : false;
+    }, [submitMessage]);
+    const dispatchText = useCallback(async (text, files, delivery, projection) => {
+        const message = createChatMessage(text, files);
+        return message ? submitMessage(message, delivery, projection) : false;
+    }, [submitMessage]);
+    const steerText = useCallback((text, files) => dispatchText(text, files, "steer", "message"), [dispatchText]);
+    const enqueueText = useCallback((text, files) => dispatchText(text, files, "enqueue", "queue"), [dispatchText]);
+    const steerQueued = useCallback(async (submissionId) => {
+        setDispatchError(undefined);
+        try {
+            const receipt = await agentRef.current.call("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;
+                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) => {
+        const result = await agentRef.current.call("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("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,
+    };
+}

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@springbrand/chat-client",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "files": [
-    "src"
+    "dist"
   ],
   "publishConfig": {
     "access": "public"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "peerDependencies": {
     "agents": "^0.19.0",
@@ -17,16 +20,17 @@
     "react": "^19.0.0"
   },
   "dependencies": {
-    "nanoid": "^5.1.16",
-    "@springbrand/agent-runtime": "0.1.0"
+    "nanoid": "^5.1.16"
   },
   "devDependencies": {
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "react-dom": "^19.2.7",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "@springbrand/agent-runtime": "0.1.3-alpha.0"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit"
   }
 }