@theoremjs/react 0.0.0-stage → 0.3.1

package/ui/TraceCharts.js

@@ -0,0 +1,266 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Grid } from '@astryxdesign/core/Grid';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Text } from '@astryxdesign/core/Text';
+import { VStack } from '@astryxdesign/core/VStack';
+import { useMemo } from 'react';
+import { Bar, BarChart, Cell, ResponsiveContainer, Tooltip, XAxis, YAxis, } from 'recharts';
+import { isCallTrace, traceActor, } from "../client/trace-story.js";
+import { traceSpans } from "../client/trace-view.js";
+import { ChartFrame, ChartTip, FIRST_WIDTH_PX } from "./TraceOverview.js";
+import { useTraceFormat } from "./TraceValues.js";
+import { ACTOR_FILL, ChartCard, TRACE_GAP, TRACE_RADIUS, TraceSwatch, traceFill, } from "./trace-patterns.js";
+/** Height of each column chart's plot, in pixels. */
+const CHART_PX = 120;
+/** Height of a share bar, in pixels. */
+const SHARE_PX = 12;
+/** Height of one row of the slowest-steps chart, in pixels. */
+const SLOW_ROW_PX = 22;
+/** Most steps the slowest-steps chart ranks. */
+const SLOWEST = 5;
+const TICK = { fill: 'var(--color-text-secondary)', fontSize: 11 };
+/** Every bar: rounded, and parted from its neighbours by the card's background. */
+const BAR = {
+    radius: TRACE_RADIUS,
+    stroke: TRACE_GAP,
+    strokeWidth: 2,
+    isAnimationActive: false,
+};
+const MODEL_CALLS = new Set(['call', 'response']);
+const SPLIT_KEYS = ['model', 'tools', 'guardrails', 'hooks', 'other'];
+const SPLIT_FILL = {
+    model: 'clear',
+    tools: 'hatch',
+    guardrails: 'shade1',
+    hooks: 'shade3',
+    other: 'shade2',
+};
+const TOKEN_KEYS = ['fresh', 'cached', 'output'];
+const TOKEN_FILL = {
+    fresh: 'clear',
+    cached: 'hatch',
+    output: 'shade1',
+};
+const compact = new Intl.NumberFormat(undefined, { notation: 'compact', maximumFractionDigits: 1 });
+const percent = new Intl.NumberFormat(undefined, { style: 'percent' });
+function numberAt(node, key) {
+    const value = node.span.attributes[key];
+    return typeof value === 'number' ? value : undefined;
+}
+/** A turn's model calls, in the order they started. */
+function modelCalls(root) {
+    return traceSpans([root])
+        .filter((node) => MODEL_CALLS.has(node.meta.type))
+        .sort((a, b) => a.startMs - b.startMs);
+}
+/** A chart's key: each series' swatch and name, with its total at the end. */
+function Legend({ items, }) {
+    return (_jsx(VStack, { gap: 1, children: items.map((item) => (_jsxs(HStack, { gap: 2, align: "center", justify: "between", children: [_jsxs(HStack, { gap: 2, align: "center", children: [_jsx(TraceSwatch, { fill: item.fill }), _jsx(Text, { type: "supporting", color: "secondary", children: item.label })] }), _jsx(Text, { type: "supporting", hasTabularNumbers: true, children: item.value })] }, item.label))) }));
+}
+/** One bar split into shares, each rounded and parted from the next. */
+function ShareBar({ parts, }) {
+    const total = parts.reduce((sum, part) => sum + part.value, 0);
+    return (_jsx(ChartFrame, { children: _jsx(ResponsiveContainer, { width: "100%", height: SHARE_PX, initialDimension: { width: FIRST_WIDTH_PX, height: SHARE_PX }, children: _jsxs(BarChart, { data: [Object.fromEntries(parts.map((part) => [part.key, part.value]))], layout: "vertical", margin: { top: 0, right: 0, bottom: 0, left: 0 }, barCategoryGap: 0, accessibilityLayer: false, children: [_jsx(XAxis, { type: "number", domain: [0, total], hide: true }), _jsx(YAxis, { type: "category", hide: true }), parts.map((part) => (_jsx(Bar, { dataKey: part.key, stackId: "share", fill: traceFill(part.fill), ...BAR }, part.key)))] }) }) }));
+}
+/** A share as a legend reads it; a sliver too thin to round up still says it is there. */
+function shareText(share) {
+    return share > 0 && share < 0.01 ? `<${percent.format(0.01)}` : percent.format(share);
+}
+function sumOf(split) {
+    return SPLIT_KEYS.reduce((total, key) => total + split[key], 0);
+}
+/** Every place time went, however small: a guardrail's few milliseconds still get their line. */
+function SplitLegend({ split, total }) {
+    const format = useTraceFormat();
+    const { t } = format;
+    return (_jsx(Legend, { items: SPLIT_KEYS.filter((key) => split[key] > 0).map((key) => ({
+            fill: SPLIT_FILL[key],
+            label: t(`@theorem.panel.trace.time.${key}`),
+            value: [format.duration(split[key]), shareText(split[key] / total)].join(t('@theorem.panel.trace.separator')),
+        })) }));
+}
+/** A turn's time by where it went: what share went to the model, the bar, and each share. */
+function TimeCard({ split }) {
+    const format = useTraceFormat();
+    const { t } = format;
+    const total = sumOf(split);
+    if (total <= 0)
+        return null;
+    // why: A share under half a percent is too thin to draw; the legend still lists it.
+    const keys = SPLIT_KEYS.filter((key) => split[key] / total >= 0.005);
+    return (_jsxs(ChartCard, { title: t('@theorem.panel.trace.time'), value: format.duration(total), note: split.model > 0
+            ? t('@theorem.panel.trace.charts.modelShare', {
+                share: percent.format(split.model / total),
+            })
+            : undefined, children: [_jsx(ShareBar, { parts: keys.map((key) => ({ key, fill: SPLIT_FILL[key], value: split[key] })) }), _jsx(SplitLegend, { split: split, total: total })] }));
+}
+/** A bar's tokens: read from cache, read fresh, written, and its cost when known. */
+function tokenSplit(usage) {
+    const cached = usage.cached ?? 0;
+    return {
+        cached,
+        fresh: Math.max(0, (usage.input ?? 0) - cached),
+        output: usage.output ?? 0,
+        ...(usage.cost !== undefined && { cost: usage.cost }),
+    };
+}
+function TokenTip({ active, payload }) {
+    const format = useTraceFormat();
+    const { t } = format;
+    const row = payload?.[0]?.payload;
+    if (!active || !row)
+        return null;
+    return (_jsx(ChartTip, { children: _jsxs(VStack, { gap: 0, children: [_jsx(Text, { weight: "medium", children: row.title }), _jsx(Text, { type: "supporting", hasTabularNumbers: true, children: [
+                        format.duration(row.ms),
+                        ...(row.cost === undefined ? [] : [format.usd(row.cost)]),
+                    ].join(t('@theorem.panel.trace.separator')) }), _jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: t('@theorem.panel.trace.charts.tokens', {
+                        cached: format.number(row.cached),
+                        fresh: format.number(row.fresh),
+                        output: format.number(row.output),
+                    }) })] }) }));
+}
+/** Columns of stacked series, one per row; a column opens its row. */
+function Columns({ rows, keys, fills, tip, }) {
+    return (_jsx(ChartFrame, { children: _jsx(ResponsiveContainer, { width: "100%", height: CHART_PX, initialDimension: { width: FIRST_WIDTH_PX, height: CHART_PX }, children: _jsxs(BarChart, { data: rows, margin: { top: 0, right: 0, bottom: 0, left: 0 }, accessibilityLayer: false, barCategoryGap: "24%", maxBarSize: 24, onClick: (state) => rows[Number(state?.activeIndex)]?.open(), style: { cursor: 'pointer' }, children: [_jsx(XAxis, { dataKey: "index", tick: TICK, tickLine: false, axisLine: false, height: 18 }), _jsx(YAxis, { hide: true }), _jsx(Tooltip, { content: tip, cursor: { fill: 'var(--color-overlay-hover)', radius: TRACE_RADIUS }, isAnimationActive: false }), keys.map((key) => (_jsx(Bar, { dataKey: key, stackId: "stack", fill: traceFill(fills[key] ?? 'clear'), ...BAR }, key)))] }) }) }));
+}
+/** Tokens stacked new, cached, and written per row: the total, the columns, and each series' sum. */
+function TokensCard({ title, rows }) {
+    const format = useTraceFormat();
+    const { t } = format;
+    const sums = { fresh: 0, cached: 0, output: 0 };
+    for (const row of rows)
+        for (const key of TOKEN_KEYS)
+            sums[key] += row[key];
+    const total = sums.fresh + sums.cached + sums.output;
+    if (total === 0)
+        return null;
+    const input = sums.fresh + sums.cached;
+    const labels = { fresh: 'input', cached: 'cached', output: 'output' };
+    return (_jsxs(ChartCard, { title: title, value: format.number(total), ...(sums.cached > 0 && {
+            note: t('@theorem.panel.trace.charts.cachedShare', {
+                share: percent.format(sums.cached / input),
+            }),
+        }), children: [_jsx(Columns, { rows: rows, keys: TOKEN_KEYS.filter((key) => sums[key] > 0), fills: TOKEN_FILL, tip: (props) => _jsx(TokenTip, { ...props }) }), _jsx(Legend, { items: TOKEN_KEYS.filter((key) => sums[key] > 0).map((key) => ({
+                    fill: TOKEN_FILL[key],
+                    label: t(`@theorem.panel.trace.charts.${labels[key]}`),
+                    value: compact.format(sums[key]),
+                })) })] }));
+}
+/** A turn's model calls as token rows. */
+function useCallRows(root, onSelect) {
+    const { t } = useTraceFormat();
+    return useMemo(() => modelCalls(root).map((node, position) => ({
+        index: position + 1,
+        title: t('@theorem.panel.trace.charts.call', { index: position + 1 }),
+        ms: node.durationMs,
+        ...tokenSplit({
+            input: numberAt(node, 'gen_ai.usage.input_tokens'),
+            cached: numberAt(node, 'gen_ai.usage.cache_read.input_tokens'),
+            output: numberAt(node, 'gen_ai.usage.output_tokens'),
+            cost: numberAt(node, 'theorem.usage.cost_usd'),
+        }),
+        open: () => onSelect(node),
+    })), [root, onSelect, t]);
+}
+function SlowTip({ active, payload }) {
+    const format = useTraceFormat();
+    const row = payload?.[0]?.payload;
+    if (!active || !row)
+        return null;
+    return (_jsx(ChartTip, { children: _jsxs(VStack, { gap: 0, children: [_jsx(Text, { weight: "medium", children: row.name }), _jsx(Text, { type: "supporting", hasTabularNumbers: true, children: format.duration(row.ms) })] }) }));
+}
+/** The steps that took longest, longest first, filled by who acted. A bar opens its step. */
+function SlowestCard({ root, onSelect }) {
+    const format = useTraceFormat();
+    const { t } = format;
+    const rows = useMemo(() => {
+        const calls = modelCalls(root);
+        return traceSpans(root.children)
+            .filter((node) => node.meta.type === 'tool' || MODEL_CALLS.has(node.meta.type))
+            .sort((a, b) => b.durationMs - a.durationMs)
+            .slice(0, SLOWEST)
+            .map((node) => ({
+            id: node.id,
+            node,
+            name: node.meta.type === 'tool'
+                ? (node.meta.subject ?? node.meta.label)
+                : t('@theorem.panel.trace.charts.call', { index: calls.indexOf(node) + 1 }),
+            ms: node.durationMs,
+        }));
+    }, [root, t]);
+    const top = rows[0];
+    if (!top)
+        return null;
+    const height = rows.length * SLOW_ROW_PX;
+    return (_jsx(ChartCard, { title: t('@theorem.panel.trace.charts.slowest'), value: format.duration(top.ms), note: top.name, children: _jsx(ChartFrame, { children: _jsx(ResponsiveContainer, { width: "100%", height: height, initialDimension: { width: FIRST_WIDTH_PX, height }, children: _jsxs(BarChart, { data: rows, layout: "vertical", margin: { top: 0, right: 48, bottom: 0, left: 0 }, accessibilityLayer: false, barCategoryGap: 5, onClick: (state) => {
+                        const row = rows[Number(state?.activeIndex)];
+                        if (row)
+                            onSelect(row.node);
+                    }, style: { cursor: 'pointer' }, children: [_jsx(XAxis, { type: "number", hide: true }), _jsx(YAxis, { type: "category", dataKey: "id", width: 104, tick: TICK, tickLine: false, axisLine: false, interval: 0, tickFormatter: (id) => {
+                                const name = rows.find((row) => row.id === id)?.name ?? '';
+                                return name.length > 15 ? `${name.slice(0, 14)}…` : name;
+                            } }), _jsx(Tooltip, { content: (props) => _jsx(SlowTip, { ...props }), cursor: false, isAnimationActive: false }), _jsx(Bar, { dataKey: "ms", ...BAR, label: {
+                                position: 'right',
+                                fill: 'var(--color-text-secondary)',
+                                fontSize: 11,
+                                formatter: (value) => format.duration(Number(value)),
+                            }, children: rows.map((row) => (_jsx(Cell, { fill: traceFill(ACTOR_FILL[traceActor(row.node)]) }, row.id))) })] }) }) }) }));
+}
+/** Where a turn's time, tokens, and slowest steps went. A bar opens its span. */
+export function TraceCharts({ root, split, onSelect, }) {
+    const { t } = useTraceFormat();
+    const callRows = useCallRows(root, onSelect);
+    return (_jsxs(Grid, { columns: { minWidth: 260, repeat: 'fit' }, gap: 3, children: [_jsx(TimeCard, { split: split }), _jsx(TokensCard, { title: t('@theorem.panel.trace.charts.calls'), rows: callRows }), _jsx(SlowestCard, { root: root, onSelect: onSelect })] }));
+}
+function TurnTimeTip({ active, payload }) {
+    const format = useTraceFormat();
+    const { t } = format;
+    const row = payload?.[0]?.payload;
+    if (!active || !row)
+        return null;
+    return (_jsx(ChartTip, { children: _jsxs(VStack, { gap: 0, children: [_jsx(Text, { weight: "medium", children: row.title }), SPLIT_KEYS.filter((key) => row[key] > 0).map((key) => (_jsx(Text, { type: "supporting", hasTabularNumbers: true, children: [t(`@theorem.panel.trace.time.${key}`), format.duration(row[key])].join(t('@theorem.panel.trace.separator')) }, key)))] }) }));
+}
+/** Each turn's time by where it went, stacked: the conversation's total and each share's sum. */
+function TurnTimeCard({ rows, isCalls }) {
+    const format = useTraceFormat();
+    const { t } = format;
+    const sums = { model: 0, tools: 0, guardrails: 0, hooks: 0, other: 0 };
+    for (const row of rows)
+        for (const key of SPLIT_KEYS)
+            sums[key] += row[key];
+    const total = sumOf(sums);
+    if (total <= 0)
+        return null;
+    return (_jsxs(ChartCard, { title: t(isCalls ? '@theorem.panel.trace.charts.callTime' : '@theorem.panel.trace.charts.turnTime'), value: format.duration(total), note: sums.model > 0
+            ? t('@theorem.panel.trace.charts.modelShare', {
+                share: percent.format(sums.model / total),
+            })
+            : undefined, children: [_jsx(Columns, { rows: rows, keys: SPLIT_KEYS, fills: SPLIT_FILL, tip: (props) => _jsx(TurnTimeTip, { ...props }) }), _jsx(SplitLegend, { split: sums, total: total })] }));
+}
+/** The whole conversation: each turn's time and tokens. A column opens its turn. */
+export function ConversationCharts({ turns, onPick, }) {
+    const { t } = useTraceFormat();
+    const isCalls = isCallTrace(turns);
+    const column = isCalls
+        ? '@theorem.panel.trace.charts.hostCall'
+        : '@theorem.panel.trace.charts.turn';
+    const time = useMemo(() => turns.map((turn, position) => ({
+        index: position + 1,
+        title: t(column, { index: position + 1 }),
+        ...turn.split,
+        open: () => onPick(position),
+    })), [turns, onPick, t, column]);
+    const tokens = useMemo(() => turns.map(({ totals }, position) => ({
+        index: position + 1,
+        title: t(column, { index: position + 1 }),
+        ms: totals.durationMs,
+        ...tokenSplit({
+            input: totals.input?.value,
+            cached: totals.cached?.value,
+            output: totals.output?.value,
+            cost: totals.cost?.value,
+        }),
+        open: () => onPick(position),
+    })), [turns, onPick, t, column]);
+    return (_jsxs(Grid, { columns: { minWidth: 260, repeat: 'fit' }, gap: 3, children: [_jsx(TurnTimeCard, { rows: time, isCalls: isCalls }), _jsx(TokensCard, { title: t('@theorem.panel.trace.charts.turnTokens'), rows: tokens })] }));
+}

package/ui/TraceGuardrails.d.ts

@@ -0,0 +1,11 @@
+import type { TraceGuardrailCheck } from '../client/trace-story.ts';
+import type { TraceNode } from '../client/trace-view.ts';
+/**
+ * Every guardrail check of the turn. The ones that acted lead, each with the
+ * rules it matched and why; the passes follow on one quiet line.
+ */
+export declare function TraceGuardrails({ checks, onSelect, }: {
+    checks: readonly TraceGuardrailCheck[];
+    /** Opens a check's step; without it a check is not a button. */
+    onSelect?: (node: TraceNode) => void;
+}): import("react").JSX.Element;

package/ui/TraceGuardrails.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Icon } from '@astryxdesign/core/Icon';
+import { Item } from '@astryxdesign/core/Item';
+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 { IconBiohazard, IconEyeOff, IconHandStop, IconInfoCircle, IconShield, } from '@tabler/icons-react';
+import { TOOL_RULES } from '@theoremjs/agents/guardrails';
+import { Arrive, Stream } from "./arrive.js";
+import { useTraceFormat } from "./TraceValues.js";
+/** What a check is called: the timed check's own name, or else the text it looked at. */
+function checkName(check) {
+    return check.checkLabel ?? check.stageLabel;
+}
+/** One rule a check matched: what it caught and how serious, why that matters, and the matched text when kept. The id is on hover, for finding the rule in code. */
+function HitWhy({ hit, separator }) {
+    return (_jsxs(VStack, { gap: 0, children: [_jsx(HoverTip, { content: hit.rule, children: _jsx(Text, { type: "supporting", weight: "medium", children: [hit.ruleLabel, hit.severityLabel].filter(Boolean).join(separator) }) }), hit.ruleDoc ? (_jsx(Text, { type: "supporting", color: "secondary", children: hit.ruleDoc })) : null, hit.match ? (_jsx(Text, { type: "supporting", color: "secondary", maxLines: 2, children: `“${hit.match}”` })) : null] }));
+}
+/** Why a check acted: which check it was and on what, each rule it matched, and the guardrail's own reason. */
+function CheckWhy({ check, format }) {
+    const separator = format.t('@theorem.panel.trace.separator');
+    return (_jsxs(VStack, { gap: 1, children: [_jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: [
+                    checkName(check),
+                    check.durationMs !== undefined && format.duration(check.durationMs),
+                    check.tool && format.t('@theorem.panel.trace.guardrails.from', { tool: check.tool }),
+                ]
+                    .filter(Boolean)
+                    .join(separator) }), check.hits.map((hit) => (_jsx(HitWhy, { hit: hit, separator: separator }, `${hit.rule}:${hit.match ?? ''}`))), check.reason ? (_jsx(Text, { type: "supporting", color: "secondary", maxLines: 3, children: check.reason })) : null] }));
+}
+/** What a check did, as a token. A report of a call made after a remote read says so in place of "flagged". */
+function ActionToken({ check, format }) {
+    if (check.action === 'block') {
+        return (_jsx(Token, { label: check.actionLabel, color: "red", icon: _jsx(Icon, { icon: IconHandStop, size: "sm" }) }));
+    }
+    if (check.action === 'redact') {
+        return (_jsx(Token, { label: check.actionLabel, color: "orange", icon: _jsx(Icon, { icon: IconEyeOff, size: "sm" }) }));
+    }
+    const rules = new Set(check.hits.map((hit) => hit.rule));
+    if (rules.has(TOOL_RULES.steeredTurn) || rules.has(TOOL_RULES.taintedTurn)) {
+        return (_jsx(Token, { label: format.t(rules.has(TOOL_RULES.steeredTurn)
+                ? '@theorem.panel.trace.guardrails.steered'
+                : '@theorem.panel.trace.guardrails.tainted'), color: "yellow", icon: _jsx(Icon, { icon: IconBiohazard, size: "sm" }) }));
+    }
+    return (_jsx(Token, { label: check.actionLabel, color: "blue", icon: _jsx(Icon, { icon: IconInfoCircle, size: "sm" }) }));
+}
+function ActedCheck({ check, format, onSelect, }) {
+    return (_jsx(Item, { startContent: _jsx(Icon, { icon: IconShield, size: "sm", color: "secondary" }), label: _jsx(HoverTip, { content: check.actionDoc ?? check.actionLabel, children: _jsx(ActionToken, { check: check, format: format }) }), description: _jsx(CheckWhy, { check: check, format: format }), endContent: _jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: format.t('@theorem.panel.trace.offset', { duration: format.duration(check.offsetMs) }) }), align: "start", density: "compact", ...(onSelect ? { onClick: () => onSelect(check.node) } : {}) }));
+}
+/** "Input check 0.8ms, Result check ×3 0.4ms": the passes, one entry per kind of check with its count and total time. */
+function passSummary(passes, format) {
+    const kinds = new Map();
+    for (const check of passes) {
+        const kind = kinds.get(checkName(check)) ?? { count: 0, ms: 0, timed: false };
+        kinds.set(checkName(check), {
+            count: kind.count + 1,
+            ms: kind.ms + (check.durationMs ?? 0),
+            timed: kind.timed || check.durationMs !== undefined,
+        });
+    }
+    return [...kinds]
+        .map(([name, { count, ms, timed }]) => [name, count > 1 && `×${count}`, timed && format.duration(ms)].filter(Boolean).join(' '))
+        .join(', ');
+}
+/**
+ * Every guardrail check of the turn. The ones that acted lead, each with the
+ * rules it matched and why; the passes follow on one quiet line.
+ */
+export function TraceGuardrails({ checks, onSelect, }) {
+    const format = useTraceFormat();
+    const acted = checks.filter((check) => check.action !== 'allow');
+    const passed = passSummary(checks.filter((check) => check.action === 'allow'), format);
+    return (_jsx(Stream, { children: _jsxs(VStack, { gap: 1, children: [acted.map((check) => (_jsx(Arrive, { children: _jsx(ActedCheck, { check: check, format: format, onSelect: onSelect }) }, check.id))), passed ? (_jsx(Arrive, { children: _jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: format.t('@theorem.panel.trace.guardrails.passed', { checks: passed }) }) })) : null] }) }));
+}

package/ui/TraceInspector.d.ts

@@ -0,0 +1,16 @@
+import type { TraceRecord } from '@theoremjs/agents';
+import { type ReactNode } from 'react';
+import type { TraceFeed } from '../client/trace-feed.ts';
+/** The inspector over the records a feed has delivered; the panel loads this module when it first opens. */
+export declare function TraceFeedBody({ traces, isWide, }: {
+    traces: TraceFeed | undefined;
+    isWide: boolean;
+}): import("react").JSX.Element;
+/**
+ * Only what the records say of guardrails: how long the checks took, how many
+ * ran and acted, then each check. `head` leads it.
+ */
+export declare function TraceGuardrailsBody({ records, head, }: {
+    records: readonly TraceRecord[];
+    head?: ReactNode;
+}): import("react").JSX.Element;

package/ui/TraceInspector.js

@@ -0,0 +1,206 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { 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 { 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";
+import { useTraceRecords } from "../hooks/use-trace-records.js";
+import { Stream, useArrive } from "./arrive.js";
+import { PaneLayout } from "./SidePanel.js";
+import { ConversationCharts, TraceCharts } from "./TraceCharts.js";
+import { TraceGuardrails } from "./TraceGuardrails.js";
+import { GuardrailStats, TurnPicker, TurnStats } from "./TraceOverview.js";
+import { TraceSpanDetail } from "./TraceSpanDetail.js";
+import { ActorMark, TraceStory } from "./TraceStory.js";
+import { useTraceFormat } from "./TraceValues.js";
+import { TraceWaterfall } from "./TraceWaterfall.js";
+import { TracePatterns } from "./trace-patterns.js";
+function unitOf(t, field) {
+    switch (field.format) {
+        case 'milliseconds':
+            return t('@theorem.panel.trace.unit.milliseconds');
+        case 'seconds':
+            return t('@theorem.panel.trace.unit.seconds');
+        case 'usd':
+            return t('@theorem.panel.trace.unit.usd');
+        default:
+            return undefined;
+    }
+}
+function operatorValue(t, field) {
+    switch (field.kind) {
+        case 'options':
+            return {
+                type: 'enum_list',
+                values: (field.options ?? []).map(({ value, label }) => ({ value, label })),
+            };
+        case 'number': {
+            const units = unitOf(t, field);
+            return units ? { type: 'float', units } : { type: 'float' };
+        }
+        case 'text':
+            return { type: 'string', isArbitraryStringAllowed: true };
+        case 'flag':
+            return { type: 'empty' };
+    }
+}
+function searchField(t, field) {
+    const value = operatorValue(t, field);
+    return {
+        key: field.key,
+        label: field.label,
+        description: field.doc,
+        ...(field.group && { group: field.group }),
+        operators: TRACE_SEARCH_OPERATORS[field.kind].map((key) => ({
+            key,
+            value,
+            i18nKey: `@astryx.powersearch.operator.${key}`,
+        })),
+    };
+}
+/** The search over the spans shown: any text first, then the fields the spans recorded. */
+function searchConfig(t, nodes) {
+    return {
+        name: t('@theorem.panel.trace.search'),
+        contentSearchFieldKey: TRACE_TEXT_FIELD,
+        fields: [
+            searchField(t, {
+                key: TRACE_TEXT_FIELD,
+                label: t('@theorem.panel.trace.search.text'),
+                doc: t('@theorem.panel.trace.search.text.description'),
+                kind: 'text',
+            }),
+            ...traceSearchFields(nodes).map((field) => searchField(t, field)),
+        ],
+    };
+}
+function SectionTitle({ title, children }) {
+    return (_jsxs(HStack, { gap: 2, align: "center", justify: "between", children: [_jsx(Text, { weight: "semibold", children: title }), children] }));
+}
+/** The turn open, or none for the whole conversation; a trace of one turn opens it. */
+function useOpenTurn(count) {
+    const [picked, setPicked] = useState(null);
+    const index = count === 1 ? 0 : picked !== null && picked < count ? picked : null;
+    return { index, pick: setPicked };
+}
+/** How the row's turn ended: its failure, else its answer. */
+function turnRowNote(row) {
+    if (row.outcome)
+        return _jsx(Badge, { variant: row.outcome.tone, label: row.outcome.label });
+    if (!row.answered)
+        return undefined;
+    return (_jsx(Text, { color: "secondary", maxLines: 2, hasTruncateTooltip: false, children: row.answered }));
+}
+/** A row's time, and its cost when it has one. */
+function TurnRowTotals({ turn }) {
+    const format = useTraceFormat();
+    return (_jsxs(VStack, { gap: 0, hAlign: "end", children: [_jsx(Text, { type: "supporting", hasTabularNumbers: true, children: format.duration(turn.totals.durationMs) }), turn.totals.cost ? (_jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: format.sum(turn.totals.cost, format.usd) })) : null] }));
+}
+/** A row of the whole-trace list: a turn by what the person asked, a host's call by its tool. */
+function TurnRow({ turn, index, isCall, onOpen, }) {
+    const { t } = useTraceFormat();
+    const arrive = useArrive();
+    const row = useMemo(() => traceTurnRow(turn, isCall), [turn, isCall]);
+    return (_jsx(Item, { className: arrive?.className, style: arrive?.style, startContent: _jsx(ActorMark, { actor: row.actor }), label: _jsx(Text, { weight: "medium", maxLines: 1, children: row.title ??
+                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, }) {
+    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.
+    const totals = useMemo(() => ({
+        ...traceTotals(nodes),
+        durationMs: turns.reduce((total, turn) => total + turn.totals.durationMs, 0),
+    }), [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))) }) })] })] }));
+}
+/** One turn at a glance, then its story, then its timeline under the search. */
+function TurnOverview({ turns, index, onPick, onBack, selectedId, onSelect, }) {
+    const { t } = useTraceFormat();
+    const [filters, setFilters] = useState([]);
+    const turn = turns[index];
+    const root = turn?.node;
+    const config = useMemo(() => searchConfig(t, root ? [root] : []), [t, root]);
+    const matches = useMemo(() => (root ? traceMatchIds([root], filters) : undefined), [root, filters]);
+    const story = useMemo(() => (root ? traceStory(root) : []), [root]);
+    const latency = useMemo(() => (root ? traceLatency(root) : undefined), [root]);
+    const guardrails = useMemo(() => (root ? traceGuardrails(root) : []), [root]);
+    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] }));
+}
+function EmptyTrace() {
+    const { t } = useTraceFormat();
+    return (_jsx(VStack, { height: "100%", vAlign: "center", padding: 4, children: _jsx(EmptyState, { icon: _jsx(Icon, { icon: IconActivity, size: "lg", color: "secondary" }), title: t('@theorem.panel.trace.empty.title'), description: t('@theorem.panel.trace.empty.description'), isCompact: true }) }));
+}
+/** The open span of the open turn; opening another turn closes it. */
+function useOpenSpan(turns) {
+    const { index, pick } = useOpenTurn(turns.length);
+    const [openId, setOpenId] = useState(null);
+    const root = index === null ? undefined : turns[index]?.node;
+    const open = openId && root ? traceSpans([root]).find((node) => node.id === openId) : undefined;
+    return {
+        index,
+        root,
+        open,
+        select: (node) => setOpenId(node.id),
+        close: () => setOpenId(null),
+        pick: (next) => {
+            pick(next);
+            setOpenId(null);
+        },
+    };
+}
+/** The open span beside or in place of the overview; nothing while none is open. */
+function SpanPane({ open, turnStartMs, isWide, onBack, onOpen, }) {
+    if (!open)
+        return null;
+    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, }) {
+    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 }));
+}
+/**
+ * The panel's content. Narrow, the turn fills it and a span opens in its
+ * place; wide, an open span sits beside the turn.
+ */
+function TraceInspectorBody({ records, isWide, }) {
+    const tree = useMemo(() => traceTree(records), [records]);
+    const turns = useMemo(() => traceTurns(tree), [tree]);
+    const { t } = useTraceFormat();
+    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 }));
+    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. */
+export function TraceFeedBody({ traces, isWide, }) {
+    return _jsx(TraceInspectorBody, { records: useTraceRecords(traces), isWide: isWide });
+}
+/**
+ * Only what the records say of guardrails: how long the checks took, how many
+ * ran and acted, then each check. `head` leads it.
+ */
+export function TraceGuardrailsBody({ records, head, }) {
+    const { t } = useTraceFormat();
+    const roots = useMemo(() => traceTurns(traceTree(records)).map((turn) => turn.node), [records]);
+    const checks = useMemo(() => roots.flatMap(traceGuardrails), [roots]);
+    return (_jsxs(VStack, { gap: 5, padding: 4, children: [head, roots.map((root) => (_jsx(GuardrailStats, { latency: traceLatency(root) }, root.id))), checks.length > 0 ? (_jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.guardrails') }), _jsx(TraceGuardrails, { checks: checks })] })) : null] }));
+}

package/ui/TraceInspectorPanel.d.ts

@@ -0,0 +1,46 @@
+import type { TraceRecord } from '@theoremjs/agents';
+import type { ProfileObservabilityView } from '@theoremjs/agents/interface';
+import { type ReactNode } from 'react';
+import type { TraceFeed } from '../client/trace-feed.ts';
+import { type SidePanelLabels } from './SidePanel.tsx';
+export type TraceInspector = {
+    /** The header toggle; null when the host drives the trace or the profile records none. */
+    toggle: ReactNode;
+    /** The trace, while it's open; null otherwise. */
+    view: ReactNode;
+    /** Words for the docked panel. */
+    labels: SidePanelLabels;
+    /** The profile records traces, so a panel page can dock them even when the host drives the toggle. */
+    offered: boolean;
+};
+/** Where an open trace sits on this page. */
+export declare function TracePlacement({ value, children, }: {
+    value: 'replace' | 'panel';
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * The trace inspector, offered when the profile records traces. By default the
+ * open trace takes the surface's place. Inside `TracePlacement value="panel"`
+ * it docks at the inline end instead, and the theme eases that panel's width.
+ * It reads the records the host delivers on `traces`; a host that delivers none
+ * shows the empty state. Pass `open` to drive it from the host's own control,
+ * which hides the built-in toggle. The open trace takes the surface's place,
+ * unless this page is inside `TracePlacement value="panel"`, where it docks.
+ */
+export declare function useTraceInspector(iface: {
+    observability?: Pick<ProfileObservabilityView, 'record'>;
+}, traces?: TraceFeed, open?: boolean): TraceInspector;
+/** The surface, or the trace in its place — or, on a docked page, beside it. */
+export declare function WithTrace({ inspector, children, }: {
+    inspector: TraceInspector;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * What `records` say of guardrails, for a host that holds a trace of its own
+ * (the studio's guardrail test): the checks' time and count, then each
+ * check, laid out as the trace lays them out. `head` leads it.
+ */
+export declare function TraceGuardrailsView({ records, head, }: {
+    records: readonly TraceRecord[];
+    head?: ReactNode;
+}): import("react").JSX.Element;