@dudousxd/nestjs-agent-react 0.4.2 → 0.5.1

package/dist/index.d.cts

@@ -43,6 +43,14 @@ interface AgentChatTransportOptions {
     getResumeRunId?: () => string | undefined;
     /** Fires whenever a stream emits its `meta` frame. */
     onMeta?: (meta: AgentStreamMeta) => void;
+    /**
+     * Fires synchronously at the very start of `sendMessages`/`reconnectToStream`, before any network
+     * call — i.e. strictly before that attempt's own `onMeta` (if any) can fire. Lets a caller reset
+     * "which run is THIS attempt settling" state without racing React's render/effect timing: a
+     * consumer that also read `onMeta` to learn the current run id would otherwise risk misattributing
+     * an early failure (no meta ever arrives) to a PRIOR attempt's id.
+     */
+    onAttemptStart?: () => void;
     /** Injectable for tests / non-browser runtimes. Defaults to global fetch. */
     fetch?: typeof fetch;
 }
@@ -190,6 +198,66 @@ declare class AgentClient {
  */
 declare function storedMessageToUiMessage(message: StoredMessage): UIMessage;
 
+/**
+ * Summed usage/cost across the stored-message rows merged into one turn (see
+ * {@link storedThreadToUiMessages}). Mirrors `MessageUsage`, but `costUsd` is always present
+ * (never omitted) since it's a computed aggregate, not a single provider report.
+ */
+interface AggregatedTurnUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /**
+     * `null` only when EVERY merged row reports a null/absent cost (no pricing store bound, or an
+     * unpriced model) — same "unknown, not a real $0" distinction `MessageUsage.costUsd` makes for a
+     * single row. A null cost on SOME rows (mixed with priced ones) contributes `0` to the sum
+     * instead of poisoning the whole turn's total to `null` — the tokens are still real and summed
+     * either way, so only the cost figure would be understated, never wrong in a "$0 turn" sense.
+     */
+    costUsd: number | null;
+}
+/** Metadata the grouped `UIMessage` carries on `.metadata.usage` — see {@link AggregatedTurnUsage}. */
+interface StoredTurnMetadata {
+    usage: AggregatedTurnUsage;
+}
+/**
+ * Convert a thread's full `StoredMessage[]` history into `UIMessage[]`, merging consecutive
+ * assistant rows (no user message between them) into ONE `UIMessage` per turn.
+ *
+ * Why: the agent loop persists one row per model iteration (see `agent-loop.ts`'s per-step
+ * `persist:assistant:${i}`) — a turn with tool calls appends "I'll check that..." + tool calls,
+ * then a separate final-answer row. `storedMessageToUiMessage` maps 1:1, so a reloaded thread
+ * renders 2-3 assistant bubbles (each with its own cost/tokens footer) for what the LIVE stream
+ * renders as one continuous response (one `UIMessage`, stepped internally — see
+ * `AgentChatTransport.toChunkStream`'s `start-step`/`finish-step` bracketing). This closes that gap
+ * for replayed history.
+ *
+ * Merge shape: each row is mapped via `storedMessageToUiMessage` (unchanged — same text-then-tool
+ * part ordering per row) and the parts are concatenated in row order, so the grouped message's parts
+ * read as `[row1 text?, row1 tools?, row2 text?, row2 tools?, ...]` — exactly the sequence the live
+ * transport streams for the same turn. The group's `id` is the LAST row's id (the final-answer row —
+ * it's the one carrying `followUps`, and what a host keys turn-level actions like "fork" or
+ * "regenerate" on). Non-assistant rows (user/system) pass through `storedMessageToUiMessage`
+ * unchanged, one row → one message, same as today.
+ *
+ * A lone assistant row between two user rows (the common case: no tool calls, or already a single
+ * iteration) has nothing to merge with, so it comes back byte-for-byte identical to calling
+ * `storedMessageToUiMessage` directly — no `metadata` is added for that case either, preserving
+ * exact backward compatibility for hosts that read stored usage some other way.
+ *
+ * Only an ACTUAL merge (2+ rows) attaches `metadata.usage` — the {@link AggregatedTurnUsage} summed
+ * across the merged rows' `usage` (rows without a `usage` at all, e.g. an older/test fixture, are
+ * skipped rather than treated as zero-and-priced).
+ *
+ * Deliberately NOT reproduced: the live transport's `{type: 'step-start'}` UI parts (one per model
+ * call, emitted by the AI SDK for every `start-step` chunk — see `repro-real-frames.spec.ts` for a
+ * captured wire dump). Those are structural brackets `MessageItem`'s `renderParts` never renders
+ * (it only special-cases text and tool parts), and `storedMessageToUiMessage` has never emitted them
+ * for a single row either — inventing them here would make a merged turn diverge from a same-shaped
+ * unmerged one instead of converging on it. "Indistinguishable from the live stream" is scoped to
+ * what actually renders: the text/tool-call content in step order, not the step brackets around it.
+ */
+declare function storedThreadToUiMessages(messages: StoredMessage[]): UIMessage[];
+
 interface UseAgentChatOptions {
     /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
     baseUrl?: string;
@@ -237,6 +305,27 @@ interface UseAgentChatOptions {
      * even before the consumer navigates.
      */
     onThreadCreated?: (threadId: string) => void;
+    /**
+     * Fired exactly once per run when its stream settles — normally (`'completed'`) or via a thrown
+     * failure / the backend's `event: error` frame (`'failed'`) — including a RESUMED stream's own
+     * completion. By the time this fires, the server has already derived and persisted the thread's
+     * title (and the run's terminal state), so it's the signal `onFinish` doesn't give you: `onFinish`
+     * only says "a turn rendered," never "the server is done writing" — without this, a host has no
+     * reason to refetch the thread/list queries, and the header/sidebar title is stuck on "Untitled".
+     *
+     * Skipped when the attempt never got far enough to learn a run id (e.g. the initial POST itself
+     * failed before any response headers/meta frame arrived) — nothing was created server-side, so
+     * there's nothing to refetch.
+     *
+     * A user-initiated `cancel()`/`stop()` reports `'completed'` here (the AI SDK's own abort signal
+     * doesn't set its `isError` flag) — the server-side cancel already recorded its own terminal run
+     * state; this callback only reflects whether the CLIENT's stream loop exited with or without an
+     * error, not why it stopped.
+     */
+    onRunSettled?: (outcome: {
+        runId: string;
+        status: 'completed' | 'failed';
+    }) => void;
 }
 interface AddToolResultArgs {
     tool: string;
@@ -490,4 +579,4 @@ interface SpeechRecognitionHook {
  */
 declare function useSpeechRecognition({ lang, onFinalTranscript, onInterimTranscript, }: UseSpeechRecognitionOptions): SpeechRecognitionHook;
 
-export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AnyToolUIPart, type CancelResult, ChatInput, type ChatInputProps, type ChatStatus, DEFAULT_SPEECH_LANG, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, SPEECH_LANGUAGES, type SpeechLanguage, type SpeechRecognitionHook, type ThreadPatch, type UseAgentChatOptions, type UseSpeechRecognitionOptions, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, storedMessageToUiMessage, useAgentChat, useSpeechRecognition };
+export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AggregatedTurnUsage, type AnyToolUIPart, type CancelResult, ChatInput, type ChatInputProps, type ChatStatus, DEFAULT_SPEECH_LANG, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, SPEECH_LANGUAGES, type SpeechLanguage, type SpeechRecognitionHook, type StoredTurnMetadata, type ThreadPatch, type UseAgentChatOptions, type UseSpeechRecognitionOptions, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useSpeechRecognition };

package/dist/index.d.ts

@@ -43,6 +43,14 @@ interface AgentChatTransportOptions {
     getResumeRunId?: () => string | undefined;
     /** Fires whenever a stream emits its `meta` frame. */
     onMeta?: (meta: AgentStreamMeta) => void;
+    /**
+     * Fires synchronously at the very start of `sendMessages`/`reconnectToStream`, before any network
+     * call — i.e. strictly before that attempt's own `onMeta` (if any) can fire. Lets a caller reset
+     * "which run is THIS attempt settling" state without racing React's render/effect timing: a
+     * consumer that also read `onMeta` to learn the current run id would otherwise risk misattributing
+     * an early failure (no meta ever arrives) to a PRIOR attempt's id.
+     */
+    onAttemptStart?: () => void;
     /** Injectable for tests / non-browser runtimes. Defaults to global fetch. */
     fetch?: typeof fetch;
 }
@@ -190,6 +198,66 @@ declare class AgentClient {
  */
 declare function storedMessageToUiMessage(message: StoredMessage): UIMessage;
 
+/**
+ * Summed usage/cost across the stored-message rows merged into one turn (see
+ * {@link storedThreadToUiMessages}). Mirrors `MessageUsage`, but `costUsd` is always present
+ * (never omitted) since it's a computed aggregate, not a single provider report.
+ */
+interface AggregatedTurnUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /**
+     * `null` only when EVERY merged row reports a null/absent cost (no pricing store bound, or an
+     * unpriced model) — same "unknown, not a real $0" distinction `MessageUsage.costUsd` makes for a
+     * single row. A null cost on SOME rows (mixed with priced ones) contributes `0` to the sum
+     * instead of poisoning the whole turn's total to `null` — the tokens are still real and summed
+     * either way, so only the cost figure would be understated, never wrong in a "$0 turn" sense.
+     */
+    costUsd: number | null;
+}
+/** Metadata the grouped `UIMessage` carries on `.metadata.usage` — see {@link AggregatedTurnUsage}. */
+interface StoredTurnMetadata {
+    usage: AggregatedTurnUsage;
+}
+/**
+ * Convert a thread's full `StoredMessage[]` history into `UIMessage[]`, merging consecutive
+ * assistant rows (no user message between them) into ONE `UIMessage` per turn.
+ *
+ * Why: the agent loop persists one row per model iteration (see `agent-loop.ts`'s per-step
+ * `persist:assistant:${i}`) — a turn with tool calls appends "I'll check that..." + tool calls,
+ * then a separate final-answer row. `storedMessageToUiMessage` maps 1:1, so a reloaded thread
+ * renders 2-3 assistant bubbles (each with its own cost/tokens footer) for what the LIVE stream
+ * renders as one continuous response (one `UIMessage`, stepped internally — see
+ * `AgentChatTransport.toChunkStream`'s `start-step`/`finish-step` bracketing). This closes that gap
+ * for replayed history.
+ *
+ * Merge shape: each row is mapped via `storedMessageToUiMessage` (unchanged — same text-then-tool
+ * part ordering per row) and the parts are concatenated in row order, so the grouped message's parts
+ * read as `[row1 text?, row1 tools?, row2 text?, row2 tools?, ...]` — exactly the sequence the live
+ * transport streams for the same turn. The group's `id` is the LAST row's id (the final-answer row —
+ * it's the one carrying `followUps`, and what a host keys turn-level actions like "fork" or
+ * "regenerate" on). Non-assistant rows (user/system) pass through `storedMessageToUiMessage`
+ * unchanged, one row → one message, same as today.
+ *
+ * A lone assistant row between two user rows (the common case: no tool calls, or already a single
+ * iteration) has nothing to merge with, so it comes back byte-for-byte identical to calling
+ * `storedMessageToUiMessage` directly — no `metadata` is added for that case either, preserving
+ * exact backward compatibility for hosts that read stored usage some other way.
+ *
+ * Only an ACTUAL merge (2+ rows) attaches `metadata.usage` — the {@link AggregatedTurnUsage} summed
+ * across the merged rows' `usage` (rows without a `usage` at all, e.g. an older/test fixture, are
+ * skipped rather than treated as zero-and-priced).
+ *
+ * Deliberately NOT reproduced: the live transport's `{type: 'step-start'}` UI parts (one per model
+ * call, emitted by the AI SDK for every `start-step` chunk — see `repro-real-frames.spec.ts` for a
+ * captured wire dump). Those are structural brackets `MessageItem`'s `renderParts` never renders
+ * (it only special-cases text and tool parts), and `storedMessageToUiMessage` has never emitted them
+ * for a single row either — inventing them here would make a merged turn diverge from a same-shaped
+ * unmerged one instead of converging on it. "Indistinguishable from the live stream" is scoped to
+ * what actually renders: the text/tool-call content in step order, not the step brackets around it.
+ */
+declare function storedThreadToUiMessages(messages: StoredMessage[]): UIMessage[];
+
 interface UseAgentChatOptions {
     /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
     baseUrl?: string;
@@ -237,6 +305,27 @@ interface UseAgentChatOptions {
      * even before the consumer navigates.
      */
     onThreadCreated?: (threadId: string) => void;
+    /**
+     * Fired exactly once per run when its stream settles — normally (`'completed'`) or via a thrown
+     * failure / the backend's `event: error` frame (`'failed'`) — including a RESUMED stream's own
+     * completion. By the time this fires, the server has already derived and persisted the thread's
+     * title (and the run's terminal state), so it's the signal `onFinish` doesn't give you: `onFinish`
+     * only says "a turn rendered," never "the server is done writing" — without this, a host has no
+     * reason to refetch the thread/list queries, and the header/sidebar title is stuck on "Untitled".
+     *
+     * Skipped when the attempt never got far enough to learn a run id (e.g. the initial POST itself
+     * failed before any response headers/meta frame arrived) — nothing was created server-side, so
+     * there's nothing to refetch.
+     *
+     * A user-initiated `cancel()`/`stop()` reports `'completed'` here (the AI SDK's own abort signal
+     * doesn't set its `isError` flag) — the server-side cancel already recorded its own terminal run
+     * state; this callback only reflects whether the CLIENT's stream loop exited with or without an
+     * error, not why it stopped.
+     */
+    onRunSettled?: (outcome: {
+        runId: string;
+        status: 'completed' | 'failed';
+    }) => void;
 }
 interface AddToolResultArgs {
     tool: string;
@@ -490,4 +579,4 @@ interface SpeechRecognitionHook {
  */
 declare function useSpeechRecognition({ lang, onFinalTranscript, onInterimTranscript, }: UseSpeechRecognitionOptions): SpeechRecognitionHook;
 
-export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AnyToolUIPart, type CancelResult, ChatInput, type ChatInputProps, type ChatStatus, DEFAULT_SPEECH_LANG, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, SPEECH_LANGUAGES, type SpeechLanguage, type SpeechRecognitionHook, type ThreadPatch, type UseAgentChatOptions, type UseSpeechRecognitionOptions, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, storedMessageToUiMessage, useAgentChat, useSpeechRecognition };
+export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AggregatedTurnUsage, type AnyToolUIPart, type CancelResult, ChatInput, type ChatInputProps, type ChatStatus, DEFAULT_SPEECH_LANG, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, SPEECH_LANGUAGES, type SpeechLanguage, type SpeechRecognitionHook, type StoredTurnMetadata, type ThreadPatch, type UseAgentChatOptions, type UseSpeechRecognitionOptions, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useSpeechRecognition };

package/dist/index.js

@@ -23,6 +23,7 @@ var AgentChatTransport = class {
     return this.currentThreadId;
   }
   async sendMessages(options) {
+    this.options.onAttemptStart?.();
     const lastMessage = options.messages.at(-1);
     const message = lastMessage ? extractText(lastMessage) : "";
     const body = {
@@ -55,6 +56,7 @@ var AgentChatTransport = class {
     return this.toChunkStream(response.body);
   }
   async reconnectToStream(options) {
+    this.options.onAttemptStart?.();
     const runId = this.options.getResumeRunId?.();
     if (runId === void 0) return null;
     const response = await this.fetchImpl()(`${this.baseUrl()}/agent/chat/${encodeURIComponent(runId)}/stream`, {
@@ -564,6 +566,59 @@ function storedMessageToUiMessage(message) {
 }
 __name(storedMessageToUiMessage, "storedMessageToUiMessage");
 
+// src/stored-thread-to-ui-messages.ts
+function storedThreadToUiMessages(messages) {
+  const turns = [];
+  for (const message of messages) {
+    const currentTurn = turns.at(-1);
+    const previousRow = currentTurn?.at(-1);
+    if (message.role === "assistant" && previousRow?.role === "assistant" && currentTurn) {
+      currentTurn.push(message);
+    } else {
+      turns.push([
+        message
+      ]);
+    }
+  }
+  return turns.map(mergeTurn);
+}
+__name(storedThreadToUiMessages, "storedThreadToUiMessages");
+function mergeTurn(rows) {
+  const lastRow = rows.at(-1);
+  if (lastRow === void 0) {
+    throw new Error("storedThreadToUiMessages: encountered an empty turn");
+  }
+  if (rows.length === 1) {
+    return storedMessageToUiMessage(lastRow);
+  }
+  const parts = rows.flatMap((row) => storedMessageToUiMessage(row).parts);
+  const usage = sumUsage(rows);
+  return {
+    id: lastRow.id,
+    role: lastRow.role,
+    parts,
+    ...usage !== void 0 ? {
+      metadata: {
+        usage
+      }
+    } : {}
+  };
+}
+__name(mergeTurn, "mergeTurn");
+function sumUsage(rows) {
+  const usages = rows.map((row) => row.usage).filter((usage) => usage !== void 0);
+  if (usages.length === 0) {
+    return void 0;
+  }
+  const allCostsUnknown = usages.every((usage) => usage.costUsd === null || usage.costUsd === void 0);
+  return {
+    inputTokens: usages.reduce((sum, usage) => sum + usage.inputTokens, 0),
+    outputTokens: usages.reduce((sum, usage) => sum + usage.outputTokens, 0),
+    costUsd: allCostsUnknown ? null : usages.reduce((sum, usage) => sum + (usage.costUsd ?? 0), 0)
+  };
+}
+__name(sumUsage, "sumUsage");
+
 // src/use-agent-chat.ts
 import { useChat } from "@ai-sdk/react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
@@ -573,6 +628,7 @@ function useAgentChat(options) {
   const [runId, setRunId] = useState(options.resumeRunId);
   const runIdRef = useRef(runId);
   runIdRef.current = runId;
+  const settlingRunIdRef = useRef(void 0);
   const autoResumeRunIdRef = useRef(void 0);
   const [autoResume, setAutoResume] = useState(false);
   const [activeRunId, setActiveRunId] = useState(null);
@@ -615,6 +671,7 @@ function useAgentChat(options) {
   ]);
   const transport = useMemo(() => {
     function onMeta(meta) {
+      settlingRunIdRef.current = meta.runId;
       setRunId(meta.runId);
       if (latest.current.threadId === void 0 && meta.threadId && createdThreadId.current !== meta.threadId) {
         createdThreadId.current = meta.threadId;
@@ -655,7 +712,10 @@ function useAgentChat(options) {
         };
       }, "getBody"),
       getResumeRunId: /* @__PURE__ */ __name(() => latest.current.resumeRunId ?? autoResumeRunIdRef.current, "getResumeRunId"),
-      onMeta
+      onMeta,
+      onAttemptStart: /* @__PURE__ */ __name(() => {
+        settlingRunIdRef.current = void 0;
+      }, "onAttemptStart")
     });
   }, []);
   const chat = useChat({
@@ -667,8 +727,15 @@ function useAgentChat(options) {
     ...options.initialMessages !== void 0 ? {
       messages: options.initialMessages
     } : {},
-    onFinish: /* @__PURE__ */ __name(() => {
+    onFinish: /* @__PURE__ */ __name(({ isError }) => {
       latest.current.onFinish?.();
+      const settledRunId = settlingRunIdRef.current;
+      if (settledRunId !== void 0) {
+        latest.current.onRunSettled?.({
+          runId: settledRunId,
+          status: isError ? "failed" : "completed"
+        });
+      }
     }, "onFinish")
   });
   const chatRef = useRef(chat);
@@ -1373,6 +1440,7 @@ export {
   loadStoredSpeechLang,
   persistSpeechLang,
   storedMessageToUiMessage,
+  storedThreadToUiMessages,
   useAgentChat,
   useSpeechRecognition
 };