@theoremjs/react 0.3.4-next.616.g595707c → 0.3.4-next.620.g9fe1aff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/react",
-  "version": "0.3.4-next.616.g595707c",
+  "version": "0.3.4-next.620.g9fe1aff",
   "description": "React bindings for Theorem: headless hooks + transport, an Astryx chat UI, and a Web-standard server handler.",
   "license": "MIT",
   "type": "module",
@@ -60,8 +60,8 @@
     "@stylexjs/stylex": "0.19.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@theoremjs/agents": "^0.3.4-next.616.g595707c",
-    "@theoremjs/web": "^0.3.4-next.616.g595707c"
+    "@theoremjs/agents": "^0.3.4-next.620.g9fe1aff",
+    "@theoremjs/web": "^0.3.4-next.620.g9fe1aff"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {

package/ui/TraceInspector.js

@@ -3,11 +3,12 @@ import { Badge } from '@astryxdesign/core/Badge';
 import { EmptyState } from '@astryxdesign/core/EmptyState';
 import { HStack } from '@astryxdesign/core/HStack';
 import { Icon } from '@astryxdesign/core/Icon';
+import { IconButton } from '@astryxdesign/core/IconButton';
 import { Item } from '@astryxdesign/core/Item';
 import { PowerSearch, } from '@astryxdesign/core/PowerSearch';
 import { Text } from '@astryxdesign/core/Text';
 import { VStack } from '@astryxdesign/core/VStack';
-import { IconActivity } from '@tabler/icons-react';
+import { IconActivity, IconDownload } from '@tabler/icons-react';
 import { useMemo, useState } from 'react';
 import { isCallTrace, traceGuardrails, traceLatency, traceStory, traceTurnRow, traceTurns, } from "../client/trace-story.js";
 import { TRACE_SEARCH_OPERATORS, TRACE_TEXT_FIELD, traceMatchIds, traceSearchFields, traceSpans, traceTotals, traceTree, } from "../client/trace-view.js";
@@ -112,7 +113,7 @@ function TurnRow({ turn, index, isCall, onOpen, }) {
                 t(isCall ? '@theorem.panel.trace.charts.hostCall' : '@theorem.panel.trace.charts.turn', { index: index + 1 }) }), description: turnRowNote(row), endContent: _jsx(TurnRowTotals, { turn: turn }), align: "start", density: "compact", onClick: onOpen }));
 }
 /** Every turn at once: the conversation's totals, each turn's time and tokens, and the turns themselves. */
-function ConversationOverview({ turns, onPick, }) {
+function ConversationOverview({ turns, onPick, end, }) {
     const { t } = useTraceFormat();
     const nodes = useMemo(() => turns.map((turn) => turn.node), [turns]);
     // why: Time between turns is the person's, not the agent's: the duration sums the turns.
@@ -122,12 +123,12 @@ function ConversationOverview({ turns, onPick, }) {
     }), [nodes, turns]);
     const tools = useMemo(() => traceSpans(nodes).filter((node) => node.meta.type === 'tool').length, [nodes]);
     const isCalls = isCallTrace(turns);
-    return (_jsxs(VStack, { gap: 5, padding: 4, children: [_jsx(Text, { weight: "semibold", children: t(isCalls ? '@theorem.panel.trace.calls.count' : '@theorem.panel.trace.conversation', {
-                    count: turns.length,
-                }) }), _jsxs(VStack, { gap: 3, children: [_jsx(TurnStats, { totals: totals, tools: tools }), _jsx(ConversationCharts, { turns: turns, onPick: onPick })] }), _jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t(isCalls ? '@theorem.panel.trace.calls' : '@theorem.panel.trace.turns') }), _jsx(Stream, { children: _jsx(VStack, { gap: 0, children: turns.map((turn, index) => (_jsx(TurnRow, { turn: turn, index: index, isCall: isCalls, onOpen: () => onPick(index) }, turn.node.id))) }) })] })] }));
+    return (_jsxs(VStack, { gap: 5, padding: 4, children: [_jsxs(HStack, { gap: 1, align: "center", justify: "between", children: [_jsx(Text, { weight: "semibold", children: t(isCalls ? '@theorem.panel.trace.calls.count' : '@theorem.panel.trace.conversation', {
+                            count: turns.length,
+                        }) }), end] }), _jsxs(VStack, { gap: 3, children: [_jsx(TurnStats, { totals: totals, tools: tools }), _jsx(ConversationCharts, { turns: turns, onPick: onPick })] }), _jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t(isCalls ? '@theorem.panel.trace.calls' : '@theorem.panel.trace.turns') }), _jsx(Stream, { children: _jsx(VStack, { gap: 0, children: turns.map((turn, index) => (_jsx(TurnRow, { turn: turn, index: index, isCall: isCalls, onOpen: () => onPick(index) }, turn.node.id))) }) })] })] }));
 }
 /** One turn at a glance, then its story, then its timeline under the search. */
-function TurnOverview({ turns, index, onPick, onBack, selectedId, onSelect, }) {
+function TurnOverview({ turns, index, onPick, onBack, selectedId, onSelect, end, }) {
     const { t } = useTraceFormat();
     const [filters, setFilters] = useState([]);
     const turn = turns[index];
@@ -140,7 +141,7 @@ function TurnOverview({ turns, index, onPick, onBack, selectedId, onSelect, }) {
     if (!turn || !root)
         return null;
     const tools = traceSpans([root]).filter((node) => node.meta.type === 'tool').length;
-    return (_jsxs(VStack, { gap: 5, padding: 4, children: [_jsx(TurnPicker, { turns: turns, index: index, onChange: onPick, onBack: onBack }), _jsxs(VStack, { gap: 3, children: [_jsx(TurnStats, { totals: turn.totals, tools: tools, latency: latency }), _jsx(TraceCharts, { root: root, split: turn.split, onSelect: onSelect })] }), _jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.timeline') }), _jsx(PowerSearch, { config: config, filters: filters, onChange: setFilters, label: t('@theorem.panel.trace.search'), isLabelHidden: true, placeholder: t('@theorem.panel.trace.search.placeholder'), resultCount: matches?.size, size: "sm" }), _jsx(TraceWaterfall, { root: root, selectedId: selectedId, matches: matches, onSelect: onSelect }, root.id)] }), story.length > 0 ? (_jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.story') }), _jsx(TraceStory, { steps: story, selectedId: selectedId, matches: matches, onSelect: onSelect })] })) : null, guardrails.length > 0 ? (_jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.guardrails') }), _jsx(TraceGuardrails, { checks: guardrails, onSelect: onSelect })] })) : null] }));
+    return (_jsxs(VStack, { gap: 5, padding: 4, children: [_jsx(TurnPicker, { turns: turns, index: index, onChange: onPick, onBack: onBack, end: end }), _jsxs(VStack, { gap: 3, children: [_jsx(TurnStats, { totals: turn.totals, tools: tools, latency: latency }), _jsx(TraceCharts, { root: root, split: turn.split, onSelect: onSelect })] }), _jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.timeline') }), _jsx(PowerSearch, { config: config, filters: filters, onChange: setFilters, label: t('@theorem.panel.trace.search'), isLabelHidden: true, placeholder: t('@theorem.panel.trace.search.placeholder'), resultCount: matches?.size, size: "sm" }), _jsx(TraceWaterfall, { root: root, selectedId: selectedId, matches: matches, onSelect: onSelect }, root.id)] }), story.length > 0 ? (_jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.story') }), _jsx(TraceStory, { steps: story, selectedId: selectedId, matches: matches, onSelect: onSelect })] })) : null, guardrails.length > 0 ? (_jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.guardrails') }), _jsx(TraceGuardrails, { checks: guardrails, onSelect: onSelect })] })) : null] }));
 }
 function EmptyTrace() {
     const { t } = useTraceFormat();
@@ -171,10 +172,36 @@ function SpanPane({ open, turnStartMs, isWide, onBack, onOpen, }) {
     return (_jsx(VStack, { padding: 4, children: _jsx(TraceSpanDetail, { node: open, turnStartMs: turnStartMs, isClose: isWide, onBack: onBack, onOpen: onOpen }) }));
 }
 /** The whole conversation, or the open turn with a way back when there are others. */
-function Overview({ turns, index, pick, selectedId, select, }) {
+function Overview({ turns, index, pick, selectedId, select, end, }) {
     if (index === null)
-        return _jsx(ConversationOverview, { turns: turns, onPick: pick });
-    return (_jsx(TurnOverview, { turns: turns, index: index, onPick: pick, onBack: turns.length > 1 ? () => pick(null) : undefined, selectedId: selectedId, onSelect: select }));
+        return _jsx(ConversationOverview, { turns: turns, onPick: pick, end: end });
+    return (_jsx(TurnOverview, { turns: turns, index: index, onPick: pick, onBack: turns.length > 1 ? () => pick(null) : undefined, selectedId: selectedId, onSelect: select, end: end }));
+}
+/** The agent the records ran, which names their file. */
+function tracedAgent(records) {
+    for (const record of records) {
+        for (const span of record.spans) {
+            const name = span.attributes['gen_ai.agent.name'];
+            if (typeof name === 'string' && name)
+                return name;
+        }
+    }
+    return 'trace';
+}
+/** Saves the records on screen as `<agent>-<time>.trace.json`, the file the studio imports. */
+function TraceDownload({ records }) {
+    const { t } = useTraceFormat();
+    const label = t('@theorem.panel.trace.download');
+    return (_jsx(IconButton, { label: label, variant: "ghost", size: "sm", tooltip: label, icon: _jsx(Icon, { icon: IconDownload }), onClick: () => {
+            const stamp = new Date().toISOString().replaceAll(':', '-').slice(0, 19);
+            const file = new Blob([JSON.stringify(records, null, 2)], { type: 'application/json' });
+            const url = URL.createObjectURL(file);
+            const link = document.createElement('a');
+            link.href = url;
+            link.download = `${tracedAgent(records)}-${stamp}.trace.json`;
+            link.click();
+            URL.revokeObjectURL(url);
+        } }));
 }
 /**
  * The panel's content. Narrow, the turn fills it and a span opens in its
@@ -187,7 +214,7 @@ function TraceInspectorBody({ records, isWide, }) {
     const { index, root, open, select, close, pick } = useOpenSpan(turns);
     if (turns.length === 0)
         return _jsx(EmptyTrace, {});
-    const overview = (_jsx(Overview, { turns: turns, index: index, pick: pick, selectedId: open?.id, select: select }));
+    const overview = (_jsx(Overview, { turns: turns, index: index, pick: pick, selectedId: open?.id, select: select, end: _jsx(TraceDownload, { records: records }) }));
     return (_jsx(PaneLayout, { isWide: isWide, label: t('@theorem.panel.trace.name'), detailLabel: open?.meta.label ?? '', lead: _jsx(TracePatterns, {}), overview: overview, detail: open && (_jsx(SpanPane, { open: open, turnStartMs: root?.startMs ?? 0, isWide: isWide, onBack: close, onOpen: select })) }));
 }
 /** The inspector over the records a feed has delivered; the panel loads this module when it first opens. */

package/ui/TraceInspectorPanel.js

@@ -1,9 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Icon } from '@astryxdesign/core/Icon';
-import { IconButton } from '@astryxdesign/core/IconButton';
-import { IconActivity, IconDownload } from '@tabler/icons-react';
+import { IconActivity } from '@tabler/icons-react';
 import { cloneElement, createContext, isValidElement, lazy, Suspense, use, useCallback, useId, useRef, useState, } from 'react';
-import { useTraceRecords } from "../hooks/use-trace-records.js";
 import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
 import { InPlace, isSidePanelWide, RaisedPane, SidePanel, SidePanelHeader, SidePanelToggle, useSidePanel, useWidth, } from "./SidePanel.js";
 // why: The inspector and its charts are fetched when the trace first opens, not with the chat.
@@ -45,9 +43,9 @@ export function useTraceInspector(iface, traces, open) {
     const view = isOpen ? openTrace(placement === 'panel', id, traces, toggle) : null;
     return { toggle, view, labels, offered: true };
 }
-/** The open trace: filling the host's docked panel, or as its own panel; Download, then the toggle, on top. */
+/** The open trace: filling the host's docked panel, or as its own panel; the toggle on top. */
 function openTrace(docked, id, traces, toggle) {
-    const header = (_jsxs(SidePanelHeader, { floating: true, children: [_jsx(TraceDownload, { traces: traces }), toggle] }));
+    const header = toggle ? _jsx(SidePanelHeader, { floating: true, children: toggle }) : null;
     if (docked)
         return _jsx(TraceFill, { id: id, header: header, traces: traces });
     return _jsx(TraceView, { id: id, header: header, traces: traces });
@@ -57,35 +55,6 @@ function TraceFill({ id, header, traces, }) {
     const { ref, width } = useWidth();
     return (_jsxs("div", { id: id, ref: ref, style: { height: '100%', position: 'relative' }, children: [header, _jsx(Suspense, { fallback: null, children: _jsx(TraceFeedBody, { traces: traces, isWide: isSidePanelWide(width) }) })] }));
 }
-/** The agent the records ran, which names their file. */
-function tracedAgent(records) {
-    for (const record of records) {
-        for (const span of record.spans) {
-            const name = span.attributes['gen_ai.agent.name'];
-            if (typeof name === 'string' && name)
-                return name;
-        }
-    }
-    return 'trace';
-}
-/** Saves the records on screen as `<agent>-<time>.trace.json`, the file the studio imports. */
-function TraceDownload({ traces }) {
-    const t = useLabels();
-    const records = useTraceRecords(traces);
-    if (records.length === 0)
-        return null;
-    const label = t('@theorem.panel.trace.download');
-    return (_jsx(IconButton, { label: label, variant: "ghost", tooltip: label, icon: _jsx(Icon, { icon: IconDownload, size: "sm" }), onClick: () => {
-            const stamp = new Date().toISOString().replaceAll(':', '-').slice(0, 19);
-            const file = new Blob([JSON.stringify(records, null, 2)], { type: 'application/json' });
-            const url = URL.createObjectURL(file);
-            const link = document.createElement('a');
-            link.href = url;
-            link.download = `${tracedAgent(records)}-${stamp}.trace.json`;
-            link.click();
-            URL.revokeObjectURL(url);
-        } }));
-}
 /** The surface, with the trace docked at its inline end. A host-driven trace stays in place. */
 function TraceDock({ inspector, children }) {
     const layoutRef = useRef(null);

package/ui/TraceOverview.d.ts

@@ -15,13 +15,14 @@ export declare function ChartFrame({ children }: {
 export declare function ChartTip({ children }: {
     children: ReactNode;
 }): import("react").JSX.Element;
-/** Which turn is open: its name, and the previous and next turn. */
-export declare function TurnPicker({ turns, index, onChange, onBack, }: {
+/** Which turn is open: its name, the previous and next turn, then `end`. */
+export declare function TurnPicker({ turns, index, onChange, onBack, end, }: {
     turns: readonly TraceTurn[];
     index: number;
     onChange: (index: number) => void;
     /** Leaves the turn for the whole conversation; absent when there is only the one turn. */
     onBack?: (() => void) | undefined;
+    end?: ReactNode;
 }): import("react").JSX.Element | null;
 /** A turn's guardrail figures alone, as {@link TurnStats} lays them out. */
 export declare function GuardrailStats({ latency }: {

package/ui/TraceOverview.js

@@ -42,8 +42,8 @@ export function ChartTip({ children }) {
             pointerEvents: 'none',
         }, children: children }));
 }
-/** Which turn is open: its name, and the previous and next turn. */
-export function TurnPicker({ turns, index, onChange, onBack, }) {
+/** Which turn is open: its name, the previous and next turn, then `end`. */
+export function TurnPicker({ turns, index, onChange, onBack, end, }) {
     const { t } = useTraceFormat();
     const turn = turns[index];
     if (!turn)
@@ -53,7 +53,7 @@ export function TurnPicker({ turns, index, onChange, onBack, }) {
                                     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) })] })] })] }));
+                                }) }), 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) }), end] })] })] }));
 }
 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]

package/ui/TraceSpanDetail.js

@@ -137,13 +137,49 @@ function ProsePanel({ attribute, text }) {
         return null;
     return (_jsx(PanePanel, { ...label(attribute), children: _jsx(Prose, { text: text }) }));
 }
+/** Content folded under a title, with its count when it is a list. */
+function Folded({ title, count, children, }) {
+    return (_jsx(Collapsible, { defaultIsOpen: false, trigger: _jsx(Text, { weight: "medium", children: count === undefined ? title : `${title} · ${String(count)}` }), children: _jsx(Card, { padding: 3, variant: "muted", style: { background: 'var(--color-background-surface)' }, children: children }) }));
+}
+/** The system prompt a model call was sent, part by part. */
+function SystemInstructions({ node }) {
+    const parts = inlineContent(node.record, node.span.attributes['gen_ai.system_instructions']);
+    const texts = (Array.isArray(parts) ? parts.filter(isObject) : []).flatMap((part) => typeof part.content === 'string' && part.content ? [part.content] : []);
+    if (texts.length === 0)
+        return null;
+    return (_jsx(Folded, { title: label('gen_ai.system_instructions').title, children: _jsx(VStack, { gap: 3, children: keyedByContent(texts, (text) => text).map(({ item: text, key }) => (_jsx(Prose, { text: text }, key))) }) }));
+}
+/** The tools a model call was offered: each one's name, what it does, and what it takes. */
+function ToolDefinitions({ node }) {
+    const value = storedValue(node, 'gen_ai.tool.definitions');
+    const tools = Array.isArray(value) ? value.filter(isObject) : [];
+    if (tools.length === 0)
+        return null;
+    return (_jsx(Folded, { title: label('gen_ai.tool.definitions').title, count: tools.length, children: _jsx(VStack, { gap: 3, children: keyedByContent(tools, (tool) => String(tool.name)).map(({ item: tool, key }) => (_jsxs(VStack, { gap: 1, children: [_jsx(Text, { weight: "medium", children: String(tool.name ?? '') }), typeof tool.description === 'string' ? (_jsx(Text, { color: "secondary", children: tool.description })) : null, tool.parameters === undefined ? null : _jsx(ShapedData, { value: tool.parameters })] }, key))) }) }));
+}
+/** What a model call was given besides its messages: the system prompt and the tools. */
+function CallContext({ node }) {
+    return (_jsxs(_Fragment, { children: [_jsx(SystemInstructions, { node: node }), _jsx(ToolDefinitions, { node: node })] }));
+}
+/** A turn's first model call: the one whose system prompt and tools the turn opened with. */
+function firstCall(node) {
+    for (const child of node.children) {
+        if ('gen_ai.system_instructions' in child.span.attributes)
+            return child;
+        const found = firstCall(child);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
 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') })] }));
+    const call = firstCall(node);
+    return (_jsxs(_Fragment, { children: [call ? _jsx(CallContext, { node: call }) : null, _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(PanePanel, { ...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] }));
+    return (_jsxs(_Fragment, { children: [output.length > 0 ? (_jsx(PanePanel, { ...label('gen_ai.output.messages'), children: _jsx(MessageList, { messages: output }) })) : null, _jsx(CallContext, { node: node }), input.length > 0 ? (_jsx(Folded, { title: label('gen_ai.input.messages').title, count: input.length, children: _jsx(MessageList, { messages: input }) })) : null] }));
 }
 function ToolIO({ node }) {
     const { attributes } = node.span;