@agents24/chat-react 0.2.0 → 0.3.1

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,20 @@ 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`
+- strict HITL response-block parsing and `waitForMcpOauthComplete(...)` for validated host-owned OAuth popup completion
 - `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 HITL action strip renders a neutral, borderless pending state and a compact terminal outcome for Tool review, MCP authentication, User Approval, and app-data permission. Tool review exposes only **Allow once** and **Don't allow**; verbose risk metadata, argument details, Edit, and Respond are not part of the chat presentation. Tool UI is client-owned through `renderPart`, `toolRenderers`, and `fallbackToolRenderer`; the package does not infer English tool labels or group tool rows.
+
+MCP OAuth remains a host side effect. `startMcpAuth(...)` returns both `authorization_url` and the authoritative `callback_origin`; hosts open the popup and pass both values to `waitForMcpOauthComplete(...)` before calling `resumeHitl(...)`. The utility verifies popup identity, callback origin, server identity, and connection UUID and owns timeout/close cleanup.
 
 `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;