@theoremjs/react 0.3.0 → 0.3.1

package/client/trace-view.js

@@ -33,7 +33,9 @@ export function traceTree(records) {
     }
     const roots = [];
     for (const node of nodes.values()) {
-        const parent = node.span.parentSpanId ? nodes.get(spanId(node.span.traceId, node.span.parentSpanId)) : undefined;
+        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())
@@ -69,7 +71,9 @@ function tokenSum(calls, key, 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 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');
@@ -101,7 +105,13 @@ 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 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) => {
@@ -125,9 +135,9 @@ function attributeKind(meta, value) {
     return undefined;
 }
 /**
- * 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 function traceSearchFields(nodes) {
     const spans = traceSpans(nodes);
@@ -153,12 +163,27 @@ export function traceSearchFields(nodes) {
         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: 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) });
+        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({
@@ -172,9 +197,14 @@ export function traceSearchFields(nodes) {
     }
     return fields;
 }
-/** Every string a span holds: what it is, its name and status, and its attributes and events with stored text inlined. */
+/** 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 strings = [
+        node.meta.label,
+        node.meta.subject ?? '',
+        node.span.name,
+        node.span.status.message ?? '',
+    ];
     const collect = (value) => {
         if (typeof value === 'string')
             strings.push(value);
@@ -225,12 +255,13 @@ function matchesFilter(node, filter) {
         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);
+            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);
+            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()));
+            const found = typeof value === 'string' &&
+                values.some((item) => String(item).toLocaleLowerCase().includes(value.toLocaleLowerCase()));
             return filter.operator === 'contains' ? found : !found;
         }
         case 'isTrue':
@@ -266,10 +297,17 @@ export function filterTraceTree(nodes, filters) {
 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));
+    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']);
+const STORED_FORMATS = new Set([
+    'content',
+    'json',
+    'messages',
+    'parts',
+]);
 function isStringList(value) {
     return Array.isArray(value) && value.every((item) => typeof item === 'string');
 }
@@ -289,5 +327,7 @@ export function traceValueShape(meta, 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' };
+    return meta?.fields && items
+        ? { kind: 'fields', fields: meta.fields, items }
+        : { kind: 'stored' };
 }

package/client/transcript-groups.d.ts

@@ -3,11 +3,22 @@
  * Tools, reasoning, and mid-turn narration stay inside the assistant turn
  * (Seance-style), not as separate messages.
  */
-import type { TranscriptBlock } from '@theoremjs/agents/interface';
+import type { TurnStop } from '@theoremjs/agents';
+import { type TranscriptBlock } from '@theoremjs/agents/interface';
+/** What a reply or a called agent used: its tokens, and its cost when the provider gave one. */
+export type TurnUsage = {
+    total: number;
+    cost?: {
+        usd: number;
+        partial?: true;
+    };
+};
 export type TranscriptTurnGroup = {
     kind: 'user';
     key: string;
     blocks: TranscriptBlock[];
+    /** How its turn stopped short before any reply. A message with a stop is closed. */
+    stop?: TurnStop;
 } | {
     kind: 'assistant';
     key: string;
@@ -15,6 +26,10 @@ export type TranscriptTurnGroup = {
     /** The reply's work and when it stopped, from its latest stamped `turn-done`. */
     workedMs?: number;
     endedAt?: number;
+    /** What the reply used, summed over its runs: a reply resumed at a gate has several. */
+    usage?: TurnUsage;
+    /** How its latest run stopped. */
+    stop?: TurnStop;
 };
 export type TraceItem = {
     kind: 'reasoning';
@@ -43,7 +58,12 @@ export type ComposedAssistantTurn = {
     /** True when the disclosure control should appear. */
     hasTrace: boolean;
 };
-export declare function groupTranscriptBlocks(blocks: readonly TranscriptBlock[]): TranscriptTurnGroup[];
+/**
+ * Blocks as turns: neighbours from the same side share one, unless a block is
+ * in `breaks`, which always starts its own. A message whose turn stopped short
+ * is closed: the next message starts its own turn.
+ */
+export declare function groupTranscriptBlocks(blocks: readonly TranscriptBlock[], breaks?: ReadonlySet<string>): 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). */
@@ -98,6 +118,12 @@ export type TurnSpan = {
 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;
+/**
+ * When the prompt at `index` was sent. Once its reply has stopped, its blocks
+ * date it (less any approval waits), so a restored chat keeps its times; until
+ * then, when this session first showed it.
+ */
+export declare function promptTime(groups: readonly TranscriptTurnGroup[], index: number, timeOf: (key: string) => number): number;
 /**
  * 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.

package/client/transcript-groups.js

@@ -3,7 +3,20 @@
  * Tools, reasoning, and mid-turn narration stay inside the assistant turn
  * (Seance-style), not as separate messages.
  */
+import { WORDED_STOP_KINDS } from '@theoremjs/agents/interface';
 import { humanize } from "./shaped-data.js";
+/** `used` with `more` added. A cost only one side reported is partial. */
+function addUsage(used, more) {
+    if (!used)
+        return more;
+    const total = used.total + more.total;
+    if (!used.cost && !more.cost)
+        return { total };
+    const usd = (used.cost?.usd ?? 0) + (more.cost?.usd ?? 0);
+    const partial = !used.cost || !more.cost || used.cost.partial || more.cost.partial;
+    return { total, cost: { usd, ...(partial ? { partial: true } : {}) } };
+}
+const WORDED = new Set(WORDED_STOP_KINDS);
 const USER_KINDS = new Set(['user-text', 'user-attachment', 'user-voice']);
 function isUserTranscriptBlock(block) {
     return USER_KINDS.has(block.kind);
@@ -12,21 +25,45 @@ function isUserTranscriptBlock(block) {
 function isHiddenTranscriptBlock(block) {
     return block.kind === 'turn-done';
 }
-export function groupTranscriptBlocks(blocks) {
+/** A `turn-done` on the turn it closes: a reply's work and usage, or a message's stop. */
+function closeTurn(last, done) {
+    if (last?.kind === 'user') {
+        if (done.stop && WORDED.has(done.stop.kind))
+            last.stop = done.stop;
+        return;
+    }
+    if (!last)
+        return;
+    if (done.workedMs !== undefined) {
+        last.workedMs = done.workedMs;
+        last.endedAt = done.endedAt;
+    }
+    if (done.tokens)
+        last.usage = addUsage(last.usage, done.tokens);
+    if (done.stop)
+        last.stop = done.stop;
+}
+/** Whether `block` joins the turn before it: the same side, and that turn still open. */
+function joinsTurn(last, isUser) {
+    if (!last || last.kind !== (isUser ? 'user' : 'assistant'))
+        return false;
+    return !(last.kind === 'user' && last.stop);
+}
+/**
+ * Blocks as turns: neighbours from the same side share one, unless a block is
+ * in `breaks`, which always starts its own. A message whose turn stopped short
+ * is closed: the next message starts its own turn.
+ */
+export function groupTranscriptBlocks(blocks, breaks) {
     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 (block.kind === 'turn-done')
+            closeTurn(groups.at(-1), block);
         if (isHiddenTranscriptBlock(block))
             continue;
         const isUser = isUserTranscriptBlock(block);
         const last = groups.at(-1);
-        if (last && last.kind === (isUser ? 'user' : 'assistant')) {
+        if (last && joinsTurn(last, isUser) && !breaks?.has(block.id)) {
             last.blocks.push(block);
             continue;
         }
@@ -66,7 +103,7 @@ function lastToolIndexOf(blocks) {
     return -1;
 }
 function pushTextBlock(block, args, trace, body) {
-    // Text before a tool call is narration; text after the latest one is the
+    // invariant: 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()) {
@@ -105,7 +142,7 @@ function classifyNonGateBlock(block, args, trace, 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.
+    // why: 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);
@@ -140,6 +177,18 @@ export function replyKey(groups, index) {
 export function promptReplyKey(prompt) {
     return `${prompt.key}:reply`;
 }
+/**
+ * When the prompt at `index` was sent. Once its reply has stopped, its blocks
+ * date it (less any approval waits), so a restored chat keeps its times; until
+ * then, when this session first showed it.
+ */
+export function promptTime(groups, index, timeOf) {
+    const reply = groups[index + 1];
+    if (reply?.kind === 'assistant' && reply.endedAt !== undefined && reply.workedMs !== undefined) {
+        return reply.endedAt - reply.workedMs;
+    }
+    return timeOf(groups[index]?.key ?? '');
+}
 /**
  * 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.
@@ -161,7 +210,8 @@ export function assistantTurnTiming(args) {
 }
 export function toolCallLabel(tool) {
     const phase = tool.state?.phase;
-    if (phase === 'error' || phase === 'cancel')
+    if (phase === 'cancel')
         return humanize(tool.name);
-    return (phase === 'complete' ? tool.activityPast : tool.activity) ?? humanize(tool.name);
+    const settled = phase === 'complete' || phase === 'error';
+    return (settled ? tool.activityPast : tool.activity) ?? humanize(tool.name);
 }

package/client/transcript-schema.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The transcript's blocks as the wire carries them: the host stores them, and
+ * the browser reads the host's conversation back through this schema.
+ *
+ * @module
+ */
+import { z } from '@theoremjs/agents';
+import type { TranscriptBlock } from '@theoremjs/agents/interface';
+/** One transcript block, as a host stores it and the browser reads it back. */
+export declare const transcriptBlockSchema: z.ZodType<TranscriptBlock>;

package/client/transcript-schema.js

@@ -0,0 +1,120 @@
+/**
+ * The transcript's blocks as the wire carries them: the host stores them, and
+ * the browser reads the host's conversation back through this schema.
+ *
+ * @module
+ */
+import { reasoningPartSchema, TURN_STOP_KINDS, turnEventSchema, z, } from '@theoremjs/agents';
+import { guardrailEventSchema } from '@theoremjs/agents/guardrails';
+// why: The block shapes' event parts have one schema, the turn event's; a probe event reuses it.
+function eventPart(probe) {
+    return z.custom((value) => turnEventSchema.safeParse(probe(value)).success);
+}
+const TOOL_CALL_STATE_PHASES = [
+    'running',
+    'gate',
+    'complete',
+    'error',
+    'cancel',
+];
+const toolCallState = z.custom((value) => {
+    const parsed = turnEventSchema.safeParse({ type: 'tool', tool: value });
+    if (!parsed.success || parsed.data.type !== 'tool' || !('phase' in parsed.data.tool)) {
+        return false;
+    }
+    const { phase } = parsed.data.tool;
+    return TOOL_CALL_STATE_PHASES.some((statePhase) => statePhase === phase);
+});
+const argumentsRecord = z.record(z.string(), z.unknown());
+const toolCall = z.object({
+    operationId: z.string().optional(),
+    name: z.string(),
+    callId: z.string(),
+    arguments: argumentsRecord,
+    draft: z.string().optional(),
+    reasoning: z.array(reasoningPartSchema).optional(),
+    stepId: z.string().optional(),
+    edited: z.object({ from: argumentsRecord, to: argumentsRecord }).optional(),
+    activity: z.string().optional(),
+    activityPast: z.string().optional(),
+    outputDraft: z.string().optional(),
+    state: toolCallState.optional(),
+    startedAt: z.number().optional(),
+    endedAt: z.number().optional(),
+    artifacts: z.array(z.unknown()),
+});
+true;
+const turnStop = z.object({ kind: z.enum(TURN_STOP_KINDS), native: z.string().optional() });
+true;
+const blockId = { id: z.string() };
+const transcriptBlock = z.discriminatedUnion('kind', [
+    z.object({ ...blockId, kind: z.literal('user-text'), text: z.string() }),
+    z.object({
+        ...blockId,
+        kind: z.enum(['user-attachment', 'user-voice']),
+        name: z.string(),
+        mimeType: z.string(),
+        sizeBytes: z.number(),
+        data: z.string().optional(),
+    }),
+    z.object({ ...blockId, kind: z.literal('thought'), text: z.string() }),
+    z.object({ ...blockId, kind: z.literal('text'), text: z.string() }),
+    z.object({ ...blockId, kind: z.literal('tool'), tool: toolCall }),
+    z.object({
+        ...blockId,
+        kind: z.literal('structured'),
+        value: z.unknown(),
+        draft: z.string().optional(),
+    }),
+    z.object({
+        ...blockId,
+        kind: z.literal('media'),
+        mimeType: z.string(),
+        data: z.string().optional(),
+        url: z.string().optional(),
+        previewUrl: z.string().optional(),
+    }),
+    z.object({
+        ...blockId,
+        kind: z.literal('grounding'),
+        grounding: eventPart((grounding) => ({
+            type: 'grounding',
+            grounding,
+        })),
+    }),
+    z.object({
+        ...blockId,
+        kind: z.literal('citation'),
+        sources: eventPart((sources) => ({
+            type: 'citation',
+            sources,
+        })),
+        callId: z.string().optional(),
+    }),
+    z.object({
+        ...blockId,
+        kind: z.literal('evidence'),
+        evidence: eventPart((evidence) => ({
+            type: 'evidence',
+            evidence,
+        })),
+    }),
+    z.object({ ...blockId, kind: z.literal('guardrail'), guardrail: guardrailEventSchema }),
+    z.object({ ...blockId, kind: z.literal('error'), message: z.string() }),
+    z.object({
+        ...blockId,
+        kind: z.literal('turn-done'),
+        stop: turnStop.optional(),
+        tokens: eventPart((tokens) => ({
+            type: 'tokens',
+            tokens,
+        })).optional(),
+        interactionId: z.string().optional(),
+        compaction: z.boolean().optional(),
+        workedMs: z.number().optional(),
+        endedAt: z.number().optional(),
+    }),
+]);
+true;
+/** One transcript block, as a host stores it and the browser reads it back. */
+export const transcriptBlockSchema = transcriptBlock;