@springbrand/chat-client 0.1.1 → 0.1.3-alpha.0

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@springbrand/chat-client",
-  "version": "0.1.1",
+  "version": "0.1.3-alpha.0",
   "type": "module",
   "files": [
-    "src"
+    "src",
+    "!src/**/*.test.ts"
   ],
   "publishConfig": {
     "access": "public"
@@ -17,14 +18,14 @@
     "react": "^19.0.0"
   },
   "dependencies": {
-    "nanoid": "^5.1.16",
-    "@springbrand/agent-runtime": "0.1.1"
+    "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.1"
   },
   "scripts": {
     "typecheck": "tsc --noEmit"

package/src/chat-sessions.ts

@@ -1,6 +1,5 @@
-import { useCallback, useRef } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useAgent } from "agents/react";
-import type { RuntimeActivity } from "@springbrand/agent-runtime/contracts";
 
 export interface ChatSessionSummary {
   id: string;
@@ -11,7 +10,7 @@ export interface ChatSessionSummary {
   updatedAt: number;
   pinned: boolean;
   archived: boolean;
-  activity: RuntimeActivity;
+  activity: "idle" | "working" | "needs-input";
   usage?: {
     totalTokens: number;
     totalCost: number;
@@ -25,18 +24,49 @@ interface InboxState {
 
 export const CURRENT_INBOX_AGENT_PATH = "api/agent-connections/inbox";
 
+type Request = typeof fetch;
+
+export async function loadChatSessions(
+  signal?: AbortSignal,
+  request: Request = fetch,
+): Promise<ChatSessionSummary[]> {
+  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 ChatSessionSummary[];
+}
+
 /** 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 [snapshot, setSnapshot] = useState<ChatSessionSummary[]>();
   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?: string) => {
     if (creatingRef.current) return undefined;
     creatingRef.current = true;
     try {
+      await inbox.ready;
       return await inbox.call<ChatSessionSummary>(
         "createChat",
         userAgentId ? [{ userAgentId }] : undefined,
@@ -83,8 +113,9 @@ export function useChatSessions() {
   );
 
   return {
-    chats: inbox.state?.chats ?? [],
-    synced: inbox.state !== undefined,
+    chats: inbox.state?.chats ?? snapshot ?? [],
+    synced: inbox.state !== undefined || snapshot !== undefined,
+    connected: inbox.identified,
     workspaceRev: inbox.state?.workspaceRev ?? 0,
     createChat,
     forkChat,

package/src/index.ts

@@ -1,6 +1,7 @@
 export {
   useUniversalAgentChat,
   type AgentToolRun,
+  type ChatConnectionOptions,
   type ChatRuntime,
 } from "./use-universal-agent-chat";
 export {

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

@@ -1,10 +1,10 @@
 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 type { ChatStatus, FileUIPart, UIMessage } from "ai";
+import type { AgentToolRunState } from "agents";
+import { getAgentMessages, useAgentChat } from "agents/chat/react";
 import { useAgent, useAgentToolEvents } from "agents/react";
 import {
-  USER_STOP_REASON,
   type MessageDelivery,
   type MessageDispatchReceipt,
   type RuntimeQueuedSubmission,
@@ -23,6 +23,92 @@ type FailedDispatch = {
   projection: "message" | "queue";
 };
 
+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 }
+);
+
 type ChatTurnTiming = {
   chatId: string;
   messageId: string;
@@ -47,6 +133,8 @@ const CHAT_TURN_SEGMENTS = {
   ready: ["firstText", "universal-agent.chat.first_text_to_ready"],
 } as const;
 
+const USER_STOP_REASON = "Stopped by user";
+
 function now(): number {
   return typeof performance === "undefined" ? Date.now() : performance.now();
 }
@@ -115,6 +203,19 @@ function queuedPreview(message: ChatMessage): string {
   }).join(" ").trim().slice(0, 160) || "Queued message";
 }
 
+function loadInitialMessages(
+  url: string | undefined,
+  credentials: RequestCredentials | undefined,
+): Promise<ChatMessage[]> {
+  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 }),
+  }) as Promise<ChatMessage[]>;
+}
+
 /**
  * 薄适配层:把 useAgent + UIMessage chat + useAgentToolEvents
  * 收敛成一个归一化 runtime,对外只暴露 messages / 发送 / 状态 / 子 agent 运行,
@@ -126,7 +227,10 @@ function queuedPreview(message: ChatMessage): string {
  * sub 数组由客户端 kebab 化;服务端按 ctx.exports 反解回 CamelCase className,
  * 与 Inbox.onBeforeSubAgent 的严格门卫(hasSubAgent)对齐。
  */
-export function useUniversalAgentChat(chatId: string) {
+export function useUniversalAgentChat(
+  chatId: string,
+  connection: ChatConnectionOptions = {},
+): ChatRuntime {
   const [optimisticMessages, setOptimisticMessages] =
     useState<ChatMessage[]>([]);
   const [optimisticQueued, setOptimisticQueued] =
@@ -135,10 +239,17 @@ export function useUniversalAgentChat(chatId: string) {
   const [canRetry, setCanRetry] = useState(false);
   const failedDispatchRef = useRef<FailedDispatch | undefined>(undefined);
   const activeSubmissionIdRef = useRef<string | undefined>(undefined);
+  const inboxAgent = connection.inboxAgent ?? "Inbox";
   const agent = useAgent<RuntimeState>({
-    agent: "Inbox",
-    basePath: CURRENT_INBOX_AGENT_PATH,
-    sub: [{ agent: "UniversalAgent", name: chatId }],
+    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),
@@ -167,6 +278,11 @@ export function useUniversalAgentChat(chatId: string) {
     connectionError,
   } = useAgentChat<RuntimeState, ChatMessage>({
     agent: chatAgent,
+    getInitialMessages: ({ url }) =>
+      loadInitialMessages(url, connection.credentials),
+    ...(connection.credentials === undefined
+      ? {}
+      : { credentials: connection.credentials }),
     syncMessagesToServer: false,
     throttle: 100,
   });
@@ -287,8 +403,10 @@ export function useUniversalAgentChat(chatId: string) {
 
   // 子 agent 运行(agentTool 前台 + runAgentTool detached 后台)的实时事件投影:
   // 状态机 + progress snapshot + durable milestones(knowledge/upstream-adoption.csv F6)
-  const { runsById } = useAgentToolEvents({ agent });
-  const agentToolRuns = useMemo(
+  const { runsById } = useAgentToolEvents<ChatMessage["parts"][number]>({
+    agent,
+  });
+  const agentToolRuns: AgentToolRunState<ChatMessage["parts"][number]>[] = useMemo(
     () => Object.values(runsById).sort((a, b) => a.order - b.order),
     [runsById],
   );
@@ -538,5 +656,4 @@ export function useUniversalAgentChat(chatId: string) {
   };
 }
 
-export type ChatRuntime = ReturnType<typeof useUniversalAgentChat>;
 export type AgentToolRun = ChatRuntime["agentToolRuns"][number];