@theoremjs/react 0.0.0-stage → 0.3.0

package/client/tool-result.js

@@ -0,0 +1,275 @@
+/**
+ * What a tool's result leads with, above its data: the figures that answer it,
+ * the series worth a chart, and the images it links. Plain decisions over the
+ * value alone, so any tool's output gets them without a schema saying so; the
+ * data itself still reads in full below, drawn by `ShapedData`.
+ *
+ * @module
+ */
+import { columnStore, fieldLabel, humanize, ISO_DATE, isPlain, isRow, printableUnit, shownEntries, storeRows, titleKey, unitsOf, unpacked, } from "./shaped-data.js";
+const MAX_FIGURES = 4;
+const MAX_CHARTS = 3;
+/** Series one time chart overlays, when they share a unit. */
+const MAX_SERIES = 3;
+/** Bars a category chart ranks. */
+const MAX_BARS = 8;
+const MAX_IMAGES = 6;
+/** Rows a list needs before it reads as a chart. */
+const MIN_POINTS = 3;
+/** Levels searched for charts and images. */
+const MAX_SEARCH_DEPTH = 3;
+/** Numbers that locate or name a thing rather than measure it. */
+const NOT_A_MEASURE = /(^|_)(id|ids|lat|lon|lng|latitude|longitude|offset|interval|index|rank|order)$|Id$|^(generationtime_ms|utc_offset_seconds)$/i;
+const IMAGE_PATH = /\.(png|jpe?g|gif|webp|avif|svg)$/i;
+function isImageUrl(text) {
+    if (/\s/.test(text))
+        return false;
+    try {
+        const url = new URL(text);
+        return (url.protocol === 'http:' || url.protocol === 'https:') && IMAGE_PATH.test(url.pathname);
+    }
+    catch {
+        return false;
+    }
+}
+function isMeasure(key) {
+    return !NOT_A_MEASURE.test(key);
+}
+/** A code-like key (`USD`, `EUR`) keeps its case; others read as words. */
+function keyLabel(key) {
+    return /^[A-Z][A-Z0-9]{1,5}$/.test(key) ? key : humanize(key);
+}
+/** A field's reading, unless its units say it's a code (`wmo code`, `iso8601`, a flag with no unit). */
+function measured(key, units) {
+    if (!isMeasure(key))
+        return undefined;
+    if (units && key in units && printableUnit(units[key]) === undefined)
+        return undefined;
+    const { label, unit } = fieldLabel(key, units);
+    return { label: keyLabel(key) === key ? key : label, unit };
+}
+function figuresOf(row, units) {
+    const figures = [];
+    for (const [key, value] of shownEntries(row)) {
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            continue;
+        const reading = measured(key, 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);
+}
+/**
+ * The figures: the numbers of the first nested object of plain fields (the
+ * `current` reading beside a forecast, a conversion's `rates`), else the
+ * value's own top-level numbers. Beside a nested reading, top-level numbers
+ * are usually the request echoed back.
+ */
+function leadFigures(value) {
+    if (!isRow(value))
+        return [];
+    for (const [key, entry] of shownEntries(value)) {
+        const inner = unpacked(entry);
+        if (!isRow(inner) || columnStore(inner))
+            continue;
+        const plain = Object.values(inner);
+        if (plain.length === 0 || !plain.every(isPlain))
+            continue;
+        const figures = figuresOf(inner, unitsOf(value, key));
+        if (figures.length > 0)
+            return figures;
+    }
+    return figuresOf(value, undefined);
+}
+function distinct(rows, key) {
+    return new Set(rows.map((row) => row[key])).size;
+}
+/** 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);
+    return keys.flatMap((key) => {
+        const reading = measured(key, units);
+        return reading ? [{ key, ...reading }] : [];
+    });
+}
+/** The field every row holds as an ISO date, if one does. */
+function dateKey(rows) {
+    const [first] = rows;
+    if (!first)
+        return undefined;
+    return Object.keys(first).find((key) => rows.every((row) => typeof row[key] === 'string' && ISO_DATE.test(row[key])));
+}
+/** Series that share leading words ("Temperature 2m max", "… min") are titled by them, and each keeps the rest. */
+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]))
+        shared++;
+    if (!shared)
+        return undefined;
+    return {
+        title: first.slice(0, shared).join(' '),
+        series: series.map((one, at) => {
+            const rest = (words[at] ?? []).slice(shared).join(' ');
+            return { ...one, label: rest.charAt(0).toUpperCase() + rest.slice(1) };
+        }),
+    };
+}
+/** Series over time, one chart per unit they share, each overlaying up to MAX_SERIES. */
+function timeCharts(path, title, rows, x, units) {
+    const byUnit = new Map();
+    for (const series of numericSeries(rows, x, units)) {
+        const group = byUnit.get(series.unit ?? '') ?? [];
+        group.push(series);
+        byUnit.set(series.unit ?? '', group);
+    }
+    return [...byUnit.values()].map((group) => {
+        const shown = group.slice(0, MAX_SERIES);
+        const shared = shown.length > 1 ? sharedWords(shown) : undefined;
+        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(' · '))),
+            x,
+            series: shared?.series ?? shown,
+            rows,
+        };
+    });
+}
+/** The field that tells rows apart: their title field, or else the shortest text field that differs on every row ("Paris" ×4 → city, suburb, town). */
+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'))
+        return undefined;
+    if (distinct(rows, title) === rows.length)
+        return title;
+    const length = (key) => rows.reduce((sum, row) => sum + String(row[key]).length, 0);
+    const [unique] = Object.keys(first)
+        .filter((key) => rows.every((row) => typeof row[key] === 'string') && distinct(rows, key) === rows.length)
+        .sort((a, b) => length(a) - length(b));
+    return unique ?? title;
+}
+/** Rows named by a title field, ranked by each series that varies, most varied first. */
+function categoryCharts(path, title, rows, units) {
+    const label = labelKey(rows);
+    if (!label)
+        return [];
+    return numericSeries(rows, label, units)
+        .sort((a, b) => distinct(rows, b.key) - distinct(rows, a.key))
+        .map((series) => ({
+        kind: 'category',
+        key: `${path}:${series.key}`,
+        title: title ? `${title} · ${series.label}` : series.label,
+        series,
+        rows: rows
+            .filter((row) => typeof row[series.key] === 'number')
+            .map((row) => ({ label: String(row[label]), value: row[series.key] }))
+            .sort((a, b) => b.value - a.value)
+            .slice(0, MAX_BARS),
+    }));
+}
+function rowsCharts(path, title, rows, units) {
+    if (rows.length < MIN_POINTS)
+        return [];
+    const x = dateKey(rows);
+    return x ? timeCharts(path, title, rows, x, units) : categoryCharts(path, title, rows, units);
+}
+/** Charts anywhere in the value, to MAX_SEARCH_DEPTH: lists of rows, column stores, and objects of numbers. */
+function chartsIn(value, path, title, units, depth) {
+    if (depth > MAX_SEARCH_DEPTH)
+        return [];
+    if (Array.isArray(value)) {
+        const rows = value.map(unpacked);
+        return rows.every(isRow) ? rowsCharts(path, title, rows, units) : [];
+    }
+    if (!isRow(value))
+        return [];
+    const store = columnStore(value);
+    if (store)
+        return rowsCharts(path, title, storeRows(value, store), units);
+    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 [
+            {
+                kind: 'category',
+                key: path,
+                title,
+                series: { key: 'value', label: title },
+                rows: rows.sort((a, b) => b.value - a.value).slice(0, MAX_BARS),
+            },
+        ];
+    }
+    return entries.flatMap(([key, entry]) => chartsIn(unpacked(entry), path ? `${path}.${key}` : key, depth === 0 ? humanize(key) : `${title} › ${humanize(key)}`, unitsOf(value, key), depth + 1));
+}
+/** Image URLs anywhere in the value, first found first, each once. */
+function imagesIn(value, key, depth, found) {
+    if (found.size >= MAX_IMAGES || depth > MAX_SEARCH_DEPTH + 1)
+        return;
+    const inner = unpacked(value);
+    if (typeof inner === 'string') {
+        if (isImageUrl(inner) && !found.has(inner))
+            found.set(inner, { src: inner, alt: humanize(key || 'image') });
+        return;
+    }
+    if (Array.isArray(inner)) {
+        for (const item of inner)
+            imagesIn(item, key, depth + 1, found);
+        return;
+    }
+    if (isRow(inner))
+        for (const [child, entry] of Object.entries(inner))
+            imagesIn(entry, child, depth + 1, found);
+}
+/** What a tool's output leads with. Empty when nothing stands out: the data alone reads best. */
+export function layoutResult(output) {
+    const value = unpacked(output);
+    const images = new Map();
+    imagesIn(value, '', 0, images);
+    return {
+        figures: leadFigures(value),
+        charts: chartsIn(value, '', '', undefined, 0).slice(0, MAX_CHARTS),
+        images: [...images.values()],
+    };
+}
+function mediaSrc(part) {
+    return part.mimeType && part.data ? `data:${part.mimeType};base64,${part.data}` : undefined;
+}
+/** The images and audio a call returned, each with its bytes; parts without them are left out. */
+export function returnedMedia(layout, parts, imageAlt) {
+    const sourced = parts.flatMap((part) => {
+        const src = mediaSrc(part);
+        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 } : {}) })),
+    };
+}
+/** 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;
+}
+const DAY_MS = 86_400_000;
+/** Days a time chart names by weekday; longer runs read as dates. */
+const MAX_WEEKDAYS = 10;
+/**
+ * How a time chart's dates read, on its axis and in its tooltip: hours within
+ * a day, else dates. A bare date is a calendar day, parsed at UTC midnight, so
+ * it reads in UTC and doesn't slip a day.
+ */
+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: 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

@@ -0,0 +1,33 @@
+import type { ToolGate } from '@theoremjs/agents/kernel';
+export type ToolDecisionAction = 'allow' | 'deny';
+export type ToolGateResolution = {
+    action: ToolDecisionAction;
+}
+/** Signed in: `secret` is a key the user typed; after an OAuth callback there is none. */
+ | {
+    action: 'auth';
+    secret?: string;
+};
+/** 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'];
+};
+/**
+ * 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,
+ * by the rule the host applies (`sessionPermissionsAfterApproval`).
+ */
+export type GatedToolContinue = {
+    decision: 'deny';
+} | {
+    decision: 'approve';
+    secret?: string;
+    sessionPermissions: string[];
+};
+export declare function continueGatedToolInvocation(args: {
+    toolName: string;
+    gate: Pick<ToolGate, 'permission'>;
+    sessionPermissions: readonly string[];
+    resolution: ToolGateResolution;
+}): GatedToolContinue;

package/client/tool-resume.js

@@ -0,0 +1,11 @@
+import { sessionPermissionsAfterApproval } from '@theoremjs/agents/kernel';
+export function continueGatedToolInvocation(args) {
+    if (args.resolution.action === 'deny')
+        return { decision: 'deny' };
+    const { resolution } = args;
+    return {
+        decision: 'approve',
+        ...(resolution.action === 'auth' && resolution.secret !== undefined ? { secret: resolution.secret } : {}),
+        sessionPermissions: sessionPermissionsAfterApproval(args.sessionPermissions, args.toolName, args.gate.permission),
+    };
+}

package/client/trace-feed.d.ts

@@ -0,0 +1,13 @@
+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.
+ */
+export interface TraceFeed {
+    push(record: TraceRecord): void;
+    /** The records so far; a new array after every push. */
+    records(): readonly TraceRecord[];
+    /** Called after every push; returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+}
+export declare function createTraceFeed(): TraceFeed;

package/client/trace-feed.js

@@ -0,0 +1,18 @@
+export function createTraceFeed() {
+    let records = [];
+    const listeners = new Set();
+    return {
+        push(record) {
+            records = [...records, record];
+            for (const listener of listeners)
+                listener();
+        },
+        records: () => records,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/client/trace-story.d.ts

@@ -0,0 +1,163 @@
+import { type TraceNode, type TraceTotals } from './trace-view.ts';
+/**
+ * The trace panel's story of a turn: who acted, in what order, and where the
+ * time went, read from the span tree. The words still come from the trace
+ * catalog; this only decides what a person reads first.
+ *
+ * @module
+ */
+/** Who acted in a step: sets its colour and icon. */
+export type TraceActor = 'user' | 'model' | 'tool' | 'host' | 'theorem' | 'error';
+/** One root of the tree (a turn, a Live session, a host span) with its totals and where its time went. */
+export interface TraceTurn {
+    node: TraceNode;
+    totals: TraceTotals;
+    split: TraceTimeSplit;
+    /** The turn itself ended in an error (a step that failed and was recovered from does not count). */
+    failed: boolean;
+}
+export declare function traceTurns(tree: readonly TraceNode[]): TraceTurn[];
+/** A host's trace: each root is one tool call, not a conversation's turn. */
+export declare function isCallTrace(turns: readonly TraceTurn[]): boolean;
+/** A row of the whole-trace list: who it's by, what names it, and how it ended. */
+export type TraceTurnRow = {
+    actor: TraceActor;
+    title?: string;
+    outcome?: TraceOutcome;
+    answered?: string;
+};
+/** A turn named by what the person asked, a host's call by its tool; a failure by its outcome, else the answer. */
+export declare function traceTurnRow(turn: TraceTurn, isCall: boolean): TraceTurnRow;
+export declare function traceActor(node: TraceNode): TraceActor;
+/** One line of the story. `offsetMs` is from the turn's start. */
+export type TraceStep = {
+    kind: 'ask';
+    id: string;
+    node: TraceNode;
+    offsetMs: number;
+    text: string;
+} | {
+    kind: 'span';
+    id: string;
+    node: TraceNode;
+    offsetMs: number;
+    nested: boolean;
+    requested: number;
+} | {
+    kind: 'event';
+    id: string;
+    node: TraceNode;
+    offsetMs: number;
+    label: string;
+    detail: readonly string[];
+    doc: string;
+} | {
+    kind: 'answer';
+    id: string;
+    node: TraceNode;
+    offsetMs: number;
+    text?: string;
+};
+/** 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
+ * 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.
+ */
+export declare function traceStory(root: TraceNode): TraceStep[];
+/** A tool call's arguments as `[key, value]` pairs of plain values, for a one-line summary. */
+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. */
+export interface TraceOutcome {
+    label: string;
+    doc?: string;
+    /** The tool's own failure code, shown as is. */
+    code?: string;
+    tone: 'error' | 'warning';
+}
+export declare function traceOutcome(node: TraceNode): TraceOutcome | undefined;
+/** One rule a guardrail check matched, worded by the catalog. */
+export interface TraceGuardrailHit {
+    rule: string;
+    /** What the rule caught, in words; the id itself for a rule the catalog does not know, such as a host's own. */
+    ruleLabel: string;
+    /** Why the rule exists and what it does. */
+    ruleDoc?: string;
+    severity: string;
+    /** The severity's label, when the catalog knows it. */
+    severityLabel: string;
+    /** The matched text, kept only when the profile records match previews. */
+    match?: string;
+}
+/** One guardrail check: what it checked, what it did and why, and how long it took when timed. */
+export interface TraceGuardrailCheck {
+    id: string;
+    /** The span it happened on: the turn, or the tool whose call or result it checked. */
+    node: TraceNode;
+    offsetMs: number;
+    stage: string;
+    stageLabel: string;
+    /** Which timed check ran, in words, when the check was timed. */
+    checkLabel?: string;
+    action: string;
+    actionLabel: string;
+    actionDoc?: string;
+    durationMs?: number;
+    hits: readonly TraceGuardrailHit[];
+    /** The tool the checked text came from. */
+    tool?: string;
+    /** The guardrail's own reason, for the builder. */
+    reason?: string;
+}
+/** Every guardrail check the turn recorded, in the order they ran: the passes as well as what they caught. */
+export declare function traceGuardrails(root: TraceNode): TraceGuardrailCheck[];
+/**
+ * Where a turn's time went: waiting on the model, running tools, guardrail
+ * checks, host hooks, and everything else. Guardrail checks during a stream
+ * come out of the model's time; the rest, like the hooks, out of the time
+ * between calls.
+ */
+export interface TraceTimeSplit {
+    model: number;
+    tools: number;
+    guardrails: number;
+    hooks: number;
+    other: number;
+}
+/**
+ * How quickly a turn answered and what its guardrails cost. Each value is
+ * absent when the trace did not record it.
+ */
+export interface TraceLatency {
+    /** From the turn's start to the first text the person saw. */
+    firstTextMs?: number;
+    /** Of that, the time guardrails held finished text back before showing it. */
+    heldMs?: number;
+    /** Output tokens per second of writing, from each call's first text to its end. */
+    tokensPerSecond?: number;
+    /** Guardrail checks the trace recorded, how long they took, and how many were not a plain pass. */
+    guardrails?: {
+        checks: number;
+        ms: number;
+        flagged: number;
+    };
+}
+export declare function traceLatency(root: TraceNode): TraceLatency;
+/** One row of the timeline: a span, how deep it sits, and its start and end from the turn's start. */
+export interface TraceBar {
+    node: TraceNode;
+    depth: number;
+    from: number;
+    to: number;
+}
+export declare function traceBars(root: TraceNode): TraceBar[];
+/** How busy the model and the tools were across the turn, in `buckets` equal slices (0 to 1 each). */
+export declare function traceActivity(root: TraceNode, buckets: number): {
+    at: number;
+    model: number;
+    tools: number;
+}[];