@springbrand/chat-client 0.1.2 → 0.1.3-alpha.1

package/package.json

@@ -1,18 +1,16 @@
 {
   "name": "@springbrand/chat-client",
-  "version": "0.1.2",
+  "version": "0.1.3-alpha.1",
   "type": "module",
   "files": [
-    "dist"
+    "src",
+    "!src/**/*.test.ts"
   ],
   "publishConfig": {
     "access": "public"
   },
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+    ".": "./src/index.ts"
   },
   "peerDependencies": {
     "agents": "^0.19.0",
@@ -27,10 +25,9 @@
     "@types/react-dom": "^19.2.3",
     "react-dom": "^19.2.7",
     "typescript": "^7.0.2",
-    "@springbrand/agent-runtime": "0.1.3-alpha.0"
+    "@springbrand/agent-runtime": "0.1.3-alpha.2"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
     "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,120 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useAgent } from "agents/react";
+
+interface InboxState<Session> {
+  chats: Session[];
+  workspaceRev?: number;
+}
+
+export const CURRENT_INBOX_AGENT_PATH = "api/agent-connections/inbox";
+
+type Request = typeof fetch;
+export type ChatSessionsOptions = {
+  protocols?: string | string[];
+};
+
+export async function loadChatSessions<Session>(
+  signal?: AbortSignal,
+  request: Request = fetch,
+): Promise<Session[]> {
+  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) as
+    | { chats?: unknown }
+    | null;
+  if (!Array.isArray(body?.chats)) {
+    throw new Error("Invalid chat sessions response");
+  }
+  return body.chats as Session[];
+}
+
+/** Browser client for the user Inbox. Routing and presentation stay with the host UI. */
+export function useChatSessions<Session>(options: ChatSessionsOptions = {}) {
+  const inbox = useAgent<InboxState<Session>>({
+    agent: "Inbox",
+    basePath: CURRENT_INBOX_AGENT_PATH,
+    ...(options.protocols === undefined ? {} : { protocols: options.protocols }),
+  });
+  const [snapshot, setSnapshot] = useState<Session[]>();
+  const creatingRef = useRef(false);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    void loadChatSessions<Session>(controller.signal)
+      .then(setSnapshot)
+      .catch(() => undefined); // WebSocket state remains the fallback.
+    return () => controller.abort();
+  }, []);
+
+  const createChat = useCallback(async (userAgentId?: string) => {
+    if (creatingRef.current) return undefined;
+    creatingRef.current = true;
+    try {
+      await inbox.ready;
+      return await inbox.call<Session>(
+        "createChat",
+        userAgentId ? [{ userAgentId }] : undefined,
+      );
+    } finally {
+      creatingRef.current = false;
+    }
+  }, [inbox]);
+
+  const forkChat = useCallback(
+    (sourceChatId: string, messageId: string) =>
+      inbox.call<Session>("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 ?? snapshot ?? [],
+    synced: inbox.state !== undefined || snapshot !== undefined,
+    connected: inbox.identified,
+    workspaceRev: inbox.state?.workspaceRev ?? 0,
+    createChat,
+    forkChat,
+    renameChat,
+    deleteChat,
+    pinChat,
+    archiveChat,
+    reloadChatRuntime,
+  };
+}
+
+export type ChatSessions<Session> = ReturnType<
+  typeof useChatSessions<Session>
+>;

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,24 @@
+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 ChatSessionsOptions,
+  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);
+    },
+  });
+}