@agents24/react 0.1.0 → 0.2.1

package/dist/model.d.ts

@@ -1,6 +1,7 @@
-import type { AttachmentResult, HitlAction, RuntimeEvent, ThreadDetail, ThreadSummary } from "@agents24/client";
+import type { AttachmentResult, FailureView, HitlAction, ResponseFeedback, RuntimeEvent, ThreadDetail, ThreadSummary } from "@agents24/client";
+import { type ContextCompression, type ContextWindow } from "@agents24/client/protocol";
 export type AgentChatMessageRole = "user" | "assistant";
-export type AgentChatRunState = "idle" | "streaming" | "reconnecting" | "paused" | "completed" | "failed";
+export type AgentChatRunState = "idle" | "streaming" | "reconnecting" | "paused" | "cancelling" | "completed" | "cancelled" | "failed";
 export type ChatCitation = {
     title: string;
     url: string;
@@ -17,38 +18,106 @@ export type ChatAttachment = {
     status?: string;
     [key: string]: unknown;
 };
+export declare function chatAttachmentIds(attachments?: readonly ChatAttachment[]): string[];
 export type ChatToolState = "input-streaming" | "input-available" | "output-available" | "output-error" | "cancelled";
-export type ChatTextPart = {
+export type ChatPartMetadata = {
     id: string;
+    runId?: string | null;
+    sequence?: number | null;
+    timestamp?: string | null;
+    raw?: Record<string, unknown>;
+};
+export type ChatToolChildRun = {
+    runId?: string | null;
+    agentId?: string | null;
+    agentName?: string | null;
+    status?: string | null;
+    error?: string | null;
+};
+export type ChatToolChild = {
+    id: string;
+    runId?: string | null;
+    toolCallId?: string | null;
+    toolName: string;
+    title: string;
+    status: string;
+    detail?: string | null;
+    sequence?: number | null;
+    timestamp?: string | null;
+};
+export type ChatToolPresentation = Record<string, unknown> & {
+    title?: string | null;
+    activity?: string | null;
+    detail?: string | null;
+    category?: string | null;
+    groupKey?: string | null;
+    groupLabel?: string | null;
+    path?: string | null;
+    threadId?: string | null;
+    isExploration?: boolean;
+    childRun?: ChatToolChildRun | null;
+    childTools?: ChatToolChild[];
+    activeChildToolId?: string | null;
+};
+export type ChatTextPart = ChatPartMetadata & {
     type: "text";
     kind: "text";
     text: string;
-    raw?: Record<string, unknown>;
 };
-export type ChatToolPart = {
-    id: string;
+export type ChatToolPart = ChatPartMetadata & {
     type: `tool-${string}`;
     kind: "tool";
     toolName: string;
+    toolKey?: string | null;
+    action?: string | null;
+    displayName?: string | null;
+    summary?: string | null;
     toolCallId?: string | null;
+    sourceKind?: string | null;
     state: ChatToolState;
     input?: unknown;
     output?: unknown;
     errorText?: string | null;
-    presentation?: Record<string, unknown> | null;
-    raw: Record<string, unknown>;
+    failure?: FailureView | null;
+    presentation: ChatToolPresentation;
 };
-export type ChatReasoningPart = {
-    id: string;
+export type ChatReasoningPart = ChatPartMetadata & {
     type: "reasoning";
     kind: "reasoning";
     label?: string | null;
     text?: string | null;
     status?: string | null;
-    raw: Record<string, unknown>;
 };
-export type ChatUiBlocksPart = {
-    id: string;
+export type ChatModelTurnPart = ChatPartMetadata & {
+    type: "model-turn";
+    kind: "model-turn";
+    modelTurnId: string;
+    turnKind: "agent" | "model";
+    status: "running";
+    iteration?: number | null;
+};
+export type ChatContextCompressionPart = ChatPartMetadata & {
+    type: "context-compression";
+    kind: "context-compression";
+    status: "started" | "completed" | "failed";
+    compression: ContextCompression;
+};
+export type ChatNodeActivityState = "running" | "completed" | "failed" | "cancelled" | "skipped";
+export type ChatNodeSkipReason = "missing_required_input" | "upstream_input_unavailable" | "empty_optional_source";
+export type ChatNodeActivityPart = ChatPartMetadata & {
+    type: "node-activity";
+    kind: "node-activity";
+    activityId: string;
+    /** Opaque trusted-host trace selector; absent from public projections. */
+    traceStepId?: string | null;
+    label: string;
+    nodeKind: string;
+    status: ChatNodeActivityState;
+    defaultChatVisible: boolean;
+    reason?: ChatNodeSkipReason | null;
+    failure?: FailureView | null;
+};
+export type ChatUiBlocksPart = ChatPartMetadata & {
     type: "ui-blocks";
     kind: "ui-blocks";
     state: ChatToolState;
@@ -56,12 +125,30 @@ export type ChatUiBlocksPart = {
     contractVersion?: string | null;
     bundle?: Record<string, unknown> | null;
     errorText?: string | null;
-    raw: Record<string, unknown>;
 };
-export type ChatHitlKind = "tool_review" | "mcp_auth" | "user_approval" | "app_data_permission";
+export type ChatHitlKind = "tool_review" | "mcp_auth" | "user_approval" | "app_data_permission" | "user_input";
 export type ChatHitlStatus = "pending" | "resolved" | "expired" | "cancelled" | "invalidated";
-export type ChatHitlPart = {
+export type ChatHitlQuestion = {
     id: string;
+    header: string;
+    question: string;
+    options: Array<{
+        id: string;
+        label: string;
+    }>;
+    multiSelect: boolean;
+};
+export type ChatHitlAnswer = {
+    questionId: string;
+    selectedOptionIds: string[];
+    customText?: string;
+};
+export type ChatHitlResolution = Record<string, unknown> & {
+    answers?: ChatHitlAnswer[];
+    outcome?: string;
+    status?: string;
+};
+export type ChatHitlPart = ChatPartMetadata & {
     type: "hitl";
     kind: "hitl";
     interruptId: string;
@@ -70,50 +157,41 @@ export type ChatHitlPart = {
     allowedActions: HitlAction[];
     status: ChatHitlStatus;
     presentation: Record<string, unknown>;
-    resolution?: Record<string, unknown> | null;
-    raw: Record<string, unknown>;
+    questions: ChatHitlQuestion[];
+    resolution?: ChatHitlResolution | null;
 };
-export type ChatErrorPart = {
-    id: string;
+export type ChatErrorPart = ChatPartMetadata & {
     type: "error";
     kind: "error";
     errorText: string;
-    raw: Record<string, unknown>;
+    failure?: FailureView | null;
 };
-export type ChatDataPart = {
-    id: string;
+export type ChatDataPart = ChatPartMetadata & {
     type: "data";
     kind: "data";
     name: string;
     data: Record<string, unknown>;
-    raw: Record<string, unknown>;
 };
-export type ChatSourcePart = {
-    id: string;
+export type ChatSourcePart = ChatPartMetadata & {
     type: "source";
     kind: "source";
     title: string;
     url?: string | null;
     description?: string | null;
-    raw: Record<string, unknown>;
 };
-export type ChatCitationPart = {
-    id: string;
+export type ChatCitationPart = ChatPartMetadata & {
     type: "citation";
     kind: "citation";
     sourceId?: string | null;
     label?: string | null;
     url?: string | null;
-    raw: Record<string, unknown>;
 };
-export type ChatAttachmentPart = {
-    id: string;
+export type ChatAttachmentPart = ChatPartMetadata & {
     type: "attachment";
     kind: "attachment";
     attachment: ChatAttachment;
-    raw: Record<string, unknown>;
 };
-export type ChatPart = ChatTextPart | ChatToolPart | ChatReasoningPart | ChatUiBlocksPart | ChatHitlPart | ChatErrorPart | ChatDataPart | ChatSourcePart | ChatCitationPart | ChatAttachmentPart;
+export type ChatPart = ChatTextPart | ChatToolPart | ChatReasoningPart | ChatModelTurnPart | ChatContextCompressionPart | ChatNodeActivityPart | ChatUiBlocksPart | ChatHitlPart | ChatErrorPart | ChatDataPart | ChatSourcePart | ChatCitationPart | ChatAttachmentPart;
 export type ChatMessage = {
     id: string;
     role: AgentChatMessageRole;
@@ -124,8 +202,7 @@ export type ChatMessage = {
     parts: ChatPart[];
     attachments?: ChatAttachment[];
     citations?: ChatCitation[];
-    liked?: boolean;
-    disliked?: boolean;
+    feedback?: ResponseFeedback | null;
     messageIndex?: number;
     reasoningSteps?: Array<Record<string, unknown>>;
     thinkingDurationMs?: number;
@@ -142,11 +219,29 @@ export type StoredChatThread = ThreadSummary & {
     isHydrated?: boolean;
     hasOlderTurns?: boolean;
     nextBeforeTurnIndex?: number | null;
+    contextWindow?: ContextWindow | null;
+    contextCompression?: ContextCompression | null;
+};
+export type ThreadActivity = {
+    status: string | null;
+    runId: string | null;
+    isSpinning: boolean;
+    isPaused: boolean;
+    isFailed: boolean;
+    isCompleted: boolean;
+    isCancelled: boolean;
 };
-export declare function partsFromResponseBlocks(blocks: unknown, fallbackText?: string): ChatPart[];
+export declare function getThreadActivity(thread: Pick<ThreadSummary, "active_run" | "last_run_id" | "last_run_status">): ThreadActivity;
+export declare function partsFromResponseBlocks(blocks: unknown, fallbackText?: string, fallbackPartId?: string): ChatPart[];
 export declare function assistantProjectionFromEvent(event: RuntimeEvent): {
     content: string;
     parts: ChatPart[];
 };
+export declare function modelTurnPartFromEvent(event: RuntimeEvent): ChatModelTurnPart | null;
+export declare function contextCompressionPartFromEvent(event: RuntimeEvent, existingParts?: readonly ChatPart[]): ChatContextCompressionPart | null;
 export declare function threadDetailToMessages(detail: ThreadDetail): ChatMessage[];
+export declare function latestThreadContext(detail: ThreadDetail): {
+    contextWindow: ContextWindow | null;
+    contextCompression: ContextCompression | null;
+};
 export declare function attachmentResultToChatAttachment(result: AttachmentResult): ChatAttachment;

package/dist/runtime-event-buffer.d.ts

@@ -0,0 +1,9 @@
+import type { RuntimeEvent } from "@agents24/client";
+export type RuntimeEventFrameScheduler = (callback: () => void) => () => void;
+export type RuntimeEventFrameBuffer = {
+    dispose(): void;
+    flush(): void;
+    push(event: RuntimeEvent): void;
+};
+export declare function runtimeEventFrameScheduler(): RuntimeEventFrameScheduler | undefined;
+export declare function createRuntimeEventFrameBuffer(apply: (events: readonly RuntimeEvent[]) => void, scheduleFrame?: RuntimeEventFrameScheduler): RuntimeEventFrameBuffer;

package/dist/state.d.ts

@@ -1,5 +1,17 @@
 import type { RuntimeEvent, ThreadSummaryEvent } from "@agents24/client";
+import { type ContextCompression, type ContextWindow } from "@agents24/client/protocol";
 import type { ChatMessage, StoredChatThread } from "./model";
+export type AgentChatOperation = "attach_run" | "cancel_run" | "delete_thread" | "load_more_threads" | "load_older_turns" | "open_thread" | "refresh_threads" | "resume_hitl" | "set_feedback" | "submit";
+export type AgentChatOperationError = {
+    kind: "operation";
+    operation: AgentChatOperation;
+    cause: unknown;
+};
+export type AgentChatBackgroundError = {
+    kind: "background";
+    source: "thread_events";
+    cause: unknown;
+};
 export type AgentChatState = {
     threads: StoredChatThread[];
     activeThreadId: string | null;
@@ -7,10 +19,30 @@ export type AgentChatState = {
     activeRunId: string | null;
     cursor: number | null;
     streamingMessageId: string | null;
-    runState: "idle" | "streaming" | "reconnecting" | "paused" | "completed" | "failed";
+    contextWindow: ContextWindow | null;
+    contextCompression: ContextCompression | null;
+    contextCompressionRevision: number;
+    runState: "idle" | "streaming" | "reconnecting" | "paused" | "cancelling" | "completed" | "cancelled" | "failed";
+    /** Fatal chat initialization/session failures only. */
     error: unknown;
+    /** The latest user-visible operation failure. It must not replace the transcript. */
+    operationError: AgentChatOperationError | null;
+    /** Failure of a non-blocking background synchronization lane. */
+    backgroundError: AgentChatBackgroundError | null;
 };
 export declare const initialAgentChatState: AgentChatState;
+export type AgentChatThreadSelectionSnapshot = Pick<AgentChatState, "activeRunId" | "activeThreadId" | "cursor" | "messages" | "runState" | "streamingMessageId" | "contextWindow" | "contextCompression" | "contextCompressionRevision">;
+export declare function captureAgentChatThreadSelection(state: AgentChatState): AgentChatThreadSelectionSnapshot;
+export declare function restoreAgentChatThreadSelection(state: AgentChatState, snapshot: AgentChatThreadSelectionSnapshot): AgentChatState;
+export declare function withAgentChatOperationError(state: AgentChatState, operation: AgentChatOperation, cause: unknown): AgentChatState;
+export declare function clearAgentChatOperationError(state: AgentChatState, operation?: AgentChatOperation): AgentChatState;
+export declare function withAgentChatBackgroundError(state: AgentChatState, cause: unknown): AgentChatState;
+export declare function clearAgentChatBackgroundError(state: AgentChatState): AgentChatState;
+/**
+ * Reconcile the authoritative first page without dropping a locally-created
+ * active thread before it becomes visible in the server's list projection.
+ */
+export declare function reconcileRefreshedThreads(current: StoredChatThread[], incoming: StoredChatThread[], activeThreadId: string | null): StoredChatThread[];
 export type StableChatMessageBase = {
     id: string;
     role: "user" | "assistant";
@@ -26,4 +58,5 @@ export type StableAssistantUpsertInput<TMessage extends StableChatMessageBase> =
 export declare function appendStableStreamingTurn<TMessage extends StableChatMessageBase>(messages: TMessage[], userMessage: TMessage, assistantMessage: TMessage): TMessage[];
 export declare function upsertStableAssistantMessage<TMessage extends StableChatMessageBase>(messages: TMessage[], input: StableAssistantUpsertInput<TMessage>): TMessage[];
 export declare function applyRuntimeEvent(state: AgentChatState, event: RuntimeEvent): AgentChatState;
+export declare function applyRuntimeEvents(state: AgentChatState, events: readonly RuntimeEvent[]): AgentChatState;
 export declare function applyThreadSummaryEvent(threads: StoredChatThread[], event: ThreadSummaryEvent): StoredChatThread[];

package/dist/use-agent-chat.d.ts

@@ -1,6 +1,6 @@
-import type { AgentClient, HitlAction } from "@agents24/client";
+import type { AgentClient, FeedbackReason, HitlResponse } from "@agents24/client";
 import type { ChatAttachment, ChatHitlPart, ChatMessage, StoredChatThread } from "./model";
-import { type AgentChatState } from "./state";
+import { type AgentChatOperation, type AgentChatState } from "./state";
 export type AgentChatSubmitInput = {
     text: string;
     attachmentIds?: readonly string[];
@@ -24,6 +24,8 @@ export type AgentChatController = AgentChatState & {
     isSubmitting: boolean;
     attachRun(runId: string, cursor?: number): Promise<void>;
     cancelRun(): Promise<void>;
+    clearBackgroundError(): void;
+    clearOperationError(operation?: AgentChatOperation): void;
     deleteThread(threadId: string): Promise<void>;
     detach(): void;
     loadOlder(): Promise<void>;
@@ -31,7 +33,12 @@ export type AgentChatController = AgentChatState & {
     openThread(threadId: string): Promise<void>;
     refreshThreads(): Promise<void>;
     regenerate(message: ChatMessage): Promise<void>;
-    resumeHitl(part: ChatHitlPart, action: HitlAction, comment?: string): Promise<void>;
+    resumeHitl(part: ChatHitlPart, response: HitlResponse): Promise<void>;
+    setFeedback(message: ChatMessage, input: {
+        rating: "like" | "dislike" | null;
+        reason?: FeedbackReason | null;
+        comment?: string | null;
+    }): Promise<void>;
     startNewThread(): void;
     submit(input: AgentChatSubmitInput): Promise<void>;
 };

package/dist/use-agent-resources.d.ts

@@ -12,7 +12,6 @@ export declare function useAgentThreads(options?: {
 export declare function useAgentThread(threadId: string | null, options?: {
     limit?: number;
     beforeTurnIndex?: number;
-    includeRunEvents?: boolean;
 }): {
     error: unknown;
     isLoading: boolean;
@@ -27,14 +26,21 @@ export declare function useAgentRun(): {
     isAttached: boolean;
 };
 export declare function useAgentAttachments(): {
+    createContentAccess: (input: {
+        attachmentId: string;
+        disposition: "inline" | "attachment";
+        signal?: AbortSignalLike;
+    }) => Promise<import("@agents24/client").AttachmentContentAccess>;
     isUploading: boolean;
-    upload: (input: {
-        data: BinaryUploadData;
-        name: string;
-        mediaType: string;
+    uploadBatch: (input: {
+        uploads: readonly {
+            data: BinaryUploadData;
+            name: string;
+            mediaType: string;
+        }[];
         threadId?: string;
         signal?: AbortSignalLike;
-    }) => Promise<import("./model").ChatAttachment>;
+    }) => Promise<import("./model").ChatAttachment[]>;
     uploads: Record<string, AttachmentResult>;
 };
 export declare function useAgentHitl(): {
@@ -45,6 +51,7 @@ export declare function useAgentHitl(): {
         interruptId: string;
         action: HitlAction;
         comment?: string;
+        answers?: import("@agents24/client").HitlAnswer[];
         signal?: AbortSignalLike;
     }) => Promise<HitlResumeResult>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents24/react",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "DOM-free React state and hooks for Agents24 client applications.",
   "license": "MIT",
   "repository": {
@@ -40,7 +40,7 @@
     "prepack": "pnpm run build && pnpm run check:boundaries"
   },
   "dependencies": {
-    "@agents24/client": "0.1.0"
+    "@agents24/client": "0.2.1"
   },
   "peerDependencies": {
     "react": ">=19.0.0 <20.0.0"