@dudousxd/nestjs-agent-react 0.7.4 → 0.8.0

package/README.md

@@ -111,8 +111,8 @@ function Chat() {
 | On the instance | What it is |
 |---|---|
 | `items` | The mounted window, oldest first. Each item carries `blocks`, `text`, `usage`, `timestamp`, `isStreaming`, `isLastAssistant`, and its action machines. |
-| `items[i].blocks` | `{ kind: 'text' \| 'reasoning' \| 'tools' \| 'sources' \| 'elicitation' }`. A `tools` block is a run of CONSECUTIVE tool parts — any other part between two calls (including a `step-start` marker) ends the run. A `reasoning` block carries `isOpen`/`toggle`, open while it streams. A `sources` block appears only under `sources: true`, an `elicitation` block only under `onAnswer` — see below. |
-| `items[i].blocks[n]` (`tools`) | Also carries `calls`: the same parts, each with `{ toolCallId, name, isAwaitingApproval, approve, reject, error }`. |
+| `items[i].blocks` | `{ kind: 'text' \| 'reasoning' \| 'tools' \| 'sources' \| 'elicitation' \| 'ui' }`. A `ui` block is a component the server pushed (`{ id, component, props, version }`) — look `component` up in your own registry. A `tools` block is a run of CONSECUTIVE tool parts — any other part between two calls (including a `step-start` marker) ends the run. A `reasoning` block carries `isOpen`/`toggle`, open while it streams. A `sources` block appears only under `sources: true`, an `elicitation` block only under `onAnswer` — see below. |
+| `items[i].blocks[n]` (`tools`) | Also carries `calls`: the same parts, each with `{ toolCallId, name, toolKind, parentId, children, approval, isAwaitingApproval, approve, reject, error }`, and `roots`: the same calls as a tree (a call nested under another by the stream's `parentId` sits in its parent's `children`). `approval` is `{ approver, expiresAt, reason }` when the runner said who has to decide, else `null`. |
 | `items[i].copy` | `{ available, copied, copy() }` — `copied` flashes for `copyResetMs` (default 1500). |
 | `items[i].edit` | `{ available, isEditing, draft, canSave, start(), cancel(), setDraft(), save(), getTextareaProps() }`. The prop-getter focuses with the caret at the end, saves on Enter, cancels on Escape. |
 | `items[i].fork` / `.regenerate` | `{ available, run() }`. Regenerate is offered on the last assistant message only. |
@@ -324,6 +324,10 @@ function CustomChat({ threadId }: { threadId?: string }) {
     onRunSettled: ({ status }) => {
       if (status === 'completed') refetchThreadList();
     },
+    // The server named (or renamed) the thread mid-stream — update the header now.
+    onTitle: (title) => setHeaderTitle(title),
+    // Every data part as it arrives: pushed `data-ui` components, `data-approval-requested`, …
+    onData: (part) => analytics.track(part.type),
   });
 
   return (
@@ -381,6 +385,20 @@ const transport = new AgentChatTransport({
 const chat = useChat({ transport });
 ```
 
+Beyond text, reasoning and tool calls, the transport maps the rest of the stream vocabulary to AI SDK
+data parts, which `useChat`'s `onData` (and `useAgentChat({ onData })`) sees as they arrive:
+
+| Stream frame | Becomes |
+|---|---|
+| `ui` | a `data-ui` part keyed by the component id (a repeat id updates it in place) |
+| `approval-requested` | a `data-approval-requested` part keyed by the call id, plus the SDK's native approval request — the tool part moves to `state: 'approval-requested'` |
+| `title` / `cancelled` | transient `data-title` / `data-cancelled` (never stored on the message); `useAgentChat({ onTitle })` |
+| a kind this version does not know | a `data-<kind>` part — forwarded, never dropped |
+
+`parentId` on a tool frame rides the part's `toolMetadata` next to `toolKind`. The full wire
+contract — for a backend that serves these routes without this library's loop — is
+[docs/stream-protocol.md](../../docs/stream-protocol.md).
+
 ### Loading persisted history
 
 A reloaded thread's `StoredMessage[]` (from `AgentClient.getThread`) needs converting to `UIMessage[]`

package/dist/index.cjs

@@ -202,7 +202,8 @@ var AgentChatTransport = class {
   * Parse the backend's SSE byte stream and re-emit it as a valid v7 UI-message chunk stream.
   * Recognized frames:
   *  - `event: meta`  `data: {"runId","threadId"}`   → records identity
-  *  - `data: <AgentStreamEvent JSON>`                → mapped to UI chunks (text / reasoning / tool)
+  *  - `data: <AgentStreamEvent JSON>`                → mapped to UI chunks (text / reasoning / tool /
+  *                                                     `data-*`; see {@link AgentChatTransport} docs)
   *  - `event: done`  `data: {}`                      → terminates
   *  - `event: error` `data: {code,message}`          → error chunk
   *
@@ -219,7 +220,10 @@ var AgentChatTransport = class {
     let stepIndex = 0;
     let textId = null;
     let reasoningId = null;
+    let textSeq = 0;
+    let reasoningSeq = 0;
     const announced = /* @__PURE__ */ new Set();
+    const toolMetadata = /* @__PURE__ */ new Map();
     const record = /* @__PURE__ */ __name((meta) => this.recordMeta(meta), "record");
     const endAttempt = /* @__PURE__ */ __name(() => {
       this.attemptLive = false;
@@ -241,6 +245,8 @@ var AgentChatTransport = class {
           stepIndex += 1;
           textId = null;
           reasoningId = null;
+          textSeq = 0;
+          reasoningSeq = 0;
           controller.enqueue({
             type: "start-step"
           });
@@ -250,8 +256,7 @@ var AgentChatTransport = class {
           if (!stepOpen) openStep();
         }
         __name(ensureStep, "ensureStep");
-        function closeStep() {
-          if (!stepOpen) return;
+        function closeRuns() {
           if (textId !== null) {
             controller.enqueue({
               type: "text-end",
@@ -266,12 +271,43 @@ var AgentChatTransport = class {
             });
             reasoningId = null;
           }
+        }
+        __name(closeRuns, "closeRuns");
+        function closeStep() {
+          if (!stepOpen) return;
+          closeRuns();
           controller.enqueue({
             type: "finish-step"
           });
           stepOpen = false;
         }
         __name(closeStep, "closeStep");
+        function metadataFor(id, toolKind2, parentId) {
+          const merged = {
+            ...toolMetadata.get(id)
+          };
+          if (toolKind2 !== void 0) merged.toolKind = toolKind2;
+          if (parentId !== void 0 && merged.parentId === void 0) merged.parentId = parentId;
+          if (Object.keys(merged).length === 0) return void 0;
+          toolMetadata.set(id, merged);
+          return merged;
+        }
+        __name(metadataFor, "metadataFor");
+        function forwardAsData(event, transient) {
+          ensureStarted();
+          const { kind, ...data } = event;
+          controller.enqueue({
+            type: `data-${kind}`,
+            ...typeof data.id === "string" ? {
+              id: data.id
+            } : {},
+            data,
+            ...transient ? {
+              transient: true
+            } : {}
+          });
+        }
+        __name(forwardAsData, "forwardAsData");
         function emit(event) {
           switch (event.kind) {
             case "step-start":
@@ -291,7 +327,8 @@ var AgentChatTransport = class {
             case "text":
               ensureStep();
               if (textId === null) {
-                textId = `txt-${stepIndex}`;
+                textId = textSeq === 0 ? `txt-${stepIndex}` : `txt-${stepIndex}.${textSeq}`;
+                textSeq += 1;
                 controller.enqueue({
                   type: "text-start",
                   id: textId
@@ -306,7 +343,8 @@ var AgentChatTransport = class {
             case "reasoning":
               ensureStep();
               if (reasoningId === null) {
-                reasoningId = `rsn-${stepIndex}`;
+                reasoningId = reasoningSeq === 0 ? `rsn-${stepIndex}` : `rsn-${stepIndex}.${reasoningSeq}`;
+                reasoningSeq += 1;
                 controller.enqueue({
                   type: "reasoning-start",
                   id: reasoningId
@@ -318,23 +356,20 @@ var AgentChatTransport = class {
                 delta: event.text
               });
               break;
-            case "tool-input-start":
+            case "tool-input-start": {
               ensureStep();
               announced.add(event.id);
+              const metadata = metadataFor(event.id, event.toolKind, event.parentId);
               controller.enqueue({
                 type: "tool-input-start",
                 toolCallId: event.id,
                 toolName: event.name,
-                // `toolKind` is absent on older backends — omitted (not `undefined`-valued) so
-                // `toolMetadata` itself is only present when there's something to say, letting a
-                // UI gate approval affordances on `kind === 'action'` without hardcoding tool names.
-                ...event.toolKind !== void 0 ? {
-                  toolMetadata: {
-                    toolKind: event.toolKind
-                  }
+                ...metadata !== void 0 ? {
+                  toolMetadata: metadata
                 } : {}
               });
               break;
+            }
             case "tool-input-delta":
               ensureStep();
               controller.enqueue({
@@ -343,21 +378,21 @@ var AgentChatTransport = class {
                 inputTextDelta: event.delta
               });
               break;
-            case "tool-input-available":
+            case "tool-input-available": {
               ensureStep();
               announced.add(event.id);
+              const metadata = metadataFor(event.id, event.toolKind, event.parentId);
               controller.enqueue({
                 type: "tool-input-available",
                 toolCallId: event.id,
                 toolName: event.name,
                 input: event.input,
-                ...event.toolKind !== void 0 ? {
-                  toolMetadata: {
-                    toolKind: event.toolKind
-                  }
+                ...metadata !== void 0 ? {
+                  toolMetadata: metadata
                 } : {}
               });
               break;
+            }
             case "elicitation":
               ensureStep();
               if (!announced.has(event.id)) {
@@ -398,7 +433,39 @@ var AgentChatTransport = class {
                 toolCallId: event.id
               });
               break;
+            case "approval-requested":
+              ensureStep();
+              forwardAsData(event, false);
+              if (announced.has(event.id)) {
+                controller.enqueue({
+                  type: "tool-approval-request",
+                  approvalId: event.id,
+                  toolCallId: event.id
+                });
+              }
+              break;
+            case "ui":
+              ensureStep();
+              closeRuns();
+              controller.enqueue({
+                type: "data-ui",
+                id: event.id,
+                data: {
+                  id: event.id,
+                  component: event.component,
+                  props: event.props,
+                  ...event.version !== void 0 ? {
+                    version: event.version
+                  } : {}
+                }
+              });
+              break;
+            case "title":
+            case "cancelled":
+              forwardAsData(event, true);
+              break;
             default:
+              forwardAsData(event, false);
               break;
           }
         }
@@ -906,15 +973,18 @@ function buildTranscriptBlocks(message, options) {
   let reasoningCounter = 0;
   let sourcesCounter = 0;
   let elicitationCounter = 0;
+  const approvals = readApprovals(message.parts ?? []);
   function flushTools() {
     if (toolBuffer.length === 0) {
       return;
     }
+    const calls = toolBuffer.map((part) => buildToolCall(part, options.approval, approvals.get(part.toolCallId) ?? null));
     blocks.push({
       kind: "tools",
       key: `${message.id}-tools-${toolCounter++}`,
       parts: toolBuffer,
-      calls: toolBuffer.map((part) => buildToolCall(part, options.approval))
+      calls,
+      roots: nestToolCalls(calls)
     });
     toolBuffer = [];
   }
@@ -977,7 +1047,21 @@ function buildTranscriptBlocks(message, options) {
       fileBuffer.push(part);
       continue;
     }
+    if (part.type === APPROVAL_PART) {
+      continue;
+    }
     flushAll();
+    if ((0, import_ai.isDataUIPart)(part)) {
+      const ui = part.type === UI_PART ? readUiComponent(part) : null;
+      if (ui !== null) {
+        blocks.push({
+          kind: "ui",
+          key: `${message.id}-ui-${ui.id}`,
+          ...ui
+        });
+      }
+      continue;
+    }
     if ((0, import_ai.isTextUIPart)(part)) {
       blocks.push({
         kind: "text",
@@ -1061,7 +1145,42 @@ function isAwaitingApproval(part) {
   return toolKind(part) === "action" && readElicitationRequest(part) === null;
 }
 __name(isAwaitingApproval, "isAwaitingApproval");
-function buildToolCall(part, options) {
+function toolParentId(part) {
+  const metadata = part.toolMetadata;
+  return isRecord(metadata) && typeof metadata.parentId === "string" ? metadata.parentId : null;
+}
+__name(toolParentId, "toolParentId");
+function nestToolCalls(calls) {
+  const byId = new Map(calls.map((call) => [
+    call.toolCallId,
+    call
+  ]));
+  const roots = [];
+  for (const call of calls) {
+    const parent = call.parentId !== null ? byId.get(call.parentId) : void 0;
+    if (parent === void 0 || isAncestor(call, parent, byId)) {
+      roots.push(call);
+      continue;
+    }
+    parent.children.push(call);
+  }
+  return roots;
+}
+__name(nestToolCalls, "nestToolCalls");
+function isAncestor(call, candidate, byId) {
+  const seen = /* @__PURE__ */ new Set();
+  let current = candidate;
+  while (current !== void 0 && !seen.has(current.toolCallId)) {
+    if (current.toolCallId === call.toolCallId) {
+      return true;
+    }
+    seen.add(current.toolCallId);
+    current = current.parentId !== null ? byId.get(current.parentId) : void 0;
+  }
+  return false;
+}
+__name(isAncestor, "isAncestor");
+function buildToolCall(part, options, approval) {
   const toolCallId = part.toolCallId;
   const awaiting = isAwaitingApproval(part);
   const sending = awaiting ? options?.submitting(toolCallId) ?? null : null;
@@ -1069,6 +1188,10 @@ function buildToolCall(part, options) {
     part,
     toolCallId,
     name: (0, import_ai.getToolName)(part),
+    toolKind: toolKind(part) ?? null,
+    parentId: toolParentId(part),
+    children: [],
+    approval,
     isAwaitingApproval: awaiting,
     approve: {
       available: awaiting && options?.canApprove === true,
@@ -1199,6 +1322,44 @@ function buildElicitationBlock(key, part, request, options) {
   };
 }
 __name(buildElicitationBlock, "buildElicitationBlock");
+var UI_PART = "data-ui";
+var APPROVAL_PART = "data-approval-requested";
+function readApprovals(parts) {
+  const out = /* @__PURE__ */ new Map();
+  for (const part of parts) {
+    if (part.type !== APPROVAL_PART) {
+      continue;
+    }
+    const data = part.data;
+    if (!isRecord(data) || typeof data.id !== "string" || typeof data.approver !== "string") {
+      continue;
+    }
+    out.set(data.id, {
+      approver: data.approver,
+      expiresAt: typeof data.expiresAt === "string" ? data.expiresAt : null,
+      reason: typeof data.reason === "string" ? data.reason : null
+    });
+  }
+  return out;
+}
+__name(readApprovals, "readApprovals");
+function readUiComponent(part) {
+  const data = part.data;
+  if (!isRecord(data) || typeof data.component !== "string") {
+    return null;
+  }
+  const id = typeof data.id === "string" ? data.id : part.id;
+  if (id === void 0) {
+    return null;
+  }
+  return {
+    id,
+    component: data.component,
+    props: isRecord(data.props) ? data.props : {},
+    version: typeof data.version === "number" ? data.version : null
+  };
+}
+__name(readUiComponent, "readUiComponent");
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -1892,6 +2053,14 @@ function renderBlocks(item, slots) {
     }
     if (block.kind === "tools") {
       nodes.push(...renderToolBlock(item, block, slots));
+      continue;
+    }
+    if (block.kind === "ui" && slots.renderUi) {
+      nodes.push(/* @__PURE__ */ import_react5.default.createElement("div", {
+        key: block.key,
+        "data-slot": "ui",
+        "data-component": block.component
+      }, slots.renderUi(block)));
     }
   }
   return nodes;
@@ -1999,7 +2168,7 @@ function joinClasses(...entries) {
 __name(joinClasses, "joinClasses");
 
 // src/components/message-list.tsx
-function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, reasoningLabel, getMeta, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames }) {
+function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, renderUi, reasoningLabel, getMeta, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames }) {
   const transcript = useChatTranscript({
     messages,
     status,
@@ -2049,6 +2218,9 @@ function MessageList({ messages, status, renderToolPart, renderToolGroup, render
     ...renderFiles ? {
       renderFiles
     } : {},
+    ...renderUi ? {
+      renderUi
+    } : {},
     ...reasoningLabel !== void 0 ? {
       reasoningLabel
     } : {},
@@ -2703,6 +2875,13 @@ function useAgentChat(options) {
     ...options.initialMessages !== void 0 ? {
       messages: options.initialMessages
     } : {},
+    onData: /* @__PURE__ */ __name((part) => {
+      latest.current.onData?.(part);
+      if (part.type === "data-title") {
+        const title = part.data?.title;
+        if (typeof title === "string") latest.current.onTitle?.(title);
+      }
+    }, "onData"),
     onFinish: /* @__PURE__ */ __name(({ isError }) => {
       latest.current.onFinish?.();
       if (latest.current.background === true) {