@dudousxd/nestjs-agent-react 0.8.0 → 0.10.0

package/README.md

@@ -126,6 +126,34 @@ function Chat() {
 itself. `MessageItemView({ item })` is the default markup for one modelled item — drive the model
 yourself and still render the shipped bubble.
 
+### Talking about tool calls
+
+Tools declare how they are spoken about on the server (`@AiTool({ presentation })`, served by
+`GET /agent/tools`). `useToolCatalog` fetches that once per client + agent and shares it; hand the
+catalog to the transcript and every tool call carries a `description`, and every tool block an
+`activity` grouping:
+
+```tsx
+const chat = useAgentChat({ baseUrl: '/agent' });
+const { catalog } = useToolCatalog({ client: chat.client });
+const transcript = useChatTranscript({ messages: chat.messages, status: chat.status, toolCatalog: catalog });
+
+// in a `tools` block:
+block.activity.map((group) => (
+  <li key={group.key} data-state={group.status}>
+    <MyGlyph name={group.icon} /> {group.phrase} {group.count > 1 ? `×${group.count}` : null}
+  </li>
+));
+```
+
+| Helper | What it gives you |
+|---|---|
+| `call.description` / `describeToolCall(part, catalog)` | `{ status, phrase, label, icon, tone, detail, confirm, result, error }` — `status` is `running` / `awaiting-approval` / `done` / `failed` / `denied`; `confirm` is the approval prompt filled from the input; `result` the output read through the declared view (`metrics` readings, `table` rows as text, `log` lines, `note` text). |
+| `groupToolActivity(block.roots, { catalog, keyOf?, expandNested?, hideCorrected? })` | Calls folded by key ("Database query ×3"), worst status first, latest phrase, `innerCount` of nested calls. `expandNested` replaces a parent (a code-mode `execute`) with the calls it made; `keyOf` groups by anything else (e.g. `github:search`). |
+| `phraseFor` / `fillTemplate` / `readPath` | The template engine: `{dotted.path}` over the input; an empty slot collapses with its leading space; an undescribed tool reads `Working` / `Done`, never its name. |
+| `resolveResultView` / `inferResultView` | A tool output through a view, as plain data — never a serialized payload. |
+| `toolCallState` / `correctedCallIds` / `isActionCall` | Per-call status, and which failures the model later corrected. |
+
 ### Where the answer came from
 
 RAG persists its retrieval as an auto-executed tool call whose output is `{ passages }` — inject
@@ -417,6 +445,8 @@ const initialMessages = storedThreadToUiMessages(detail.messages);
 calls persists as "thinking…" + tool calls, then a separate final-answer row) into ONE `UIMessage` per
 conversational turn, matching how the live stream renders — and stamps `metadata.usage` on any turn it
 merged. For a single already-atomic row, `storedMessageToUiMessage` maps it 1:1 with no merging.
+Persisted reasoning comes back as a `reasoning` part before the text (with its duration), and
+persisted pushed components as `data-ui` parts, so a reloaded thread shows what the live one did.
 
 ### Attachments and the raw client
 
@@ -452,6 +482,19 @@ Reasoning frames arrive as `reasoning` parts on the message (the transport maps
 each run behind a disclosure toggle — open while it streams, folded once the answer lands — with
 `renderReasoning` and `reasoningLabel` slots to override the body and the label.
 
+Thinking is timed and persisted: the backend reports each step's `reasoningMs` on `step-finish`, the
+transport stamps it on the reasoning part, and the stored message keeps it, so a reasoning block's
+`durationMs` reads the same live and after a reload. `useElapsed(running)` is the headless ticker
+for while it still streams, and `formatElapsed(ms)` the label:
+
+```tsx
+function ThoughtFor({ block }: { block: TranscriptReasoningBlock }) {
+  const elapsed = useElapsed(block.isStreaming);
+  const ms = block.isStreaming ? elapsed : block.durationMs;
+  return ms === null ? null : <span>Thought for {formatElapsed(ms)}</span>;
+}
+```
+
 `ChatInput` surfaces cancel next to send:
 
 ```tsx