@theoremjs/react 0.0.0-stage → 0.3.0

package/ui/TraceOverview.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '@astryxdesign/core/Button';
+import { Card } from '@astryxdesign/core/Card';
+import { Grid } from '@astryxdesign/core/Grid';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Icon } from '@astryxdesign/core/Icon';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { Text } from '@astryxdesign/core/Text';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconArrowLeft, IconChevronLeft, IconChevronRight } from '@tabler/icons-react';
+import { TRACE_FIELDS, traceAttributeMeta } from '@theoremjs/agents';
+import { isCallTrace } from "../client/trace-story.js";
+import { TRACE_HUE } from "./trace-palette.js";
+import { useTraceFormat } from "./TraceValues.js";
+/** Width a chart draws at before it has measured its column: the panel's narrowest. */
+export const FIRST_WIDTH_PX = 280;
+/**
+ * Holds a chart. Recharts makes its layers focusable, so a click would move
+ * focus into the SVG and draw the browser's ring; a press here keeps focus
+ * where it was. Clicks and pointer drags still reach the chart.
+ */
+export function ChartFrame({ children }) {
+    return _jsx("div", { onMouseDown: (event) => event.preventDefault(), children: children });
+}
+/** A chart's hover card, drawn like Astryx's own tooltip. */
+export function ChartTip({ children }) {
+    return (_jsx("div", { style: {
+            background: 'var(--color-background-popover)',
+            border: '1px solid var(--color-border)',
+            borderRadius: 'var(--radius-element)',
+            padding: '6px 8px',
+            boxShadow: 'var(--shadow-med)',
+            pointerEvents: 'none',
+        }, children: children }));
+}
+/** Which turn is open: its name, and the previous and next turn. */
+export function TurnPicker({ turns, index, onChange, onBack, }) {
+    const { t } = useTraceFormat();
+    const turn = turns[index];
+    if (!turn)
+        return null;
+    const isCalls = isCallTrace(turns);
+    return (_jsxs(VStack, { gap: 1, hAlign: "start", children: [onBack ? (_jsx(Button, { label: t(isCalls ? '@theorem.panel.trace.calls.back' : '@theorem.panel.trace.conversation.back'), variant: "ghost", size: "sm", icon: _jsx(Icon, { icon: IconArrowLeft }), onClick: onBack })) : null, _jsxs(HStack, { gap: 1, align: "center", justify: "between", width: "100%", children: [_jsxs(HStack, { gap: 2, align: "center", children: [_jsx(Text, { weight: "semibold", children: t('@theorem.panel.trace.turn', { label: turn.node.meta.label, index: index + 1, count: turns.length }) }), turn.node.meta.subject ? (_jsx(Text, { color: "secondary", maxLines: 1, children: turn.node.meta.subject })) : null] }), _jsxs(HStack, { gap: 0, children: [_jsx(IconButton, { label: t(isCalls ? '@theorem.panel.trace.calls.previous' : '@theorem.panel.trace.previous'), icon: _jsx(Icon, { icon: IconChevronLeft }), variant: "ghost", size: "sm", isDisabled: index === 0, onClick: () => onChange(index - 1) }), _jsx(IconButton, { label: t(isCalls ? '@theorem.panel.trace.calls.next' : '@theorem.panel.trace.next'), icon: _jsx(Icon, { icon: IconChevronRight }), variant: "ghost", size: "sm", isDisabled: index === turns.length - 1, onClick: () => onChange(index + 1) })] })] })] }));
+}
+function Stat({ label, value, detail }) {
+    return (_jsx(Card, { padding: 3, variant: "muted", style: { background: 'var(--color-background-surface)' }, children: _jsxs(VStack, { gap: 1, children: [_jsx(Text, { type: "supporting", color: "secondary", children: label }), _jsx(Text, { type: "large", weight: "semibold", hasTabularNumbers: true, children: value }), _jsx(VStack, { gap: 0, children: [detail]
+                        .flat()
+                        .filter(Boolean)
+                        .map((line) => (_jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: line }, String(line)))) })] }) }));
+}
+function FirstTextStat({ latency, format }) {
+    if (latency?.firstTextMs === undefined)
+        return null;
+    const { t } = format;
+    return (_jsx(Stat, { label: t('@theorem.panel.trace.firstText'), value: format.duration(latency.firstTextMs), detail: [
+            latency.tokensPerSecond !== undefined && t('@theorem.panel.trace.rate', { rate: format.number(Math.round(latency.tokensPerSecond)) }),
+            latency.heldMs && t('@theorem.panel.trace.held', { duration: format.duration(latency.heldMs) }),
+        ] }));
+}
+function CostStat({ totals, format }) {
+    if (!totals.cost)
+        return null;
+    return _jsx(Stat, { label: traceAttributeMeta('theorem.usage.cost_usd')?.label ?? '', value: format.sum(totals.cost, format.usd) });
+}
+/** A token total as its card reads it: "–" when no call reported it. */
+function tokenSide(total, format) {
+    return total ? format.sum(total, format.number) : '–';
+}
+function TokensStat({ totals, format }) {
+    const { input, output } = totals;
+    if (!input && !output)
+        return null;
+    const all = [input, output].reduce((sum, total) => sum + (total?.value ?? 0), 0);
+    return (_jsx(Stat, { label: format.t('@theorem.panel.trace.tokens'), value: format.number(all), detail: format.t('@theorem.panel.trace.tokens.detail', { input: tokenSide(input, format), output: tokenSide(output, format) }) }));
+}
+function StepsStat({ totals, tools, format }) {
+    const { t } = format;
+    // With no model, every step is a tool call the heading already counts.
+    if (totals.calls === 0 && totals.errors === 0)
+        return null;
+    return (_jsx(Stat, { label: t('@theorem.panel.trace.steps'), value: format.number(totals.calls + tools), detail: totals.errors > 0 ? (_jsx("span", { style: { color: TRACE_HUE.oxblood }, children: t('@theorem.panel.trace.failed', { count: totals.errors }) })) : (t('@theorem.panel.trace.steps.detail', { calls: totals.calls, tools })) }));
+}
+function GuardrailsStat({ latency, format }) {
+    const guardrails = latency?.guardrails;
+    if (!guardrails)
+        return null;
+    return (_jsx(Stat, { label: format.t('@theorem.panel.trace.guardrails'), value: format.duration(guardrails.ms), detail: format.t('@theorem.panel.trace.guardrails.detail', { checks: guardrails.checks, flagged: guardrails.flagged }) }));
+}
+/**
+ * Duration, first text, cost, tokens, steps and guardrails of the open turn;
+ * a total the trace did not record is left out.
+ */
+export function TurnStats({ totals, tools, latency }) {
+    const format = useTraceFormat();
+    return (_jsxs(Grid, { columns: { minWidth: 120, repeat: 'fit' }, gap: 2, children: [_jsx(Stat, { label: TRACE_FIELDS.duration.label, value: format.duration(totals.durationMs) }), _jsx(FirstTextStat, { latency: latency, format: format }), _jsx(CostStat, { totals: totals, format: format }), _jsx(TokensStat, { totals: totals, format: format }), _jsx(StepsStat, { totals: totals, tools: tools, format: format }), _jsx(GuardrailsStat, { latency: latency, format: format })] }));
+}

package/ui/TraceSpanDetail.d.ts

@@ -0,0 +1,10 @@
+import { type TraceNode } from '../client/trace-view.ts';
+/** One span in full: who acted and how it ended, what went in and came out, its tokens, then every detail it recorded. */
+export declare function TraceSpanDetail({ node, turnStartMs, isClose, onBack, onOpen, }: {
+    node: TraceNode;
+    turnStartMs: number;
+    /** In the wide panel the span sits beside the turn: close, not back. */
+    isClose?: boolean;
+    onBack: () => void;
+    onOpen: (node: TraceNode) => void;
+}): import("react").JSX.Element;

package/ui/TraceSpanDetail.js

@@ -0,0 +1,188 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Badge } from '@astryxdesign/core/Badge';
+import { Button } from '@astryxdesign/core/Button';
+import { Card } from '@astryxdesign/core/Card';
+import { Collapsible } from '@astryxdesign/core/Collapsible';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Icon } from '@astryxdesign/core/Icon';
+import { Item } from '@astryxdesign/core/Item';
+import { MetadataList, MetadataListItem } from '@astryxdesign/core/MetadataList';
+import { Text } from '@astryxdesign/core/Text';
+import { Token } from '@astryxdesign/core/Token';
+import { Tooltip as HoverTip } from '@astryxdesign/core/Tooltip';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconArrowLeft, IconX } from '@tabler/icons-react';
+import { inlineContent, TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceEventAttributeMeta, traceEventMeta, } from '@theoremjs/agents';
+import { messageText, storedValue, traceActor, traceOutcome } from "../client/trace-story.js";
+import { nanosToMs } from "../client/trace-view.js";
+import { ShapedData } from "./ShapedData.js";
+import { ActorMark } from "./TraceStory.js";
+import { attributeSections, TRACE_LABEL_PX, TraceAttributeList, TraceValue, useTraceFormat } from "./TraceValues.js";
+/** A span's own field, read as an attribute of that format. */
+function fieldMeta(field, format) {
+    return { ...field, format, group: 'record' };
+}
+const SPAN_FIELD_META = {
+    type: { ...fieldMeta(TRACE_FIELDS.type, 'text'), options: TRACE_SPAN_TYPES },
+    status: { ...fieldMeta(TRACE_FIELDS.status, 'text'), options: TRACE_STATUS },
+    start: fieldMeta(TRACE_FIELDS.start, 'time'),
+    traceId: fieldMeta(TRACE_FIELDS.traceId, 'id'),
+    spanId: fieldMeta(TRACE_FIELDS.spanId, 'id'),
+};
+function spanFieldMeta(key) {
+    return key in SPAN_FIELD_META ? SPAN_FIELD_META[key] : undefined;
+}
+function Section({ title, children }) {
+    return (_jsx(Collapsible, { defaultIsOpen: false, trigger: _jsx(Text, { weight: "medium", children: title }), children: children }));
+}
+function EventList({ node }) {
+    const format = useTraceFormat();
+    return (_jsx(VStack, { gap: 3, children: node.span.events.map((event, index) => {
+            const offset = format.t('@theorem.panel.trace.offset', {
+                duration: format.duration(nanosToMs(event.timeUnixNano) - node.startMs),
+            });
+            const label = traceEventMeta(event.name)?.label ?? event.name;
+            return (_jsxs(VStack, { gap: 1, children: [_jsxs(HStack, { gap: 2, align: "center", children: [_jsx(Text, { weight: "medium", children: label }), _jsx(Text, { type: "supporting", hasTabularNumbers: true, children: offset })] }), _jsx(TraceAttributeList, { record: node.record, attributes: event.attributes, metaOf: (key) => traceEventAttributeMeta(event.name, key) })] }, `${event.name}:${event.timeUnixNano}:${index}`));
+        }) }));
+}
+function LinkList({ node }) {
+    return (_jsx(VStack, { gap: 3, children: node.span.links.map((link) => (_jsx(TraceAttributeList, { record: node.record, attributes: { traceId: link.traceId, spanId: link.spanId, ...link.attributes }, metaOf: (key) => spanFieldMeta(key) ?? traceAttributeMeta(key) }, `${link.traceId}:${link.spanId}`))) }));
+}
+const SPAN_FIELD_VALUES = {
+    type: (node) => node.meta.type,
+    start: (node) => node.span.startTimeUnixNano,
+    traceId: (node) => node.span.traceId,
+    spanId: (node) => node.span.spanId,
+};
+/** What the span was, how long it took, what it cost and when it started. */
+function spanFacts(node, turnStartMs, format) {
+    const cost = node.span.attributes['theorem.usage.cost_usd'];
+    return [
+        node.meta.label,
+        format.duration(node.durationMs),
+        ...(typeof cost === 'number' ? [format.usd(cost)] : []),
+        format.t('@theorem.panel.trace.offset', { duration: format.duration(node.startMs - turnStartMs) }),
+    ].join(format.t('@theorem.panel.trace.separator'));
+}
+function OutcomeBadge({ outcome }) {
+    if (!outcome)
+        return null;
+    return (_jsx(HoverTip, { content: outcome.doc ?? outcome.label, children: _jsx(Badge, { variant: outcome.tone, label: outcome.label }) }));
+}
+/** The span's status message, unless the outcome badge already says it. */
+function StatusMessage({ node, outcome }) {
+    const message = node.span.status.message;
+    if (!message || message.toLowerCase() === outcome?.label.toLowerCase())
+        return null;
+    return _jsx(Text, { color: "secondary", children: message });
+}
+/** Back (or close), then who acted, what it was, how it ended, how long it took and what it cost. */
+function SpanHeader({ node, turnStartMs, onBack, isClose }) {
+    const format = useTraceFormat();
+    const outcome = traceOutcome(node);
+    return (_jsxs(VStack, { gap: 2, children: [_jsx(HStack, { children: _jsx(Button, { label: format.t(isClose ? '@theorem.panel.trace.close' : '@theorem.panel.trace.back'), variant: "ghost", size: "sm", icon: _jsx(Icon, { icon: isClose ? IconX : IconArrowLeft }), onClick: onBack }) }), _jsx(Item, { startContent: _jsx(ActorMark, { actor: traceActor(node) }), label: _jsx(Text, { weight: "semibold", children: node.meta.subject ?? node.meta.label }), description: spanFacts(node, turnStartMs, format), endContent: _jsx(OutcomeBadge, { outcome: outcome }), align: "start" }), _jsx(StatusMessage, { node: node, outcome: outcome })] }));
+}
+function Panel({ title, doc, children }) {
+    return (_jsx(Card, { padding: 3, variant: "muted", style: { background: 'var(--color-background-surface)' }, children: _jsxs(VStack, { gap: 2, children: [_jsx(HoverTip, { content: doc ?? title, children: _jsx(Text, { type: "supporting", color: "secondary", children: title }) }), children] }) }));
+}
+function Prose({ text }) {
+    return _jsx("span", { style: { whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: text });
+}
+function parsed(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function ToolCallPart({ part }) {
+    return (_jsxs(VStack, { gap: 1, children: [_jsx(Text, { weight: "medium", children: String(part.name ?? '') }), _jsx(ShapedData, { value: parsed(part.arguments) })] }));
+}
+/** One message part: its text, or a tool call's name and arguments, or what a tool returned. */
+function PartView({ part }) {
+    if (part.type === 'text' && typeof part.content === 'string')
+        return _jsx(Prose, { text: part.content });
+    if (part.type === 'tool_call')
+        return _jsx(ToolCallPart, { part: part });
+    const body = part.response ?? part.result ?? part.content;
+    return body === undefined ? null : _jsx(ShapedData, { value: parsed(body) });
+}
+/** Messages as the model saw them: each one's role, then its parts. */
+function MessageList({ messages }) {
+    return (_jsx(VStack, { gap: 3, children: messages.map((message, index) => (_jsxs(VStack, { gap: 1, children: [_jsx(HStack, { children: _jsx(Token, { label: String(message.role ?? ''), size: "sm", color: "gray" }) }), Array.isArray(message.parts)
+                    ? message.parts.filter(isObject).map((part, at) => _jsx(PartView, { part: part }, at))
+                    : null] }, index))) }));
+}
+function messagesOf(node, key) {
+    const value = inlineContent(node.record, node.span.attributes[key]);
+    return Array.isArray(value) ? value.filter(isObject) : [];
+}
+function label(key) {
+    const meta = traceAttributeMeta(key);
+    return meta ? { title: meta.label, doc: meta.doc } : { title: key };
+}
+/** A stored value under its attribute's name; nothing when the span has none. */
+function DataPanel({ attribute, value }) {
+    if (value === undefined)
+        return null;
+    return (_jsx(Panel, { ...label(attribute), children: _jsx(ShapedData, { value: value }) }));
+}
+/** Text under its attribute's name; nothing when there is none. */
+function ProsePanel({ attribute, text }) {
+    if (typeof text !== 'string' || !text)
+        return null;
+    return (_jsx(Panel, { ...label(attribute), children: _jsx(Prose, { text: text }) }));
+}
+function TurnIO({ node }) {
+    return (_jsxs(_Fragment, { children: [_jsx(ProsePanel, { attribute: "gen_ai.input.messages", text: messageText(node, 'gen_ai.input.messages', 'user') }), _jsx(ProsePanel, { attribute: "gen_ai.output.messages", text: messageText(node, 'gen_ai.output.messages', 'assistant') })] }));
+}
+function CallIO({ node }) {
+    const input = messagesOf(node, 'gen_ai.input.messages');
+    const output = messagesOf(node, 'gen_ai.output.messages');
+    return (_jsxs(_Fragment, { children: [output.length > 0 ? (_jsx(Panel, { ...label('gen_ai.output.messages'), children: _jsx(MessageList, { messages: output }) })) : null, input.length > 0 ? (_jsx(Collapsible, { defaultIsOpen: false, trigger: _jsx(Text, { weight: "medium", children: `${label('gen_ai.input.messages').title} · ${input.length}` }), children: _jsx(Card, { padding: 3, variant: "muted", style: { background: 'var(--color-background-surface)' }, children: _jsx(MessageList, { messages: input }) }) })) : null] }));
+}
+function ToolIO({ node }) {
+    const { attributes } = node.span;
+    const result = 'theorem.tool.data' in attributes ? 'theorem.tool.data' : 'gen_ai.tool.call.result';
+    return (_jsxs(_Fragment, { children: [_jsx(DataPanel, { attribute: "gen_ai.tool.call.arguments", value: storedValue(node, 'gen_ai.tool.call.arguments') }), _jsx(DataPanel, { attribute: result, value: storedValue(node, result) }), _jsx(ProsePanel, { attribute: "exception.message", text: 'exception.message' in attributes ? storedValue(node, 'exception.message') : undefined })] }));
+}
+/** What went in and what came out, read the way a person would: text, messages, or a tool's data. */
+function SpanIO({ node }) {
+    switch (node.meta.type) {
+        case 'turn':
+            return _jsx(TurnIO, { node: node });
+        case 'call':
+        case 'response':
+            return _jsx(CallIO, { node: node });
+        case 'tool':
+            return _jsx(ToolIO, { node: node });
+        default:
+            return null;
+    }
+}
+/** The span's own fields: its type, start and IDs. */
+function SpanFields({ node }) {
+    return (_jsx(MetadataList, { columns: "single", label: { position: 'start', width: TRACE_LABEL_PX }, children: Object.keys(SPAN_FIELD_VALUES).map((key) => (_jsx(MetadataListItem, { label: SPAN_FIELD_META[key].label, children: _jsx(TraceValue, { record: node.record, meta: SPAN_FIELD_META[key], value: SPAN_FIELD_VALUES[key](node) }) }, key))) }));
+}
+/** The record's host resource and request metadata, shown on the span that roots the record. */
+function RecordSections({ node }) {
+    const { record } = node;
+    if (record.spans[0]?.spanId !== node.span.spanId)
+        return null;
+    return (_jsxs(_Fragment, { children: [Object.keys(record.resource).length > 0 ? (_jsx(Section, { title: TRACE_FIELDS.resource.label, children: _jsx(TraceAttributeList, { record: record, attributes: record.resource, metaOf: traceAttributeMeta }) })) : null, record.metadata ? (_jsx(Section, { title: TRACE_FIELDS.metadata.label, children: _jsx(TraceAttributeList, { record: record, attributes: record.metadata, metaOf: () => undefined }) })) : null] }));
+}
+/** One span in full: who acted and how it ended, what went in and came out, its tokens, then every detail it recorded. */
+export function TraceSpanDetail({ node, turnStartMs, isClose = false, onBack, onOpen, }) {
+    const format = useTraceFormat();
+    const { t } = format;
+    const { span, record } = node;
+    const sections = attributeSections(span.attributes);
+    const usage = sections.find((section) => section.key === 'usage');
+    return (_jsxs(VStack, { gap: 4, children: [_jsx(SpanHeader, { node: node, turnStartMs: turnStartMs, onBack: onBack, isClose: isClose }), _jsx(SpanIO, { node: node }), usage ? (_jsx(Panel, { title: TRACE_ATTRIBUTE_GROUPS.usage.label, doc: TRACE_ATTRIBUTE_GROUPS.usage.doc, children: _jsx(TraceAttributeList, { record: record, attributes: usage.attributes, metaOf: traceAttributeMeta }) })) : null, node.children.length > 0 ? (_jsx(Panel, { title: TRACE_FIELDS.children.label, doc: TRACE_FIELDS.children.doc, children: _jsx(VStack, { gap: 0, children: node.children.map((child) => (_jsx(Item, { startContent: _jsx(ActorMark, { actor: traceActor(child) }), label: child.meta.subject ?? child.meta.label, description: child.meta.label, endContent: _jsx(Text, { type: "supporting", hasTabularNumbers: true, children: format.duration(child.durationMs) }), density: "compact", onClick: () => onOpen(child) }, child.id))) }) })) : null, _jsx(Collapsible, { defaultIsOpen: false, trigger: _jsx(Text, { weight: "medium", children: t('@theorem.panel.trace.details') }), children: _jsxs(VStack, { gap: 3, children: [_jsx(SpanFields, { node: node }), sections.filter((section) => section !== usage).map((section) => (_jsx(Section, { title: section.key === 'other' ? t('@theorem.panel.trace.other') : TRACE_ATTRIBUTE_GROUPS[section.key].label, children: _jsx(TraceAttributeList, { record: record, attributes: section.attributes, metaOf: traceAttributeMeta }) }, section.key))), span.events.length > 0 ? (_jsx(Section, { title: TRACE_FIELDS.events.label, children: _jsx(EventList, { node: node }) })) : null, span.links.length > 0 ? (_jsx(Section, { title: TRACE_FIELDS.links.label, children: _jsx(LinkList, { node: node }) })) : null, _jsx(RecordSections, { node: node })] }) })] }));
+}

package/ui/TraceStory.d.ts

@@ -0,0 +1,20 @@
+import { IconUser } from '@tabler/icons-react';
+import { type TraceActor, type TraceStep } from '../client/trace-story.ts';
+import type { TraceNode } from '../client/trace-view.ts';
+/** An actor's icon, in the text's own colour. */
+export declare function ActorMark({ actor, icon }: {
+    actor: TraceActor;
+    icon?: typeof IconUser;
+}): import("react").JSX.Element;
+/**
+ * The turn, told in order: what the user asked, each model call with the tool
+ * calls it asked for set in under it, what changed course, and how it ended.
+ * A line opens its span.
+ */
+export declare function TraceStory({ steps, selectedId, matches, onSelect, }: {
+    steps: readonly TraceStep[];
+    selectedId: string | undefined;
+    /** Spans the search matched; the others dim. Absent when nothing is searched. */
+    matches: ReadonlySet<string> | undefined;
+    onSelect: (node: TraceNode) => void;
+}): import("react").JSX.Element;

package/ui/TraceStory.js

@@ -0,0 +1,107 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge } from '@astryxdesign/core/Badge';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Icon } from '@astryxdesign/core/Icon';
+import { Item } from '@astryxdesign/core/Item';
+import { Text } from '@astryxdesign/core/Text';
+import { Tooltip } from '@astryxdesign/core/Tooltip';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconAlertTriangle, IconBolt, IconInputAi, IconMessageCircle, IconServer, IconTool, IconUser, } from '@tabler/icons-react';
+import { toolArguments, traceActor, traceOutcome } from "../client/trace-story.js";
+import { useTraceFormat } from "./TraceValues.js";
+/** Each actor's mark, shared by the story and the turn list. */
+const ACTOR_ICON = {
+    user: IconUser,
+    model: IconInputAi,
+    tool: IconTool,
+    host: IconServer,
+    theorem: IconBolt,
+    error: IconAlertTriangle,
+};
+/** An actor's icon, in the text's own colour. */
+export function ActorMark({ actor, icon }) {
+    return _jsx(Icon, { icon: icon ?? ACTOR_ICON[actor], size: "sm", color: "secondary" });
+}
+/** "city: Lisbon · to: USD": a tool call's plain arguments on one line. */
+function argumentsLine(node, separator) {
+    return toolArguments(node)
+        .map(([key, value]) => (key ? `${key}: ${value}` : value))
+        .join(separator);
+}
+/** Duration, then cost when the span reported one. */
+function StepMeasure({ node }) {
+    const format = useTraceFormat();
+    const cost = node.span.attributes['theorem.usage.cost_usd'];
+    return (_jsxs(VStack, { gap: 0, hAlign: "end", children: [_jsx(Text, { type: "supporting", hasTabularNumbers: true, children: format.duration(node.durationMs) }), typeof cost === 'number' ? (_jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: format.usd(cost) })) : null] }));
+}
+function Offset({ ms }) {
+    const format = useTraceFormat();
+    return (_jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: format.t('@theorem.panel.trace.offset', { duration: format.duration(ms) }) }));
+}
+/** A span step's line: the tools a call asked for or that it wrote, a tool's arguments, else the span's own label. */
+function spanLine(step, format) {
+    const { node } = step;
+    if (node.meta.type === 'tool')
+        return argumentsLine(node, format.t('@theorem.panel.trace.separator'));
+    if (node.meta.type !== 'call' && node.meta.type !== 'response')
+        return node.meta.label;
+    return step.requested > 0
+        ? format.t('@theorem.panel.trace.story.requested', { count: step.requested })
+        : format.t('@theorem.panel.trace.story.wrote');
+}
+/** What a span step says under its name: how it ended when that is news, then its line. */
+function spanDescription(step, format) {
+    const outcome = traceOutcome(step.node);
+    const line = spanLine(step, format);
+    if (!outcome)
+        return line;
+    return (_jsxs(HStack, { gap: 1, align: "center", wrap: "wrap", children: [_jsx(Tooltip, { content: outcome.doc ?? outcome.label, children: _jsx(Badge, { variant: outcome.tone, label: outcome.label }) }), line ? _jsx(Text, { type: "supporting", children: line }) : null] }));
+}
+function Quote({ text }) {
+    return (_jsx(Text, { color: "secondary", maxLines: 3, hasTruncateTooltip: false, children: text }));
+}
+function AskItem({ step, isSelected, select }) {
+    const { t } = useTraceFormat();
+    return (_jsx(Item, { startContent: _jsx(ActorMark, { actor: "user" }), label: _jsx(Text, { weight: "medium", children: t('@theorem.panel.trace.story.asked') }), description: _jsx(Quote, { text: step.text }), endContent: _jsx(Offset, { ms: 0 }), align: "start", density: "compact", onClick: select, isSelected: isSelected }));
+}
+function SpanItem({ step, isSelected, select }) {
+    const format = useTraceFormat();
+    return (_jsx(Item, { startContent: _jsx(ActorMark, { actor: traceActor(step.node) }), label: _jsx(Text, { weight: "medium", maxLines: 1, children: step.node.meta.subject ?? step.node.meta.label }), description: spanDescription(step, format), endContent: _jsx(StepMeasure, { node: step.node }), align: "start", density: "compact", onClick: select, isSelected: isSelected }));
+}
+function EventItem({ step, isSelected, select }) {
+    const { t } = useTraceFormat();
+    return (_jsx(Item, { startContent: _jsx(ActorMark, { actor: "theorem" }), label: _jsx(Tooltip, { content: step.doc, children: _jsx(Text, { weight: "medium", children: step.label }) }), description: step.detail.join(t('@theorem.panel.trace.separator')), endContent: _jsx(Offset, { ms: step.offsetMs }), align: "start", density: "compact", onClick: select, isSelected: isSelected }));
+}
+function AnswerItem({ step, isSelected, select }) {
+    const { t } = useTraceFormat();
+    const failed = step.node.span.status.code === 'ERROR';
+    const answer = step.text ? _jsx(Quote, { text: step.text }) : undefined;
+    return (_jsx(Item, { startContent: _jsx(ActorMark, { actor: failed ? 'error' : 'model', icon: failed ? undefined : IconMessageCircle }), label: _jsx(Text, { weight: "medium", children: t(failed ? '@theorem.panel.trace.story.failed' : '@theorem.panel.trace.story.answered') }), description: failed ? traceOutcome(step.node)?.label : answer, endContent: _jsx(Offset, { ms: step.offsetMs }), align: "start", density: "compact", onClick: select, isSelected: isSelected }));
+}
+function StepBody({ step, isSelected, select }) {
+    switch (step.kind) {
+        case 'ask':
+            return _jsx(AskItem, { step: step, isSelected: isSelected, select: select });
+        case 'span':
+            return _jsx(SpanItem, { step: step, isSelected: isSelected, select: select });
+        case 'event':
+            return _jsx(EventItem, { step: step, isSelected: isSelected, select: select });
+        case 'answer':
+            return _jsx(AnswerItem, { step: step, isSelected: isSelected, select: select });
+    }
+}
+function StepItem({ step, isSelected, isDimmed, onSelect, }) {
+    return (_jsx("div", { style: {
+            paddingInlineStart: step.kind === 'span' && step.nested ? 20 : 0,
+            opacity: isDimmed ? 0.35 : 1,
+            transition: 'opacity 120ms ease',
+        }, children: _jsx(StepBody, { step: step, isSelected: isSelected, select: () => onSelect(step.node) }) }));
+}
+/**
+ * The turn, told in order: what the user asked, each model call with the tool
+ * calls it asked for set in under it, what changed course, and how it ended.
+ * A line opens its span.
+ */
+export function TraceStory({ steps, selectedId, matches, onSelect, }) {
+    return (_jsx(VStack, { gap: 0, children: steps.map((step) => (_jsx(StepItem, { step: step, isSelected: step.kind === 'span' ? step.node.id === selectedId : false, isDimmed: matches !== undefined && !matches.has(step.node.id), onSelect: onSelect }, step.id))) }));
+}

package/ui/TraceValues.d.ts

@@ -0,0 +1,36 @@
+import { type TraceAttributeGroup, type TraceAttributeMeta, type TraceRecord } from '@theoremjs/agents';
+import { type TraceSum, type TraceTokenSum } from '../client/trace-view.ts';
+import { type LabelText } from './labels.ts';
+/** Width of every label column in the panel's lists, so they line up. */
+export declare const TRACE_LABEL_PX = 120;
+export type AttributeSection = {
+    key: TraceAttributeGroup | 'other';
+    attributes: Record<string, unknown>;
+};
+/** A span's attributes by catalog group, in the catalog's order; keys it does not name last. */
+export declare function attributeSections(attributes: Readonly<Record<string, unknown>>): AttributeSection[];
+/** Formats for trace values, in the viewer's locale. */
+export interface TraceFormat {
+    t: LabelText;
+    number(value: number): string;
+    usd(value: number): string;
+    duration(ms: number): string;
+    list(items: readonly string[]): string;
+    /** A total, worded as partial or estimated when it is. */
+    sum(sum: TraceSum | TraceTokenSum, format: (value: number) => string): string;
+}
+export declare function useTraceFormat(): TraceFormat;
+/** One attribute value, read by its catalog entry; a key the catalog does not name reads by its shape. */
+export declare function TraceValue({ record, meta, value, }: {
+    record: TraceRecord;
+    meta: TraceAttributeMeta | undefined;
+    value: unknown;
+}): import("react").JSX.Element;
+/** Attributes as label and value rows, worded by `metaOf`; a key it does not name shows as recorded. */
+export declare function TraceAttributeList({ record, attributes, metaOf, maxNumOfItems, title, }: {
+    record: TraceRecord;
+    attributes: Readonly<Record<string, unknown>>;
+    metaOf: (key: string) => TraceAttributeMeta | undefined;
+    maxNumOfItems?: number;
+    title?: string;
+}): import("react").JSX.Element | null;

package/ui/TraceValues.js

@@ -0,0 +1,113 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '@astryxdesign/core/Button';
+import { CodeBlock } from '@astryxdesign/core/CodeBlock';
+import { useLocale } from '@astryxdesign/core/i18n';
+import { MetadataList, MetadataListItem } from '@astryxdesign/core/MetadataList';
+import { Text } from '@astryxdesign/core/Text';
+import { Timestamp } from '@astryxdesign/core/Timestamp';
+import { Tooltip } from '@astryxdesign/core/Tooltip';
+import { VStack } from '@astryxdesign/core/VStack';
+import { useMemo, useState } from 'react';
+import { inlineContent, TRACE_ATTRIBUTE_GROUPS, traceAttributeMeta, } from '@theoremjs/agents';
+import { nanosToMs, traceValueShape } from "../client/trace-view.js";
+import { workDuration } from "./labels.js";
+import { useLabels } from "./labels-provider.js";
+/** Width of every label column in the panel's lists, so they line up. */
+export const TRACE_LABEL_PX = 120;
+/** A span's attributes by catalog group, in the catalog's order; keys it does not name last. */
+export function attributeSections(attributes) {
+    const byGroup = new Map();
+    for (const [key, value] of Object.entries(attributes)) {
+        const group = traceAttributeMeta(key)?.group ?? 'other';
+        byGroup.set(group, { ...byGroup.get(group), [key]: value });
+    }
+    const order = [...Object.keys(TRACE_ATTRIBUTE_GROUPS), 'other'];
+    return order.flatMap((key) => {
+        const grouped = byGroup.get(key);
+        return grouped ? [{ key, attributes: grouped }] : [];
+    });
+}
+export function useTraceFormat() {
+    const t = useLabels();
+    const locale = useLocale();
+    return useMemo(() => {
+        const number = new Intl.NumberFormat(locale);
+        const usd = new Intl.NumberFormat(locale, { style: 'currency', currency: 'USD', maximumFractionDigits: 6 });
+        const list = new Intl.ListFormat(locale, { type: 'conjunction' });
+        return {
+            t,
+            number: (value) => number.format(value),
+            usd: (value) => usd.format(value),
+            duration: (ms) => workDuration(t, ms),
+            list: (items) => list.format(items),
+            sum(total, format) {
+                const value = 'estimated' in total && total.estimated ? t('@theorem.panel.trace.about', { value: format(total.value) }) : format(total.value);
+                return total.complete ? value : t('@theorem.panel.trace.at_least', { value });
+            },
+        };
+    }, [t, locale]);
+}
+/** A value as it was stored, with its references rebuilt, shown on click. */
+function StoredText({ record, value }) {
+    const { t } = useTraceFormat();
+    const [isShown, setIsShown] = useState(false);
+    const inlined = inlineContent(record, value);
+    return (_jsxs(VStack, { gap: 1, children: [_jsx(Button, { label: t(isShown ? '@theorem.panel.trace.hide_text' : '@theorem.panel.trace.show_text'), variant: "ghost", size: "sm", "aria-expanded": isShown, onClick: () => setIsShown((shown) => !shown) }), isShown ? (_jsx(CodeBlock, { code: typeof inlined === 'string' ? inlined : JSON.stringify(inlined, null, 2), language: typeof inlined === 'string' ? 'text' : 'json', isWrapped: true, size: "sm", hasCopyButton: true })) : null] }));
+}
+/** An option's label, with its meaning on hover. */
+function OptionValue({ option }) {
+    return (_jsx(Tooltip, { content: option.doc, children: _jsx(Text, { children: option.label }) }));
+}
+function formatNumber(format, meta, value) {
+    switch (meta?.format) {
+        case 'usd':
+            return format.usd(value);
+        case 'milliseconds':
+            return format.duration(value);
+        case 'seconds':
+            return format.duration(value * 1_000);
+        default:
+            return format.number(value);
+    }
+}
+function StringValue({ meta, value }) {
+    const option = meta?.options?.[value];
+    if (option)
+        return _jsx(OptionValue, { option: option });
+    if (meta?.format === 'time')
+        return _jsx(Timestamp, { value: nanosToMs(value), format: "system_date_time", size: "base", color: "primary" });
+    return _jsx(Text, { wordBreak: "break-word", children: value });
+}
+function ScalarValue({ meta, value }) {
+    const format = useTraceFormat();
+    if (typeof value === 'boolean')
+        return _jsx(Text, { children: format.t(value ? '@theorem.panel.trace.yes' : '@theorem.panel.trace.no') });
+    return _jsx(Text, { hasTabularNumbers: true, children: formatNumber(format, meta, value) });
+}
+function ListValue({ meta, value }) {
+    const format = useTraceFormat();
+    return _jsx(Text, { children: format.list(value.map((item) => meta?.options?.[item]?.label ?? item)) });
+}
+/** One attribute value, read by its catalog entry; a key the catalog does not name reads by its shape. */
+export function TraceValue({ record, meta, value, }) {
+    const shape = traceValueShape(meta, value);
+    switch (shape.kind) {
+        case 'text':
+            return _jsx(StringValue, { meta: meta, value: shape.value });
+        case 'scalar':
+            return _jsx(ScalarValue, { meta: meta, value: shape.value });
+        case 'list':
+            return _jsx(ListValue, { meta: meta, value: shape.value });
+        case 'fields':
+            return (_jsx(VStack, { gap: 2, children: shape.items.map((item, index) => (_jsx(TraceAttributeList, { record: record, attributes: item, metaOf: (key) => shape.fields[key] }, index))) }));
+        case 'stored':
+            return _jsx(StoredText, { record: record, value: value });
+    }
+}
+/** Attributes as label and value rows, worded by `metaOf`; a key it does not name shows as recorded. */
+export function TraceAttributeList({ record, attributes, metaOf, maxNumOfItems, title, }) {
+    const entries = Object.entries(attributes);
+    if (entries.length === 0)
+        return null;
+    return (_jsx(MetadataList, { columns: "single", label: { position: 'start', width: TRACE_LABEL_PX }, maxNumOfItems: maxNumOfItems, title: title, children: entries.map(([key, value]) => (_jsx(MetadataListItem, { label: metaOf(key)?.label ?? key, children: _jsx(TraceValue, { record: record, meta: metaOf(key), value: value }) }, key))) }));
+}

package/ui/TraceWaterfall.d.ts

@@ -0,0 +1,13 @@
+import type { TraceNode } from '../client/trace-view.ts';
+/**
+ * Every span of the turn on one time axis, nested by depth and coloured by
+ * who acted. Above it, how busy the model and tools were over the turn; drag
+ * across that strip to zoom the rows into the window, as in a performance
+ * profile. A bar opens its span.
+ */
+export declare function TraceWaterfall({ root, selectedId, matches, onSelect, }: {
+    root: TraceNode;
+    selectedId: string | undefined;
+    matches: ReadonlySet<string> | undefined;
+    onSelect: (node: TraceNode) => void;
+}): import("react").JSX.Element;