@theoremjs/react 0.0.0-stage → 0.3.1

package/client/generation-selection.d.ts

@@ -0,0 +1,15 @@
+import { type ComposerProfileInterface } from '@theoremjs/agents/interface';
+/** A model and effort for the next turn. */
+export type GenerationSelection = {
+    model?: string;
+    effort?: string;
+};
+/** The profile's default model (its first, when it names none). */
+export declare function defaultModel(iface: ComposerProfileInterface): string | undefined;
+/**
+ * The selection for `iface`, given what was `selected` under the `previous` interface (none on
+ * first load). A pick that was on the previous default follows the new one, and a pick `iface` no
+ * longer has falls back to its default; any other pick is kept. Model and effort are each judged
+ * this way, the effort against its model's default, and a new model takes its own default effort.
+ */
+export declare function followGenerationDefaults(iface: ComposerProfileInterface, selected: GenerationSelection, previous: ComposerProfileInterface | undefined): GenerationSelection;

package/client/generation-selection.js

@@ -0,0 +1,24 @@
+import { defaultInterfaceEffort } from '@theoremjs/agents/interface';
+/** The profile's default model (its first, when it names none). */
+export function defaultModel(iface) {
+    return iface.defaultModel ?? Object.keys(iface.models)[0];
+}
+/**
+ * The selection for `iface`, given what was `selected` under the `previous` interface (none on
+ * first load). A pick that was on the previous default follows the new one, and a pick `iface` no
+ * longer has falls back to its default; any other pick is kept. Model and effort are each judged
+ * this way, the effort against its model's default, and a new model takes its own default effort.
+ */
+export function followGenerationDefaults(iface, selected, previous) {
+    const keepModel = selected.model !== undefined &&
+        Object.hasOwn(iface.models, selected.model) &&
+        (previous === undefined || selected.model !== defaultModel(previous));
+    const model = keepModel ? selected.model : defaultModel(iface);
+    const efforts = model === undefined ? undefined : iface.models[model]?.efforts;
+    const keepEffort = model === selected.model &&
+        selected.effort !== undefined &&
+        efforts !== undefined &&
+        Object.hasOwn(efforts, selected.effort) &&
+        (previous === undefined || selected.effort !== defaultInterfaceEffort(previous, model));
+    return { model, effort: keepEffort ? selected.effort : defaultInterfaceEffort(iface, model) };
+}

package/client/host-call.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A host call's standing, read from its folded state: the phase it's in, and
+ * what to say when it failed.
+ *
+ * @module
+ */
+import type { TranscriptBlock } from '@theoremjs/agents/interface';
+import type { ClientFailure } from './failure.ts';
+import { type JsonSchema } from './schema-fields.ts';
+export type ToolCall = Extract<TranscriptBlock, {
+    kind: 'tool';
+}>['tool'];
+export type HostCallStatus = 'running' | 'gate' | 'complete' | 'error' | 'cancel';
+/** What a call's standing reads from. */
+export type HostCallState = {
+    call: ToolCall | null;
+    failure: ClientFailure | null;
+    isRunning: boolean;
+};
+/** The phase a call is in; a stream that broke is an error, one that stopped short a cancel. */
+export declare function hostCallStatus({ call, failure, isRunning }: HostCallState): HostCallStatus;
+/** Why a call failed, as a banner reads it: it never reached its tool, or the tool failed. */
+export declare function hostCallFailure({ call, failure, }: HostCallState): {
+    title: string;
+    description?: string;
+} | null;
+/** What the console shows: the picked tool, its request text, its call on show, and the calls before it. */
+export type HostConsoleView<Tool, Call> = {
+    tool: Tool | undefined;
+    text: string;
+    shown: Call | null;
+    earlier: Call[];
+};
+/**
+ * The console's view of its state. An unknown pick falls back to the first
+ * tool; a tool's request is its draft, else a sample of its schema; the call on
+ * show is the one opened from history, else the tool's latest.
+ */
+export declare function hostConsoleView<Tool extends {
+    name: string;
+    inputSchema: JsonSchema;
+}, Call extends {
+    id: string;
+    name: string;
+}>(args: {
+    tools: readonly Tool[];
+    picked: string | undefined;
+    drafts: Readonly<Record<string, string>>;
+    calls: readonly Call[];
+    shownId: string | null;
+}): HostConsoleView<Tool, Call>;

package/client/host-call.js

@@ -0,0 +1,47 @@
+/**
+ * A host call's standing, read from its folded state: the phase it's in, and
+ * what to say when it failed.
+ *
+ * @module
+ */
+import { sampleFromSchema } from "./schema-fields.js";
+import { json } from "./shaped-data.js";
+const SETTLED = new Set([
+    'gate',
+    'complete',
+    'error',
+    'cancel',
+]);
+/** The phase a call is in; a stream that broke is an error, one that stopped short a cancel. */
+export function hostCallStatus({ call, failure, isRunning }) {
+    const phase = call?.state?.phase;
+    if (phase !== undefined && SETTLED.has(phase))
+        return phase;
+    if (failure)
+        return 'error';
+    return isRunning ? 'running' : 'cancel';
+}
+/** Why a call failed, as a banner reads it: it never reached its tool, or the tool failed. */
+export function hostCallFailure({ call, failure, }) {
+    if (failure)
+        return { title: failure.error };
+    const state = call?.state;
+    if (state?.phase !== 'error')
+        return null;
+    const { error, message } = state.failure;
+    if (!error)
+        return { title: message };
+    return error === message ? { title: error } : { title: error, description: message };
+}
+/**
+ * The console's view of its state. An unknown pick falls back to the first
+ * tool; a tool's request is its draft, else a sample of its schema; the call on
+ * show is the one opened from history, else the tool's latest.
+ */
+export function hostConsoleView(args) {
+    const tool = args.tools.find((candidate) => candidate.name === args.picked) ?? args.tools[0];
+    const text = tool ? (args.drafts[tool.name] ?? json(sampleFromSchema(tool.inputSchema))) : '';
+    const ofTool = args.calls.filter((call) => call.name === tool?.name);
+    const shown = ofTool.find((call) => call.id === args.shownId) ?? ofTool[0] ?? null;
+    return { tool, text, shown, earlier: args.calls.filter((call) => call !== shown) };
+}

package/client/host-transport.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The browser side of a host profile: the tools the host lets the page call,
+ * each with the schemas its request and response are drawn from, and the calls
+ * themselves, streamed as the kernel runs them.
+ *
+ * @module
+ */
+import { type Profile, type ToolAccess, type ToolPermission, z } from '@theoremjs/agents';
+import type { PageDispatchResult } from './page-dispatch.ts';
+import type { TraceFeed } from './trace-feed.ts';
+import { type HttpOptions, type TheoremInvokeRequest, type TurnEventSink } from './transport.ts';
+/** How a tool reaches its work: a function on the host, an HTTP endpoint, or an MCP server. */
+export declare const HOST_TOOL_KINDS: readonly ["function", "http", "mcp"];
+export type HostToolKind = (typeof HOST_TOOL_KINDS)[number];
+/** One tool as the page sees it. Its endpoint, headers, and credentials stay on the host. */
+export type HostToolView = {
+    name: string;
+    description: string;
+    kind: HostToolKind;
+    access: ToolAccess;
+    permission: ToolPermission;
+    /** JSON Schema for the call's input: the form is drawn from it. */
+    inputSchema: Record<string, unknown>;
+    /** JSON Schema for the tool's output: the result is laid out from it. */
+    outputSchema: Record<string, unknown>;
+};
+/** What a host profile shows the page. */
+export type HostInterface = {
+    type: 'host';
+    id: string;
+    tools: HostToolView[];
+    observability?: {
+        record: boolean;
+    };
+};
+/** A tool as registered: the fields the page's view keeps. */
+export type HostToolSource = {
+    type: string;
+    name: string;
+    description: string;
+    access: ToolAccess;
+    permission: ToolPermission;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+};
+/** The page's view of a host profile: its allowed tools, in the order it allows them. */
+export declare function hostInterface(profile: Pick<Extract<Profile, {
+    type: 'host';
+}>, 'id' | 'tools' | 'observability'>, tools: (name: string) => HostToolSource | undefined): HostInterface;
+/** One call of one of the host's tools. */
+export type TheoremHostCallRequest = {
+    name: string;
+    input: unknown;
+};
+/** A `/call` body as `createTheoremHostHandler` reads it. */
+export declare const theoremHostCallRequestSchema: z.ZodType<TheoremHostCallRequest>;
+export interface HostTransport {
+    pageResult?(result: PageDispatchResult, signal?: AbortSignal): Promise<void>;
+    describe(signal?: AbortSignal): Promise<HostInterface>;
+    /** Runs one tool; its events stream to `onEvent`, ending in `done`. */
+    call(request: TheoremHostCallRequest, onEvent: TurnEventSink, signal?: AbortSignal): Promise<void>;
+    /** The user's answer to a call the host paused on a gate. */
+    invoke(request: TheoremInvokeRequest, onEvent: TurnEventSink, signal?: AbortSignal): Promise<void>;
+    /** Where the host's trace records land, for the inspector. */
+    traces?: TraceFeed;
+}
+/** Transport for a host mounted with `createTheoremHostHandler`. Default endpoint `/api/host`. */
+export declare function createHostTransport(options?: HttpOptions & {
+    endpoint?: string;
+}): HostTransport;

package/client/host-transport.js

@@ -0,0 +1,75 @@
+/**
+ * The browser side of a host profile: the tools the host lets the page call,
+ * each with the schemas its request and response are drawn from, and the calls
+ * themselves, streamed as the kernel runs them.
+ *
+ * @module
+ */
+import { resolveObservabilityPolicy, TOOL_ACCESS, TOOL_PERMISSION, TURN_EVENT_SCHEMAS, z, } from '@theoremjs/agents';
+import { fetchJson, postJson, postNdjson, } from "./transport.js";
+import { checkWire } from "./wire-line.js";
+/** How a tool reaches its work: a function on the host, an HTTP endpoint, or an MCP server. */
+export const HOST_TOOL_KINDS = ['function', 'http', 'mcp'];
+function isHostToolKind(type) {
+    return HOST_TOOL_KINDS.includes(type);
+}
+/** The page's view of a host profile: its allowed tools, in the order it allows them. */
+export function hostInterface(profile, tools) {
+    return {
+        type: 'host',
+        id: profile.id,
+        tools: profile.tools.allow.flatMap((name) => {
+            const tool = tools(name);
+            if (!tool || !isHostToolKind(tool.type))
+                return [];
+            return [
+                {
+                    name: tool.name,
+                    description: tool.description,
+                    kind: tool.type,
+                    access: tool.access,
+                    permission: tool.permission,
+                    inputSchema: tool.inputSchema,
+                    outputSchema: tool.outputSchema,
+                },
+            ];
+        }),
+        ...(profile.observability
+            ? { observability: { record: resolveObservabilityPolicy(profile.observability).record } }
+            : {}),
+    };
+}
+const theoremHostCallRequest = z.object({ name: z.string().min(1).max(128), input: z.unknown() });
+true;
+/** A `/call` body as `createTheoremHostHandler` reads it. */
+export const theoremHostCallRequestSchema = theoremHostCallRequest;
+const schemaObject = z.record(z.string(), z.unknown());
+const describedSchema = z.object({
+    interface: z.object({
+        type: z.literal('host'),
+        id: z.string(),
+        tools: z.array(z.object({
+            name: z.string(),
+            description: z.string(),
+            kind: z.enum(HOST_TOOL_KINDS),
+            access: z.enum(TOOL_ACCESS),
+            permission: z.enum(TOOL_PERMISSION),
+            inputSchema: schemaObject,
+            outputSchema: schemaObject,
+        })),
+        observability: z.object({ record: z.boolean() }).optional(),
+    }),
+});
+/** Transport for a host mounted with `createTheoremHostHandler`. Default endpoint `/api/host`. */
+export function createHostTransport(options = {}) {
+    const base = (options.endpoint ?? '/api/host').replace(/\/$/, '');
+    return {
+        pageResult: (body, signal) => postJson(`${base}/page-result`, body, { ...options, signal }),
+        async describe(signal) {
+            // labels-exempt: internal diagnostic; the user reads error.bad_response
+            return checkWire(describedSchema, await fetchJson(base, { signal }, options), 'the host description').interface;
+        },
+        call: (body, onEvent, signal) => postNdjson(`${base}/call`, body, TURN_EVENT_SCHEMAS, onEvent, { ...options, signal }),
+        invoke: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/invoke`, body, TURN_EVENT_SCHEMAS, onEvent, { ...options, signal }),
+    };
+}

package/client/image-output.d.ts

@@ -0,0 +1,6 @@
+/** Display helpers for image-profile output. */
+/**
+ * Profile `image.aspectRatio` (`"16:9"`) as width / height, for Astryx
+ * `AspectRatio`. Undefined when unset or malformed — the provider picks.
+ */
+export declare function parseAspectRatio(value: string | undefined): number | undefined;

package/client/image-output.js

@@ -0,0 +1,13 @@
+/** Display helpers for image-profile output. */
+/**
+ * Profile `image.aspectRatio` (`"16:9"`) as width / height, for Astryx
+ * `AspectRatio`. Undefined when unset or malformed — the provider picks.
+ */
+export function parseAspectRatio(value) {
+    const match = value?.trim().match(/^(\d+(?:\.\d+)?)\s*:\s*(\d+(?:\.\d+)?)$/);
+    if (!match)
+        return undefined;
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    return width > 0 && height > 0 ? width / height : undefined;
+}

package/client/index.d.ts

@@ -0,0 +1,28 @@
+export { float32Rms, float32RmsToLevel, INPUT_LEVEL_GAIN, timeDomainBytesToLevel, } from './audio-level.ts';
+export { createDecisionTransport, type DecisionInterface, type DecisionQuestionView, type DecisionReply, type DecisionTransport, decisionAssets, decisionInterface, failedDecisionTraces, failedTraces, postDecision, readDecisionReply, withFailedTraces, } from './decision-transport.ts';
+export { type ComposerDraftFields, composerFieldsFromDraft } from './decode-composer-draft.ts';
+export { addUsage, checkEmbeddingInputs, checkInputs, cosineSimilarity, type EmbeddingFields, type EmbeddingInputCheck, type EmbeddingMatch, type EmbeddingMediaPart, type EmbeddingSplit, embeddingBatches, fieldsInput, inputFields, MAX_BATCH_INPUTS, rankMatches, readEmbeddingInput, readEmbeddingInputs, readsAsText, splitText, } from './embedding-input.ts';
+export { type EmbeddingSpace, layoutSpace, layoutSpaceSoon, placeQuery, type SpaceCluster, type SpaceDocument, type SpaceLink, type SpacePoint, } from './embedding-space.ts';
+export { createEmbeddingTransport, type EmbeddingInterface, type EmbeddingReply, type EmbeddingTransport, type EmbedOptions, embeddingInterface, postEmbedding, readEmbeddingReply, } from './embedding-transport.ts';
+export { encodeComposerDraft } from './encode-composer-draft.ts';
+export { filesToPending, pendingAttachmentsToFiles } from './encode-files.ts';
+export { type ClientFailure, clientFailure, type TurnFailure } from './failure.ts';
+export { createHostTransport, HOST_TOOL_KINDS, type HostInterface, type HostToolKind, type HostToolSource, type HostToolView, type HostTransport, hostInterface, type TheoremHostCallRequest, } from './host-transport.ts';
+export type { LiveCallOptions, PageTool, PageToolAnswer, PageTools, } from './live/live-page-tool.ts';
+export { type LiveConnectPhase, type LiveSessionStatus, type LiveState, liveState, } from './live/live-state.ts';
+export type { LiveToolGatePrompt } from './live/live-tool.ts';
+export type { LiveConnection } from './live-client.ts';
+export { LiveSessionClient } from './live-client.ts';
+export type { LiveSocket } from './live-messages.ts';
+export { isOAuthComplete, notifyOAuthComplete } from './oauth-popup.ts';
+export { type PageDispatchResult, withPageToolDispatch } from './page-dispatch.ts';
+export { keepsConversation, type RunOutcome, resumeInterfaceTool, type StreamView, streamInterfaceDraftTurn, streamInterfaceTurn, } from './run-session.ts';
+export { type JsonSchema, type SchemaControl, type SchemaField, sampleFromSchema, schemaControl, schemaFields, } from './schema-fields.ts';
+export { citationsFromBlock, type SourceCitation, type SourceCitationBlock, } from './source-citations.ts';
+export type { QueryMatch } from './space-geometry.ts';
+export { layoutResult, type ResultChart, type ResultFigure, type ResultImage, type ResultLayout, } from './tool-result.ts';
+export type { AnsweringGate, ToolDecisionAction, ToolGateResolution, } from './tool-resume.ts';
+export { continueGatedToolInvocation } from './tool-resume.ts';
+export { createTraceFeed, type TraceFeed } from './trace-feed.ts';
+export { CHAT_LINES, type ChatLine, type ChatLineSink, type ClientTurnEvent, type ConversationLine, type ConversationView, createHttpTransport, fetchConversation, fetchRewound, type HostErrorBody, type HttpOptions, type HttpTransportOptions, hostError, isTheoremStreamError, type MalformedEvent, postJson, postNdjson, readNdjsonStream, type TheoremConversationRequest, type TheoremInvokeRequest, type TheoremReplay, type TheoremRewindRequest, type TheoremRewound, type TheoremSteerRequest, TheoremStreamError, type TheoremTransport, type TheoremTurnInput, type TheoremTurnRequest, type TurnEventSink, type UnsupportedEvent, type WireLines, } from './transport.ts';
+export { buildInvokeRequest, buildTurnRequest, issuedOperationId, type RunScope, type WalkAway, } from './turn-client.ts';

package/client/index.js

@@ -0,0 +1,22 @@
+export { float32Rms, float32RmsToLevel, INPUT_LEVEL_GAIN, timeDomainBytesToLevel, } from "./audio-level.js";
+export { createDecisionTransport, decisionAssets, decisionInterface, failedDecisionTraces, failedTraces, postDecision, readDecisionReply, withFailedTraces, } from "./decision-transport.js";
+export { composerFieldsFromDraft } from "./decode-composer-draft.js";
+export { addUsage, checkEmbeddingInputs, checkInputs, cosineSimilarity, embeddingBatches, fieldsInput, inputFields, MAX_BATCH_INPUTS, rankMatches, readEmbeddingInput, readEmbeddingInputs, readsAsText, splitText, } from "./embedding-input.js";
+export { layoutSpace, layoutSpaceSoon, placeQuery, } from "./embedding-space.js";
+export { createEmbeddingTransport, embeddingInterface, postEmbedding, readEmbeddingReply, } from "./embedding-transport.js";
+export { encodeComposerDraft } from "./encode-composer-draft.js";
+export { filesToPending, pendingAttachmentsToFiles } from "./encode-files.js";
+export { clientFailure } from "./failure.js";
+export { createHostTransport, HOST_TOOL_KINDS, hostInterface, } from "./host-transport.js";
+export { liveState, } from "./live/live-state.js";
+export { LiveSessionClient } from "./live-client.js";
+export { isOAuthComplete, notifyOAuthComplete } from "./oauth-popup.js";
+export { withPageToolDispatch } from "./page-dispatch.js";
+export { keepsConversation, resumeInterfaceTool, streamInterfaceDraftTurn, streamInterfaceTurn, } from "./run-session.js";
+export { sampleFromSchema, schemaControl, schemaFields, } from "./schema-fields.js";
+export { citationsFromBlock, } from "./source-citations.js";
+export { layoutResult, } from "./tool-result.js";
+export { continueGatedToolInvocation } from "./tool-resume.js";
+export { createTraceFeed } from "./trace-feed.js";
+export { CHAT_LINES, createHttpTransport, fetchConversation, fetchRewound, hostError, isTheoremStreamError, postJson, postNdjson, readNdjsonStream, TheoremStreamError, } from "./transport.js";
+export { buildInvokeRequest, buildTurnRequest, issuedOperationId, } from "./turn-client.js";

package/client/ink-waveform.d.ts

@@ -0,0 +1,17 @@
+export declare const INK_WAVE_BAR_COUNT = 21;
+export declare const INK_WAVE_HERO_BAR_COUNT = 45;
+/** Per-bar phase offsets — stable undulation, not a fixed bell curve. */
+export declare function inkWavePhases(count: number): number[];
+export type InkWaveStatus = 'disconnected' | 'connecting' | 'reconnecting' | 'connected' | 'ready' | 'listening' | 'speaking' | 'working' | 'error';
+export type InkWaveDriver = 'idle' | 'input' | 'output' | 'tool' | 'working' | 'connecting';
+export declare function inkWaveDriver(status: InkWaveStatus, toolActive: boolean, inputLevel: number, outputLevel: number, frozen?: boolean): InkWaveDriver;
+export declare function computeInkBarTargets(args: {
+    phases: readonly number[];
+    timeMs: number;
+    driver: InkWaveDriver;
+    inputLevel: number;
+    outputLevel: number;
+    frozen?: boolean;
+}): number[];
+/** Smooth toward targets each animation frame (orchid ease feel). */
+export declare function stepInkBarHeights(current: number[], targets: number[], alpha?: number): number[];

package/client/ink-waveform.js

@@ -0,0 +1,68 @@
+export const INK_WAVE_BAR_COUNT = 21;
+export const INK_WAVE_HERO_BAR_COUNT = 45;
+const LEVEL_FLOOR = 0.02;
+/** Per-bar phase offsets — stable undulation, not a fixed bell curve. */
+export function inkWavePhases(count) {
+    return Array.from({ length: count }, (_, i) => i * 0.73 + Math.sin(i * 1.17) * 0.4);
+}
+export function inkWaveDriver(status, toolActive, inputLevel, outputLevel, frozen = false) {
+    if (frozen)
+        return 'idle';
+    if (status === 'disconnected' || status === 'error')
+        return 'idle';
+    if (status === 'connecting' || status === 'reconnecting')
+        return 'connecting';
+    if (toolActive)
+        return 'tool';
+    if (status === 'speaking' || outputLevel > LEVEL_FLOOR)
+        return 'output';
+    if (inputLevel > LEVEL_FLOOR)
+        return 'input';
+    if (status === 'working')
+        return 'working';
+    if (status === 'listening' || status === 'ready')
+        return 'idle';
+    return 'idle';
+}
+export function computeInkBarTargets(args) {
+    const t = args.timeMs * 0.001;
+    if (args.frozen) {
+        return args.phases.map((phase, index) => {
+            const silhouette = 0.22 + 0.55 * (0.5 + 0.5 * Math.sin(phase * 1.7 + index * 0.41));
+            return Math.min(0.82, Math.max(0.1, silhouette));
+        });
+    }
+    const input = args.inputLevel;
+    const output = args.outputLevel;
+    let master;
+    switch (args.driver) {
+        case 'output':
+            master = 0.18 + output * 0.95;
+            break;
+        case 'input':
+            master = 0.16 + input * 0.96;
+            break;
+        case 'tool':
+            master = 0.28 + 0.18 * Math.sin(t * 5.2) + Math.max(output, input) * 0.45;
+            break;
+        case 'working':
+            master = 0.16 + 0.08 * Math.sin(t * 2.2) + Math.max(output, input) * 0.45;
+            break;
+        case 'connecting':
+            master = 0.14 + 0.1 * Math.sin(t * 3.1);
+            break;
+        default:
+            master = 0.08 + 0.04 * Math.sin(t * 1.4);
+            break;
+    }
+    return args.phases.map((phase, index) => {
+        const wobble = 0.72 + 0.28 * Math.sin(t * 3.4 + phase);
+        const ripple = 0.68 + 0.32 * Math.sin(t * 5.3 + index * 0.62);
+        const height = master * wobble * ripple;
+        return Math.min(1, Math.max(0.06, height));
+    });
+}
+/** Smooth toward targets each animation frame (orchid ease feel). */
+export function stepInkBarHeights(current, targets, alpha = 0.14) {
+    return current.map((value, index) => value + (targets[index] - value) * alpha);
+}

package/client/live/apply-live-turn-tool-event.d.ts

@@ -0,0 +1,14 @@
+import type { TurnEvent } from '@theoremjs/agents';
+type LiveToolEventArgs = {
+    /** The call whose gate the user is looking at, if one is open. */
+    gateCallId: string | undefined;
+    /** Close the open gate without an answer: its call is gone. */
+    withdrawGate: () => void;
+    clearInterim: () => void;
+    clearActiveTool: () => void;
+    reportFailure: (err: unknown) => void;
+    setActiveTool: (name: string) => void;
+};
+export type { LiveToolEventArgs };
+/** Apply a live turn event to active-tool / caption / error state. */
+export declare function applyLiveTurnToolEvent(event: TurnEvent, args: LiveToolEventArgs): void;

package/client/live/apply-live-turn-tool-event.js

@@ -0,0 +1,39 @@
+import { TheoremStreamError } from "../transport.js";
+/**
+ * A failed tool step as the host reported it: the user reads its wording (else
+ * the labels' for its kind); the model's `message` stays builder detail.
+ */
+function toolStepFailure(failure) {
+    return new TheoremStreamError(failure.kind, failure.error, failure.message);
+}
+function clearToolUnlessGated(args) {
+    if (args.gateCallId === undefined)
+        args.clearActiveTool();
+}
+function applyToolPhase(tool, args) {
+    if (tool.phase === 'cancel' && tool.callId === args.gateCallId) {
+        args.withdrawGate();
+        args.clearActiveTool();
+        return;
+    }
+    if (tool.phase === 'cancel' || tool.phase === 'complete') {
+        clearToolUnlessGated(args);
+        return;
+    }
+    if (tool.phase === 'error') {
+        args.reportFailure(toolStepFailure(tool.failure));
+        clearToolUnlessGated(args);
+        return;
+    }
+    args.setActiveTool(tool.name);
+}
+/** Apply a live turn event to active-tool / caption / error state. */
+export function applyLiveTurnToolEvent(event, args) {
+    if (event.type === 'done') {
+        args.clearInterim();
+        clearToolUnlessGated(args);
+        return;
+    }
+    if (event.type === 'tool')
+        applyToolPhase(event.tool, args);
+}

package/client/live/live-captions.d.ts

@@ -0,0 +1,53 @@
+import type { TurnEvent } from '@theoremjs/agents';
+import { type TranscriptBlock } from '@theoremjs/agents/interface';
+/** What the agent did between its lines of speech: the events the chat folds into a reply's work. */
+export type LiveWorkEvent = Extract<TurnEvent, {
+    type: 'thought' | 'tool' | 'citation';
+}>;
+/** A line of speech, or the work the agent did before its next one. */
+export type LiveCaptionTurn = {
+    id: string;
+    role: 'user' | 'agent';
+    text: string;
+} | {
+    id: string;
+    role: 'work';
+    events: LiveWorkEvent[];
+};
+export type LiveCaptionState = {
+    turns: LiveCaptionTurn[];
+    interimUser: string;
+    interimAgent: string;
+    /** The agent has worked and its reply has not ended. */
+    working: boolean;
+};
+export type ApplyLiveTranscriptOptions = {
+    /** Commit as a new turn even when the last turn shares the same role (explicit text send). */
+    forceNew?: boolean;
+};
+export declare function emptyLiveCaptionState(): LiveCaptionState;
+/** Keep this call's lines so the next call starts below a divider. A call with no lines adds nothing. */
+export declare function stashLiveCaptionCall(past: LiveCaptionTurn[][], turns: readonly LiveCaptionTurn[]): LiveCaptionTurn[][];
+/**
+ * Fold streaming ASR deltas into turn-by-turn caption lines.
+ * Final chunks for the same role append to the open turn; role switches start a new turn.
+ */
+export declare function applyLiveTranscript(state: LiveCaptionState, text: string, isUser: boolean, interim?: boolean, options?: ApplyLiveTranscriptOptions): LiveCaptionState;
+/**
+ * Fold a live turn event into the captions. A thought, a tool call, or a citation joins the open
+ * work, else starts it; a tool call's later events go to the work that made the call. `done` ends
+ * the reply.
+ */
+export declare function applyLiveTurnEvent(state: LiveCaptionState, event: TurnEvent): LiveCaptionState;
+export type LiveCaptionTranscript = {
+    blocks: TranscriptBlock[];
+    /** The first block of each call after the first: where one call's captions end and the next begin. */
+    callStarts: string[];
+};
+/** Captions as the chat's transcript blocks: past calls, this call, then the lines still being heard. */
+export declare function liveCaptionTranscript(pastCalls: readonly (readonly LiveCaptionTurn[])[], { turns, interimUser, interimAgent }: LiveCaptionState): LiveCaptionTranscript;
+/** The agent is mid-reply: a line of its speech is still arriving, or it is working. */
+export declare function liveCaptionStreaming({ working, interimAgent }: LiveCaptionState): boolean;
+/** Clear streaming partials when a live turn completes or is interrupted. */
+export declare function clearLiveCaptionInterim(state: LiveCaptionState): LiveCaptionState;
+export declare function latestLiveCaptionTurnId(state: LiveCaptionState): string | null;