@agents24/react 0.2.26 → 0.2.28

package/compatibility.json

@@ -47,8 +47,8 @@
   },
   "schemaVersion": "agents24.compatibility.v1",
   "targetOperationCounts": {
-    "client": 31,
-    "node": 139,
-    "python": 132
+    "client": 36,
+    "node": 196,
+    "python": 190
   }
 }

package/dist/assistant-preview.d.ts

@@ -0,0 +1,18 @@
+/** Ephemeral display only: these fragments never enter stored messages or replay cursors. */
+import type { AssistantPreview } from "@agents24/client/protocol";
+import type { RuntimeEvent } from "@agents24/client";
+import type { ChatMessage } from "./model";
+export type AssistantPreviewState = {
+    runId: string;
+    key: string;
+    segmentId: string;
+    committed: number;
+    dispatchId: string;
+    generation: number;
+    chunks: Record<number, string>;
+    retired: string[];
+};
+export declare function acceptAssistantPreview(current: AssistantPreviewState | null | undefined, frame: AssistantPreview | null): AssistantPreviewState | null;
+export declare function commitAssistantPreview(current: AssistantPreviewState | null | undefined, event: RuntimeEvent): AssistantPreviewState | null;
+export declare function previewText(state: AssistantPreviewState | null | undefined): string;
+export declare function messagesWithAssistantPreview(messages: ChatMessage[], state: AssistantPreviewState | null | undefined): ChatMessage[];

package/dist/index.js

@@ -637,6 +637,79 @@ function createRuntimeEventFrameBuffer(apply, scheduleFrame) {
   };
 }
 
+// src/assistant-preview.ts
+var keyOf = (frame) => `${frame.dispatch_id}:${frame.generation}:${frame.segment_id}`;
+function acceptAssistantPreview(current, frame) {
+  if (!frame) return current ? { ...current, chunks: {} } : null;
+  const key = keyOf(frame);
+  if (current?.runId === frame.run_id && current.dispatchId === frame.dispatch_id && current.generation > frame.generation) return current;
+  if (current?.runId === frame.run_id && current.retired.includes(key)) return current;
+  const state = current?.runId === frame.run_id && current.key === key ? current : {
+    runId: frame.run_id,
+    dispatchId: frame.dispatch_id,
+    generation: frame.generation,
+    key,
+    segmentId: frame.segment_id,
+    committed: -1,
+    chunks: {},
+    retired: current?.runId === frame.run_id ? [...current.retired, current.key].slice(-8) : []
+  };
+  if (frame.chunk_index <= state.committed || Object.keys(state.chunks).length >= 32 || Object.values(state.chunks).reduce((size, text2) => size + text2.length, 0) + frame.text.length > 65536) return state;
+  return { ...state, chunks: { ...state.chunks, [frame.chunk_index]: frame.text } };
+}
+function commitAssistantPreview(current, event) {
+  if (event.event === "run.accepted" && current && current.runId !== event.run_id) return null;
+  if (current && current.runId !== event.run_id) return current;
+  if (["assistant.completed", "run.completed", "run.failed", "run.cancelled", "run.waiting", "run.interrupted", "run.paused", "run.snapshot"].includes(event.event)) return null;
+  const ack = event.payload.preview_ack;
+  if (event.event !== "assistant.delta" || !ack || typeof ack.dispatch_id !== "string" || typeof ack.segment_id !== "string" || !Number.isSafeInteger(ack.generation) || !Number.isSafeInteger(ack.chunk_index)) return current || null;
+  const key = keyOf(ack);
+  if (current && current.key !== key) return current;
+  const committed = Math.max(current?.committed ?? -1, ack.chunk_index);
+  return {
+    runId: event.run_id,
+    dispatchId: ack.dispatch_id,
+    generation: ack.generation,
+    key,
+    segmentId: ack.segment_id,
+    committed,
+    retired: current?.retired || [],
+    chunks: Object.fromEntries(Object.entries(current?.chunks || {}).filter(([index]) => Number(index) > committed))
+  };
+}
+function previewText(state) {
+  if (!state) return "";
+  let text2 = "";
+  for (let index = state.committed + 1; Object.hasOwn(state.chunks, index); index++) text2 += state.chunks[index];
+  return text2;
+}
+function messagesWithAssistantPreview(messages, state) {
+  const tail = previewText(state);
+  if (!state || !tail) return messages;
+  let index = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === "assistant" && messages[i].runId === state.runId && !messages[i].isFinal) {
+      index = i;
+      break;
+    }
+  }
+  const base = index < 0 ? {
+    id: `preview-${state.runId}`,
+    role: "assistant",
+    runId: state.runId,
+    content: "",
+    parts: [],
+    createdAt: /* @__PURE__ */ new Date(0),
+    isFinal: false
+  } : messages[index];
+  const parts = [...base.parts];
+  const last = parts[parts.length - 1];
+  if (last?.type === "text") parts[parts.length - 1] = { ...last, text: last.text + tail };
+  else parts.push({ id: `preview-${state.segmentId}`, type: "text", kind: "text", text: tail });
+  const rendered = { ...base, content: base.content + tail, parts };
+  return index < 0 ? [...messages, rendered] : messages.map((message, i) => i === index ? rendered : message);
+}
+
 // src/hitl-resolution.ts
 function applyHitlResolution(messages, receipt) {
   return messages.map((message) => message.runId !== receipt.run_id ? message : {
@@ -856,11 +929,11 @@ function reconcileModelTurnParts(parts, event) {
   const terminal = eventName === "run.completed" || eventName === "run.failed" || eventName === "run.cancelled";
   const modelTurnId = typeof payload.model_turn_id === "string" ? payload.model_turn_id : null;
   let next = parts;
-  if (eventName === "run.snapshot" || eventName === "assistant.completed" || terminal) {
+  if (["run.snapshot", "run.waiting", "run.interrupted", "run.paused", "assistant.completed"].includes(eventName) || terminal) {
     next = next.filter((part) => part.kind !== "model-turn");
   } else if (eventName === "assistant.delta" && typeof payload.content === "string" && payload.content) {
     next = next.filter((part) => part.kind !== "model-turn" || part.turnKind !== "agent");
-  } else if (eventName.startsWith("tool.") || eventName === "node.status.updated") {
+  } else if (eventName === "tool.started") {
     next = next.filter((part) => part.kind !== "model-turn" || part.turnKind !== "agent");
   } else if ((eventName === "model.turn.failed" || eventName === "model.turn.completed" && payload.outcome !== "tool_calls") && modelTurnId) {
     next = next.filter((part) => part.kind !== "model-turn" || part.modelTurnId !== modelTurnId);
@@ -869,6 +942,11 @@ function reconcileModelTurnParts(parts, event) {
   return active ? upsertResponseBlockParts(next, [active]) : next;
 }
 function applyRuntimeEvent(state, event) {
+  const next = applyCanonicalRuntimeEvent(state, event);
+  if (!state.assistantPreview && !event.payload.preview_ack) return next;
+  return { ...next, assistantPreview: commitAssistantPreview(state.assistantPreview, event) };
+}
+function applyCanonicalRuntimeEvent(state, event) {
   if (state.activeRunId && event.run_id && event.run_id !== state.activeRunId) {
     const previous = state.messages.find((message) => message.role === "assistant" && message.runId === event.run_id);
     if (event.event !== "run.accepted") {
@@ -906,12 +984,24 @@ function applyRuntimeEvent(state, event) {
   const distinctSegment = Boolean(segmentId && segmentId !== `${runId}:0`);
   const messageId = distinctSegment ? `${runId || "run"}-assistant-${segmentId}` : state.streamingMessageId || `${runId || "run"}-assistant`;
   const terminal = eventName === "run.completed" || eventName === "run.failed" || eventName === "run.cancelled";
-  const paused = eventName === "run.paused" || projection.parts.some((part) => part.kind === "hitl" && part.status === "pending");
-  const suspension = eventName === "run.waiting" ? "waiting" : eventName === "run.interrupted" ? "interrupted" : null;
+  const snapshotStatus = eventName === "run.snapshot" ? event.payload?.status : null;
+  const paused = eventName === "run.paused" || snapshotStatus === "paused" || projection.parts.some((part) => part.kind === "hitl" && part.status === "pending");
+  const retainedSuspension = !eventName.startsWith("run.") && !["model.turn.started", "assistant.delta", "tool.started"].includes(eventName) && (state.runState === "waiting" || state.runState === "interrupted") ? state.runState : null;
+  const suspension = eventName === "run.waiting" || snapshotStatus === "waiting" ? "waiting" : eventName === "run.interrupted" || snapshotStatus === "interrupted" ? "interrupted" : retainedSuspension;
   const cancelling = eventName === "run.cancelling" || String(event.payload?.status || "") === "cancelling";
   const existing = state.messages.find((message) => message.role === "assistant" && message.id === messageId) || (!distinctSegment ? state.messages.find((message) => message.role === "assistant" && Boolean(runId && message.runId === runId)) : void 0);
   const sealedAfterTerminal = responseCompleted && !state.activeRunId && ["completed", "failed", "cancelled"].includes(state.runState) && existing?.runId === runId;
   const payload = event.payload || {};
+  const wait = payload.capacity_wait;
+  const capacityWait = wait && typeof wait.reason === "string" ? {
+    reason: wait.reason,
+    ...typeof wait.retry_at === "string" ? { retryAt: wait.retry_at } : {},
+    ...typeof wait.deadline === "string" ? { deadline: wait.deadline } : {}
+  } : state.runState === "waiting" ? existing?.activity?.capacityWait : void 0;
+  const activity = terminal || paused || responseCompleted || existing?.responseCompletion ? void 0 : {
+    status: suspension || (cancelling ? "cancelling" : "running"),
+    ...suspension === "waiting" && capacityWait ? { capacityWait } : {}
+  };
   const eventThreadId = typeof payload.thread_id === "string" && payload.thread_id.trim() ? payload.thread_id.trim() : null;
   const contextApplies = (!state.activeThreadId || !eventThreadId || eventThreadId === state.activeThreadId) && (!state.activeRunId || !runId || runId === state.activeRunId);
   const contextPayload = payload.context_window && typeof payload.context_window === "object" ? { ...payload.context_window, run_id: runId } : payload.context_window;
@@ -946,6 +1036,7 @@ function applyRuntimeEvent(state, event) {
       content,
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
       isFinal: terminal || responseCompleted,
+      activity,
       responseCompletion: completion,
       parts
     }),
@@ -955,6 +1046,7 @@ function applyRuntimeEvent(state, event) {
       content,
       parts,
       isFinal: terminal || responseCompleted || message.isFinal,
+      activity,
       responseCompletion: completion || message.responseCompletion
     })
   });
@@ -964,10 +1056,12 @@ function applyRuntimeEvent(state, event) {
     return {
       ...message,
       isFinal: true,
+      activity: void 0,
       responseCompletion: completion,
       ...segment ? { durableId: segment.message_id } : {}
     };
   });
+  if (terminal || distinctSegment) messages = messages.map((message) => message.role === "assistant" && message.runId === runId && message.activity && (terminal || message.id !== (existing?.id || messageId)) ? { ...message, activity: void 0 } : message);
   const activityStatus = suspension || (paused ? "paused" : cancelling ? "cancelling" : "running");
   const terminalThread = runId && !sealedAfterTerminal ? {
     active_run: terminal ? null : {
@@ -2130,6 +2224,12 @@ function useAgentChat(options = {}) {
       }
     }
   }, [clearOperationError, client, detach, failOperation, pageSize, queue.hydrate, runtime, update, invalidateThreadOpen, ownOperation, captureFeedbackRead]);
+  const consumePreview = React8.useCallback((frame) => {
+    update((current) => {
+      if (frame && current.activeRunId && current.activeRunId !== frame.run_id) return current;
+      return { ...current, assistantPreview: acceptAssistantPreview(current.assistantPreview, frame) };
+    });
+  }, [update]);
   const consumeEvent = React8.useCallback((event) => {
     const timing = continuationTiming.current.get(event.run_id);
     if (timing && !timing.attached) {
@@ -2158,7 +2258,9 @@ function useAgentChat(options = {}) {
     clearOperationError("attach_run");
     update((current) => ({ ...current, activeRunId: runId, runState: "reconnecting", error: null }));
     try {
-      const result = await client.runs.attach({ runId, cursor, leaseSeconds: 60, signal: controller.signal }, (event) => {
+      const result = await client.runs.attach({ runId, cursor, onPreview: (frame) => {
+        if (isCurrent()) consumePreview(frame);
+      }, leaseSeconds: 60, signal: controller.signal }, (event) => {
         if (isCurrent()) consumeEvent(event);
       });
       if (!isCurrent()) return;
@@ -2174,7 +2276,7 @@ function useAgentChat(options = {}) {
     } finally {
       if (streamControllerRef.current === controller) streamControllerRef.current = null;
     }
-  }, [clearOperationError, client, consumeEvent, eventBuffer, failOperation, refreshMessages, runtime, update, ownOperation]);
+  }, [clearOperationError, client, consumeEvent, consumePreview, eventBuffer, failOperation, refreshMessages, runtime, update, ownOperation]);
   attachRunRef.current = attachRun;
   const submit = React8.useCallback(async (input) => {
     if (!input.text.trim() && !input.attachmentIds?.length && !input.uploads?.length) return;
@@ -2285,6 +2387,9 @@ function useAgentChat(options = {}) {
           }));
         }
         const result = await client.chat.stream({
+          onPreview: (frame) => {
+            if (isCurrent()) consumePreview(frame);
+          },
           leaseSeconds: 60,
           clientSubmissionId: ticket.client_submission_id,
           input: input.text.trim(),
@@ -2336,7 +2441,7 @@ function useAgentChat(options = {}) {
     } catch (error) {
       if (submissionOwner() || !isAbortLike(error)) throw error;
     }
-  }, [clearOperationError, client, consumeEvent, detach, eventBuffer, failOperation, invalidateThreadOpen, queue.submit, refreshMessages, refreshThreads, runtime, update, ownOperation]);
+  }, [clearOperationError, client, consumeEvent, consumePreview, detach, eventBuffer, failOperation, invalidateThreadOpen, queue.submit, refreshMessages, refreshThreads, runtime, update, ownOperation]);
   const { steer, editPendingMessage, steerPendingMessage, removePendingMessage, resumeQueue } = useAgentChatQueueActions({
     queue,
     stateRef,
@@ -2563,6 +2668,7 @@ function useAgentChat(options = {}) {
   const hasMoreThreads = threadTotal === void 0 ? state.threads.length >= threadPageSize : state.threads.length < threadTotal;
   return {
     ...state,
+    messages: messagesWithAssistantPreview(state.messages, state.assistantPreview),
     activeThread,
     pendingMessages,
     messageQueue,