@agents24/chat-react 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Agents24 Chat React
 
-Last Updated: 2026-07-13
+Last Updated: 2026-07-15
 
 Headless React primitives for Agents24 chat surfaces.
 
@@ -22,16 +22,17 @@ The package owns thread hydration, older-page pagination, stream/reattach state,
 - `appendStableStreamingTurn(messages, userMessage, assistantMessage)`
 - `upsertStableAssistantMessage(messages, input)`
 - normalized chat message, part, transport, and storage types
+- typed V2 `pendingHitl`, `isResolvingHitl`, and `resumeHitl(...)` controller state/actions in package `0.3.0`
 - `partsFromResponseBlocks(blocks, fallbackText)`
 - `renderChatPart(part, message, renderOptions)`
 - `@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)`, `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.
+`useAgents24ChatController` exposes reactive `threads`, `activeThreadId`, `activeThread`, `activeRunId`, `pendingHitl`, `isResolvingHitl`, `isRefreshingThreads`, `resumeHitl(...)`, `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. V2 resume always reattaches after successful or idempotent resolution so the backend snapshot remains authoritative.
 
 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.
 
-`ChatMessage.parts` is the only render model. Backend `response_blocks` are normalized into ordered parts such as `text`, `tool-get_meteo`, `ui-blocks`, `reasoning`, `approval`, `error`, and `data`. Tool UI is client-owned through `renderPart`, `toolRenderers`, and `fallbackToolRenderer`; the package does not infer English tool labels or group tool rows.
+`ChatMessage.parts` is the only render model. Backend `response_blocks` are normalized into ordered parts such as `text`, `tool-get_meteo`, `ui-blocks`, `reasoning`, `hitl`, `error`, and `data`. The shared compact HITL card renders pending and terminal states for Tool review, MCP authentication, User Approval, and app-data permission. Tool review exposes only **Allow once** and **Don't allow**; Edit and Respond are not part of the contract. Tool UI is client-owned through `renderPart`, `toolRenderers`, and `fallbackToolRenderer`; the package does not infer English tool labels or group tool rows.
 
 `useStreamingText` owns reusable visual pacing for active assistant text. It returns `displayedText`, `isAnimating`, `mode`, and `parseIncompleteMarkdown` so host renderers can pass those values into their markdown component without the package depending on any markdown/UI library. The package only chooses text timing, cache behavior, reduced-motion handling, and active text-part helpers.
 

package/dist/controller-hitl.d.ts

@@ -0,0 +1,22 @@
+import { type MutableRefObject } from "react";
+import type { ChatHitlPart, ChatHitlResumeInput, ChatHitlResumeResult, ChatMessage, ChatTransport } from "./types";
+type RunStream = (input: {
+    mode: "attach";
+    threadId: string;
+    runId: string;
+}) => Promise<void>;
+export declare function useControllerHitl({ messages, transport, activeRunId, activeRunIdRef, activeThreadIdRef, runStream, }: {
+    messages: ChatMessage[];
+    transport: ChatTransport;
+    activeRunId: string | null;
+    activeRunIdRef: MutableRefObject<string | null>;
+    activeThreadIdRef: MutableRefObject<string | null>;
+    runStream: RunStream;
+}): {
+    pendingHitl: ChatHitlPart | null;
+    isResolvingHitl: boolean;
+    resumeHitl: (input: Omit<ChatHitlResumeInput, "runId"> & {
+        runId?: string;
+    }) => Promise<ChatHitlResumeResult>;
+};
+export {};

package/dist/controller-options.d.ts

@@ -0,0 +1,15 @@
+import type { ChatRuntimeEventContext } from "./controller-helpers";
+import type { ChatMessage, ChatRuntimeEvent, ChatStorageAdapter, ChatTransport } from "./types";
+export type UseAgents24ChatControllerOptions = {
+    transport: ChatTransport;
+    storage: ChatStorageAdapter;
+    activeThreadId?: string | null;
+    pageSize?: number;
+    storageKey?: unknown;
+    createId?: () => string;
+    onActiveThreadIdChange?: (threadId: string | null) => void;
+    onSourceClick?: (citations: ChatMessage["citations"]) => void;
+    onStreamErrorMessage?: (error: unknown) => string;
+    onRuntimeEvent?: (event: ChatRuntimeEvent, context: ChatRuntimeEventContext) => void | Promise<void>;
+    onThreadDetailLoaded?: (detail: unknown) => void | Promise<void>;
+};

package/dist/controller-thread-events.d.ts

@@ -0,0 +1,7 @@
+import type { ChatStorageAdapter, ChatTransport, StoredChatThread } from "./types";
+export declare function useControllerThreadEvents({ transport, storage, refresh, setThreads, }: {
+    transport: ChatTransport;
+    storage: ChatStorageAdapter;
+    refresh: () => Promise<void>;
+    setThreads: (threads: StoredChatThread[]) => void;
+}): void;

package/dist/controller.d.ts

@@ -1,17 +1,5 @@
-import { type ChatRuntimeEventContext } from "./controller-helpers";
-import type { ChatController, ChatMessage, ChatRuntimeEvent, ChatStorageAdapter, ChatTransport } from "./types";
+import type { UseAgents24ChatControllerOptions } from "./controller-options";
+import type { ChatController } from "./types";
 export { mergeStoredThreadsForRefresh } from "./controller-helpers";
-export type UseAgents24ChatControllerOptions = {
-    transport: ChatTransport;
-    storage: ChatStorageAdapter;
-    activeThreadId?: string | null;
-    pageSize?: number;
-    storageKey?: unknown;
-    createId?: () => string;
-    onActiveThreadIdChange?: (threadId: string | null) => void;
-    onSourceClick?: (citations: ChatMessage["citations"]) => void;
-    onStreamErrorMessage?: (error: unknown) => string;
-    onRuntimeEvent?: (event: ChatRuntimeEvent, context: ChatRuntimeEventContext) => void | Promise<void>;
-    onThreadDetailLoaded?: (detail: unknown) => void | Promise<void>;
-};
-export declare function useAgents24ChatController({ transport, storage, activeThreadId: controlledActiveThreadId, pageSize, storageKey, createId, onActiveThreadIdChange, onSourceClick, onStreamErrorMessage, onRuntimeEvent, onThreadDetailLoaded, }: UseAgents24ChatControllerOptions): ChatController;
+export type { UseAgents24ChatControllerOptions } from "./controller-options";
+export declare function useAgents24ChatController(options: UseAgents24ChatControllerOptions): ChatController;