feat(chatbot): open reasoning details in a dialog matching the XTM One web chat (#322) (#323)

* feat(chatbot): open reasoning details in a dialog matching the XTM One web chat (#322)

* fix(chatbot): gate reasoning dialog on trace/transfer fields, a11y, docs (#322)

Address the Copilot review pass plus re-review findings:

- ChatMessages: the reasoning-details affordance now also renders when a
  message carries only toolCallTrace and/or transferChain (a backend can
  send the trace without tool_names/reasoning); added aria-label,
  aria-haspopup="dialog" and aria-expanded to the icon-only trigger
- ReasoningDetailsDialog: the header summary count falls back to the
  trace length before the flat tool-name list, so it can never read
  "0 tool calls" above rendered trace rows; transfer-chain chips use a
  composite agentId-index key (the same agent can appear twice in a
  chain and older payloads have no agent_id)
- README: document the new done-payload fields (tool_call_trace,
  transfer_chain, is_truncated) with the restore behavior, and the new
  translation keys

* fix(chatbot): explicit boolean success coercion and dialog focus management (#322)

Address the second Copilot review pass:

- parseToolCallTrace: only a boolean `success` is honored; any missing
  or malformed value defaults to true explicitly (typeof check matching
  the file's defensive-parsing style) instead of the `!== false`
  comparison whose intent was easy to misread
- ReasoningDetailsDialog: move initial keyboard focus to the Close
  button once the portal mounts (aria-modal dialogs must take focus)
  and hand focus back to the previously focused element - the trigger
  button - when the dialog closes

* fix(chatbot): trap Tab focus inside the reasoning-details dialog (#322)

Address the third Copilot review pass: aria-modal promises that focus
stays inside the dialog, but Tab/Shift+Tab could still walk out into
the panel behind the backdrop. The document keydown handler now cycles
focus across the dialog's focusable elements (first <-> last, and pulls
focus back in if it is outside), with dialogRef attached to the dialog
element.

* fix(chatbot): pretty-print trace outputs and share findChatbotRoot (#322)

Address the fourth Copilot review pass:

- ReasoningDetailsDialog: the Output block now goes through the same
  pretty-printing as Input (shared prettyTraceValue helper - compact
  JSON is expanded, plain text / oversized / malformed payloads stay
  raw), matching the XTM One web chat and the PR description
- Extract findChatbotRoot to utils and reuse it from Tooltip, Dropdown
  and ReasoningDetailsDialog - the portal-targeting DOM walk was
  copy-pasted three times and could drift

Author: SamuelHassine

packages/filigran-chatbot/README.md

@@ -256,14 +256,30 @@ data: {"type": "status", "status": "analyzing"}
 data: {"type": "status", "status": "streaming"}
 data: {"type": "stream", "content": "The weather "}
 data: {"type": "stream", "content": "today is sunny."}
-data: {"type": "done", "content": "The weather today is sunny.", "conversation_id": "new-uuid", "tool_names": ["search_web"], "tool_call_count": 1, "iterations": 1, "reasoning": "Let me check the weather data first."}
+data: {"type": "done", "content": "The weather today is sunny.", "conversation_id": "new-uuid", "tool_names": ["search_web"], "tool_call_count": 1, "iterations": 1, "reasoning": "Let me check the weather data first.", "tool_call_trace": [{"name": "search_web", "input": "{\"query\": \"weather\"}", "output": "Sunny, 24C", "success": true}], "transfer_chain": [{"agent_id": "uuid", "agent_name": "General"}], "is_truncated": false}
 ```
 
 The optional `reasoning` field on `done` (and on restored session messages)
 carries the accumulated model reasoning / pre-tool preamble prose for the
-turn. When present it is surfaced in the per-message reasoning-details panel
+turn. When present it is surfaced in the per-message reasoning-details dialog
 (the "i" button), mirroring the XTM One web chat.
 
+The reasoning-details dialog also consumes three more optional `done` fields
+(all parsed defensively — older backends without them fall back to the flat
+tool-name list and the plain "i" affordance):
+
+- `tool_call_trace` — array of `{ name, input, output, success }` entries
+  rendered as expandable rows (numbered, success/failure icon, pretty-printed
+  JSON input, output)
+- `transfer_chain` — array of `{ agent_id, agent_name }` hops rendered as the
+  agent transfer chain
+- `is_truncated` — `true` when the agent's iteration budget was exhausted;
+  the message then shows an always-visible amber warning triangle instead of
+  the hover-only "i" and the dialog opens with a "Turn limit reached" banner
+
+The same fields are read from restored session messages, so the dialog
+survives a page reload.
+
 #### Internal links
 
 Assistant markdown links are routed through `onRelativeLinkClick` when they
@@ -435,8 +451,14 @@ function App() {
 - `'Browse agents'`
 - `'Create agent'`
 - `'Reasoning details'`
+- `'Reasoning details — turn limit reached'`
 - `'Model reasoning'`
 - `'iterations'`
+- `'transfer'` / `'transfers'`
+- `'Transfer chain'`
+- `'Turn limit reached.'`
+- `"The agent's iteration budget was exhausted - execution stopped before completing all planned steps. The final response is a best-effort summary of work done so far."`
+- `'Input'` / `'Output'` / `'(no output)'`
 - `'Download'`
 - `'tool call'` / `'tool calls'`
 - `'Uses AI. Verify results.'`

packages/filigran-chatbot/src/components/ChatMessages.tsx

@@ -1,9 +1,10 @@
 import { useEffect, useRef, useState } from 'react';
 import type { AgentStatusState, ChatAttachment, ChatMessage } from '../types';
 import { splitFileMarkers } from '../utils';
-import { BrainIcon, DownloadIcon, FileIcon, InfoIcon, WrenchIcon } from './icons';
-import { ChatThinking, cleanReasoningText } from './ChatThinking';
+import { AlertTriangleIcon, DownloadIcon, FileIcon, InfoIcon } from './icons';
+import { ChatThinking } from './ChatThinking';
 import { MarkdownMessage } from './MarkdownMessage';
+import { ReasoningDetailsDialog } from './ReasoningDetailsDialog';
 
 interface ChatMessagesProps {
   messages: ChatMessage[];
@@ -258,59 +259,36 @@ export const ChatMessages = ({
               </div>
             )}
 
-            {isAssistant && !isEmpty && !isStreamingMessage && ((msg.toolNames && msg.toolNames.length > 0) || (msg.reasoning ?? '').trim()) && (
-              <>
-                <button
-                  type="button"
-                  onClick={() => setToolDetailMsgId(toolDetailMsgId === msg.id ? null : msg.id)}
-                  className="mt-0.5 p-1 rounded-lg opacity-50 hover:opacity-100 hover:text-[var(--chat-accent)] transition-opacity"
-                  title={t('Reasoning details')}
-                >
-                  <InfoIcon size={14} />
-                </button>
-                {toolDetailMsgId === msg.id && (
-                  <div className="mt-1.5 p-3 rounded-lg bg-gray-50 dark:bg-white/[0.04] border border-gray-200 dark:border-white/10 max-w-[90%]">
-                    {/* Header — mirrors the XTM One web chat "Reasoning details"
-                        dialog (title + iterations/calls summary) so the embedded
-                        chatbot and the native web chat read the same. */}
-                    <div className="flex items-center gap-1.5 mb-1">
-                      <WrenchIcon size={13} className="text-[var(--chat-accent)]" />
-                      <span className="text-[0.75rem] font-semibold text-gray-900 dark:text-white">{t('Reasoning details')}</span>
-                    </div>
-                    <p className="text-[0.7rem] text-gray-500 dark:text-white/40 mb-1.5">
-                      {msg.iterations && msg.iterations > 1 ? `${msg.iterations} ${t('iterations')} · ` : ''}
-                      {msg.toolCallCount ?? msg.toolNames?.length ?? 0}{' '}
-                      {(msg.toolCallCount ?? msg.toolNames?.length ?? 0) === 1 ? t('tool call') : t('tool calls')}
-                    </p>
-                    {(msg.reasoning ?? '').trim() && (
-                      <div className="mb-2">
-                        <div className="flex items-center gap-1.5 mb-1">
-                          <BrainIcon size={13} className="text-[var(--chat-accent)]/70" />
-                          <span className="text-[0.7rem] font-medium text-gray-500 dark:text-white/50">{t('Model reasoning')}</span>
-                        </div>
-                        <div className="rounded-md border border-gray-200 dark:border-white/[0.06] bg-white dark:bg-white/[0.01] px-2.5 py-2 max-h-44 overflow-y-auto">
-                          <p className="m-0 whitespace-pre-wrap break-words text-[0.7rem] leading-5 text-gray-500 dark:text-white/45">
-                            {cleanReasoningText(msg.reasoning!)}
-                          </p>
-                        </div>
-                      </div>
-                    )}
-                    {msg.toolNames && msg.toolNames.length > 0 && (
-                      <div className="flex flex-wrap gap-1">
-                        {Array.from(new Set(msg.toolNames)).map((tn) => (
-                          <span
-                            key={tn}
-                            className="inline-flex items-center px-2 py-0.5 rounded-full border border-gray-200 dark:border-white/10 text-[0.68rem] font-mono text-gray-500 dark:text-white/40"
-                          >
-                            {tn.replace(/_/g, ' ')}
-                          </span>
-                        ))}
-                      </div>
-                    )}
-                  </div>
-                )}
-              </>
-            )}
+            {isAssistant &&
+              !isEmpty &&
+              !isStreamingMessage &&
+              ((msg.toolNames && msg.toolNames.length > 0) ||
+                (msg.reasoning ?? '').trim() ||
+                (msg.toolCallTrace && msg.toolCallTrace.length > 0) ||
+                (msg.transferChain && msg.transferChain.length > 0) ||
+                msg.isTruncated) && (
+                <>
+                  <button
+                    type="button"
+                    onClick={() => setToolDetailMsgId(toolDetailMsgId === msg.id ? null : msg.id)}
+                    className={`mt-0.5 p-1 rounded-lg transition-opacity ${
+                      msg.isTruncated
+                        ? // A truncated turn must be visible at a glance (not
+                          // gated on hover) so the user notices the warning —
+                          // mirrors the XTM One web chat affordance.
+                          'opacity-100 text-amber-500 dark:text-amber-400 hover:text-amber-600 dark:hover:text-amber-300'
+                        : 'opacity-50 hover:opacity-100 hover:text-[var(--chat-accent)]'
+                    }`}
+                    title={msg.isTruncated ? t('Reasoning details — turn limit reached') : t('Reasoning details')}
+                    aria-label={msg.isTruncated ? t('Reasoning details — turn limit reached') : t('Reasoning details')}
+                    aria-haspopup="dialog"
+                    aria-expanded={toolDetailMsgId === msg.id}
+                  >
+                    {msg.isTruncated ? <AlertTriangleIcon size={14} /> : <InfoIcon size={14} />}
+                  </button>
+                  {toolDetailMsgId === msg.id && <ReasoningDetailsDialog msg={msg} onClose={() => setToolDetailMsgId(null)} t={t} />}
+                </>
+              )}
           </div>
         );
       })}

packages/filigran-chatbot/src/components/ChatPanel.tsx

@@ -1,7 +1,7 @@
 import { type FunctionComponent, useCallback, useEffect, useRef, useState } from 'react';
 import type { ChatAttachment, ChatMessage, ChatPanelProps } from '../types';
 import { hexAlpha, identity } from '../utils';
-import { parseAttachments } from '../hooks/protocols/parseRestEvent';
+import { parseAttachments, parseToolCallTrace, parseTransferChain } from '../hooks/protocols/parseRestEvent';
 import { useChat } from '../hooks/useChat';
 import { useAgents } from '../hooks/useAgents';
 import { useConversations } from '../hooks/useConversations';
@@ -308,6 +308,9 @@ export const ChatPanel: FunctionComponent<ChatPanelProps> = ({
               tool_call_count?: unknown;
               iterations?: unknown;
               reasoning?: unknown;
+              tool_call_trace?: unknown;
+              transfer_chain?: unknown;
+              is_truncated?: unknown;
             },
             i: number,
           ) => ({
@@ -329,6 +332,9 @@ export const ChatPanel: FunctionComponent<ChatPanelProps> = ({
             toolCallCount: typeof m.tool_call_count === 'number' ? m.tool_call_count : undefined,
             iterations: typeof m.iterations === 'number' ? m.iterations : undefined,
             reasoning: typeof m.reasoning === 'string' ? m.reasoning : undefined,
+            toolCallTrace: parseToolCallTrace(m.tool_call_trace),
+            transferChain: parseTransferChain(m.transfer_chain),
+            isTruncated: m.is_truncated === true || undefined,
           }),
         );
         setMessages(restored);

packages/filigran-chatbot/src/components/Dropdown.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { useClickOutside } from '../hooks/useClickOutside';
+import { findChatbotRoot } from '../utils';
 
 interface DropdownProps {
   open: boolean;
@@ -11,15 +12,6 @@ interface DropdownProps {
   children: React.ReactNode;
 }
 
-function findChatbotRoot(el: HTMLElement | null): HTMLElement {
-  let node = el;
-  while (node) {
-    if (node.classList.contains('filigran-chatbot')) return node;
-    node = node.parentElement;
-  }
-  return document.body;
-}
-
 export const Dropdown = ({ open, onClose, anchorRef, placement = 'bottom-start', width = 280, children }: DropdownProps) => {
   const panelRef = useRef<HTMLDivElement>(null);
   const [pos, setPos] = useState({ top: 0, left: 0 });