+
+ )
+}
diff --git a/frontends/ui/src/shared/components/Sources/parse-references.spec.ts b/frontends/ui/src/shared/components/Sources/parse-references.spec.ts
new file mode 100644
index 000000000..f294f4c97
--- /dev/null
+++ b/frontends/ui/src/shared/components/Sources/parse-references.spec.ts
@@ -0,0 +1,203 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, test } from 'vitest'
+import {
+ splitReferences,
+ tabularizeEntityLines,
+ renumberOrderedLists,
+ nestBulletsUnderOrderedItems,
+ stripTrailingReferences,
+ extractSchemaTables,
+} from './parse-references'
+
+describe('extractSchemaTables', () => {
+ const diagram = [
+ 'Here is the schema:',
+ '',
+ '```mermaid',
+ 'erDiagram',
+ ' customers ||--o{ sales_orders : places',
+ ' sales_orders ||--|{ order_lines : contains',
+ ' customers {',
+ ' string customer_id',
+ ' string segment',
+ ' }',
+ ' sales_orders {',
+ ' string order_id',
+ ' }',
+ ' order_lines {',
+ ' string line_id',
+ ' }',
+ '```',
+ ].join('\n')
+
+ test('pulls table names from entity blocks and relationships, sorted and de-duped', () => {
+ expect(extractSchemaTables(diagram)).toEqual(['customers', 'order_lines', 'sales_orders'])
+ })
+
+ test('returns empty for content with no mermaid ER diagram', () => {
+ expect(extractSchemaTables('just a normal answer with no diagram')).toEqual([])
+ expect(extractSchemaTables('```mermaid\nflowchart TD\n A --> B\n```')).toEqual([])
+ })
+})
+
+describe('nestBulletsUnderOrderedItems', () => {
+ test('indents bullets that follow a numbered item so they nest under it', () => {
+ const md = '1. Top drivers:\n- Schumacher: 91\n- Prost: 51'
+ expect(nestBulletsUnderOrderedItems(md)).toBe('1. Top drivers:\n - Schumacher: 91\n - Prost: 51')
+ })
+
+ test('leaves top-level bullets with no preceding numbered item alone', () => {
+ const md = '- a\n- b'
+ expect(nestBulletsUnderOrderedItems(md)).toBe(md)
+ })
+
+ test('stops nesting at a heading', () => {
+ const md = '1. x\n- under x\n## Section\n- top level'
+ expect(nestBulletsUnderOrderedItems(md)).toBe('1. x\n - under x\n## Section\n- top level')
+ })
+
+ test('re-indents an under-indented (1-2 space) bullet to nest under the item', () => {
+ const md = '2. Categories:\n - Garment: $1\n - Swimwear: $2'
+ expect(nestBulletsUnderOrderedItems(md)).toBe('2. Categories:\n - Garment: $1\n - Swimwear: $2')
+ })
+
+ test('leaves an already-nested (3+ space) bullet untouched', () => {
+ const md = '2. Categories:\n - Garment: $1\n - deeper'
+ expect(nestBulletsUnderOrderedItems(md)).toBe(md)
+ })
+})
+
+describe('stripTrailingReferences', () => {
+ test('strips a trailing `## Sources` section ([N] Title: URL format)', () => {
+ const md =
+ 'The report is complete [1].\n\n## Sources\n[1] Q4 report: https://x.com/r\n[2] Internal notes: knowledge_search'
+ expect(stripTrailingReferences(md)).toBe('The report is complete [1].')
+ })
+
+ test('strips a `### References` heading section', () => {
+ const md = 'Body text [1].\n\n### References\n[1] fleet_overview.pdf, p.4'
+ expect(stripTrailingReferences(md)).toBe('Body text [1].')
+ })
+
+ test('strips a bold `**Sources**` label section', () => {
+ const md = 'Body.\n\n**Sources**\n[1] thing - https://a.example.com'
+ expect(stripTrailingReferences(md)).toBe('Body.')
+ })
+
+ test('strips even when the listed lines are not [N]-parseable', () => {
+ const md = 'Body.\n\n## Sources\n1 Internal KB: schema\n7 Internal KB: knowledge_search'
+ expect(stripTrailingReferences(md)).toBe('Body.')
+ })
+
+ test('leaves a body with no references section unchanged', () => {
+ const md = 'Just a report.\n\n## Conclusion\nAll good.'
+ expect(stripTrailingReferences(md)).toBe(md)
+ })
+})
+
+describe('renumberOrderedLists', () => {
+ test('renumbers top-level items that all restart at 1', () => {
+ const md = '1. Counts:\n- a: 1\n- b: 2\n1. Top drivers:\n- x\n1. Summary:'
+ expect(renumberOrderedLists(md)).toBe('1. Counts:\n- a: 1\n- b: 2\n2. Top drivers:\n- x\n3. Summary:')
+ })
+
+ test('resets numbering at each heading so sections keep 1-based order', () => {
+ const md = '## A\n1. one\n1. two\n## B\n1. three'
+ expect(renumberOrderedLists(md)).toBe('## A\n1. one\n2. two\n## B\n1. three')
+ })
+
+ test('leaves already-sequential lists and nested items untouched', () => {
+ const md = '1. one\n2. two\n 1. nested'
+ expect(renumberOrderedLists(md)).toBe(md)
+ })
+
+ test('renumber + nest-bullets leave fenced content untouched', () => {
+ const body = '1. one\n```chart\n1. not-a-list-item\n- not-a-bullet\n```\n1. two'
+ expect(renumberOrderedLists(body)).toBe('1. one\n```chart\n1. not-a-list-item\n- not-a-bullet\n```\n2. two')
+ expect(nestBulletsUnderOrderedItems(body)).toBe(body)
+ })
+})
+
+describe('splitReferences', () => {
+ test('returns the body unchanged when there is no references block', () => {
+ const content = 'The fleet has 11,463 GPUs across 12 clusters.'
+ const { body, sources } = splitReferences(content)
+ expect(body).toBe(content)
+ expect(sources).toEqual([])
+ })
+
+ test('strips a **References:** block and parses web sources', () => {
+ const content =
+ 'NVIDIA shipped record volume [1].\n\n**References:**\n- [1] NVIDIA Q4 results - https://www.nvidia.com/news\n- [2] Industry brief - https://docs.example.ai/report'
+ const { body, sources } = splitReferences(content)
+ expect(body).toBe('NVIDIA shipped record volume [1].')
+ expect(sources).toHaveLength(2)
+ expect(sources[0]).toMatchObject({
+ title: 'NVIDIA Q4 results',
+ url: 'https://www.nvidia.com/news',
+ kind: 'web',
+ label: 'nvidia.com',
+ })
+ expect(sources[1]).toMatchObject({ url: 'https://docs.example.ai/report', kind: 'web', label: 'docs.example.ai' })
+ })
+
+ test('parses file-with-page and bare tool references as documents', () => {
+ const content =
+ 'See attached docs [1] and the search [2].\n\n## Sources\n- [1] fleet_overview.pdf, p.4\n- [2] knowledge_search'
+ const { body, sources } = splitReferences(content)
+ expect(body).toBe('See attached docs [1] and the search [2].')
+ expect(sources[0]).toMatchObject({ kind: 'doc', title: 'fleet_overview.pdf, p.4' })
+ expect(sources[1]).toMatchObject({ kind: 'doc', title: 'knowledge_search', label: 'knowledge_search' })
+ })
+
+ test('orders sources by their [N] index regardless of line order', () => {
+ const content =
+ 'Body.\n\n**References**\n- [2] Second - https://b.example.com\n- [1] First - https://a.example.com'
+ const { sources } = splitReferences(content)
+ expect(sources.map((s) => s.title)).toEqual(['First', 'Second'])
+ })
+
+ test('leaves content intact when the block has no parseable lines', () => {
+ const content = 'Body.\n\n**References:**\nnothing structured here'
+ const { body, sources } = splitReferences(content)
+ expect(body).toBe(content)
+ expect(sources).toEqual([])
+ })
+})
+
+describe('tabularizeEntityLines', () => {
+ test('reflows 2+ consecutive label: value lines into a GFM table', () => {
+ const body = 'Top teams by job count:\n\nteam_051: ~11,285 jobs\nteam_009: ~8,210 jobs\nteam_044: ~6,140 jobs'
+ const out = tabularizeEntityLines(body)
+ expect(out).toContain('| Item | Value |')
+ expect(out).toContain('| --- | --- |')
+ expect(out).toContain('| team_051 | ~11,285 jobs |')
+ expect(out).toContain('| team_044 | ~6,140 jobs |')
+ })
+
+ test('leaves prose untouched', () => {
+ const body = 'The result is clear: the fleet is healthy. Utilization rose this quarter.'
+ expect(tabularizeEntityLines(body)).toBe(body)
+ })
+
+ test('does not tabularize a single label: value line', () => {
+ const body = 'Summary: the fleet is healthy'
+ expect(tabularizeEntityLines(body)).toBe(body)
+ })
+
+ test('does not touch markdown list items', () => {
+ const body = '- team_051: ~11,285 jobs\n- team_009: ~8,210 jobs'
+ expect(tabularizeEntityLines(body)).toBe(body)
+ })
+
+ test('copies fenced ```chart blocks through verbatim (no table from JSON)', () => {
+ const body =
+ 'Distribution by model:\n\n```chart\n{\n "type": "bar",\n "series": [{ "key": "count" }],\n "data": [{ "model": "H100", "count": 5120 }]\n}\n```\n\nH100 leads.'
+ const out = tabularizeEntityLines(body)
+ expect(out).toBe(body)
+ expect(out).not.toContain('| Item | Value |')
+ expect(out).toContain('"count": 5120')
+ })
+})
diff --git a/frontends/ui/src/shared/components/Sources/parse-references.ts b/frontends/ui/src/shared/components/Sources/parse-references.ts
new file mode 100644
index 000000000..65f2ae747
--- /dev/null
+++ b/frontends/ui/src/shared/components/Sources/parse-references.ts
@@ -0,0 +1,295 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { inferSourceKind, prettyDomain, sourceLabel } from './source-utils'
+import type { SourceRef } from './types'
+
+/**
+ * Matches a trailing references block baked into a response by the backend, e.g.
+ * `\n\n**References:**\n- [1] Title - https://...`. Captures everything after the
+ * heading so each `- [N] ...` line can be parsed into a {@link SourceRef}.
+ */
+const REFERENCES_BLOCK_RE =
+ /\n{1,2}(?:\*\*References:?\*\*|#{2,3}\s+(?:References|Sources))\s*\n([\s\S]*)$/i
+
+/** A single `- [N] ...` reference line. */
+const REFERENCE_LINE_RE = /^\s*[-*]?\s*\[(\d{1,3})\]\s*(.+?)\s*$/
+
+/** A trailing ` - URL` (web source) on a reference line. */
+const TRAILING_URL_RE = /^(.*?)\s*[-\u2013\u2014]\s*(https?:\/\/\S+)\s*$/i
+
+/** A `filename, p.N` / `filename p. N` file-with-page tail. */
+const FILE_PAGE_RE = /,?\s*p\.?\s*\d+\s*$/i
+
+export interface SplitReferencesResult {
+ /** The response body with the trailing references block removed. */
+ body: string
+ /** Sources parsed from the references block, ordered by their `[N]` index. */
+ sources: SourceRef[]
+}
+
+/**
+ * Parse one `- [N] ...` reference line into a {@link SourceRef}. Supports three
+ * baked shapes: `Title - URL` (web), `filename, p.X` (document) and a bare
+ * `tool name`. The kind/label are inferred from the URL when present, else the
+ * text, reusing {@link inferSourceKind}/{@link sourceLabel}/{@link prettyDomain}.
+ */
+function parseReferenceLine(n: number, rest: string): SourceRef {
+ const urlMatch = rest.match(TRAILING_URL_RE)
+ if (urlMatch) {
+ const title = urlMatch[1].trim()
+ const url = urlMatch[2].trim()
+ const kind = inferSourceKind(url)
+ return {
+ id: `ref-${n}`,
+ title: title || prettyDomain(url) || url,
+ url,
+ kind,
+ label: sourceLabel(url, kind),
+ }
+ }
+
+ const ref = rest.trim()
+ const kind = inferSourceKind(ref)
+ const isFile = FILE_PAGE_RE.test(ref) || kind === 'doc'
+ return {
+ id: `ref-${n}`,
+ title: ref || `Source ${n}`,
+ kind: isFile ? 'doc' : kind,
+ label: isFile ? ref || sourceLabel(ref, 'doc') : sourceLabel(ref, kind),
+ }
+}
+
+/**
+ * Split a response into its prose `body` and the structured `sources` parsed
+ * from a trailing references block (`**References:**` / `## Sources`). When no
+ * such block exists, `body` is the unchanged input and `sources` is empty.
+ * Sources are ordered by their `[N]` index.
+ */
+export function splitReferences(content: string): SplitReferencesResult {
+ if (!content) return { body: content ?? '', sources: [] }
+
+ const match = content.match(REFERENCES_BLOCK_RE)
+ if (!match) return { body: content, sources: [] }
+
+ const block = match[1]
+ const byIndex = new Map()
+ for (const line of block.split('\n')) {
+ const lineMatch = line.match(REFERENCE_LINE_RE)
+ if (!lineMatch) continue
+ const n = parseInt(lineMatch[1], 10)
+ if (!Number.isFinite(n) || byIndex.has(n)) continue
+ byIndex.set(n, parseReferenceLine(n, lineMatch[2]))
+ }
+
+ if (byIndex.size === 0) return { body: content, sources: [] }
+
+ const sources = [...byIndex.entries()].sort((a, b) => a[0] - b[0]).map(([, s]) => s)
+ const body = content.slice(0, match.index).replace(/\s+$/, '')
+ return { body, sources }
+}
+
+/**
+ * A trailing References/Sources section: a heading of any level (`# Sources` ...
+ * `###### Sources`) or a bold label (`**Sources**` / `**References:**`), through
+ * to the end of the document.
+ */
+const TRAILING_REFERENCES_RE =
+ /\n{1,2}(?:#{1,6}\s+(?:References|Sources)|\*\*\s*(?:References|Sources)\s*:?\s*\*\*)\s*:?\s*\n[\s\S]*$/i
+
+/**
+ * Remove a trailing References/Sources section from a body, unconditionally.
+ * Unlike {@link splitReferences}, this does not require the listed lines to be
+ * individually parseable. A report renders its citations as a structured source
+ * list, so the writer's text `## Sources` block at the end is redundant and is
+ * stripped here to avoid showing sources twice.
+ */
+export function stripTrailingReferences(body: string): string {
+ if (!body) return body
+ return body.replace(TRAILING_REFERENCES_RE, '').replace(/\s+$/, '')
+}
+
+const HEADING_RE = /^\s{0,3}#{1,6}\s/
+const TOP_ORDERED_RE = /^(\d+)\.(\s)/
+/** A fenced code-block delimiter (```). */
+const FENCE_RE = /^\s*```/
+
+/**
+ * Renumber top-level ordered-list items sequentially. Markdown restarts an
+ * ordered list whenever a sub-list or block interrupts it, so a model that emits
+ * `1.` for every section renders as "1. 1. 1." instead of "1. 2. 3.". This walks
+ * the body and renumbers top-level `N.` items in order, resetting at each heading
+ * (so distinct sections keep their own 1-based numbering). Indented / nested
+ * ordered items are left untouched, and already-sequential lists are unchanged.
+ */
+export function renumberOrderedLists(body: string): string {
+ if (!body) return body
+ const lines = body.split('\n')
+ let counter = 0
+ let inFence = false
+ for (let i = 0; i < lines.length; i++) {
+ if (FENCE_RE.test(lines[i])) {
+ inFence = !inFence
+ continue
+ }
+ if (inFence) continue
+ if (HEADING_RE.test(lines[i])) {
+ counter = 0
+ continue
+ }
+ const match = lines[i].match(TOP_ORDERED_RE)
+ if (match) {
+ counter += 1
+ lines[i] = lines[i].replace(TOP_ORDERED_RE, `${counter}.${match[2]}`)
+ }
+ }
+ return lines.join('\n')
+}
+
+const BULLET_TOP_RE = /^(\s*)[-*+]\s/
+
+/**
+ * Indent bullet lists that follow a top-level ordered item so they render nested
+ * under it. A model often emits the bullets at (or near) the same left margin as
+ * the `N.` items, which reads as a flat list. While in an ordered list, an
+ * under-indented bullet (0-2 leading spaces) is normalized to a 3-space indent
+ * so CommonMark nests it as a sub-list of the preceding numbered item; bullets
+ * already indented >= 3 (correctly nested or deeper) are left untouched, and
+ * top-level bullets with no preceding numbered item are never moved.
+ */
+export function nestBulletsUnderOrderedItems(body: string): string {
+ if (!body) return body
+ const lines = body.split('\n')
+ let inOrdered = false
+ let inFence = false
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i]
+ if (FENCE_RE.test(line)) {
+ inFence = !inFence
+ continue
+ }
+ if (inFence) continue
+ if (HEADING_RE.test(line)) {
+ inOrdered = false
+ continue
+ }
+ if (TOP_ORDERED_RE.test(line)) {
+ inOrdered = true
+ continue
+ }
+ const bullet = line.match(BULLET_TOP_RE)
+ if (bullet) {
+ if (inOrdered && bullet[1].length < 3) lines[i] = ` ${line.replace(/^\s+/, '')}`
+ continue
+ }
+ if (line.trim() !== '' && !/^\s/.test(line)) inOrdered = false
+ }
+ return lines.join('\n')
+}
+
+/** A short `label: value` line with no sentence punctuation. */
+const ENTITY_LINE_RE = /^\s*([^:\n]{1,60}?):\s+(\S.{0,80})$/
+/** Sentence-like punctuation that signals prose, not a metric line. */
+const SENTENCE_PUNCT_RE = /[.!?](\s|$)/
+
+function isEntityLine(line: string): boolean {
+ const m = line.match(ENTITY_LINE_RE)
+ if (!m) return false
+ const [, label, value] = m
+ if (SENTENCE_PUNCT_RE.test(label) || SENTENCE_PUNCT_RE.test(value)) return false
+ if (label.includes('|') || value.includes('|')) return false
+ return true
+}
+
+function escapeCell(text: string): string {
+ return text.trim().replace(/\|/g, '\\|')
+}
+
+/**
+ * Conservatively reflow runs of 2+ consecutive `label: value` lines (entity /
+ * metric lists like `team_051: ~11,285 jobs`) into a 2-column GFM table so they
+ * render as a scannable grid instead of flat lines. Anything that looks like a
+ * sentence, a list item, or a heading is left untouched. Tightly gated to avoid
+ * mangling prose.
+ */
+export function tabularizeEntityLines(body: string): string {
+ if (!body || !body.includes(':')) return body
+
+ const lines = body.split('\n')
+ const out: string[] = []
+ let i = 0
+ while (i < lines.length) {
+ // Copy fenced code blocks through verbatim so their JSON `"key": value`
+ // lines are never reflowed into a table.
+ if (FENCE_RE.test(lines[i])) {
+ out.push(lines[i])
+ i++
+ while (i < lines.length && !FENCE_RE.test(lines[i])) {
+ out.push(lines[i])
+ i++
+ }
+ if (i < lines.length) {
+ out.push(lines[i])
+ i++
+ }
+ continue
+ }
+ const isMarkup =
+ /^\s*[-*+]\s/.test(lines[i]) || /^\s*#{1,6}\s/.test(lines[i]) || /^\s*\d+\.\s/.test(lines[i])
+ if (!isMarkup && isEntityLine(lines[i])) {
+ let j = i
+ while (
+ j < lines.length &&
+ !/^\s*[-*+]\s/.test(lines[j]) &&
+ !/^\s*#{1,6}\s/.test(lines[j]) &&
+ !/^\s*\d+\.\s/.test(lines[j]) &&
+ isEntityLine(lines[j])
+ ) {
+ j++
+ }
+ const run = lines.slice(i, j)
+ if (run.length >= 2) {
+ out.push('| Item | Value |')
+ out.push('| --- | --- |')
+ for (const line of run) {
+ const m = line.match(ENTITY_LINE_RE) as RegExpMatchArray
+ out.push(`| ${escapeCell(m[1])} | ${escapeCell(m[2])} |`)
+ }
+ i = j
+ continue
+ }
+ }
+ out.push(lines[i])
+ i++
+ }
+
+ return out.join('\n')
+}
+
+const MERMAID_FENCE_RE = /```mermaid\s*([\s\S]*?)```/i
+const ER_ENTITY_RE = /^[ \t]*([A-Za-z_][\w-]*)\s*\{/gm
+const ER_RELATION_RE = /^[ \t]*([A-Za-z_][\w-]*)\s+[|}{o.\-]+\s+([A-Za-z_][\w-]*)\s*:/gm
+
+/**
+ * Pulls the table (entity) names out of a fenced mermaid `erDiagram`, from both
+ * the `TABLE { ... }` definition blocks and the `A ||--o{ B :` relationship
+ * lines. A schema answer is otherwise just a diagram with no `**References:**`
+ * block, so {@link splitReferences} finds nothing; these names let the answer
+ * still surface what it covers. Returns a sorted, de-duped list (empty when the
+ * content has no ER diagram).
+ */
+export function extractSchemaTables(content: string): string[] {
+ const fence = content.match(MERMAID_FENCE_RE)
+ if (!fence) return []
+ const codeBlock = fence[1]
+ if (!/\berDiagram\b/i.test(codeBlock)) return []
+
+ const names = new Set()
+ for (const m of codeBlock.matchAll(ER_ENTITY_RE)) names.add(m[1])
+ for (const m of codeBlock.matchAll(ER_RELATION_RE)) {
+ names.add(m[1])
+ names.add(m[2])
+ }
+ names.delete('erDiagram')
+ return [...names].sort((a, b) => a.localeCompare(b))
+}
diff --git a/frontends/ui/src/shared/components/Sources/source-utils.spec.ts b/frontends/ui/src/shared/components/Sources/source-utils.spec.ts
new file mode 100644
index 000000000..166af9cc2
--- /dev/null
+++ b/frontends/ui/src/shared/components/Sources/source-utils.spec.ts
@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, test } from 'vitest'
+import { inferSourceKind, mapCitationSource, prettyDomain, sourceLabel } from './source-utils'
+
+describe('inferSourceKind', () => {
+ test('classifies web urls as web', () => {
+ expect(inferSourceKind('https://nvidia.com/blog')).toBe('web')
+ expect(inferSourceKind('http://docs.example.ai/x')).toBe('web')
+ })
+ test('classifies everything else as doc', () => {
+ expect(inferSourceKind('knowledge_search')).toBe('doc')
+ expect(inferSourceKind('fleet_overview.pdf')).toBe('doc')
+ expect(inferSourceKind('mystery')).toBe('doc')
+ expect(inferSourceKind(undefined)).toBe('doc')
+ })
+})
+
+describe('prettyDomain', () => {
+ test('strips protocol and www', () => {
+ expect(prettyDomain('https://www.nvidia.com/path?q=1')).toBe('nvidia.com')
+ expect(prettyDomain('http://docs.example.ai/x')).toBe('docs.example.ai')
+ })
+ test('degrades for non-urls', () => {
+ expect(prettyDomain('knowledge_search')).toBe('knowledge_search')
+ expect(prettyDomain(undefined)).toBe('')
+ })
+})
+
+describe('sourceLabel', () => {
+ test('domain for web, document label otherwise', () => {
+ expect(sourceLabel('https://www.example.com', 'web')).toBe('example.com')
+ expect(sourceLabel('knowledge_search', 'doc')).toBe('knowledge_search')
+ expect(sourceLabel(undefined, 'doc')).toBe('Document')
+ })
+})
+
+describe('mapCitationSource', () => {
+ test('maps a web citation', () => {
+ const ref = mapCitationSource({ id: 'c1', url: 'https://www.nvidia.com', content: 'NVIDIA news\nmore' }, 0)
+ expect(ref).toMatchObject({ id: 'c1', kind: 'web', label: 'nvidia.com', title: 'NVIDIA news', url: 'https://www.nvidia.com' })
+ expect(ref.snippet).toContain('NVIDIA news')
+ })
+ test('maps a document citation with no real url', () => {
+ const ref = mapCitationSource({ id: 'c2', url: 'knowledge_search', content: 'There are 11,463 users.' }, 1)
+ expect(ref.kind).toBe('doc')
+ expect(ref.label).toBe('knowledge_search')
+ expect(ref.url).toBeUndefined()
+ expect(ref.title).toBe('There are 11,463 users.')
+ })
+ test('synthesises an id and title when missing', () => {
+ const ref = mapCitationSource({ id: '', url: 'knowledge_search', content: '' }, 2)
+ expect(ref.id).toBe('src-2')
+ expect(ref.title).toBe('knowledge_search')
+ })
+})
diff --git a/frontends/ui/src/shared/components/Sources/source-utils.ts b/frontends/ui/src/shared/components/Sources/source-utils.ts
new file mode 100644
index 000000000..34d765013
--- /dev/null
+++ b/frontends/ui/src/shared/components/Sources/source-utils.ts
@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { SourceKind, SourceRef } from './types'
+
+/**
+ * Infer the {@link SourceKind} from a source reference (a URL or a file ref).
+ * Web URLs map to `web`; everything else (files, tool refs, bare text) to `doc`.
+ */
+export function inferSourceKind(ref: string | undefined): SourceKind {
+ if (!ref) return 'doc'
+ if (/^https?:\/\//i.test(ref)) return 'web'
+ return 'doc'
+}
+
+/**
+ * Reduce a URL to a clean, scannable domain (`www.` and protocol stripped),
+ * falling back to the raw ref when it is not a parseable URL.
+ */
+export function prettyDomain(ref: string | undefined): string {
+ if (!ref) return ''
+ try {
+ return new URL(ref).hostname.replace(/^www\./, '')
+ } catch {
+ return ref.replace(/^[a-z]+:\/\//i, '').split('/')[0]
+ }
+}
+
+/**
+ * Build the footer label shown on a source card: the domain for web sources,
+ * a friendly document label otherwise.
+ */
+export function sourceLabel(ref: string | undefined, kind: SourceKind): string {
+ if (kind === 'web') return prettyDomain(ref)
+ return prettyDomain(ref) || 'Document'
+}
+
+/**
+ * Map a backend {@link CitationSource}-like record into a UI {@link SourceRef}.
+ * The first non-empty line of `content` becomes the title; the full content is
+ * kept as the hover snippet.
+ */
+export function mapCitationSource(
+ cs: { id: string; url: string; content?: string },
+ index: number,
+): SourceRef {
+ const kind = inferSourceKind(cs.url)
+ const firstLine = (cs.content ?? '').split('\n').map((l) => l.trim()).find(Boolean)
+ const label = sourceLabel(cs.url, kind)
+ return {
+ id: cs.id || `src-${index}`,
+ title: firstLine || label || cs.url || `Source ${index + 1}`,
+ url: kind === 'web' ? cs.url : undefined,
+ snippet: cs.content || undefined,
+ kind,
+ label: label || `Source ${index + 1}`,
+ }
+}
diff --git a/frontends/ui/src/shared/components/Sources/types.ts b/frontends/ui/src/shared/components/Sources/types.ts
new file mode 100644
index 000000000..d8b7209c9
--- /dev/null
+++ b/frontends/ui/src/shared/components/Sources/types.ts
@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Origin of a cited source. Drives the icon and accent so users can tell
+ * document-backed claims from web ones at a glance.
+ */
+export type SourceKind = 'web' | 'doc'
+
+/**
+ * UI-facing representation of a cited source, mapped from the backend's
+ * {@link CitationSource}. Kept renderer-agnostic so both inline citation chips
+ * and the source-card strip consume the same shape.
+ */
+export interface SourceRef {
+ id: string
+ title: string
+ url?: string
+ snippet?: string
+ kind: SourceKind
+ label: string
+}
diff --git a/frontends/ui/src/shared/components/Surface/Card.spec.tsx b/frontends/ui/src/shared/components/Surface/Card.spec.tsx
new file mode 100644
index 000000000..bec976f43
--- /dev/null
+++ b/frontends/ui/src/shared/components/Surface/Card.spec.tsx
@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'vitest'
+import { Card } from './Card'
+
+describe('Card', () => {
+ test('renders children', () => {
+ render(hello)
+ expect(screen.getByText('hello')).toBeInTheDocument()
+ })
+
+ test('applies the shared surface and default tone', () => {
+ const { container } = render(x)
+ const el = container.firstChild as HTMLElement
+ expect(el.className).toContain('bg-surface-raised')
+ expect(el.className).toContain('border-base')
+ })
+
+ test('source tones add an accent border without changing the base shape', () => {
+ const { container } = render(x)
+ const el = container.firstChild as HTMLElement
+ expect(el.className).toContain('border-l-[color:var(--text-color-subtle)]')
+ expect(el.className).toContain('bg-surface-raised')
+ })
+
+ test('the doc tone accents the left border', () => {
+ const { container } = render(x)
+ const el = container.firstChild as HTMLElement
+ expect(el.className).toContain('border-l-[color:var(--text-color-base)]')
+ })
+
+ test('merges a caller className and forwards arbitrary props', () => {
+ render(
+
+ x
+ ,
+ )
+ const el = screen.getByTestId('card')
+ expect(el).toHaveAttribute('role', 'group')
+ expect(el.className).toContain('p-2')
+ expect(el.className).not.toContain('p-4')
+ })
+})
diff --git a/frontends/ui/src/shared/components/Surface/Card.tsx b/frontends/ui/src/shared/components/Surface/Card.tsx
new file mode 100644
index 000000000..71a3bd52b
--- /dev/null
+++ b/frontends/ui/src/shared/components/Surface/Card.tsx
@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cn } from '@/shared/lib/cn'
+
+/**
+ * Visual tone of a {@link Card}. Status tones (`active`/`success`/`error`) and
+ * source tones (`web`/`doc`) add an accent without changing the base surface, so
+ * every card in the chat UI shares one shape and radius.
+ */
+export type CardTone = 'default' | 'active' | 'success' | 'error' | 'web' | 'doc'
+
+const TONE_CLASS: Record = {
+ default: 'border-base',
+ active: 'border-[color:var(--color-brand)]',
+ success: 'border-[color:var(--color-green-500)]',
+ error: 'border-[color:var(--text-color-error,#d9534f)]',
+ web: 'border-base border-l-2 border-l-[color:var(--text-color-subtle)]',
+ doc: 'border-base border-l-2 border-l-[color:var(--text-color-base)]',
+}
+
+interface CardProps extends HTMLAttributes {
+ tone?: CardTone
+}
+
+/**
+ * Single surface primitive used across the chat UI. Replaces the ad-hoc
+ * `rounded-lg border bg-surface-*` blocks so cards are visually consistent.
+ */
+export function Card({ tone = 'default', className, children, ...rest }: CardProps): ReactNode {
+ return (
+
+ {children}
+
+ )
+}
diff --git a/frontends/ui/src/shared/components/research/StatusDot.tsx b/frontends/ui/src/shared/components/research/StatusDot.tsx
new file mode 100644
index 000000000..3a507d284
--- /dev/null
+++ b/frontends/ui/src/shared/components/research/StatusDot.tsx
@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { FC } from 'react'
+import { cn } from '@/shared/lib/cn'
+
+/**
+ * Lifecycle state of an agent-trace node. Drives the single status atom used by
+ * both the inline chat trace and the research panel, so a node looks identical
+ * wherever it appears.
+ */
+export type NodeState = 'running' | 'done' | 'pending' | 'waiting' | 'interrupted' | 'error'
+
+/** A single status atom: the only source of truth for every node's look. */
+export const StatusDot: FC<{ state: NodeState; size?: 'sm' | 'xs' }> = ({ state, size = 'sm' }) => (
+
+)
diff --git a/frontends/ui/src/shared/components/research/ToolCallRow.tsx b/frontends/ui/src/shared/components/research/ToolCallRow.tsx
new file mode 100644
index 000000000..5e286c7d8
--- /dev/null
+++ b/frontends/ui/src/shared/components/research/ToolCallRow.tsx
@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { FC } from 'react'
+import { Text } from '@/adapters/ui'
+import { SourceKindIcon } from '@/shared/components/Sources/SourceKindIcon'
+import { StatusDot, type NodeState } from './StatusDot'
+import { getToolLabel } from './research-labels'
+
+/**
+ * One tool / model call in an agent trace: a status atom, the source-kind glyph,
+ * the human label, and an optional truncated summary of the call's input. Shared
+ * verbatim by the inline chat trace and the research panel so a tool call reads
+ * the same wherever it shows up. `label` overrides the derived human label (used
+ * by group headers that summarize several calls under one family name) while
+ * keeping the source-kind glyph driven by `name`.
+ */
+export const ToolCallRow: FC<{
+ name: string
+ status: NodeState
+ args?: string
+ size?: 'sm' | 'xs'
+ label?: string
+}> = ({ name, status, args, size = 'sm', label: labelOverride }) => {
+ const { label: derivedLabel, kind } = getToolLabel(name)
+ const label = labelOverride ?? derivedLabel
+ return (
+
+
+
+
+
+
+
+
+
+ {label}
+
+ {args && (
+
+ {args}
+
+ )}
+
+
+ )
+}
diff --git a/frontends/ui/src/shared/components/research/index.ts b/frontends/ui/src/shared/components/research/index.ts
new file mode 100644
index 000000000..e9ccc117f
--- /dev/null
+++ b/frontends/ui/src/shared/components/research/index.ts
@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Shared agent-trace primitives consumed by both the inline chat trace
+ * (ChatThinking) and the research panel.
+ */
+
+export { StatusDot, type NodeState } from './StatusDot'
+export { ToolCallRow } from './ToolCallRow'
+export {
+ getAgentLabel,
+ getToolLabel,
+ isKnownTool,
+ getToolArgSummary,
+ formatModelName,
+ statusToNodeState,
+ todoStatusToNodeState,
+} from './research-labels'
diff --git a/frontends/ui/src/shared/components/research/research-labels.spec.ts b/frontends/ui/src/shared/components/research/research-labels.spec.ts
new file mode 100644
index 000000000..76ff196a9
--- /dev/null
+++ b/frontends/ui/src/shared/components/research/research-labels.spec.ts
@@ -0,0 +1,113 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, test } from 'vitest'
+import {
+ formatModelName,
+ getToolArgSummary,
+ getToolLabel,
+ isKnownTool,
+ statusToNodeState,
+ todoStatusToNodeState,
+} from './research-labels'
+
+describe('getToolLabel', () => {
+ test('maps known tools to human labels and kinds', () => {
+ expect(getToolLabel('web_search_tool')).toEqual({ label: 'Searching the web', kind: 'web' })
+ expect(getToolLabel('advanced_web_search_tool')).toEqual({
+ label: 'Searching the web (advanced)',
+ kind: 'web',
+ })
+ expect(getToolLabel('paper_search_tool')).toEqual({ label: 'Searching papers', kind: 'doc' })
+ expect(getToolLabel('knowledge_search')).toEqual({
+ label: 'Searching the knowledge base',
+ kind: 'doc',
+ })
+ })
+
+ test('collapses a function-group prefix to the recognized tool', () => {
+ expect(getToolLabel('search__web_search_tool').label).toBe('Searching the web')
+ })
+
+ test('strips angle brackets from internal wrapper names', () => {
+ expect(getToolLabel('').label).not.toContain('<')
+ expect(getToolLabel('').label).not.toContain('>')
+ })
+
+ test('renders agent nodes with their human agent title', () => {
+ expect(getToolLabel('researcher').label).toBe('Researching')
+ expect(getToolLabel('writer-agent').label).toBe('Writing the report')
+ expect(getToolLabel('source-router-agent').label).toBe('Routing sources')
+ })
+
+ test('renders a model id as its last path segment in all caps', () => {
+ expect(getToolLabel('azure/openai/gpt-5.2').label).toBe('GPT-5.2')
+ expect(getToolLabel('gpt-oss-120b').label).toBe('GPT-OSS-120B')
+ expect(getToolLabel('nemotron-3-super-120b-long-ctx').label).toBe(
+ 'NEMOTRON-3-SUPER-120B-LONG-CTX'
+ )
+ })
+})
+
+describe('formatModelName', () => {
+ test('upper-cases the final path segment', () => {
+ expect(formatModelName('azure/openai/gpt-5.2')).toBe('GPT-5.2')
+ expect(formatModelName('gpt-oss-120b')).toBe('GPT-OSS-120B')
+ })
+})
+
+describe('isKnownTool', () => {
+ test('true for tools, false for agents and models', () => {
+ expect(isKnownTool('web_search_tool')).toBe(true)
+ expect(isKnownTool('knowledge_search')).toBe(true)
+ expect(isKnownTool('researcher')).toBe(false)
+ expect(isKnownTool('gpt-5.2')).toBe(false)
+ })
+})
+
+describe('getToolArgSummary', () => {
+ test('extracts the field value from a json payload string, not the raw dict', () => {
+ expect(getToolArgSummary('web_search_tool', "```json {'query': 'Count the drivers'}```")).toBe(
+ 'Count the drivers'
+ )
+ })
+
+ test('reads the query from a structured web-search input', () => {
+ expect(getToolArgSummary('web_search_tool', { query: 'latest GPU roadmap' })).toBe(
+ 'latest GPU roadmap'
+ )
+ })
+
+ test('reads the path from a structured file-op input', () => {
+ expect(getToolArgSummary('write_file', { file_path: '/shared/x.json', content: 'big blob' })).toBe(
+ '/shared/x.json'
+ )
+ })
+
+ test('suppresses raw LLM message / prompt dumps', () => {
+ expect(
+ getToolArgSummary('intent_classifier', "```python messages=[HumanMessage(content='hi')]```")
+ ).toBeUndefined()
+ expect(getToolArgSummary('llm', "[SystemMessage(content='You are the orchestrator')]")).toBeUndefined()
+ })
+
+ test('returns undefined for a dict with no known field and for missing input', () => {
+ expect(getToolArgSummary('x', "{'foo': 'bar'}")).toBeUndefined()
+ expect(getToolArgSummary('x', undefined)).toBeUndefined()
+ })
+})
+
+describe('status mappers', () => {
+ test('statusToNodeState maps streaming statuses', () => {
+ expect(statusToNodeState('complete')).toBe('done')
+ expect(statusToNodeState('error')).toBe('error')
+ expect(statusToNodeState('running')).toBe('running')
+ })
+
+ test('todoStatusToNodeState maps todo statuses', () => {
+ expect(todoStatusToNodeState('in_progress')).toBe('running')
+ expect(todoStatusToNodeState('completed')).toBe('done')
+ expect(todoStatusToNodeState('stopped')).toBe('interrupted')
+ expect(todoStatusToNodeState('pending')).toBe('pending')
+ })
+})
diff --git a/frontends/ui/src/shared/components/research/research-labels.ts b/frontends/ui/src/shared/components/research/research-labels.ts
new file mode 100644
index 000000000..7c2e614c6
--- /dev/null
+++ b/frontends/ui/src/shared/components/research/research-labels.ts
@@ -0,0 +1,244 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Research labels: the single source of truth for human-readable agent / tool
+ * copy. The UI never shows a raw backend name; it asks this module for a title,
+ * a blurb, a kind (for icon + accent), and a short argument summary instead.
+ */
+
+import { titleCaseWords } from '@/shared/lib/humanize'
+import type { SourceKind } from '@/shared/components/Sources/types'
+import type { NodeState } from './StatusDot'
+
+interface AgentLabel {
+ /** Short present-participle headline (e.g. "Researching"). */
+ title: string
+ /** One-line explanation of what the agent is doing. */
+ blurb: string
+}
+
+const AGENT_LABELS: Record = {
+ 'source-router-agent': {
+ title: 'Routing sources',
+ blurb: 'Choosing which sources can answer the question',
+ },
+ 'planner-agent': {
+ title: 'Planning',
+ blurb: 'Breaking the question into research steps',
+ },
+ researcher: {
+ title: 'Researching',
+ blurb: 'Gathering and reading sources',
+ },
+ 'researcher-agent': {
+ title: 'Researching',
+ blurb: 'Gathering and reading sources',
+ },
+ 'writer-agent': {
+ title: 'Writing the report',
+ blurb: 'Synthesizing findings into the final answer',
+ },
+}
+
+/**
+ * Human-readable label for an agent / workflow node. Falls back to a title-cased
+ * version of the name with any trailing "-agent" suffix dropped.
+ */
+export const getAgentLabel = (name: string): AgentLabel => {
+ const known = AGENT_LABELS[name]
+ if (known) return known
+ return { title: titleCaseWords(name.replace(/-agent$/, '')), blurb: '' }
+}
+
+interface ToolLabel {
+ label: string
+ kind: SourceKind
+}
+
+const TOOL_LABELS: Record = {
+ write_todos: { label: 'Planning tasks', kind: 'doc' },
+ task: { label: 'Delegating a sub-task', kind: 'doc' },
+ lookup_source_catalog: { label: 'Browsing data sources', kind: 'doc' },
+ write_file: { label: 'Writing a file', kind: 'doc' },
+ read_file: { label: 'Reading a file', kind: 'doc' },
+ ls: { label: 'Listing files', kind: 'doc' },
+ edit_file: { label: 'Editing a file', kind: 'doc' },
+ grep: { label: 'Searching files', kind: 'doc' },
+ glob: { label: 'Finding files', kind: 'doc' },
+ run_research_batch: { label: 'Running research', kind: 'doc' },
+ web_search_tool: { label: 'Searching the web', kind: 'web' },
+ advanced_web_search_tool: { label: 'Searching the web (advanced)', kind: 'web' },
+ paper_search_tool: { label: 'Searching papers', kind: 'doc' },
+ knowledge_search: { label: 'Searching the knowledge base', kind: 'doc' },
+ get_verified_sources: { label: 'Finding verified sources', kind: 'doc' },
+ think: { label: 'Reasoning', kind: 'doc' },
+}
+
+/**
+ * Normalize a raw tool name to its lookup key: lowercase, drop a leading
+ * "tool:" announcement prefix, and collapse a single leading "__"
+ * function-group prefix when the full name is not itself a recognized tool.
+ */
+const normalizeToolName = (name: string): string => {
+ let normalized = (name || '').toLowerCase().trim().replace(/^tool:\s*/, '')
+ if (TOOL_LABELS[normalized]) return normalized
+ const prefixed = normalized.match(/^[a-z0-9]+__(.+)$/)
+ if (prefixed && !TOOL_LABELS[normalized]) {
+ normalized = prefixed[1]
+ }
+ return normalized
+}
+
+/**
+ * Display form of a model id: the final path segment, fully upper-cased
+ * (e.g. "azure/openai/gpt-5.2" -> "GPT-5.2", "gpt-oss-120b" -> "GPT-OSS-120B").
+ * Model names read as identifiers, so they are shown in all caps rather than
+ * title-cased.
+ */
+export const formatModelName = (name: string): string => {
+ const base = (name || '').includes('/') ? (name.split('/').pop() ?? name) : name
+ return base.toUpperCase()
+}
+
+/**
+ * Human-readable label + source kind for a tool node. Falls back to a
+ * title-cased name with a generic 'doc' kind.
+ */
+export const getToolLabel = (name: string): ToolLabel => {
+ name = (name || '').replace(/^<+|>+$/g, '')
+ const raw = name.toLowerCase().trim().replace(/^tool:\s*/, '')
+ if (TOOL_LABELS[raw]) return TOOL_LABELS[raw]
+ const normalized = normalizeToolName(name)
+ if (TOOL_LABELS[normalized]) return TOOL_LABELS[normalized]
+ // Agent / workflow nodes (e.g. "researcher", "writer-agent") show their human
+ // agent title so the inline trace reads the same as the research panel.
+ if (AGENT_LABELS[raw] || /-agent$/.test(raw) || raw === 'researcher') {
+ return { label: getAgentLabel(raw).title, kind: 'doc' }
+ }
+ const base = name.includes('/') ? (name.split('/').pop() ?? name) : name
+ const looksLikeModel = name.includes('/') || (base.includes('-') && !/[_\s]/.test(base))
+ return { label: looksLikeModel ? formatModelName(name) : titleCaseWords(base), kind: 'doc' }
+}
+
+/**
+ * Whether a function name maps to a recognized tool (one in TOOL_LABELS, e.g.
+ * web_search_tool, paper_search_tool). Agents, model/LLM nodes, and folded
+ * reasoning steps are not tools. Used by the trace to dedupe a tool that
+ * surfaces more than once without touching non-tool rows.
+ */
+export const isKnownTool = (name: string): boolean => {
+ const raw = (name || '').replace(/^<+|>+$/g, '').toLowerCase().trim().replace(/^tool:\s*/, '')
+ return Boolean(TOOL_LABELS[raw] || TOOL_LABELS[normalizeToolName(name)])
+}
+
+const ARG_KEYS = [
+ 'question',
+ 'query',
+ 'search_query',
+ 'prompt',
+ 'description',
+ 'file_path',
+ 'filename',
+ 'path',
+ 'pattern',
+ 'content',
+] as const
+
+const MAX_ARG_LEN = 240
+
+const truncate = (text: string): string => {
+ const trimmed = text.replace(/\s+/g, ' ').trim()
+ if (trimmed.length <= MAX_ARG_LEN) return trimmed
+ return trimmed.slice(0, MAX_ARG_LEN - 1).trimEnd() + '…'
+}
+
+/** Leading ```json / ```python fence + trailing fence, so we can read the body. */
+const CODE_FENCE = /^```[a-z]*\s*|\s*```$/gi
+
+/** Signatures of a raw LLM message / prompt dump that carries no useful "input". */
+const DUMP_SIGNATURE = /messages\s*=|SystemMessage|HumanMessage|AIMessage|TextContent|ChatContentType|\bMessage\(/
+
+const unescapeQuotedValue = (value: string): string => value.replace(/\\([\\"'])/g, '$1')
+
+/** Pull one quoted string field from JSON or a Python-dict-style payload. */
+const extractStringField = (text: string, key: string): string | undefined => {
+ const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+ const doubleQuoted = text.match(
+ new RegExp(`["']${escapedKey}["']\\s*:\\s*"((?:\\\\.|[^"\\\\])*)"`)
+ )
+ if (doubleQuoted) return unescapeQuotedValue(doubleQuoted[1]).trim()
+
+ const singleQuoted = text.match(
+ new RegExp(`["']${escapedKey}["']\\s*:\\s*'((?:\\\\.|[^'\\\\])*)'`)
+ )
+ if (singleQuoted) return unescapeQuotedValue(singleQuoted[1]).trim()
+ return undefined
+}
+
+/** Pull the value of the first known arg key out of a json/dict-ish string. */
+const extractField = (text: string): string | undefined => {
+ for (const key of ARG_KEYS) {
+ const value = extractStringField(text, key)
+ if (value) return value
+ }
+ return undefined
+}
+
+/**
+ * Short, human summary of a tool's INPUT for a secondary trace line: a few
+ * relevant words (a file path, a query), never a raw JSON / python / message
+ * dump. Reads structured input directly; for the inline payload string it strips
+ * code fences and pulls out a known field. Returns undefined when there is
+ * nothing readable to show (e.g. an LLM messages array).
+ */
+export const getToolArgSummary = (
+ name: string,
+ input?: Record | string
+): string | undefined => {
+ if (input == null) return undefined
+
+ if (typeof input === 'object') {
+ for (const key of ARG_KEYS) {
+ const value = input[key]
+ if (typeof value !== 'string' || !value.trim()) continue
+ return truncate(value)
+ }
+ return undefined
+ }
+
+ let text = input.trim()
+ if (!text) return undefined
+ const markerMatch = text.match(/(?:Function Input:|Input:)\s*([\s\S]+)/i)
+ if (markerMatch) text = markerMatch[1].trim()
+ text = text.replace(CODE_FENCE, '').trim()
+
+ const field = extractField(text)
+ if (field) return truncate(field)
+ // A messages/prompt dump or an unparseable dict has nothing readable to show.
+ if (DUMP_SIGNATURE.test(text) || text.startsWith('{') || text.startsWith('[')) return undefined
+ return truncate(text) || undefined
+}
+
+/** Map a streaming agent/tool status to a trace NodeState. */
+export const statusToNodeState = (s: 'running' | 'complete' | 'error'): NodeState => {
+ if (s === 'complete') return 'done'
+ if (s === 'error') return 'error'
+ return 'running'
+}
+
+/** Map a todo-item status to a trace NodeState. */
+export const todoStatusToNodeState = (
+ s: 'pending' | 'in_progress' | 'completed' | 'stopped'
+): NodeState => {
+ switch (s) {
+ case 'in_progress':
+ return 'running'
+ case 'completed':
+ return 'done'
+ case 'stopped':
+ return 'interrupted'
+ default:
+ return 'pending'
+ }
+}
diff --git a/frontends/ui/src/shared/lib/cn.spec.ts b/frontends/ui/src/shared/lib/cn.spec.ts
new file mode 100644
index 000000000..d40d41dd1
--- /dev/null
+++ b/frontends/ui/src/shared/lib/cn.spec.ts
@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, test } from 'vitest'
+import { cn } from './cn'
+
+describe('cn', () => {
+ test('joins truthy class names and drops falsy values', () => {
+ expect(cn('a', false, 'b', undefined, null, 'c', 0 && 'd')).toBe('a b c')
+ })
+
+ test('later conflicting Tailwind utilities win', () => {
+ expect(cn('p-2', 'p-4')).toBe('p-4')
+ expect(cn('rounded-sm', 'rounded-lg')).toBe('rounded-lg')
+ })
+
+ test('supports conditional object and array inputs', () => {
+ expect(cn('base', { active: true, hidden: false }, ['x', 'y'])).toBe('base active x y')
+ })
+})
diff --git a/frontends/ui/src/shared/lib/cn.ts b/frontends/ui/src/shared/lib/cn.ts
new file mode 100644
index 000000000..eb4aa03d7
--- /dev/null
+++ b/frontends/ui/src/shared/lib/cn.ts
@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/**
+ * Compose conditional class names with clsx and resolve conflicting Tailwind
+ * utilities with tailwind-merge so later classes win deterministically.
+ */
+export function cn(...inputs: ClassValue[]): string {
+ return twMerge(clsx(inputs))
+}
diff --git a/frontends/ui/src/shared/lib/humanize.spec.ts b/frontends/ui/src/shared/lib/humanize.spec.ts
new file mode 100644
index 000000000..ccf1faa9e
--- /dev/null
+++ b/frontends/ui/src/shared/lib/humanize.spec.ts
@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, test } from 'vitest'
+import { ACRONYMS, titleCaseWords } from './humanize'
+
+describe('titleCaseWords', () => {
+ test('title-cases ordinary tokens', () => {
+ expect(titleCaseWords('web_search_tool')).toBe('Web Search Tool')
+ expect(titleCaseWords('knowledge_search')).toBe('Knowledge Search')
+ })
+
+ test('upper-cases known acronyms', () => {
+ expect(titleCaseWords('api_gateway')).toBe('API Gateway')
+ expect(titleCaseWords('sql_query')).toBe('SQL Query')
+ expect(titleCaseWords('gpt_router')).toBe('GPT Router')
+ for (const acronym of ACRONYMS) {
+ expect(titleCaseWords(acronym)).toBe(acronym.toUpperCase())
+ }
+ })
+
+ test('collapses repeated separators and whitespace, tolerates empty', () => {
+ expect(titleCaseWords('api__gateway')).toBe('API Gateway')
+ expect(titleCaseWords('web search tool')).toBe('Web Search Tool')
+ expect(titleCaseWords('')).toBe('')
+ })
+})
diff --git a/frontends/ui/src/shared/lib/humanize.ts b/frontends/ui/src/shared/lib/humanize.ts
new file mode 100644
index 000000000..1da7d6074
--- /dev/null
+++ b/frontends/ui/src/shared/lib/humanize.ts
@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Tokens that render fully upper-cased in humanized names (e.g. tool / function
+ * labels) rather than title-cased, so `api_gateway` becomes "API Gateway", not
+ * "Api Gateway".
+ */
+export const ACRONYMS = new Set(['ai', 'api', 'sql', 'gpt', 'llm', 'url', 'pdf', 'csv', 'json'])
+
+/**
+ * Humanize a snake_case / `__`-separated identifier into a display label,
+ * upper-casing known acronyms. Collapses runs of separators (so
+ * `web_search_tool` -> "Web Search Tool", `api__gateway` -> "API Gateway").
+ */
+export function titleCaseWords(text: string): string {
+ return text
+ .split(/[_\s]+/)
+ .filter(Boolean)
+ .map((word) =>
+ ACRONYMS.has(word.toLowerCase())
+ ? word.toUpperCase()
+ : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+ )
+ .join(' ')
+}
diff --git a/frontends/ui/src/shared/lib/motion.spec.tsx b/frontends/ui/src/shared/lib/motion.spec.tsx
new file mode 100644
index 000000000..7354daa16
--- /dev/null
+++ b/frontends/ui/src/shared/lib/motion.spec.tsx
@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ReactNode } from 'react'
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { render, screen } from '@/test-utils'
+import { AppMotionConfig } from './motion'
+
+const useReducedMotion = vi.hoisted(() => vi.fn(() => false))
+vi.mock('@/hooks/use-reduced-motion', () => ({ useReducedMotion }))
+
+const captured = vi.hoisted(() => ({ reducedMotion: undefined as string | undefined }))
+vi.mock('motion/react', () => ({
+ MotionConfig: ({ reducedMotion, children }: { reducedMotion?: string; children: ReactNode }) => {
+ captured.reducedMotion = reducedMotion
+ return children
+ },
+}))
+
+describe('AppMotionConfig', () => {
+ afterEach(() => {
+ vi.clearAllMocks()
+ captured.reducedMotion = undefined
+ })
+
+ test('maps allowed motion to reducedMotion="never"', () => {
+ useReducedMotion.mockReturnValue(false)
+ render(
+
+ content
+ ,
+ )
+ expect(screen.getByText('content')).toBeInTheDocument()
+ expect(captured.reducedMotion).toBe('never')
+ })
+
+ test('maps a reduced-motion preference to reducedMotion="always"', () => {
+ useReducedMotion.mockReturnValue(true)
+ render(
+
+ reduced
+ ,
+ )
+ expect(screen.getByText('reduced')).toBeInTheDocument()
+ expect(captured.reducedMotion).toBe('always')
+ })
+})
diff --git a/frontends/ui/src/shared/lib/motion.tsx b/frontends/ui/src/shared/lib/motion.tsx
new file mode 100644
index 000000000..a44000007
--- /dev/null
+++ b/frontends/ui/src/shared/lib/motion.tsx
@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+'use client'
+
+import type { ReactNode } from 'react'
+import { MotionConfig } from 'motion/react'
+import { useReducedMotion } from '@/hooks/use-reduced-motion'
+
+/**
+ * Centralizes Motion configuration so every animation honors the user's
+ * `prefers-reduced-motion` setting. Mount once near the application root.
+ */
+export function AppMotionConfig({ children }: { children: ReactNode }): ReactNode {
+ const reduce = useReducedMotion()
+
+ return {children}
+}