@theoremjs/react 0.0.0-stage → 0.3.0

package/client/trace-view.js

@@ -0,0 +1,293 @@
+import { inlineContent, TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceEventMeta, traceSpanMeta, } from '@theoremjs/agents';
+import { isRecord } from '@theoremjs/agents/kernel';
+/** A unix-nanosecond timestamp string as unix milliseconds. */
+export function nanosToMs(nanos) {
+    return Number(BigInt(nanos) / 1000n) / 1_000;
+}
+function spanId(traceId, id) {
+    return `${traceId}:${id}`;
+}
+function byStart(a, b) {
+    return a.startMs - b.startMs;
+}
+/**
+ * Every span of `records` as one tree. A span written twice keeps its later
+ * copy; a span whose parent has not arrived yet (a Live response before its
+ * session root) is a root until the parent does.
+ */
+export function traceTree(records) {
+    const nodes = new Map();
+    for (const record of records) {
+        for (const span of record.spans) {
+            const startMs = nanosToMs(span.startTimeUnixNano);
+            nodes.set(spanId(span.traceId, span.spanId), {
+                id: spanId(span.traceId, span.spanId),
+                span,
+                record,
+                meta: traceSpanMeta(span),
+                startMs,
+                durationMs: nanosToMs(span.endTimeUnixNano) - startMs,
+                children: [],
+            });
+        }
+    }
+    const roots = [];
+    for (const node of nodes.values()) {
+        const parent = node.span.parentSpanId ? nodes.get(spanId(node.span.traceId, node.span.parentSpanId)) : undefined;
+        (parent ? parent.children : roots).push(node);
+    }
+    for (const node of nodes.values())
+        node.children.sort(byStart);
+    return roots.sort(byStart);
+}
+/** Every node of `nodes`, depth first. */
+export function traceSpans(nodes) {
+    return nodes.flatMap((node) => [node, ...traceSpans(node.children)]);
+}
+const MODEL_CALL_TYPES = new Set(['call', 'response']);
+function numberAttribute(span, key) {
+    const value = span.attributes[key];
+    return typeof value === 'number' ? value : undefined;
+}
+function isEstimated(span, side) {
+    const estimated = span.attributes['theorem.usage.estimated'];
+    return Array.isArray(estimated) && estimated.includes(side);
+}
+function sum(calls, key, partial) {
+    const values = calls.map((span) => numberAttribute(span, key));
+    const reported = values.filter((value) => value !== undefined);
+    if (reported.length === 0)
+        return undefined;
+    return {
+        value: reported.reduce((total, value) => total + value, 0),
+        complete: reported.length === calls.length && !calls.some((span) => partial?.(span) === true),
+    };
+}
+function tokenSum(calls, key, side) {
+    const total = sum(calls, key);
+    return total && { ...total, estimated: calls.some((span) => isEstimated(span, side)) };
+}
+export function traceTotals(nodes) {
+    const spans = traceSpans(nodes);
+    const calls = spans.filter((node) => MODEL_CALL_TYPES.has(node.meta.type)).map((node) => node.span);
+    const start = Math.min(...spans.map((node) => node.startMs));
+    const end = Math.max(...spans.map((node) => node.startMs + node.durationMs));
+    const input = tokenSum(calls, 'gen_ai.usage.input_tokens', 'input');
+    const cached = sum(calls, 'gen_ai.usage.cache_read.input_tokens');
+    const output = tokenSum(calls, 'gen_ai.usage.output_tokens', 'output');
+    const cost = sum(calls, 'theorem.usage.cost_usd', (span) => span.attributes['theorem.usage.cost_partial'] === true);
+    return {
+        spans: spans.length,
+        errors: spans.filter((node) => node.span.status.code === 'ERROR').length,
+        durationMs: spans.length === 0 ? 0 : end - start,
+        calls: calls.length,
+        ...(input && { input }),
+        ...(cached && { cached }),
+        ...(output && { output }),
+        ...(cost && { cost }),
+    };
+}
+/** The operators each kind offers, by PowerSearch operator key. */
+export const TRACE_SEARCH_OPERATORS = {
+    options: ['isAnyOf', 'isNoneOf'],
+    number: ['greaterThan', 'lessThan'],
+    text: ['contains', 'notContains'],
+    flag: ['isTrue', 'isFalse'],
+};
+/** The field that searches any text a span holds: its name, its values, its stored text. */
+export const TRACE_TEXT_FIELD = 'text';
+/** Span fields beside the attributes. */
+const TYPE_FIELD = 'type';
+const STATUS_FIELD = 'status';
+const DURATION_FIELD = 'duration';
+const EVENTS_FIELD = 'events';
+const NUMBER_FORMATS = new Set(['number', 'tokens', 'seconds', 'milliseconds', 'usd']);
+const TEXT_FORMATS = new Set(['text', 'id', 'list']);
+function optionsOf(seen, known) {
+    return [...seen].sort().map((value) => {
+        const meta = known[value];
+        return meta ? { value, label: meta.label, doc: meta.doc } : { value, label: value };
+    });
+}
+function attributeValues(value) {
+    return Array.isArray(value) ? value : [value];
+}
+function attributeKind(meta, value) {
+    if (meta?.options)
+        return 'options';
+    const format = meta?.format;
+    if (format === 'boolean' || (!meta && typeof value === 'boolean'))
+        return 'flag';
+    if ((format && NUMBER_FORMATS.has(format)) || (!meta && typeof value === 'number'))
+        return 'number';
+    if ((format && TEXT_FORMATS.has(format)) || (!meta && typeof value === 'string'))
+        return 'text';
+    return undefined;
+}
+/**
+ * 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.
+ */
+export function traceSearchFields(nodes) {
+    const spans = traceSpans(nodes);
+    const types = new Set(spans.map((node) => node.meta.type));
+    const statuses = new Set(spans.map((node) => node.span.status.code));
+    const events = new Set(spans.flatMap((node) => node.span.events.map((event) => event.name)));
+    const attributes = new Map();
+    for (const node of spans) {
+        for (const [key, value] of Object.entries(node.span.attributes)) {
+            const kind = attributeKind(traceAttributeMeta(key), value);
+            if (!kind)
+                continue;
+            const field = attributes.get(key) ?? { kind, seen: new Set() };
+            if (kind === 'options')
+                for (const item of attributeValues(value))
+                    if (typeof item === 'string')
+                        field.seen.add(item);
+            attributes.set(key, field);
+        }
+    }
+    const eventLabels = Object.fromEntries([...events].flatMap((name) => {
+        const meta = traceEventMeta(name);
+        return meta ? [[name, meta]] : [];
+    }));
+    const fields = [
+        { key: TYPE_FIELD, ...TRACE_FIELDS.type, kind: 'options', options: optionsOf(types, TRACE_SPAN_TYPES) },
+        { key: STATUS_FIELD, ...TRACE_FIELDS.status, kind: 'options', options: optionsOf(statuses, TRACE_STATUS) },
+        { key: DURATION_FIELD, ...TRACE_FIELDS.duration, kind: 'number', format: 'milliseconds' },
+    ];
+    if (events.size > 0)
+        fields.push({ key: EVENTS_FIELD, ...TRACE_FIELDS.events, kind: 'options', options: optionsOf(events, eventLabels) });
+    for (const [key, { kind, seen }] of [...attributes].sort(([a], [b]) => a.localeCompare(b))) {
+        const meta = traceAttributeMeta(key);
+        fields.push({
+            key,
+            label: meta?.label ?? key,
+            doc: meta?.doc ?? key,
+            kind,
+            ...(meta && { group: TRACE_ATTRIBUTE_GROUPS[meta.group].label, format: meta.format }),
+            ...(kind === 'options' && { options: optionsOf(seen, meta?.options ?? {}) }),
+        });
+    }
+    return fields;
+}
+/** Every string a span holds: what it is, its name and status, and its attributes and events with stored text inlined. */
+function spanText(node) {
+    const strings = [node.meta.label, node.meta.subject ?? '', node.span.name, node.span.status.message ?? ''];
+    const collect = (value) => {
+        if (typeof value === 'string')
+            strings.push(value);
+        else if (Array.isArray(value))
+            for (const item of value)
+                collect(item);
+        else if (value && typeof value === 'object')
+            for (const nested of Object.values(value))
+                collect(nested);
+    };
+    collect(inlineContent(node.record, { attributes: node.span.attributes, events: node.span.events }));
+    for (const event of node.span.events)
+        strings.push(traceEventMeta(event.name)?.label ?? '');
+    return strings.join('\n').toLocaleLowerCase();
+}
+/** A field's values on one span: strings for options and text, a number, or a yes/no. */
+function fieldValues(node, field) {
+    switch (field) {
+        case TYPE_FIELD:
+            return [node.meta.type];
+        case STATUS_FIELD:
+            return [node.span.status.code];
+        case DURATION_FIELD:
+            return [node.durationMs];
+        case EVENTS_FIELD:
+            return node.span.events.map((event) => event.name);
+        default: {
+            const value = node.span.attributes[field];
+            if (value === undefined)
+                return [];
+            return attributeValues(value).filter((item) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean');
+        }
+    }
+}
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function matchesFilter(node, filter) {
+    const { value } = filter.value;
+    if (filter.field === TRACE_TEXT_FIELD) {
+        const found = typeof value === 'string' && spanText(node).includes(value.toLocaleLowerCase());
+        return filter.operator === 'notContains' ? !found : found;
+    }
+    const values = fieldValues(node, filter.field);
+    switch (filter.operator) {
+        case 'isAnyOf':
+            return values.some((item) => typeof item === 'string' && stringList(value).includes(item));
+        case 'isNoneOf':
+            return !values.some((item) => typeof item === 'string' && stringList(value).includes(item));
+        case 'greaterThan':
+            return typeof value === 'number' && values.some((item) => typeof item === 'number' && item > value);
+        case 'lessThan':
+            return typeof value === 'number' && values.some((item) => typeof item === 'number' && item < value);
+        case 'contains':
+        case 'notContains': {
+            const found = typeof value === 'string' && values.some((item) => String(item).toLocaleLowerCase().includes(value.toLocaleLowerCase()));
+            return filter.operator === 'contains' ? found : !found;
+        }
+        case 'isTrue':
+            return values.includes(true);
+        case 'isFalse':
+            return values.includes(false);
+        default:
+            return false;
+    }
+}
+/** Whether a span meets every filter. */
+function traceMatches(node, filters) {
+    return filters.every((filter) => matchesFilter(node, filter));
+}
+/**
+ * The tree cut to the spans that meet every filter, each kept under its
+ * ancestors so it reads in place; `matches` counts the spans that met them.
+ */
+export function filterTraceTree(nodes, filters) {
+    if (filters.length === 0)
+        return { nodes: [...nodes], matches: traceSpans(nodes).length };
+    let matches = 0;
+    const keep = (node) => {
+        const hit = traceMatches(node, filters);
+        if (hit)
+            matches += 1;
+        const children = node.children.flatMap((child) => keep(child) ?? []);
+        return hit || children.length > 0 ? { ...node, children } : undefined;
+    };
+    return { nodes: nodes.flatMap((node) => keep(node) ?? []), matches };
+}
+/** The ids of the spans under `nodes` that meet every filter; undefined when there are none to meet. */
+export function traceMatchIds(nodes, filters) {
+    if (filters.length === 0)
+        return undefined;
+    return new Set(traceSpans(nodes).filter((node) => traceMatches(node, filters)).map((node) => node.id));
+}
+/** Formats whose value is stored text or structure: shown on click, never inline. */
+const STORED_FORMATS = new Set(['content', 'json', 'messages', 'parts']);
+function isStringList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+/** An object, or a list of objects, as items to read by a catalog entry's fields. */
+function fieldItems(value) {
+    if (isRecord(value))
+        return [value];
+    return Array.isArray(value) && value.every(isRecord) ? value : undefined;
+}
+export function traceValueShape(meta, value) {
+    if (meta && STORED_FORMATS.has(meta.format))
+        return { kind: 'stored' };
+    if (typeof value === 'string')
+        return { kind: 'text', value };
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return { kind: 'scalar', value };
+    if (isStringList(value))
+        return { kind: 'list', value };
+    const items = meta?.fields ? fieldItems(value) : undefined;
+    return meta?.fields && items ? { kind: 'fields', fields: meta.fields, items } : { kind: 'stored' };
+}

package/client/transcript-groups.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Group flat transcript blocks into user / assistant turns for message-shell UI.
+ * Tools, reasoning, and mid-turn narration stay inside the assistant turn
+ * (Seance-style), not as separate messages.
+ */
+import type { TranscriptBlock } from '@theoremjs/agents/interface';
+export type TranscriptTurnGroup = {
+    kind: 'user';
+    key: string;
+    blocks: TranscriptBlock[];
+} | {
+    kind: 'assistant';
+    key: string;
+    blocks: TranscriptBlock[];
+    /** The reply's work and when it stopped, from its latest stamped `turn-done`. */
+    workedMs?: number;
+    endedAt?: number;
+};
+export type TraceItem = {
+    kind: 'reasoning';
+    id: string;
+    text: string;
+} | {
+    kind: 'narration';
+    id: string;
+    text: string;
+} | {
+    kind: 'tool';
+    id: string;
+    block: Extract<TranscriptBlock, {
+        kind: 'tool';
+    }>;
+};
+export type ComposedAssistantTurn = {
+    /** Ordered reasoning / narration / tools for the disclosure. */
+    trace: TraceItem[];
+    /** Gate tools rendered as interactive cards outside the collapsed list. */
+    gatedTools: Extract<TranscriptBlock, {
+        kind: 'tool';
+    }>[];
+    /** Final answer segments (text / media / structured / grounding / evidence / error). */
+    body: TranscriptBlock[];
+    /** True when the disclosure control should appear. */
+    hasTrace: boolean;
+};
+export declare function groupTranscriptBlocks(blocks: readonly TranscriptBlock[]): TranscriptTurnGroup[];
+/** A reply's text to copy; a failure is the message's status, not part of the reply. */
+export declare function assistantTurnCopyText(blocks: readonly TranscriptBlock[]): string;
+/** A turn's work, for the status line: running, or done (with its duration when known). */
+export type WorkStatus = {
+    phase: 'working' | 'worked';
+    elapsedMs?: number;
+};
+/** Working while streaming; worked after, when it has a duration or a trace; else nothing to show. */
+export declare function workStatus(args: {
+    streaming: boolean;
+    hasTrace: boolean;
+    elapsedMs?: number;
+}): WorkStatus | null;
+/**
+ * Split an assistant turn into Seance-style trace + final body.
+ *
+ * - `thought` → always reasoning in the trace
+ * - non-gate `tool` → tool item in the trace
+ * - first gate `tool` → interactive card outside the collapsed list; later gates → trace
+ * - `text` before/between tools → narration; text and answer kinds after the
+ *   latest tool → body (while streaming too, so the answer streams formatted)
+ * - No tools: thoughts still go to trace; remaining kinds → body
+ */
+export declare function composeAssistantTurn(blocks: readonly TranscriptBlock[]): ComposedAssistantTurn;
+/** The trailing user group while its reply has not started streaming back. */
+export declare function pendingPromptOf(groups: readonly TranscriptTurnGroup[]): TranscriptTurnGroup | undefined;
+export type AssistantTurnTiming = {
+    /**
+     * Keyed by its prompt, not its blocks: the reply stays mounted from the
+     * "Working…" placeholder through streaming and commit (which re-keys blocks).
+     */
+    key: string;
+    live: boolean;
+    /** While live: when the reply started, its approval waits skipped. */
+    startedAt?: number;
+    /** Once stopped: how long it worked and when it stopped, as its blocks record. */
+    workedMs?: number;
+    endedAt?: number;
+};
+/**
+ * A turn sent in this session, keyed by its prompt: when it last stopped, and
+ * how long it sat paused on approvals, which doesn't count as work.
+ */
+export type TurnSpan = {
+    endedAt?: number;
+    pausedMs: number;
+};
+/**
+ * The key of the assistant group at `index`: its prompt's, so the reply keeps
+ * one identity from "Working…" through commit. Block ids restart every reply.
+ */
+export declare function replyKey(groups: readonly TranscriptTurnGroup[], index: number): string;
+/** The key of the reply to `prompt`, before and after it streams. */
+export declare function promptReplyKey(prompt: TranscriptTurnGroup): string;
+/**
+ * Key and timing for the assistant group at `index`. A stopped reply reads its
+ * time from its blocks; a live one counts from its span in this session.
+ */
+export declare function assistantTurnTiming(args: {
+    groups: readonly TranscriptTurnGroup[];
+    index: number;
+    streaming: boolean;
+    timeOf: (key: string) => number;
+    spans: ReadonlyMap<string, TurnSpan>;
+}): AssistantTurnTiming;
+export declare function toolCallLabel(tool: Extract<TranscriptBlock, {
+    kind: 'tool';
+}>['tool']): string;

package/client/transcript-groups.js

@@ -0,0 +1,167 @@
+/**
+ * Group flat transcript blocks into user / assistant turns for message-shell UI.
+ * Tools, reasoning, and mid-turn narration stay inside the assistant turn
+ * (Seance-style), not as separate messages.
+ */
+import { humanize } from "./shaped-data.js";
+const USER_KINDS = new Set(['user-text', 'user-attachment', 'user-voice']);
+function isUserTranscriptBlock(block) {
+    return USER_KINDS.has(block.kind);
+}
+/** Hide bookkeeping from the message body. */
+function isHiddenTranscriptBlock(block) {
+    return block.kind === 'turn-done';
+}
+export function groupTranscriptBlocks(blocks) {
+    const groups = [];
+    for (const block of blocks) {
+        if (block.kind === 'turn-done') {
+            const last = groups.at(-1);
+            if (last?.kind === 'assistant' && block.workedMs !== undefined) {
+                last.workedMs = block.workedMs;
+                last.endedAt = block.endedAt;
+            }
+        }
+        if (isHiddenTranscriptBlock(block))
+            continue;
+        const isUser = isUserTranscriptBlock(block);
+        const last = groups.at(-1);
+        if (last && last.kind === (isUser ? 'user' : 'assistant')) {
+            last.blocks.push(block);
+            continue;
+        }
+        groups.push({
+            kind: isUser ? 'user' : 'assistant',
+            key: block.id,
+            blocks: [block],
+        });
+    }
+    return groups;
+}
+/** A reply's text to copy; a failure is the message's status, not part of the reply. */
+export function assistantTurnCopyText(blocks) {
+    return blocks
+        .filter((block) => block.kind === 'text')
+        .map((block) => block.text)
+        .filter(Boolean)
+        .join('\n\n');
+}
+/** Working while streaming; worked after, when it has a duration or a trace; else nothing to show. */
+export function workStatus(args) {
+    const elapsed = args.elapsedMs !== undefined ? { elapsedMs: args.elapsedMs } : {};
+    if (args.streaming)
+        return { phase: 'working', ...elapsed };
+    if (args.elapsedMs !== undefined && args.elapsedMs > 0)
+        return { phase: 'worked', elapsedMs: args.elapsedMs };
+    return args.hasTrace ? { phase: 'worked' } : null;
+}
+function isGatedTool(block) {
+    return block.kind === 'tool' && block.tool.state?.phase === 'gate';
+}
+function lastToolIndexOf(blocks) {
+    for (let i = blocks.length - 1; i >= 0; i -= 1) {
+        if (blocks[i]?.kind === 'tool')
+            return i;
+    }
+    return -1;
+}
+function pushTextBlock(block, args, trace, body) {
+    // Text before a tool call is narration; text after the latest one is the
+    // answer, streamed in place. If another tool call follows, it becomes narration.
+    if (args.hasTools && args.index < args.lastToolIndex) {
+        if (block.text.trim()) {
+            trace.push({ kind: 'narration', id: block.id, text: block.text });
+        }
+        return;
+    }
+    body.push(block);
+}
+function classifyNonGateBlock(block, args, trace, body) {
+    if (block.kind === 'thought') {
+        if (block.text.trim()) {
+            trace.push({ kind: 'reasoning', id: block.id, text: block.text });
+        }
+        return;
+    }
+    if (block.kind === 'tool') {
+        trace.push({ kind: 'tool', id: block.id, block });
+        return;
+    }
+    if (block.kind === 'text') {
+        pushTextBlock(block, args, trace, body);
+        return;
+    }
+    body.push(block);
+}
+/**
+ * Split an assistant turn into Seance-style trace + final body.
+ *
+ * - `thought` → always reasoning in the trace
+ * - non-gate `tool` → tool item in the trace
+ * - first gate `tool` → interactive card outside the collapsed list; later gates → trace
+ * - `text` before/between tools → narration; text and answer kinds after the
+ *   latest tool → body (while streaming too, so the answer streams formatted)
+ * - No tools: thoughts still go to trace; remaining kinds → body
+ */
+export function composeAssistantTurn(blocks) {
+    const visible = blocks.filter((block) => !isHiddenTranscriptBlock(block));
+    // One card at a time: the gate answered next. The step's later gates wait in the trace.
+    const nextGate = visible.find(isGatedTool);
+    const gatedTools = nextGate ? [nextGate] : [];
+    const nonGate = visible.filter((block) => block !== nextGate);
+    const lastToolIndex = lastToolIndexOf(nonGate);
+    const hasTools = lastToolIndex >= 0;
+    const trace = [];
+    const body = [];
+    for (const [index, block] of nonGate.entries()) {
+        classifyNonGateBlock(block, { hasTools, index, lastToolIndex }, trace, body);
+    }
+    return {
+        trace,
+        gatedTools,
+        body,
+        hasTrace: trace.length > 0,
+    };
+}
+/** The trailing user group while its reply has not started streaming back. */
+export function pendingPromptOf(groups) {
+    const last = groups.at(-1);
+    return last?.kind === 'user' ? last : undefined;
+}
+/**
+ * The key of the assistant group at `index`: its prompt's, so the reply keeps
+ * one identity from "Working…" through commit. Block ids restart every reply.
+ */
+export function replyKey(groups, index) {
+    const prompt = groups[index - 1];
+    return prompt?.kind === 'user' ? promptReplyKey(prompt) : (groups[index]?.key ?? String(index));
+}
+/** The key of the reply to `prompt`, before and after it streams. */
+export function promptReplyKey(prompt) {
+    return `${prompt.key}:reply`;
+}
+/**
+ * Key and timing for the assistant group at `index`. A stopped reply reads its
+ * time from its blocks; a live one counts from its span in this session.
+ */
+export function assistantTurnTiming(args) {
+    const key = replyKey(args.groups, args.index);
+    const live = args.streaming && args.index === args.groups.length - 1;
+    const group = args.groups[args.index];
+    if (!live) {
+        return group?.kind === 'assistant' && group.workedMs !== undefined
+            ? { key, live, workedMs: group.workedMs, endedAt: group.endedAt }
+            : { key, live };
+    }
+    const prompt = args.groups[args.index - 1];
+    const span = prompt?.kind === 'user' ? args.spans.get(prompt.key) : undefined;
+    if (!prompt || !span)
+        return { key, live };
+    return { key, live, startedAt: args.timeOf(prompt.key) + span.pausedMs };
+}
+export function toolCallLabel(tool) {
+    const phase = tool.state?.phase;
+    if (phase === 'error' || phase === 'cancel')
+        return humanize(tool.name);
+    return (phase === 'complete' ? tool.activityPast : tool.activity) ?? humanize(tool.name);
+}

package/client/transcript-scroll.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Transcript scroll geometry — pure helpers.
+ */
+export declare function resolveScrollToBottomScrollTop(args: {
+    scrollHeight: number;
+    clientHeight: number;
+}): number;

package/client/transcript-scroll.js

@@ -0,0 +1,6 @@
+/**
+ * Transcript scroll geometry — pure helpers.
+ */
+export function resolveScrollToBottomScrollTop(args) {
+    return Math.max(0, args.scrollHeight - args.clientHeight);
+}