@springbrand/chat-client 0.1.1 → 0.1.2

package/dist/chat-attachments.d.ts

@@ -0,0 +1,36 @@
+import type { FileUIPart } from "ai";
+export interface UploadReceipt {
+    path: string;
+    size: number;
+    mime: string;
+    markdownPath?: string | null;
+}
+export declare function isVisionFile(meta: {
+    mediaType?: string;
+    size?: number;
+}): boolean;
+export declare function uploadFileToWorkspace(file: File, chatId: string): Promise<UploadReceipt>;
+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 declare function prepareAttachmentParts(files: readonly Attachment[]): Promise<FileUIPart[]>;
+/** 浏览器附件 module：公共 Composer 负责选择与展示，这里维护 Workspace 上传和提交状态。 */
+export declare function useWorkspaceAttachments(chatId: string | null): {
+    files: Attachment[];
+    add: (incoming: readonly File[]) => void;
+    remove: (id: string) => void;
+    retry: (id: string) => void;
+    reorder: (fromIndex: number, toIndex: number) => void;
+    clear: () => void;
+    allReady: boolean;
+    toSubmit: () => Promise<FileUIPart[]>;
+};

package/dist/chat-attachments.js

@@ -0,0 +1,173 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { nanoid } from "nanoid";
+const VISION_MAX_BYTES = 500 * 1024;
+const VISION_TYPES = /^image\/(png|jpe?g|webp|gif)$/i;
+export function isVisionFile(meta) {
+    return (VISION_TYPES.test(meta.mediaType ?? "") && (meta.size ?? 0) <= VISION_MAX_BYTES);
+}
+export async function uploadFileToWorkspace(file, chatId) {
+    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());
+}
+async function toDataUrl(part) {
+    if (!part.url.startsWith("blob:"))
+        return part;
+    try {
+        const blob = await (await fetch(part.url)).blob();
+        const dataUrl = await new Promise((resolve) => {
+            const reader = new FileReader();
+            reader.onloadend = () => resolve(reader.result);
+            reader.onerror = () => resolve(null);
+            reader.readAsDataURL(blob);
+        });
+        return { ...part, url: dataUrl ?? part.url };
+    }
+    catch {
+        return part;
+    }
+}
+export async function prepareAttachmentParts(files) {
+    return Promise.all(files.map(async (file) => {
+        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) {
+    const [files, setFiles] = useState([]);
+    const rawRef = useRef(new Map());
+    const patch = useCallback((id, value) => {
+        setFiles((current) => current.map((file) => (file.id === id ? { ...file, ...value } : file)));
+    }, []);
+    const startUpload = useCallback((id, 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) => {
+        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",
+                filename: file.name,
+                mediaType: file.type,
+                size: file.size,
+                url: URL.createObjectURL(file),
+                isVision,
+                status: (isVision ? "ready" : "uploading"),
+            };
+        });
+        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) => {
+        const raw = rawRef.current.get(id);
+        if (raw)
+            startUpload(id, raw);
+    }, [startUpload]);
+    const remove = useCallback((id) => {
+        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, toIndex) => {
+        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/dist/chat-sessions.d.ts

@@ -0,0 +1,35 @@
+export interface ChatSessionSummary {
+    id: string;
+    userAgentId: string;
+    title: string;
+    titleSource: "default" | "generated" | "manual";
+    createdAt: number;
+    updatedAt: number;
+    pinned: boolean;
+    archived: boolean;
+    activity: "idle" | "working" | "needs-input";
+    usage?: {
+        totalTokens: number;
+        totalCost: number;
+    };
+}
+export declare const CURRENT_INBOX_AGENT_PATH = "api/agent-connections/inbox";
+type Request = typeof fetch;
+export declare function loadChatSessions(signal?: AbortSignal, request?: Request): Promise<ChatSessionSummary[]>;
+/** Browser client for the user Inbox. Routing and presentation stay with the host UI. */
+export declare function useChatSessions(): {
+    chats: ChatSessionSummary[];
+    synced: boolean;
+    workspaceRev: number;
+    createChat: (userAgentId?: string) => Promise<ChatSessionSummary | undefined>;
+    forkChat: (sourceChatId: string, messageId: string) => Promise<ChatSessionSummary>;
+    renameChat: (id: string, title: string) => Promise<void>;
+    deleteChat: (id: string) => Promise<void>;
+    pinChat: (id: string, pinned: boolean) => Promise<void>;
+    archiveChat: (id: string, archived: boolean) => Promise<void>;
+    reloadChatRuntime: (chatId: string, userAgentId: string) => Promise<{
+        userAgentId: string;
+    }>;
+};
+export type ChatSessions = ReturnType<typeof useChatSessions>;
+export {};

package/dist/chat-sessions.js

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useAgent } from "agents/react";
+export const CURRENT_INBOX_AGENT_PATH = "api/agent-connections/inbox";
+export async function loadChatSessions(signal, request = fetch) {
+    const response = await request("/api/chats", {
+        cache: "no-store",
+        headers: { Accept: "application/json" },
+        signal,
+    });
+    if (!response.ok)
+        throw new Error("Unable to load chat sessions");
+    const body = await response.json().catch(() => null);
+    if (!Array.isArray(body?.chats)) {
+        throw new Error("Invalid chat sessions response");
+    }
+    return body.chats;
+}
+/** Browser client for the user Inbox. Routing and presentation stay with the host UI. */
+export function useChatSessions() {
+    const inbox = useAgent({
+        agent: "Inbox",
+        basePath: CURRENT_INBOX_AGENT_PATH,
+    });
+    const [snapshot, setSnapshot] = useState();
+    const creatingRef = useRef(false);
+    useEffect(() => {
+        const controller = new AbortController();
+        void loadChatSessions(controller.signal)
+            .then(setSnapshot)
+            .catch(() => undefined); // WebSocket state remains the fallback.
+        return () => controller.abort();
+    }, []);
+    const createChat = useCallback(async (userAgentId) => {
+        if (creatingRef.current)
+            return undefined;
+        creatingRef.current = true;
+        try {
+            return await inbox.call("createChat", userAgentId ? [{ userAgentId }] : undefined);
+        }
+        finally {
+            creatingRef.current = false;
+        }
+    }, [inbox]);
+    const forkChat = useCallback((sourceChatId, messageId) => inbox.call("forkChat", [sourceChatId, messageId]), [inbox]);
+    const renameChat = useCallback(async (id, title) => {
+        const normalizedTitle = title.trim();
+        if (!normalizedTitle)
+            return;
+        await inbox.call("renameChat", [id, normalizedTitle]);
+    }, [inbox]);
+    const deleteChat = useCallback(async (id) => {
+        await inbox.call("deleteChat", [id]);
+    }, [inbox]);
+    const pinChat = useCallback(async (id, pinned) => {
+        await inbox.call("pinChat", [id, pinned]);
+    }, [inbox]);
+    const archiveChat = useCallback(async (id, archived) => {
+        await inbox.call("archiveChat", [id, archived]);
+    }, [inbox]);
+    const reloadChatRuntime = useCallback(async (chatId, userAgentId) => {
+        const result = await inbox.call("chatReloadRuntime", [chatId, userAgentId]);
+        if (!result)
+            throw new Error("Session is unavailable");
+        return result;
+    }, [inbox]);
+    return {
+        chats: inbox.state?.chats ?? snapshot ?? [],
+        synced: inbox.state !== undefined || snapshot !== undefined,
+        workspaceRev: inbox.state?.workspaceRev ?? 0,
+        createChat,
+        forkChat,
+        renameChat,
+        deleteChat,
+        pinChat,
+        archiveChat,
+        reloadChatRuntime,
+    };
+}

package/dist/chat-summary.d.ts

@@ -0,0 +1,13 @@
+import { type UIMessage } from "ai";
+export interface ChatSummarySource {
+    kind: "file" | "link";
+    label: string;
+    href?: string;
+}
+export interface ChatMessageSummary {
+    activityCount: number;
+    currentGoal: string;
+    sources: ChatSummarySource[];
+}
+export declare function extractUrls(output: unknown): string[];
+export declare function summarizeChatMessages(messages: readonly UIMessage[]): ChatMessageSummary;

package/dist/chat-summary.js

@@ -0,0 +1,96 @@
+import { isToolUIPart } from "ai";
+export function extractUrls(output) {
+    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) {
+    try {
+        const parsed = new URL(url);
+        return `${parsed.host}${parsed.pathname === "/" ? "" : parsed.pathname}`;
+    }
+    catch {
+        return url;
+    }
+}
+function stringField(record, field) {
+    return typeof record[field] === "string" ? record[field] : undefined;
+}
+export function summarizeChatMessages(messages) {
+    const sources = [];
+    const seen = new Set();
+    let activityCount = 0;
+    let currentGoal = "";
+    const add = (key, source) => {
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        sources.push(source);
+    };
+    const addUrls = (value) => {
+        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;
+            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.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/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { useUniversalAgentChat, type AgentToolRun, type ChatConnectionOptions, 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/dist/index.js

@@ -0,0 +1,4 @@
+export { useUniversalAgentChat, } from "./use-universal-agent-chat";
+export { prepareAttachmentParts, useWorkspaceAttachments, } from "./chat-attachments";
+export { extractUrls, summarizeChatMessages, } from "./chat-summary";
+export { useChatSessions, } from "./chat-sessions";

package/dist/ui-message-stream-guard.d.ts

@@ -0,0 +1,8 @@
+type AgentListener = (event: MessageEvent) => void;
+interface AgentConnection {
+    addEventListener(type: string, listener: AgentListener, options?: AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: AgentListener): void;
+}
+/** Drops orphan AI SDK streaming chunks so one malformed part cannot stop chat. */
+export declare function createSafeUIMessageAgentConnection<T extends AgentConnection>(agent: T): T;
+export {};

package/dist/ui-message-stream-guard.js

@@ -0,0 +1,104 @@
+function createStreamState() {
+    return {
+        text: new Set(),
+        reasoning: new Set(),
+        toolInput: new Set(),
+    };
+}
+function acceptsChunk(state, chunk) {
+    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(agent) {
+    const states = new Map();
+    const decisions = new WeakMap();
+    const listenerMaps = new Map();
+    const bound = new Map();
+    const shouldForward = (event) => {
+        const decided = decisions.get(event);
+        if (decided !== undefined)
+            return decided;
+        let forward = true;
+        try {
+            const frame = JSON.parse(event.data);
+            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);
+                    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, listener, options) => {
+        if (type !== "message") {
+            agent.addEventListener(type, listener, options);
+            return;
+        }
+        const wrapped = (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, listener) => {
+        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);
+            if (typeof value !== "function")
+                return value;
+            if (!bound.has(property))
+                bound.set(property, value.bind(target));
+            return bound.get(property);
+        },
+    });
+}

package/dist/use-universal-agent-chat.d.ts

@@ -0,0 +1,102 @@
+import type { ChatStatus, FileUIPart, UIMessage } from "ai";
+import type { AgentToolRunState } from "agents";
+type ChatMessageMetadata = Record<string, unknown> & {
+    turnStatus?: string;
+};
+type ChatMessage = UIMessage<ChatMessageMetadata>;
+type ChatRuntimeLoadState = {
+    status: "idle";
+    available: false;
+} | {
+    status: "loading";
+    phase: "config" | "plugins" | "mcp" | "pi";
+    available: boolean;
+    startedAt: number;
+    updatedAt: number;
+} | {
+    status: "ready";
+    available: true;
+    startedAt: number;
+    completedAt: number;
+} | {
+    status: "error";
+    phase: "config" | "plugins" | "mcp" | "pi";
+    available: boolean;
+    startedAt: number;
+    failedAt: number;
+};
+type ChatApproval = {
+    executionId: string;
+    source: "action" | "codemode" | "temporary-agent";
+    action: string;
+    summary: string;
+    executionLevel: "safe" | "low" | "medium" | "high";
+    requiredExecutionLevel: "safe" | "low" | "medium" | "high";
+    inputJson: string;
+    requestId: string;
+};
+type ChatQueuedSubmission = {
+    submissionId: string;
+    messageId: string;
+    preview: string;
+    position: number;
+    createdAt: number;
+};
+type ChatTurn = {
+    activeSubmissionId?: string;
+    steerable: boolean;
+    hasPendingSteer: boolean;
+    queued: ChatQueuedSubmission[];
+};
+export interface ChatRuntime {
+    messages: ChatMessage[];
+    status: ChatStatus;
+    runtimeLoad: ChatRuntimeLoadState | undefined;
+    isStreaming: boolean;
+    error: string | Error | undefined;
+    sendText: (text: string, files?: readonly FileUIPart[]) => Promise<boolean>;
+    steerText: (text: string, files?: readonly FileUIPart[]) => Promise<boolean>;
+    enqueueText: (text: string, files?: readonly FileUIPart[]) => Promise<boolean>;
+    steerQueued: (submissionId: string) => Promise<boolean>;
+    cancelQueued: (submissionId: string) => Promise<boolean>;
+    stop: () => Promise<void>;
+    regenerate: () => void;
+    canRetry: boolean;
+    agentToolRuns: AgentToolRunState<ChatMessage["parts"][number]>[];
+    isServerStreaming: boolean;
+    isRecovering: boolean;
+    isToolContinuation: boolean;
+    approvals: ChatApproval[] | undefined;
+    approvalsLoaded: boolean;
+    turn: ChatTurn | undefined;
+    turnActive: boolean;
+    canSteer: boolean;
+}
+type SharedChatConnectionOptions = {
+    host?: string;
+    credentials?: RequestCredentials;
+    inboxAgent?: string;
+    sessionAgent?: string;
+};
+export type ChatConnectionOptions = SharedChatConnectionOptions & ({
+    inboxName: string;
+    basePath?: never;
+} | {
+    inboxName?: never;
+    basePath?: string;
+});
+export declare function mergeOptimisticMessages<T extends UIMessage>(messages: T[], optimistic: T[]): T[];
+/**
+ * 薄适配层:把 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 declare function useUniversalAgentChat(chatId: string, connection?: ChatConnectionOptions): ChatRuntime;
+export type AgentToolRun = ChatRuntime["agentToolRuns"][number];
+export {};