@theoremjs/react 0.3.0 → 0.3.1

package/client/space-geometry.js

@@ -0,0 +1,183 @@
+/**
+ * What the embedding space draws, as flat arrays a GPU takes as they are:
+ * the axes' three circles, each document's dot, a line for each link, heavier
+ * the further its cosine similarity passes the threshold, and a query's white
+ * dot with a line to each match that passes its own.
+ * Every other line joins two real points and stands for their cosine
+ * similarity; nothing is drawn for show.
+ *
+ * @module
+ */
+/**
+ * Floats per line segment: from (3), to (3), colour (3), alpha, width in CSS
+ * pixels, the two slots it reads its state from, where it sits along its line
+ * (0 at the start, 1 at the end), and the gap in CSS pixels it leaves before
+ * its start and after its end, where a dot sits.
+ */
+export const SEGMENT_FLOATS = 16;
+/** Floats per dot: position (3), colour (3), alpha, radius in CSS pixels, its slot, and where it sits along the line that reaches it. */
+export const DOT_FLOATS = 10;
+/** Stands for the query where a slot would go. */
+export const QUERY_SLOT = -1;
+/** Stands for the axes' circles, which no document's state reaches. */
+export const FRAME_SLOT = -2;
+/** Every cluster's colour has this lightness and chroma, so none reads dirtier or louder than another. */
+const LIGHTNESS = 0.72;
+const CHROMA = 0.085;
+const QUERY_COLOUR = [0.97, 0.98, 1.0];
+/**
+ * Every line is a faint hairline in its documents' colour: it hints at a
+ * connection, and the dots carry the picture. Its width in CSS pixels and its
+ * opacity, at the threshold and at identical.
+ */
+const LINE_WIDTH = [0.3, 0.5];
+const LINE_ALPHA = [0.18, 0.4];
+function weighted([at, to], strength) {
+    return at + (to - at) * strength;
+}
+function gamma(linear) {
+    return linear <= 0.0031308 ? 12.92 * linear : 1.055 * linear ** (1 / 2.4) - 0.055;
+}
+/** An OKLCH colour as sRGB from 0 to 1, or `null` when the screen cannot show it. */
+function oklch(l, c, hue) {
+    const a = c * Math.cos(hue);
+    const b = c * Math.sin(hue);
+    const l_ = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m_ = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s_ = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;
+    const rgb = [
+        4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_,
+        -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_,
+        -0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_,
+    ];
+    if (rgb.some((v) => v < -1e-4 || v > 1 + 1e-4))
+        return null;
+    return rgb.map((v) => gamma(Math.min(1, Math.max(0, v))));
+}
+/** A cluster's colour from its tone, a hue from 0 to 1, at the palette's one lightness; chroma gives way only where the screen runs out. */
+function colourOf(tone) {
+    const hue = tone * 2 * Math.PI;
+    for (let c = CHROMA; c > 0; c -= 0.005) {
+        const colour = oklch(LIGHTNESS, c, hue);
+        if (colour)
+            return colour;
+    }
+    return oklch(LIGHTNESS, 0, hue) ?? [0.8, 0.8, 0.8];
+}
+function mixed(a, b, u) {
+    return [a[0] + (b[0] - a[0]) * u, a[1] + (b[1] - a[1]) * u, a[2] + (b[2] - a[2]) * u];
+}
+/** The longest piece a line is cut into, so depth fades along it, not only at its ends. */
+const PIECE = 0.1;
+/** Points along the straight line from one point to another, through the ball. */
+function pieces(a, b) {
+    const steps = Math.max(1, Math.ceil(Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]) / PIECE));
+    return Array.from({ length: steps + 1 }, (_, s) => mixed(a, b, s / steps));
+}
+class Strokes {
+    segments = [];
+    dots = [];
+    line({ from, to, colour, alpha, width, slots, gaps }) {
+        const points = pieces(from, to);
+        const last = points.length - 1;
+        for (let i = 1; i <= last; i += 1) {
+            const u = i / last;
+            this.segments.push(...points[i - 1], ...points[i], ...colour((i - 0.5) / last), alpha, width, slots[0], slots[1], u, i === 1 ? gaps[0] : 0, i === last ? gaps[1] : 0);
+        }
+    }
+    /** One segment no document's state reaches, always shown, with no gaps. */
+    segment(from, to, colour, alpha, width) {
+        this.segments.push(...from, ...to, ...colour, alpha, width, FRAME_SLOT, FRAME_SLOT, 0, 0, 0);
+    }
+    dot({ at, colour, alpha, radius, slot, along }) {
+        this.dots.push(...at, ...colour, alpha, radius, slot, along);
+    }
+    done() {
+        return { segments: new Float32Array(this.segments), dots: new Float32Array(this.dots) };
+    }
+}
+/** A document's dot, and the query's, a little larger, in CSS pixels. */
+const DOCUMENT_RADIUS = 2.6;
+const QUERY_RADIUS = 3.6;
+/** The clear space between a line's end and the dot it reaches. */
+const GAP = 1.75;
+/** How far a link passes the threshold, from 0 at it to 1 at identical. */
+function strengthOf(space, similarity) {
+    if (space.threshold >= 1)
+        return 1;
+    return Math.min(Math.max((similarity - space.threshold) / (1 - space.threshold), 0), 1);
+}
+/** The axes' circles: a hairline round the rim in each plane two of the three axes span. */
+const FRAME_COLOUR = [0.88, 0.9, 0.94];
+/** At the ball's front; the renderer fades a circle with the square of its depth, toward a quarter of this at the back. */
+const FRAME_ALPHA = 0.29;
+const FRAME_WIDTH = 0.7;
+const FRAME_STEPS = 96;
+function frame(strokes) {
+    const planes = [
+        (a) => [Math.cos(a), Math.sin(a), 0],
+        (a) => [Math.cos(a), 0, Math.sin(a)],
+        (a) => [0, Math.cos(a), Math.sin(a)],
+    ];
+    for (const at of planes)
+        for (let i = 0; i < FRAME_STEPS; i += 1)
+            strokes.segment(at((i / FRAME_STEPS) * 2 * Math.PI), at(((i + 1) / FRAME_STEPS) * 2 * Math.PI), FRAME_COLOUR, FRAME_ALPHA, FRAME_WIDTH);
+}
+/** Everything a space draws before any query: the axes' circles, a line for each link, then every document's dot. */
+export function spaceGeometry(space) {
+    const strokes = new Strokes();
+    frame(strokes);
+    const colourOfDocument = (index) => colourOf(space.clusters[space.documents[index].cluster].tone);
+    for (const link of space.links) {
+        const strength = strengthOf(space, link.similarity);
+        // invariant: a link's two documents are in one cluster, so it takes their colour.
+        const colour = colourOfDocument(link.a);
+        strokes.line({
+            from: space.documents[link.a].position,
+            to: space.documents[link.b].position,
+            colour: () => colour,
+            alpha: weighted(LINE_ALPHA, strength),
+            width: weighted(LINE_WIDTH, strength),
+            slots: [link.a, link.b],
+            gaps: [DOCUMENT_RADIUS + GAP, DOCUMENT_RADIUS + GAP],
+        });
+    }
+    for (const document of space.documents)
+        strokes.dot({
+            at: document.position,
+            colour: colourOfDocument(document.index),
+            alpha: 1,
+            radius: DOCUMENT_RADIUS,
+            slot: document.index,
+            along: 0,
+        });
+    return strokes.done();
+}
+/** A query's white dot where it landed, and a line from it to each match, weighted as a link is. */
+export function queryGeometry(space, at, matches) {
+    const strokes = new Strokes();
+    for (const match of matches) {
+        const document = space.documents[match.index];
+        if (!document)
+            continue;
+        const colour = colourOf(space.clusters[document.cluster].tone);
+        strokes.line({
+            from: at,
+            to: document.position,
+            colour: (u) => mixed(QUERY_COLOUR, colour, u),
+            alpha: weighted(LINE_ALPHA, match.closeness),
+            width: weighted(LINE_WIDTH, match.closeness),
+            slots: [QUERY_SLOT, match.index],
+            gaps: [QUERY_RADIUS + GAP, DOCUMENT_RADIUS + GAP],
+        });
+    }
+    strokes.dot({
+        at,
+        colour: QUERY_COLOUR,
+        alpha: 1,
+        radius: QUERY_RADIUS,
+        slot: QUERY_SLOT,
+        along: 0,
+    });
+    return strokes.done();
+}

package/client/state-fields.js

@@ -35,7 +35,7 @@ export function tableColumns(value) {
         Object.values(row).every((cell) => cell === null || typeof cell !== 'object'));
     if (!alike)
         return null;
-    // Wider columns for longer values: a role stays narrow beside its message.
+    // why: Wider columns for longer values: a role stays narrow beside its message.
     return keys.map((key) => {
         const lengths = value.map((row) => String(row[key] ?? '').length);
         const longest = Math.max(key.length, ...lengths);

package/client/tool-result.js

@@ -57,8 +57,10 @@ function figuresOf(row, units) {
         if (reading)
             figures.push({ key, value, ...reading });
     }
-    // Numbers with a unit say more at a glance: they lead.
-    return figures.sort((a, b) => Number(b.unit !== undefined) - Number(a.unit !== undefined)).slice(0, MAX_FIGURES);
+    // why: Numbers with a unit say more at a glance: they lead.
+    return figures
+        .sort((a, b) => Number(b.unit !== undefined) - Number(a.unit !== undefined))
+        .slice(0, MAX_FIGURES);
 }
 /**
  * The figures: the numbers of the first nested object of plain fields (the
@@ -87,7 +89,9 @@ function distinct(rows, key) {
 }
 /** Fields every row holds as a number, that measure something and vary. */
 function numericSeries(rows, skip, units) {
-    const keys = [...new Set(rows.flatMap((row) => Object.keys(row)))].filter((key) => key !== skip && rows.every((row) => typeof row[key] === 'number' || row[key] === null) && distinct(rows, key) > 1);
+    const keys = [...new Set(rows.flatMap((row) => Object.keys(row)))].filter((key) => key !== skip &&
+        rows.every((row) => typeof row[key] === 'number' || row[key] === null) &&
+        distinct(rows, key) > 1);
     return keys.flatMap((key) => {
         const reading = measured(key, units);
         return reading ? [{ key, ...reading }] : [];
@@ -105,7 +109,8 @@ function sharedWords(series) {
     const words = series.map((one) => one.label.split(' '));
     const [first = []] = words;
     let shared = 0;
-    while (shared < first.length && words.every((one) => one.length > shared + 1 && one[shared] === first[shared]))
+    while (shared < first.length &&
+        words.every((one) => one.length > shared + 1 && one[shared] === first[shared]))
         shared++;
     if (!shared)
         return undefined;
@@ -131,7 +136,9 @@ function timeCharts(path, title, rows, x, units) {
         return {
             kind: 'time',
             key: `${path}:${shown.map((series) => series.key).join('+')}`,
-            title: shown.length === 1 ? (shown[0]?.label ?? title) : (shared?.title ?? (title || shown.map((series) => series.label).join(' · '))),
+            title: shown.length === 1
+                ? (shown[0]?.label ?? title)
+                : (shared?.title ?? (title || shown.map((series) => series.label).join(' · '))),
             x,
             series: shared?.series ?? shown,
             rows,
@@ -142,7 +149,9 @@ function timeCharts(path, title, rows, x, units) {
 function labelKey(rows) {
     const [first] = rows;
     const title = first ? titleKey(first) : undefined;
-    if (!first || !title || !rows.every((row) => typeof row[title] === 'string' || typeof row[title] === 'number'))
+    if (!first ||
+        !title ||
+        !rows.every((row) => typeof row[title] === 'string' || typeof row[title] === 'number'))
         return undefined;
     if (distinct(rows, title) === rows.length)
         return title;
@@ -193,7 +202,6 @@ function chartsIn(value, path, title, units, depth) {
     const entries = shownEntries(value);
     const numbers = entries.filter(([key, entry]) => typeof entry === 'number' && isMeasure(key));
     if (depth > 0 && numbers.length >= MIN_POINTS && numbers.length === entries.length) {
-        // An object of numbers (`rates`): each key a bar.
         const rows = numbers.map(([key, entry]) => ({ label: keyLabel(key), value: entry }));
         return [
             {
@@ -247,13 +255,18 @@ export function returnedMedia(layout, parts, imageAlt) {
         return src ? [{ type: part.type, src, mimeType: part.mimeType }] : [];
     });
     return {
-        images: [...sourced.filter((part) => part.type === 'image').map(({ src }) => ({ src, alt: imageAlt })), ...layout.images],
-        audio: sourced.filter((part) => part.type === 'audio').map(({ src, mimeType }) => ({ src, ...(mimeType ? { mimeType } : {}) })),
+        images: [
+            ...sourced.filter((part) => part.type === 'image').map(({ src }) => ({ src, alt: imageAlt })),
+            ...layout.images,
+        ],
+        audio: sourced
+            .filter((part) => part.type === 'audio')
+            .map(({ src, mimeType }) => ({ src, ...(mimeType ? { mimeType } : {}) })),
     };
 }
 /** Whether the result has anything to lead with above its data. */
 export function hasLead(layout, media) {
-    return layout.figures.length + layout.charts.length + media.images.length + media.audio.length > 0;
+    return (layout.figures.length + layout.charts.length + media.images.length + media.audio.length > 0);
 }
 const DAY_MS = 86_400_000;
 /** Days a time chart names by weekday; longer runs read as dates. */
@@ -266,10 +279,15 @@ const MAX_WEEKDAYS = 10;
 export function timeFormats(dates) {
     if (dates.some((date) => date.includes('T'))) {
         const span = Math.abs(Date.parse(dates.at(-1) ?? '') - Date.parse(dates[0] ?? ''));
-        return { tick: span <= DAY_MS ? { hour: 'numeric' } : { month: 'short', day: 'numeric' }, when: { dateStyle: 'medium', timeStyle: 'short' } };
+        return {
+            tick: span <= DAY_MS ? { hour: 'numeric' } : { month: 'short', day: 'numeric' },
+            when: { dateStyle: 'medium', timeStyle: 'short' },
+        };
     }
     return {
-        tick: dates.length <= MAX_WEEKDAYS ? { weekday: 'short', timeZone: 'UTC' } : { month: 'short', day: 'numeric', timeZone: 'UTC' },
+        tick: dates.length <= MAX_WEEKDAYS
+            ? { weekday: 'short', timeZone: 'UTC' }
+            : { month: 'short', day: 'numeric', timeZone: 'UTC' },
         when: { dateStyle: 'medium', timeZone: 'UTC' },
     };
 }

package/client/tool-resume.d.ts

@@ -7,12 +7,28 @@ export type ToolGateResolution = {
  | {
     action: 'auth';
     secret?: string;
+}
+/** The page answered a `page` gate: no person decides it. */
+ | {
+    action: 'page';
+    page: PagePart;
+};
+/** What the page sends for a call it was asked to answer: its output, or that nothing here answers the tool. */
+export type PagePart = {
+    output: unknown;
+} | {
+    unanswered: true;
 };
 /** An answer on its way to the gate on `callId`; the gate shows it until the answer settles or fails. */
 export type AnsweringGate = {
     callId: string;
-    action: ToolGateResolution['action'];
+    operationId: string;
+    action: PersonGateResolution['action'];
 };
+/** An answer a person gives: every resolution but the page's own. */
+export type PersonGateResolution = Exclude<ToolGateResolution, {
+    action: 'page';
+}>;
 /**
  * What the browser sends for the user's answer to a gate. The host settles a
  * refusal; an approval carries the permissions the session holds after it,
@@ -23,6 +39,7 @@ export type GatedToolContinue = {
 } | {
     decision: 'approve';
     secret?: string;
+    page?: PagePart;
     sessionPermissions: string[];
 };
 export declare function continueGatedToolInvocation(args: {

package/client/tool-resume.js

@@ -5,7 +5,10 @@ export function continueGatedToolInvocation(args) {
     const { resolution } = args;
     return {
         decision: 'approve',
-        ...(resolution.action === 'auth' && resolution.secret !== undefined ? { secret: resolution.secret } : {}),
+        ...(resolution.action === 'auth' && resolution.secret !== undefined
+            ? { secret: resolution.secret }
+            : {}),
+        ...(resolution.action === 'page' ? { page: resolution.page } : {}),
         sessionPermissions: sessionPermissionsAfterApproval(args.sessionPermissions, args.toolName, args.gate.permission),
     };
 }

package/client/trace-feed.d.ts

@@ -1,7 +1,7 @@
 import type { TraceRecord } from '@theoremjs/agents';
 /**
  * Trace records a host sends back to the client, in arrival order. Only a host
- * that delivers its traces (the playground) has one; `useTraceRecords` reads it.
+ * that delivers its traces (the studio) has one; `useTraceRecords` reads it.
  */
 export interface TraceFeed {
     push(record: TraceRecord): void;

package/client/trace-story.d.ts

@@ -61,7 +61,7 @@ export type TraceStep = {
 /** The last message's text from `role`, read from a span's input or output messages. */
 export declare function messageText(node: TraceNode, key: 'gen_ai.input.messages' | 'gen_ai.output.messages', role: string): string;
 /**
- * A turn as it happened: what the user asked, each model call and the tool
+ * A turn as it happened: what the user asked, each model call, and the tool
  * calls it asked for (nested under it), the events that changed the course,
  * and how it ended. HTTP tries stay in the timeline; they are how a call
  * travelled, not a step of the story.
@@ -71,7 +71,7 @@ export declare function traceStory(root: TraceNode): TraceStep[];
 export declare function toolArguments(node: TraceNode): [string, string][];
 /** A stored JSON or text value, parsed when it is JSON. */
 export declare function storedValue(node: TraceNode, key: string): unknown;
-/** How a span ended when it did not simply succeed: a tool denied, paused or failed, or any span's error. */
+/** How a span ended when it did not simply succeed: a tool denied, paused, or failed, or any span's error. */
 export interface TraceOutcome {
     label: string;
     doc?: string;

package/client/trace-story.js

@@ -1,6 +1,6 @@
-import { inlineContent, traceAttributeMeta, traceEventAttributeMeta, traceEventMeta } from '@theoremjs/agents';
+import { inlineContent, traceAttributeMeta, traceEventAttributeMeta, traceEventMeta, } from '@theoremjs/agents';
 import { isRecord } from '@theoremjs/agents/kernel';
-import { nanosToMs, traceSpans, traceTotals } from "./trace-view.js";
+import { nanosToMs, traceSpans, traceTotals, } from "./trace-view.js";
 export function traceTurns(tree) {
     return tree.map((node) => ({
         node,
@@ -44,7 +44,7 @@ export function traceActor(node) {
             return 'theorem';
     }
 }
-/** Events worth a line of their own: something acted, retried, waited or warned. */
+/** Events worth a line of their own: something acted, retried, waited, or warned. */
 const STORY_EVENTS = new Set([
     'theorem.guardrail',
     'theorem.attempt.retry',
@@ -116,7 +116,7 @@ function storyEvents(node, turnStart) {
     });
 }
 /**
- * A turn as it happened: what the user asked, each model call and the tool
+ * A turn as it happened: what the user asked, each model call, and the tool
  * calls it asked for (nested under it), the events that changed the course,
  * and how it ended. HTTP tries stay in the timeline; they are how a call
  * travelled, not a step of the story.
@@ -185,7 +185,9 @@ export function toolArguments(node) {
     }
     if (!isRecord(value))
         return [];
-    return Object.entries(value).flatMap(([key, item]) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean' ? [[key, String(item)]] : []);
+    return Object.entries(value).flatMap(([key, item]) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean'
+        ? [[key, String(item)]]
+        : []);
 }
 /** A stored JSON or text value, parsed when it is JSON. */
 export function storedValue(node, key) {
@@ -209,14 +211,22 @@ export function traceOutcome(node) {
     const codePart = typeof code === 'string' ? { code } : {};
     const tool = outcome !== 'ok' ? optionOf('theorem.tool.outcome', outcome) : undefined;
     if (tool)
-        return { ...tool, ...codePart, tone: status.code === 'ERROR' || outcome === 'error' ? 'error' : 'warning' };
+        return {
+            ...tool,
+            ...codePart,
+            tone: status.code === 'ERROR' || outcome === 'error' ? 'error' : 'warning',
+        };
     if (status.code !== 'ERROR')
         return undefined;
     const type = attributes['error.type'];
     const kind = optionOf('error.type', type);
     if (kind)
         return { ...kind, ...codePart, tone: 'error' };
-    return { label: typeof type === 'string' ? type : (status.message ?? ''), ...codePart, tone: 'error' };
+    return {
+        label: typeof type === 'string' ? type : (status.message ?? ''),
+        ...codePart,
+        tone: 'error',
+    };
 }
 function guardrailHits(value) {
     if (!Array.isArray(value))
@@ -226,7 +236,7 @@ function guardrailHits(value) {
         if (typeof hit.rule !== 'string')
             return [];
         const severity = typeof hit.severity === 'string' ? hit.severity : '';
-        // A host names its own rules on the hit; Theorem's are named in the catalog.
+        // why: A host names its own rules on the hit; Theorem's are named in the catalog.
         const rule = fields?.rule?.options?.[hit.rule];
         const ruleDoc = typeof hit.doc === 'string' ? hit.doc : rule?.doc;
         return [
@@ -268,7 +278,9 @@ export function traceGuardrails(root) {
                 action,
                 actionLabel: actionMeta?.label ?? action,
                 ...(actionMeta && { actionDoc: actionMeta.doc }),
-                ...(typeof attributes.duration_ms === 'number' && { durationMs: attributes.duration_ms }),
+                ...(typeof attributes.duration_ms === 'number' && {
+                    durationMs: attributes.duration_ms,
+                }),
                 hits: guardrailHits(attributes.hits),
                 ...(typeof provenance?.tool === 'string' && { tool: provenance.tool }),
                 ...(typeof reason === 'string' && reason && { reason }),
@@ -290,7 +302,9 @@ function union(intervals) {
     return total;
 }
 function intervalsOf(nodes, types) {
-    return nodes.filter((node) => types.has(node.meta.type)).map((node) => [node.startMs, node.startMs + node.durationMs]);
+    return nodes
+        .filter((node) => types.has(node.meta.type))
+        .map((node) => [node.startMs, node.startMs + node.durationMs]);
 }
 const MODEL_TYPES = new Set(['call', 'response', 'decision']);
 const TOOL_TYPES = new Set(['tool']);
@@ -311,8 +325,10 @@ function eventsMs(nodes, name, key) {
  * their own share, so the model and tools keep only their own work.
  */
 function traceTimeSplit(root) {
-    // A host's call is its own root: the tool span is the whole trace.
-    const spans = TOOL_TYPES.has(root.meta.type) ? [root, ...traceSpans(root.children)] : traceSpans(root.children);
+    // why: A host's call is its own root: the tool span is the whole trace.
+    const spans = TOOL_TYPES.has(root.meta.type)
+        ? [root, ...traceSpans(root.children)]
+        : traceSpans(root.children);
     const model = intervalsOf(spans, MODEL_TYPES);
     const tools = intervalsOf(spans, TOOL_TYPES);
     const toolNodes = spans.filter((node) => TOOL_TYPES.has(node.meta.type));
@@ -321,10 +337,12 @@ function traceTimeSplit(root) {
         return total + (typeof value === 'number' ? value : 0);
     }, 0);
     const modelMs = union(model);
-    const toolsMs = union(tools);
+    const covered = union([...model, ...tools]);
+    // why: A tool that runs an agent holds that agent's model calls: their time is the model's, not the tool's too.
+    const toolsMs = covered - modelMs;
     const toolGuard = Math.min(toolsMs, eventsMs(toolNodes, 'theorem.guardrail', 'duration_ms'));
     const toolHooks = Math.min(toolsMs - toolGuard, eventsMs(toolNodes, 'theorem.stage', 'hook_ms'));
-    const between = Math.max(0, root.durationMs - union([...model, ...tools]));
+    const between = Math.max(0, root.durationMs - covered);
     const turnGuard = Math.min(between, eventMs(root, 'theorem.guardrail', 'duration_ms'));
     const turnHooks = Math.min(between - turnGuard, eventMs(root, 'theorem.stage', 'hook_ms'));
     return {
@@ -344,7 +362,6 @@ export function traceLatency(root) {
     const spans = traceSpans([root]);
     const calls = spans.filter((node) => MODEL_TYPES.has(node.meta.type));
     const firstTextMs = secondsAttribute(root, 'theorem.turn.time_to_first_text');
-    // When the model first wrote, measured from the turn's start.
     const written = calls
         .map((node) => {
         const at = secondsAttribute(node, 'theorem.response.time_to_first_text');
@@ -379,14 +396,15 @@ export function traceLatency(root) {
             if (typeof event.attributes.runs === 'number')
                 streamChecksMs += took;
         }
-        // A call's stream checks carry their own time; the call's total adds only what they do not (a trace from before they did).
+        // why: A call's stream checks carry their own time; the call's total adds only what they do not (a trace from before they did).
         const stream = node.span.attributes['theorem.guardrail.stream_ms'];
         if (typeof stream === 'number')
             guardMs += Math.max(0, stream - streamChecksMs);
     }
     return {
         ...(firstTextMs !== undefined && { firstTextMs }),
-        ...(firstTextMs !== undefined && Number.isFinite(firstWritten) && { heldMs: Math.max(0, firstTextMs - firstWritten) }),
+        ...(firstTextMs !== undefined &&
+            Number.isFinite(firstWritten) && { heldMs: Math.max(0, firstTextMs - firstWritten) }),
         ...(writingMs > 0 && { tokensPerSecond: tokens / (writingMs / MS_PER_S) }),
         ...(checks > 0 && { guardrails: { checks, ms: guardMs, flagged } }),
     };
@@ -408,9 +426,15 @@ export function traceActivity(root, buckets) {
     const model = intervalsOf(spans, MODEL_TYPES);
     const tools = intervalsOf(spans, TOOL_TYPES);
     const width = Math.max(root.durationMs, 1) / buckets;
-    const share = (intervals, from, to) => Math.min(1, union(intervals.map(([a, b]) => [Math.max(a, from), Math.min(b, to)]).filter(([a, b]) => b > a)) / width);
+    const share = (intervals, from, to) => Math.min(1, union(intervals
+        .map(([a, b]) => [Math.max(a, from), Math.min(b, to)])
+        .filter(([a, b]) => b > a)) / width);
     return Array.from({ length: buckets + 1 }, (_, index) => {
         const from = root.startMs + index * width;
-        return { at: index * width, model: share(model, from, from + width), tools: share(tools, from, from + width) };
+        return {
+            at: index * width,
+            model: share(model, from, from + width),
+            tools: share(tools, from, from + width),
+        };
     });
 }

package/client/trace-view.d.ts

@@ -95,9 +95,9 @@ export interface TraceFilter {
     };
 }
 /**
- * The fields a search over `nodes` offers: type, status, duration and events,
+ * The fields a search over `nodes` offers: type, status, duration, and events,
  * then every attribute the spans recorded that compares as a value. Stored
- * text, JSON and structured values are reached by the text field.
+ * text, JSON, and structured values are reached by the text field.
  */
 export declare function traceSearchFields(nodes: readonly TraceNode[]): TraceSearchField[];
 /**