@theoremjs/studio 0.3.4-next.403.g5de27f3 → 0.3.4-next.407.gd93ec2c

package/replay.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A recorded conversation, run again through the profile as it is now. Every model call is
+ * answered from the recording, in order, and by default every tool's result too; the profile's
+ * guardrails, stages, gates and transcript run for real. When the profile asks for something the
+ * recording does not hold, the replay stops there and says why (a divergence).
+ *
+ * The recording is a run's `TraceRecord`s: one per turn, with its model calls (`chat` spans) and
+ * tool calls (`execute_tool` spans). A replay needs no keys: it reaches no model.
+ *
+ * @module
+ */
+import { type Profile } from '@theoremjs/agents';
+import { type TranscriptBlock } from '@theoremjs/agents/interface';
+import type { ModelEvent, TurnModel } from '@theoremjs/agents/kernel';
+import { type TraceRecord } from '@theoremjs/agents/observability';
+import type { ToolRegistration } from './registrations.ts';
+import type { StudioRunPayload } from './run-payload.ts';
+import type { StudioToolHandlers } from './tools.ts';
+/** One model call as recorded: what it answered, and whether the recording holds all of it. */
+export interface ReplayCall {
+    /** The agent that made the call. */
+    agent: string;
+    events: ModelEvent[];
+    /** The tools its reply calls, by name. */
+    calls: string[];
+    /** Some of the reply was not recorded (media a model made), so it cannot be answered again. */
+    missing: boolean;
+}
+/** One tool call's recorded result. */
+export interface ReplayResult {
+    name: string;
+    result: string;
+    failed: boolean;
+}
+/** One recorded turn: what the person sent, the model calls and tool results it took, and what they saw. */
+export interface ReplayTurn {
+    text: string;
+    /** Files sent with the message. Their bytes are never recorded, so such a turn cannot be sent again. */
+    attachments: number;
+    calls: ReplayCall[];
+    results: ReplayResult[];
+    /** The turn as the person saw it. */
+    blocks: TranscriptBlock[];
+}
+/** A recording as a replay reads it. */
+export interface ReplayScript {
+    /** The agent the conversation was with. */
+    agent: string;
+    turns: ReplayTurn[];
+    /** When the first turn started (epoch ms). */
+    recordedAt?: number;
+}
+/** Why a replay stopped where it did. */
+export interface ReplayDivergence {
+    /** The turn, from 0. */
+    turn: number;
+    /** The model call within the turn, from 1. */
+    call: number;
+    reason: string;
+}
+/**
+ * The replay a run's records stand for. Each record whose root is a turn of the conversation's
+ * agent is a turn; a record of another agent's turn (an agent tool's) adds its calls to the turn
+ * before it. Records of anything else (a host's tool call, a decision) hold no turn.
+ */
+export declare function replayScript(records: readonly TraceRecord[]): ReplayScript;
+export interface Replay {
+    /** Answers each model call from the recording: pass as the runtime's `provider`. */
+    provider: (profile: Profile) => TurnModel;
+    /** Answers each tool from the recording, by name, in order: pass as the runtime's `toolHandlers`. */
+    toolHandlers: StudioToolHandlers;
+    /**
+     * Sets the turn the next calls belong to. A turn set again goes on where it stopped: a reply
+     * that waited on a gate resumes with the calls it had left.
+     */
+    startTurn(turn: number): void;
+}
+/**
+ * A replay of `script` for the agent `agent` (the conversation's agent, as the profile now names
+ * it). `onDiverge` hears where it stopped; the call that diverged then fails its turn.
+ */
+export declare function createReplay(script: ReplayScript, agent: string, onDiverge: (divergence: ReplayDivergence) => void): Replay;
+/**
+ * `tools` with every tool that reaches past the page answered by a handler instead: http, MCP,
+ * the page's own, and those that answer with a sample. An agent tool still runs its agent, whose
+ * model calls the replay answers too.
+ */
+export declare function recordedTools(tools: readonly ToolRegistration[]): ToolRegistration[];
+/** `payload` with its tools, and those of the agents it names, answered from the recording. */
+export declare function recordedPayload(payload: StudioRunPayload): StudioRunPayload;
+/** The conversation as the person saw it, every turn. */
+export declare function recordedTranscript(script: ReplayScript): TranscriptBlock[];
+/**
+ * The records a trace file holds: a JSON array of `TraceRecord`s, as the studio downloads them,
+ * or one record. Throws, saying why, for anything else.
+ */
+export declare function parseTraceFile(text: string): TraceRecord[];

package/replay.js

@@ -0,0 +1,387 @@
+/**
+ * A recorded conversation, run again through the profile as it is now. Every model call is
+ * answered from the recording, in order, and by default every tool's result too; the profile's
+ * guardrails, stages, gates and transcript run for real. When the profile asks for something the
+ * recording does not hold, the replay stops there and says why (a divergence).
+ *
+ * The recording is a run's `TraceRecord`s: one per turn, with its model calls (`chat` spans) and
+ * tool calls (`execute_tool` spans). A replay needs no keys: it reaches no model.
+ *
+ * @module
+ */
+import { TheoremError, traceRecordSchema } from '@theoremjs/agents';
+import { foldConversationTurn } from '@theoremjs/agents/interface';
+import { inlineContent, } from '@theoremjs/agents/observability';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const attribute = (span, name) => span.attributes[name];
+const stringAttribute = (span, name) => {
+    const value = attribute(span, name);
+    return typeof value === 'string' ? value : undefined;
+};
+/** A stored attribute, its content put back. */
+function content(record, span, name) {
+    const value = attribute(span, name);
+    return value === undefined ? undefined : inlineContent(record, value);
+}
+/** A stored attribute as text: its content, or its JSON. */
+function contentText(record, span, name) {
+    const value = content(record, span, name);
+    if (value === undefined)
+        return '';
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+function messagesOf(record, span, name) {
+    const value = content(record, span, name);
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+const partsOf = (message) => Array.isArray(message.parts) ? message.parts.filter(isRecord) : [];
+const startOf = (span) => BigInt(String(span.startTimeUnixNano));
+const byStart = (a, b) => {
+    const order = startOf(a) - startOf(b);
+    return order === 0n ? 0 : order < 0n ? -1 : 1;
+};
+/** A part whose content the record does not hold keeps its hash. */
+const unrecorded = (part) => 'content_sha256' in part || 'json_sha256' in part;
+/** A tool call's arguments, as the model sent them. */
+function argumentsOf(part) {
+    const raw = part.arguments;
+    if (isRecord(raw))
+        return raw;
+    if (typeof raw !== 'string')
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The text or visible thought a recorded part says, if it says any. */
+function saidOf(part) {
+    if (typeof part.content !== 'string')
+        return undefined;
+    if (part.type === 'reasoning')
+        return { type: 'thought', text: part.content };
+    if (part.type === 'text')
+        return { type: 'text', text: part.content };
+    return undefined;
+}
+/** The events one recorded reply stands for, in the order the model wrote them. */
+function replyEvents(messages) {
+    const events = [];
+    const calls = [];
+    let missing = false;
+    for (const message of messages) {
+        const parts = partsOf(message);
+        const hasText = parts.some((part) => part.type === 'text');
+        for (const part of parts) {
+            const said = saidOf(part);
+            if (unrecorded(part))
+                missing = true;
+            else if (said)
+                events.push(said);
+            else if (part.type === 'structured' && !hasText)
+                events.push({ type: 'text', text: JSON.stringify(part.content) });
+            else if (part.type === 'tool_call' && typeof part.name === 'string') {
+                calls.push(part.name);
+                events.push({
+                    type: 'tool',
+                    tool: {
+                        name: part.name,
+                        callId: typeof part.id === 'string' ? part.id : `replay-${String(calls.length)}`,
+                        arguments: argumentsOf(part),
+                    },
+                });
+            }
+            else if (part.type === 'blob' || part.type === 'uri')
+                missing = true;
+        }
+    }
+    return { events, calls, missing };
+}
+/** The agent whose turn `span` is part of: the nearest `invoke_agent` above it. */
+function agentOf(span, spans) {
+    for (let at = span; at; at = spans.get(at.parentSpanId ?? '')) {
+        const name = stringAttribute(at, 'gen_ai.agent.name');
+        if (stringAttribute(at, 'gen_ai.operation.name') === 'invoke_agent' && name)
+            return name;
+    }
+    return '';
+}
+const operation = (span) => stringAttribute(span, 'gen_ai.operation.name');
+/** The model calls a record holds, in order, each with its agent and ending as it was recorded to. */
+function recordCalls(record) {
+    const spans = new Map(record.spans.map((span) => [span.spanId, span]));
+    return record.spans
+        .filter((span) => operation(span) === 'chat')
+        .toSorted(byStart)
+        .map((span) => {
+        const reply = replyEvents(messagesOf(record, span, 'gen_ai.output.messages'));
+        const kind = stringAttribute(span, 'theorem.stop.kind') ?? 'completed';
+        return {
+            agent: agentOf(span, spans),
+            ...reply,
+            events: [...reply.events, { type: 'done', stop: { kind } }],
+        };
+    });
+}
+/** The tool results a record holds, in order. */
+function recordResults(record) {
+    return record.spans
+        .filter((span) => operation(span) === 'execute_tool')
+        .toSorted(byStart)
+        .map((span) => ({
+        name: stringAttribute(span, 'gen_ai.tool.name') ?? '',
+        result: contentText(record, span, 'gen_ai.tool.call.result'),
+        failed: stringAttribute(span, 'theorem.tool.outcome') === 'error',
+    }));
+}
+/** What the person sent: the turn's last user message. */
+function userMessage(record, root) {
+    const user = messagesOf(record, root, 'gen_ai.input.messages').findLast((message) => message.role === 'user');
+    const parts = user ? partsOf(user) : [];
+    return {
+        text: parts
+            .flatMap((part) => part.type === 'text' && typeof part.content === 'string' ? [part.content] : [])
+            .join('\n'),
+        attachments: parts.filter((part) => part.type === 'blob' || part.type === 'uri').length,
+    };
+}
+/** The events the person was shown in a turn, from what it delivered and the tools it ran. */
+function shownEvents(record, root) {
+    const tools = record.spans.filter((span) => operation(span) === 'execute_tool').toSorted(byStart);
+    const used = new Set();
+    /** The tool span for a call: by its id, else the next one by its name. */
+    const toolSpan = (callId, name) => {
+        const span = tools.find((each) => stringAttribute(each, 'gen_ai.tool.call.id') === callId) ??
+            tools.find((each) => !used.has(each) && stringAttribute(each, 'gen_ai.tool.name') === name);
+        if (span)
+            used.add(span);
+        return span;
+    };
+    const events = [];
+    for (const message of messagesOf(record, root, 'gen_ai.output.messages')) {
+        for (const part of partsOf(message)) {
+            const said = saidOf(part);
+            if (said)
+                events.push(said);
+            else if (part.type === 'tool_call' && typeof part.name === 'string') {
+                const callId = typeof part.id === 'string' ? part.id : `call-${String(events.length)}`;
+                events.push(...toolEvents(record, part.name, callId, argumentsOf(part), toolSpan));
+            }
+        }
+    }
+    const failure = contentText(record, root, 'theorem.error.public');
+    if (root.status.code === 'ERROR')
+        events.push({ type: 'error', errorKind: 'internal', error: failure || root.status.message });
+    const kind = stringAttribute(root, 'theorem.stop.kind') ?? 'completed';
+    events.push({ type: 'done', stop: { kind } });
+    return events;
+}
+/** A tool call and how it ended, as the transcript shows it. */
+function toolEvents(record, name, callId, args, toolSpan) {
+    const span = toolSpan(callId, name);
+    const made = { type: 'tool', tool: { name, callId, arguments: args } };
+    if (!span)
+        return [made];
+    const at = Number(startOf(span) / 1000000n);
+    const result = contentText(record, span, 'gen_ai.tool.call.result');
+    const failed = stringAttribute(span, 'theorem.tool.outcome') === 'error';
+    const settled = failed
+        ? {
+            phase: 'error',
+            failure: {
+                code: stringAttribute(span, 'theorem.tool.failure.code') ?? 'failed',
+                kind: 'internal',
+                message: result,
+            },
+        }
+        : { phase: 'complete', output: parsed(result) };
+    return [made, { type: 'tool', tool: { name, callId, at, ...settled } }];
+}
+function parsed(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+const rootOf = (record) => record.spans.find((span) => !span.parentSpanId);
+/**
+ * The replay a run's records stand for. Each record whose root is a turn of the conversation's
+ * agent is a turn; a record of another agent's turn (an agent tool's) adds its calls to the turn
+ * before it. Records of anything else (a host's tool call, a decision) hold no turn.
+ */
+export function replayScript(records) {
+    let agent = '';
+    let recordedAt;
+    const turns = [];
+    records.forEach((record, index) => {
+        const root = rootOf(record);
+        if (!root || operation(root) !== 'invoke_agent')
+            return;
+        const name = stringAttribute(root, 'gen_ai.agent.name') ?? '';
+        agent ||= name;
+        const calls = recordCalls(record);
+        const results = recordResults(record);
+        const last = turns.at(-1);
+        if (name !== agent && last) {
+            last.calls.push(...calls);
+            last.results.push(...results);
+            return;
+        }
+        recordedAt ??= Number(startOf(root) / 1000000n);
+        const sent = userMessage(record, root);
+        turns.push({
+            ...sent,
+            calls,
+            results,
+            blocks: foldConversationTurn({ text: sent.text }, shownEvents(record, root), {
+                idPrefix: `recorded-${String(index)}`,
+            }),
+        });
+    });
+    return { agent, turns, ...(recordedAt === undefined ? {} : { recordedAt }) };
+}
+/** A recorded result as a function tool returns it: its JSON object, else its text. */
+function resultOutput(result) {
+    if (result.failed)
+        throw new Error(result.result);
+    const value = parsed(result.result);
+    return isRecord(value) ? value : { result: value };
+}
+/** Ordinal wording for a call's place in its turn. */
+const nth = (n) => {
+    const tens = n % 100;
+    const suffix = tens >= 11 && tens <= 13 ? 'th' : ({ 1: 'st', 2: 'nd', 3: 'rd' }[n % 10] ?? 'th');
+    return `${String(n)}${suffix}`;
+};
+/** The divergence, if `call` cannot answer `request`. */
+function divergence(call, recorded, request) {
+    if (!call)
+        return `The profile asked the model a ${nth(recorded + 1)} time this turn; the recording answered ${String(recorded)}.`;
+    if (call.missing)
+        return 'The recording does not hold all of this reply.';
+    const offered = new Set((request.wireTools ?? []).map((tool) => tool.name));
+    const gone = call.calls.find((name) => !offered.has(name));
+    return gone && `The recording calls ${gone}, which the profile no longer offers.`;
+}
+/**
+ * A replay of `script` for the agent `agent` (the conversation's agent, as the profile now names
+ * it). `onDiverge` hears where it stopped; the call that diverged then fails its turn.
+ */
+export function createReplay(script, agent, onDiverge) {
+    let turn = 0;
+    /** How often each agent has asked in each turn, by `turn agent`. */
+    const asked = new Map();
+    /** Each turn's results not yet given, by tool name. */
+    const pending = new Map();
+    const resultsOf = (index) => {
+        let results = pending.get(index);
+        if (!results) {
+            results = new Map();
+            for (const result of script.turns[index]?.results ?? [])
+                results.set(result.name, [...(results.get(result.name) ?? []), result]);
+            pending.set(index, results);
+        }
+        return results;
+    };
+    const model = (name) => ({
+        // why: a generator, so a divergence fails the call the engine is reading, not the one before.
+        async *complete(request) {
+            const calls = script.turns[turn]?.calls.filter((call) => call.agent === name) ?? [];
+            const key = `${String(turn)} ${name}`;
+            const index = asked.get(key) ?? 0;
+            asked.set(key, index + 1);
+            const reason = divergence(calls[index], calls.length, request);
+            if (reason) {
+                onDiverge({ turn, call: index + 1, reason });
+                throw new TheoremError('request', `Replay stopped: ${reason}`); // labels-exempt: builder diagnostic
+            }
+            yield* calls[index]?.events ?? [];
+        },
+    });
+    const handler = (name) => () => {
+        const next = resultsOf(turn).get(name)?.shift();
+        if (!next)
+            throw new Error(`The recording has no further result for ${name}.`);
+        return resultOutput(next);
+    };
+    const names = new Set(script.turns.flatMap((each) => each.results.map((result) => result.name)));
+    const toolHandlers = Object.fromEntries([...names].map((name) => [name, handler(name)]));
+    return {
+        provider: (profile) => model(profile.id === agent ? script.agent : profile.id),
+        toolHandlers,
+        startTurn: (index) => {
+            turn = index;
+        },
+    };
+}
+/**
+ * `tools` with every tool that reaches past the page answered by a handler instead: http, MCP,
+ * the page's own, and those that answer with a sample. An agent tool still runs its agent, whose
+ * model calls the replay answers too.
+ */
+export function recordedTools(tools) {
+    return tools.map((tool) => {
+        if (tool.type === 'agent')
+            return tool;
+        const { name, description, category, access, permission, loadTier, paths } = tool;
+        return {
+            type: 'function',
+            name,
+            description,
+            category,
+            access,
+            permission,
+            loadTier,
+            paths,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            ...(tool.labels ? { labels: tool.labels } : {}),
+        };
+    });
+}
+/** `payload` with its tools, and those of the agents it names, answered from the recording. */
+export function recordedPayload(payload) {
+    return {
+        ...payload,
+        customTools: recordedTools(payload.customTools),
+        ...(payload.dependencies
+            ? {
+                dependencies: payload.dependencies.map((dependency) => ({
+                    ...dependency,
+                    customTools: recordedTools(dependency.customTools),
+                })),
+            }
+            : {}),
+    };
+}
+/** The conversation as the person saw it, every turn. */
+export function recordedTranscript(script) {
+    return script.turns.flatMap((turn) => turn.blocks);
+}
+/**
+ * The records a trace file holds: a JSON array of `TraceRecord`s, as the studio downloads them,
+ * or one record. Throws, saying why, for anything else.
+ */
+export function parseTraceFile(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new TheoremError('request', 'This file is not JSON.'); // labels-exempt: builder diagnostic
+    }
+    const records = Array.isArray(value) ? value : [value];
+    return records.map((record, index) => {
+        const parsed = traceRecordSchema.safeParse(record);
+        if (parsed.success)
+            return parsed.data;
+        const where = records.length > 1 ? ` (record ${String(index + 1)})` : '';
+        // labels-exempt: builder diagnostic
+        throw new TheoremError('request', `This file is not a Theorem trace${where}.`);
+    });
+}

package/server/draft-handler.js

@@ -13,7 +13,7 @@
  */
 import { TheoremError, z } from '@theoremjs/agents';
 import { clientError } from '@theoremjs/agents/host';
-import { checkRequest, createMemoryPageToolBroker, createMemorySessionStore, createMemorySteerInbox, createSealedConversationStore, createTheoremSessionBoundary, pageToolResultSchema, readBody, steerUnitOf, theoremConversationRequestSchema, theoremHostCallRequestSchema, theoremInvokeRequestSchema, theoremRewindRequestSchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from '@theoremjs/web/server';
+import { checkRequest, createMemoryPageToolBroker, createMemorySessionStore, createMemorySteerInbox, createSealedConversationStore, createTheoremSessionBoundary, pageToolResultSchema, readBody, steerUnitOf, theoremConversationRequestSchema, theoremHostCallRequestSchema, theoremInvokeRequestSchema, theoremRewindRequestSchema, theoremStartRequestSchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from '@theoremjs/web/server';
 import { newConversationKey } from "../conversation-key.js";
 import { rewindStudio, startStudioConversation, streamStudioCall, streamStudioHostInvoke, streamStudioInvoke, streamStudioTurn, studioConversation, } from "../runtime.js";
 import { draftDecide } from "./draft-decide.js";
@@ -130,6 +130,7 @@ export function createStudioDraftHandler(options = {}) {
                 }));
         }),
         conversation: (request) => draftRequest(request, async (draft, boundary) => Response.json(await studioConversation(draftRun(lent, draft, boundary, request), conversationsOf(boundary), checkRequest(theoremConversationRequestSchema, draft, 'request body')))),
+        'conversation/start': (request) => draftRequest(request, async (draft, boundary) => Response.json(await startStudioConversation(draftRun(lent, draft, boundary, request), conversationsOf(boundary), checkRequest(theoremStartRequestSchema, draft, 'request body').blocks))),
         rewind: (request) => draftRequest(request, async (draft, boundary) => Response.json(await rewindStudio(draftRun(lent, draft, boundary, request), conversationsOf(boundary), checkRequest(theoremRewindRequestSchema, draft, 'request body'), request.signal))),
         call: (request) => draftRequest(request, async (draft, boundary) => {
             const call = checkRequest(theoremHostCallRequestSchema, draft, 'request body');

package/transport.d.ts

@@ -5,7 +5,7 @@
  * `createTheoremHandler`).
  */
 import { type TurnEvent } from '@theoremjs/agents';
-import { type ProfileInterface } from '@theoremjs/agents/interface';
+import { type ProfileInterface, type TranscriptBlock } from '@theoremjs/agents/interface';
 import { type ChatLineSink, type ConversationLine, type DecisionTransport, type EmbeddingTransport, type HostTransport, type HttpOptions, type MalformedEvent, type TheoremTransport, type TraceFeed, type TurnEventSink, type UnsupportedEvent } from '@theoremjs/web/client';
 import { z } from 'zod';
 import { type StudioRunPayload } from './run-payload.ts';
@@ -43,6 +43,10 @@ export type StudioTransportOptions = HttpOptions & {
 };
 export declare function createStudioEmbeddingTransport(payload: StudioRunPayload, options?: StudioTransportOptions): EmbeddingTransport;
 export declare function createStudioTransport(payload: StudioRunPayload, options?: StudioTransportOptions): TheoremTransport;
+/** A conversation with the draft that opens on `blocks`, kept in this visitor's session: its ref and view. */
+export declare function startStudioConversation(payload: StudioRunPayload, blocks: readonly TranscriptBlock[], options?: HttpOptions & {
+    signal?: AbortSignal;
+}): Promise<import("@theoremjs/web/client").TheoremRewound>;
 /**
  * A decision draft's transport: the page describes the profile itself, and every decision posts
  * the draft's profile and questions beside the state, since the studio user authors both.

package/transport.js

@@ -5,9 +5,9 @@
  * `createTheoremHandler`).
  */
 import { defineProfile, TheoremError, TURN_EVENT_SCHEMAS, traceRecordSchema, } from '@theoremjs/agents';
-import { interfaceFromProfile } from '@theoremjs/agents/interface';
+import { interfaceFromProfile, } from '@theoremjs/agents/interface';
 import { createToolRegistry } from '@theoremjs/agents/kernel';
-import { CHAT_LINES, createTraceFeed, decisionAssets, decisionInterface, embeddingInterface, fetchConversation, fetchRewound, hostInterface, postDecision, postEmbedding, postJson, postNdjson, } from '@theoremjs/web/client';
+import { CHAT_LINES, createTraceFeed, decisionAssets, decisionInterface, embeddingInterface, fetchConversation, fetchRewound, fetchStarted, hostInterface, postDecision, postEmbedding, postJson, postNdjson, } from '@theoremjs/web/client';
 import { z } from 'zod';
 import { uncompiled } from "./compile.js";
 import { clearStudioRunPayload, keptStudioRunIds, loadStudioRunPayload, } from "./run-payload.js";
@@ -143,6 +143,11 @@ export function createStudioTransport(payload, options = {}) {
         traces,
     };
 }
+/** A conversation with the draft that opens on `blocks`, kept in this visitor's session: its ref and view. */
+export function startStudioConversation(payload, blocks, options = {}) {
+    const { profile, customTools, structured, dependencies } = payload;
+    return fetchStarted('/api/studio/conversation/start', { profile, customTools, structured, dependencies, blocks }, options);
+}
 /**
  * A decision draft's transport: the page describes the profile itself, and every decision posts
  * the draft's profile and questions beside the state, since the studio user authors both.

package/ui/inspector-context.d.ts

@@ -72,7 +72,7 @@ export declare const LocalConnection: import("react").Context<Pick<{
         ids: string[];
         error?: string;
     };
-    mode: "local" | "demo" | "byok";
+    mode: "local" | "byok" | "demo";
     on: StudioRunsOn;
     runtime: import("../browser-transport.ts").StudioBrowserRuntime | null;
     vault: Readonly<Record<string, string | undefined>>;

package/ui/lib/send-when-ready.d.ts

@@ -0,0 +1,7 @@
+import type { TheoremChatHandle } from '@theoremjs/react/ui';
+import type { RefObject } from 'react';
+/**
+ * Sends `text` once the chat takes it: a chat just mounted takes nothing until it has described
+ * its agent. Null when it took nothing in `ms`, or `signal` aborted.
+ */
+export declare function sendWhenReady(chat: RefObject<TheoremChatHandle | null>, text: string, signal: AbortSignal, ms?: number): Promise<import("@theoremjs/web/client").SentTurn | null>;

package/ui/lib/send-when-ready.js

@@ -0,0 +1,14 @@
+/**
+ * Sends `text` once the chat takes it: a chat just mounted takes nothing until it has described
+ * its agent. Null when it took nothing in `ms`, or `signal` aborted.
+ */
+export async function sendWhenReady(chat, text, signal, ms = 10_000) {
+    const until = Date.now() + ms;
+    while (!signal.aborted && Date.now() < until) {
+        const sent = await chat.current?.send(text);
+        if (sent)
+            return sent;
+        await new Promise((resolve) => requestAnimationFrame(resolve));
+    }
+    return null;
+}

package/ui/studio-connection.d.ts

@@ -20,7 +20,7 @@ export declare function useStudioConnection(models: readonly (ModelRoute & {
     entries: KeyEntry[];
     setEntries: Dispatch<SetStateAction<KeyEntry[]>>;
     localModels: LocalModels;
-    mode: "local" | "demo" | "byok";
+    mode: "local" | "byok" | "demo";
     on: StudioRunsOn;
     runtime: StudioBrowserRuntime | null;
     vault: Readonly<Record<string, string | undefined>>;

package/ui/studio-runner.d.ts

@@ -1,4 +1,5 @@
 import { TheoremChat } from '@theoremjs/react/ui';
+import { type TraceFeed } from '@theoremjs/web/client';
 import { type ComponentProps } from 'react';
 import { type StudioBrowserRuntime } from '../browser.ts';
 import { type StudioConnectionMode, type StudioRunPayload, type StudioWorkspace } from '../mod.ts';
@@ -34,6 +35,8 @@ export interface StudioRunnerProps {
      * answers twice while it holds edits the files do not: as the files, and as the edits.
      */
     tested?: StudioWorkspace;
+    /** The feed its trace records land in, when the page reads them too; else its own. */
+    traces?: TraceFeed;
 }
 /**
  * The builder preview and existing run page select transports under the same runner UI.
@@ -41,5 +44,5 @@ export interface StudioRunnerProps {
  * A runner is one conversation. The chat keeps its transcript when an edit recompiles the draft,
  * so its trace feed outlives each transport too; remount the runner (a new `key`) to start over.
  */
-export declare function StudioRunner({ payload, mode, runtime, trace, className, flush, columns, onActivity, conversation, conversationView, initialText, onConversationChange, chatRef, slots, context, tested, }: StudioRunnerProps): import("react").JSX.Element;
+export declare function StudioRunner({ payload, mode, runtime, trace, className, flush, columns, onActivity, conversation, conversationView, initialText, onConversationChange, chatRef, slots, context, tested, traces: given, }: StudioRunnerProps): import("react").JSX.Element;
 export type ChatProps = ComponentProps<typeof TheoremChat>;

package/ui/studio-runner.js

@@ -43,8 +43,9 @@ function RunLoading() {
  * A runner is one conversation. The chat keeps its transcript when an edit recompiles the draft,
  * so its trace feed outlives each transport too; remount the runner (a new `key`) to start over.
  */
-export function StudioRunner({ payload, mode, runtime, trace, className, flush, columns, onActivity, conversation, conversationView, initialText, onConversationChange, chatRef, slots, context, tested, }) {
-    const [traces] = useState(createTraceFeed);
+export function StudioRunner({ payload, mode, runtime, trace, className, flush, columns, onActivity, conversation, conversationView, initialText, onConversationChange, chatRef, slots, context, tested, traces: given, }) {
+    const [own] = useState(createTraceFeed);
+    const traces = given ?? own;
     const activity = useRef(onActivity);
     activity.current = onActivity;
     const [note] = useState(() => () => activity.current?.());