@agents24/chat-react 0.1.9 → 0.1.10

package/README.md

@@ -1,6 +1,6 @@
 # Agents24 Chat React
 
-Last Updated: 2026-06-29
+Last Updated: 2026-07-07
 
 Headless React primitives for Agents24 chat surfaces.
 
@@ -19,13 +19,15 @@ The package owns thread hydration, older-page pagination, stream/reattach state,
 - `isActiveStreamingTextPart(message, part, streamingMessageId)`
 - `createFetchChatTransport(options)`
 - `consumeSseResponse(response, onEvent)`
+- `appendStableStreamingTurn(messages, userMessage, assistantMessage)`
+- `upsertStableAssistantMessage(messages, input)`
 - normalized chat message, part, transport, and storage types
 - `partsFromResponseBlocks(blocks, fallbackText)`
 - `renderChatPart(part, message, renderOptions)`
-- `@agents24/chat-react/ui` for shared shadcn-derived `Message`, `Bubble`, `Attachment`, `Marker`, `MessageResponse`, and Agents24 message/attachment adapters
+- `@agents24/chat-react/ui` for shared shadcn-derived `Message`, `Bubble`, `Attachment`, `Marker`, `MessageResponse`, `AgentChatMessage`, `AgentChatComposer`, `McpConnectRequiredCard`, and Agents24 message/attachment adapters
 - `@agents24/chat-react/templates` for the slot-based `AgentChatShell` starter shell
 
-`useAgents24ChatController` exposes reactive `threads`, `activeThreadId`, `activeThread`, `activeRunId`, `isRefreshingThreads`, `loadThreadById(threadId)`, and `startNewThread()` in addition to message and stream state. It hydrates selected threads, detects active runs from `active_run`/`last_run_status`, attaches through the host transport, detaches local SSE streams on navigation, and refreshes history after terminal events.
+`useAgents24ChatController` exposes reactive `threads`, `activeThreadId`, `activeThread`, `activeRunId`, `isRefreshingThreads`, `loadThreadById(threadId)`, `attachRun(runId, threadId)`, and `startNewThread()` in addition to message and stream state. It hydrates selected threads, detects active runs from `active_run`/`last_run_status`, attaches through the host transport, detaches local SSE streams on navigation, and refreshes history after terminal events.
 
 Hosts can pass `onRuntimeEvent(event, context)` and `onThreadDetailLoaded(detail)` to layer product-specific runtime UI, trace panels, analytics, or metadata over the shared chat lifecycle without forking stream handling. That surface is enough for running-history badges and read-only live thread inspectors without a separate host-owned reattach state machine.
 
@@ -35,6 +37,10 @@ Hosts can pass `onRuntimeEvent(event, context)` and `onThreadDetailLoaded(detail
 
 Network access is always injected by the host. This browser package never requires platform API keys.
 
+## Message Lifecycle
+
+Chat surfaces should keep active assistant turns as stable rows in `messages`: append the user row and assistant placeholder together, stream updates into that assistant `messageId`, finalize that same row in place, then clear the streaming marker. `appendStableStreamingTurn` and `upsertStableAssistantMessage` centralize that invariant for custom hosts. Avoid host-side synthetic assistant rows because removing and re-adding the same response can flicker and can make MessageScroller treat the turn as new content.
+
 ## MessageScroller Behavior
 
 The package re-exports shadcn `@shadcn/react/message-scroller` and provides `LatestThreadScroller`, a thin native preset around the official primitives. Host chat shells should prefer:
@@ -53,4 +59,10 @@ The preset defaults to `autoScroll`, `defaultScrollPosition="last-anchor"`, `scr
 
 `@agents24/chat-react/ui` contains package-owned source adapted from the shadcn CLI `message`, `bubble`, `attachment`, and `marker` components. Base primitive names stay close to shadcn, while Agents24-specific compatibility adapters sit beside them as `Message`, `MessageContent`, `MessageActions`, `MessageAction`, `MessageAttachments`, `MessageAttachment`, and `MessageResponse`.
 
-`@agents24/chat-react/templates` exposes `AgentChatShell`, a convenience shell that composes `LatestThreadScroller`, the outline rail, latest button, composer overlay spacing, older-history trigger, and message slots. Product apps still own transport, citations, TTS, source panes, artifact actions, and row-specific rendering.
+`AgentChatMessage` and `AgentChatComposer` provide the default customer starter UI used by `AgentChatShell` consumers that want a platform-playground-like baseline without importing platform internals. Hosts can still replace assistant/user message bodies, actions, HITL side effects, and toolbar controls through composition slots.
+
+`AgentChatMessage` collapses long user messages by default to keep bubbles compact. The default user bubble shows a four-line preview with `Show more` / `Show less` controls, and hosts can tune the threshold, visible lines, or labels through the `userMessage*` props.
+
+`@agents24/chat-react/templates` exposes `AgentChatShell`, a convenience shell that composes `LatestThreadScroller`, the outline rail, latest button, composer overlay spacing, older-history trigger, scroll-state reporting, and message slots. Product apps still own transport, citations, TTS, source panes, artifact actions, and row-specific rendering.
+
+The starter shell is suitable for public/shared chat pages and customer apps. Internal playground/admin controls such as traces, debug actions, source viewers, citations, TTS, artifacts, and approval side effects remain host-owned extensions.

package/dist/controller-actions.d.ts

@@ -0,0 +1,45 @@
+import { type Dispatch, type MutableRefObject, type SetStateAction } from "react";
+import type { ChatCitation, ChatMessage, ChatReasoningStep, ChatStorageAdapter, ChatSubmitMessage } from "./types";
+type PagingRef = MutableRefObject<number | null>;
+export declare function useControllerMessageActions(input: {
+    activeThreadIdRef: MutableRefObject<string | null>;
+    createId: () => string;
+    detachActiveStream: () => void;
+    disliked: Record<string, boolean>;
+    handleSubmit: (message: ChatSubmitMessage) => Promise<void>;
+    hasOlderTurnsRef: MutableRefObject<boolean>;
+    liked: Record<string, boolean>;
+    liveVoiceIdsRef: MutableRefObject<{
+        user?: string;
+        assistant?: string;
+    }>;
+    loadedThreadIdRef: MutableRefObject<string | null>;
+    messagesRef: MutableRefObject<ChatMessage[]>;
+    nextBeforeTurnIndexRef: PagingRef;
+    onActiveThreadIdChange?: (threadId: string | null) => void;
+    persistThread: (threadId: string, nextMessages: ChatMessage[]) => void;
+    requestSeqRef: MutableRefObject<number>;
+    setContextStatus: Dispatch<SetStateAction<any>>;
+    setCopiedMessageId: Dispatch<SetStateAction<string | null>>;
+    setDisliked: Dispatch<SetStateAction<Record<string, boolean>>>;
+    setHasOlderTurns: Dispatch<SetStateAction<boolean>>;
+    setIsLoadingOlder: Dispatch<SetStateAction<boolean>>;
+    setLiked: Dispatch<SetStateAction<Record<string, boolean>>>;
+    setLoadingHistory: (value: boolean) => void;
+    setMessages: Dispatch<SetStateAction<ChatMessage[]>>;
+    storage: ChatStorageAdapter;
+}): {
+    handleCopy: (content: string, messageId: string) => void;
+    handleDislike: (msg: ChatMessage) => Promise<void>;
+    handleLike: (msg: ChatMessage) => Promise<void>;
+    handleRetry: (msg: ChatMessage) => Promise<void>;
+    startNewThread: () => void;
+    upsertLiveVoiceMessage: (payload: {
+        role: "user" | "assistant";
+        content: string;
+        isFinal?: boolean;
+        citations?: ChatCitation[];
+        reasoningSteps?: ChatReasoningStep[];
+    }) => void;
+};
+export {};

package/dist/controller-helpers.d.ts

@@ -0,0 +1,27 @@
+import type { ChatMessage, ChatReasoningStep, ChatPart, ChatThreadSummaryEvent, StoredChatThread } from "./types";
+export type ChatRuntimeEventContext = {
+    mode: "submit" | "attach";
+    assistantMessageId: string;
+    threadId: string | null;
+    runId: string | null;
+    startedAt: number;
+};
+export type FinalizeInput = {
+    threadId: string | null;
+    baseMessages: ChatMessage[];
+    assistantText: string;
+    reasoning: ChatReasoningStep[];
+    thinkingDurationMs: number;
+    messageId?: string | null;
+    runId?: string | null;
+    parts?: ChatPart[];
+    error?: string;
+};
+export declare const threadSummaryToStored: (thread: Record<string, unknown>) => StoredChatThread;
+export declare const isThreadNotFoundError: (error: unknown) => boolean;
+export declare const isAbortError: (error: unknown) => boolean;
+export declare const abortDetachedStream: (controller: AbortController | null) => void;
+export declare const mergeStoredThreadsForRefresh: (currentThreads: StoredChatThread[], serverThreads: StoredChatThread[]) => StoredChatThread[];
+export declare const hasRunningStoredThreads: (threads: StoredChatThread[]) => boolean;
+export declare const sameStoredThread: (left: StoredChatThread | undefined, right: StoredChatThread | undefined) => boolean;
+export declare const applyThreadSummaryEvent: (currentThreads: StoredChatThread[], event: ChatThreadSummaryEvent) => StoredChatThread[];

package/dist/controller.d.ts

@@ -1,11 +1,6 @@
+import { type ChatRuntimeEventContext } from "./controller-helpers";
 import type { ChatController, ChatMessage, ChatRuntimeEvent, ChatStorageAdapter, ChatTransport } from "./types";
-export type ChatRuntimeEventContext = {
-    mode: "submit" | "attach";
-    assistantMessageId: string;
-    threadId: string | null;
-    runId: string | null;
-    startedAt: number;
-};
+export { mergeStoredThreadsForRefresh } from "./controller-helpers";
 export type UseAgents24ChatControllerOptions = {
     transport: ChatTransport;
     storage: ChatStorageAdapter;