@dudousxd/nestjs-agent-react 0.9.0 → 0.11.0

package/README.md

@@ -112,7 +112,7 @@ function Chat() {
 |---|---|
 | `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' \| '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].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, status, remember, decidedBy, decidedVia, decisionReason }` when the runner said who has to decide, else `null` — `status` is `pending` / `approved` / `rejected` / `expired`. |
 | `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. |
@@ -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
@@ -195,7 +223,20 @@ An `action` tool's input lands and its output never follows on its own — the l
 between the two — so a call stuck at `input-available` IS the pending approval. A question set parks
 the same way and is deliberately excluded: approving one settles nothing.
 
-A refused settlement (403 "not your thread", a network failure) lands on `block.error` /
+`call.approve.run({ remember: true })` approves this tool for the rest of the thread (the server
+stops asking); `call.approval` says who has to decide and, once settled, who did and through what.
+For a request with an expiry, `useApprovalCountdown(call.approval?.expiresAt)` ticks the time left
+(`{ remainingMs, isExpired }`, headless — pair it with `formatElapsed`):
+
+```tsx
+function ApprovalDeadline({ expiresAt }: { expiresAt: string | null }) {
+  const { remainingMs, isExpired } = useApprovalCountdown(expiresAt);
+  if (remainingMs === null) return null;
+  return <span>{isExpired ? 'Expired' : `${formatElapsed(remainingMs)} left`}</span>;
+}
+```
+
+A refused settlement (403 "not your thread" or "not your approval", 410 "expired", a network failure) lands on `block.error` /
 `call.error` with the affordance still live, rather than escaping as an unhandled rejection. Render
 it — a button that silently does nothing is indistinguishable from a broken one.
 
@@ -392,6 +433,7 @@ data parts, which `useChat`'s `onData` (and `useAgentChat({ onData })`) sees as
 |---|---|
 | `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'` |
+| `approval-settled` | a `data-approval-settled` part keyed by the call id — who decided, through what, remembered or not; folded into `call.approval` |
 | `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 |