@theoremjs/react 0.3.0 → 0.3.1

package/client/embedding-transport.d.ts

@@ -0,0 +1,40 @@
+import { type EmbeddingInput, type EmbeddingProfile, type EmbeddingResult, type EmbeddingRules, type EmbeddingTask, type Protocol, type TraceRecord } from '@theoremjs/agents';
+import type { TraceFeed } from './trace-feed.ts';
+import { type HttpOptions } from './transport.ts';
+export type EmbeddingInterface = {
+    type: 'embedding';
+    identity: {
+        handle: string;
+    };
+    /** The profile's inputs held to what its default model takes. */
+    inputs: EmbeddingRules;
+    observability?: {
+        record: boolean;
+    };
+};
+/**
+ * The interface a client reads: the profile's inputs held to its default model's limits. Pass
+ * `protocols` when a model speaks a protocol of your own.
+ */
+export declare function embeddingInterface(profile: Pick<EmbeddingProfile, 'identity' | 'inputs' | 'observability' | 'models' | 'defaultModel'>, protocols?: readonly Protocol[]): EmbeddingInterface;
+export type EmbeddingReply = {
+    result: EmbeddingResult;
+    traces?: TraceRecord[];
+};
+/** What an embedding asks beyond its inputs: a named model, and what the inputs are for. */
+export type EmbedOptions = {
+    model?: string;
+    task?: EmbeddingTask;
+};
+export interface EmbeddingTransport {
+    describe(signal?: AbortSignal): Promise<EmbeddingInterface>;
+    embed(input: EmbeddingInput | readonly EmbeddingInput[], options?: EmbedOptions, signal?: AbortSignal): Promise<EmbeddingReply>;
+    traces?: TraceFeed;
+}
+export declare function readEmbeddingReply(raw: unknown): EmbeddingReply;
+/** POSTs an embedding and reads its reply; a failure keeps the trace records its body carried. */
+export declare function postEmbedding(url: string, body: unknown, signal: AbortSignal | undefined, options?: HttpOptions): Promise<EmbeddingReply>;
+/** Transport for a host mounted with `createTheoremEmbeddingHandler`. Default endpoint `/api/embedding`. */
+export declare function createEmbeddingTransport(options?: HttpOptions & {
+    endpoint?: string;
+}): EmbeddingTransport;

package/client/embedding-transport.js

@@ -0,0 +1,71 @@
+import { embeddingModelLimits, embeddingRules, resolveObservabilityPolicy, traceRecordSchema, z, } from '@theoremjs/agents';
+import { postWithTraces } from "./decision-transport.js";
+import { fetchJson } from "./transport.js";
+import { checkWire } from "./wire-line.js";
+/**
+ * The interface a client reads: the profile's inputs held to its default model's limits. Pass
+ * `protocols` when a model speaks a protocol of your own.
+ */
+export function embeddingInterface(profile, protocols = []) {
+    const binding = profile.models[profile.defaultModel];
+    return {
+        type: 'embedding',
+        identity: { handle: profile.identity.handle },
+        inputs: embeddingRules(profile.inputs, binding ? embeddingModelLimits(binding, protocols) : undefined),
+        ...(profile.observability
+            ? { observability: { record: resolveObservabilityPolicy(profile.observability).record } }
+            : {}),
+    };
+}
+const embeddingReplySchema = z.object({
+    result: z.object({
+        model: z.string().min(1),
+        embeddings: z.array(z
+            .object({
+            index: z.number().int().nonnegative(),
+            values: z.array(z.number()),
+            dimensions: z.number().int().positive(),
+        })
+            .refine((embedding) => embedding.values.length === embedding.dimensions, 'vector length must match dimensions')),
+        usage: z
+            .object({
+            inputTokens: z.number().int().nonnegative().optional(),
+            costUsd: z.number().nonnegative().optional(),
+            estimated: z.literal(true).optional(),
+        })
+            .optional(),
+    }),
+    traces: z.array(traceRecordSchema).optional(),
+});
+const describedSchema = z.object({
+    interface: z.object({
+        type: z.literal('embedding'),
+        identity: z.object({ handle: z.string() }),
+        inputs: z.object({
+            text: z.boolean(),
+            attachments: z.object({ accept: z.array(z.string()) }).optional(),
+            maxFiles: z.number().optional(),
+            maxBytes: z.number().optional(),
+            maxTurnBytes: z.number().optional(),
+            limitsByMime: z.record(z.string(), z.number()).optional(),
+        }),
+        observability: z.object({ record: z.boolean() }).optional(),
+    }),
+});
+export function readEmbeddingReply(raw) {
+    return checkWire(embeddingReplySchema, raw, 'the embedding');
+}
+/** POSTs an embedding and reads its reply; a failure keeps the trace records its body carried. */
+export function postEmbedding(url, body, signal, options = {}) {
+    return postWithTraces(url, body, signal, options, readEmbeddingReply);
+}
+/** Transport for a host mounted with `createTheoremEmbeddingHandler`. Default endpoint `/api/embedding`. */
+export function createEmbeddingTransport(options = {}) {
+    const base = (options.endpoint ?? '/api/embedding').replace(/\/$/, '');
+    return {
+        async describe(signal) {
+            return checkWire(describedSchema, await fetchJson(base, { signal }, options), 'the embedding description').interface;
+        },
+        embed: (input, embed, signal) => postEmbedding(`${base}/embed`, { input, ...embed }, signal, options),
+    };
+}

package/client/failure.d.ts

@@ -4,29 +4,26 @@
  *
  * @module
  */
-import { type ErrorKind, type LexiconOverrides } from '@theoremjs/agents';
-import type { AttachmentValidationIssue, InterfaceTurnSession } from '@theoremjs/agents/interface';
+import { type ErrorKind, type LabelOverrides } from '@theoremjs/agents';
+import type { AttachmentValidationIssue } from '@theoremjs/agents/interface';
 export type ClientFailure = {
-    /** What the user reads: the host's wording, else the profile lexicon's for the failure. */
+    /** What the user reads: the host's wording, else the profile labels' for the failure. */
     error: string;
     errorKind: ErrorKind;
     /** Raw detail for the builder; never shown to the user. */
     errorInternal?: string;
 };
 /**
- * Word a caught value for the user with the profile's `lexicon` (the interface's
- * `lexicon`). A host-reported failure keeps the host's wording.
+ * Word a caught value for the user with the profile's `labels` (the interface's
+ * `labels`). A host-reported failure keeps the host's wording.
  */
-export declare function clientFailure(err: unknown, lexicon?: LexiconOverrides): ClientFailure;
+export declare function clientFailure(err: unknown, labels?: LabelOverrides): ClientFailure;
 /** A turn that did not run or did not finish. */
 export type TurnFailure = ClientFailure & {
-    ok: false;
     /** The files the profile refused, one entry per reason (the kernel's check). */
     issues?: AttachmentValidationIssue[];
     /** The user stopped it; nothing to show. */
     aborted?: boolean;
-    /** The conversation with what the turn got through before it stopped; the next turn resumes from it. */
-    session?: InterfaceTurnSession;
 };
 /** A caught value as a turn failure; an aborted `signal` marks it the user's stop. */
-export declare function turnFailure(err: unknown, lexicon?: LexiconOverrides, signal?: AbortSignal): TurnFailure;
+export declare function turnFailure(err: unknown, labels?: LabelOverrides, signal?: AbortSignal): TurnFailure;

package/client/failure.js

@@ -4,21 +4,21 @@
  *
  * @module
  */
-import { describeError, errorKind, lexiconText, publicError, } from '@theoremjs/agents';
+import { describeError, errorKind, labelText, publicError, } from '@theoremjs/agents';
 import { isTheoremStreamError } from "./transport.js";
 /**
- * Word a caught value for the user with the profile's `lexicon` (the interface's
- * `lexicon`). A host-reported failure keeps the host's wording.
+ * Word a caught value for the user with the profile's `labels` (the interface's
+ * `labels`). A host-reported failure keeps the host's wording.
  */
-export function clientFailure(err, lexicon) {
+export function clientFailure(err, labels) {
     if (isTheoremStreamError(err)) {
         return {
-            error: err.publicMessage ?? lexiconText(`error.${err.kind}`, {}, lexicon),
+            error: err.publicMessage ?? labelText(`error.${err.kind}`, {}, labels),
             errorKind: err.kind,
             ...(err.internalMessage ? { errorInternal: err.internalMessage } : {}),
         };
     }
-    const error = publicError(err, lexicon);
+    const error = publicError(err, labels);
     const internal = describeError(err);
     return {
         error,
@@ -27,8 +27,8 @@ export function clientFailure(err, lexicon) {
     };
 }
 /** A caught value as a turn failure; an aborted `signal` marks it the user's stop. */
-export function turnFailure(err, lexicon, signal) {
-    const failure = clientFailure(err, lexicon);
+export function turnFailure(err, labels, signal) {
+    const failure = clientFailure(err, labels);
     const aborted = failure.errorKind === 'cancelled' || signal?.aborted === true;
-    return { ok: false, ...failure, ...(aborted ? { aborted: true } : {}) };
+    return { ...failure, ...(aborted ? { aborted: true } : {}) };
 }

package/client/host-call.d.ts

@@ -20,7 +20,7 @@ export type HostCallState = {
 /** 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): {
+export declare function hostCallFailure({ call, failure, }: HostCallState): {
     title: string;
     description?: string;
 } | null;

package/client/host-call.js

@@ -6,7 +6,12 @@
  */
 import { sampleFromSchema } from "./schema-fields.js";
 import { json } from "./shaped-data.js";
-const SETTLED = new Set(['gate', 'complete', 'error', 'cancel']);
+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;
@@ -17,7 +22,7 @@ export function hostCallStatus({ call, failure, isRunning }) {
     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 }) {
+export function hostCallFailure({ call, failure, }) {
     if (failure)
         return { title: failure.error };
     const state = call?.state;

package/client/host-transport.d.ts

@@ -6,6 +6,7 @@
  * @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. */
@@ -54,6 +55,7 @@ export type TheoremHostCallRequest = {
 /** 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>;

package/client/host-transport.js

@@ -6,7 +6,7 @@
  * @module
  */
 import { resolveObservabilityPolicy, TOOL_ACCESS, TOOL_PERMISSION, TURN_EVENT_SCHEMAS, z, } from '@theoremjs/agents';
-import { fetchJson, postNdjson, } from "./transport.js";
+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'];
@@ -64,8 +64,9 @@ const describedSchema = z.object({
 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) {
-            // lexicon-exempt: internal diagnostic; the user reads error.bad_response
+            // 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 }),

package/client/index.d.ts

@@ -1,20 +1,28 @@
 export { float32Rms, float32RmsToLevel, INPUT_LEVEL_GAIN, timeDomainBytesToLevel, } from './audio-level.ts';
-export { createDecisionTransport, type DecisionInterface, decisionInterface, type DecisionQuestionView, type DecisionReply, type DecisionTransport, readDecisionReply, } from './decision-transport.ts';
-export { filesToPending, pendingAttachmentsToFiles } from './encode-files.ts';
-export { createHostTransport, HOST_TOOL_KINDS, type HostInterface, hostInterface, type HostToolKind, type HostToolSource, type HostToolView, type HostTransport, type TheoremHostCallRequest, } from './host-transport.ts';
-export { layoutResult, type ResultChart, type ResultFigure, type ResultImage, type ResultLayout } from './tool-result.ts';
-export { type JsonSchema, sampleFromSchema, type SchemaControl, type SchemaField, schemaControl, schemaFields } from './schema-fields.ts';
-export { composerFieldsFromDraft, type ComposerDraftFields } from './decode-composer-draft.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 { applyTurnResultToTranscript, resumeInterfaceTool, type StreamView, streamInterfaceDraftTurn, streamInterfaceTurn, } from './run-session.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 { citationsFromBlock, type SourceCitation, type SourceCitationBlock } from './source-citations.ts';
+export { continueGatedToolInvocation } from './tool-resume.ts';
 export { createTraceFeed, type TraceFeed } from './trace-feed.ts';
-export { buildInvokeRequest, buildTurnRequest, turnInputFromSession, type WalkAway } from './turn-client.ts';
-export { type ClientTurnEvent, createHttpTransport, type HostErrorBody, type HttpOptions, type HttpTransportOptions, isTheoremStreamError, type MalformedEvent, postJson, postNdjson, readNdjsonStream, type TheoremInvokeRequest, type TheoremReplay, type TheoremSteerRequest, TheoremStreamError, type TheoremTransport, type TheoremTurnInput, type TheoremTurnRequest, type TurnEventSink, type UnsupportedEvent, type WireLines, } from './transport.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

@@ -1,18 +1,22 @@
 export { float32Rms, float32RmsToLevel, INPUT_LEVEL_GAIN, timeDomainBytesToLevel, } from "./audio-level.js";
-export { createDecisionTransport, decisionInterface, readDecisionReply, } from "./decision-transport.js";
-export { filesToPending, pendingAttachmentsToFiles } from "./encode-files.js";
-export { createHostTransport, HOST_TOOL_KINDS, hostInterface, } from "./host-transport.js";
-export { layoutResult } from "./tool-result.js";
-export { sampleFromSchema, schemaControl, schemaFields } from "./schema-fields.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 { applyTurnResultToTranscript, resumeInterfaceTool, streamInterfaceDraftTurn, streamInterfaceTurn, } from "./run-session.js";
-export { continueGatedToolInvocation, } from "./tool-resume.js";
-export { citationsFromBlock } from "./source-citations.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 { buildInvokeRequest, buildTurnRequest, turnInputFromSession } from "./turn-client.js";
-export { createHttpTransport, isTheoremStreamError, postJson, postNdjson, readNdjsonStream, TheoremStreamError, } from "./transport.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

@@ -2,7 +2,7 @@ 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' | 'connected' | 'ready' | 'listening' | 'speaking' | 'working' | 'error';
+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: {

package/client/ink-waveform.js

@@ -10,7 +10,7 @@ export function inkWaveDriver(status, toolActive, inputLevel, outputLevel, froze
         return 'idle';
     if (status === 'disconnected' || status === 'error')
         return 'idle';
-    if (status === 'connecting')
+    if (status === 'connecting' || status === 'reconnecting')
         return 'connecting';
     if (toolActive)
         return 'tool';
@@ -46,7 +46,6 @@ export function computeInkBarTargets(args) {
             master = 0.28 + 0.18 * Math.sin(t * 5.2) + Math.max(output, input) * 0.45;
             break;
         case 'working':
-            // Quiet, slow breathing: the server is reasoning, nobody is speaking.
             master = 0.16 + 0.08 * Math.sin(t * 2.2) + Math.max(output, input) * 0.45;
             break;
         case 'connecting':

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

@@ -1,7 +1,7 @@
 import { TheoremStreamError } from "../transport.js";
 /**
  * A failed tool step as the host reported it: the user reads its wording (else
- * the lexicon's for its kind); the model's `message` stays builder detail.
+ * the labels' for its kind); the model's `message` stays builder detail.
  */
 function toolStepFailure(failure) {
     return new TheoremStreamError(failure.kind, failure.error, failure.message);

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

@@ -1,23 +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;

package/client/live/live-captions.js

@@ -1,5 +1,12 @@
+import { foldTurnEvents } from '@theoremjs/agents/interface';
 export function emptyLiveCaptionState() {
-    return { turns: [], interimUser: '', interimAgent: '' };
+    return { turns: [], interimUser: '', interimAgent: '', working: false };
+}
+/** Keep this call's lines so the next call starts below a divider. A call with no lines adds nothing. */
+export function stashLiveCaptionCall(past, turns) {
+    if (turns.length === 0)
+        return past;
+    return [...past, [...turns]];
 }
 function mergeInterimWithFinal(interim, final) {
     if (!interim)
@@ -54,11 +61,108 @@ export function applyLiveTranscript(state, text, isUser, interim, options) {
         });
     }
     return {
+        ...state,
         turns,
         interimUser: isUser ? '' : state.interimUser,
         interimAgent: isUser ? state.interimAgent : '',
     };
 }
+function isWorkEvent(event) {
+    return event.type === 'thought' || event.type === 'tool' || event.type === 'citation';
+}
+/** The work that made the call `callId`: where the call's later events go. -1 when no work made it. */
+function callWorkIndex(turns, callId) {
+    return turns.findIndex((turn) => turn.role === 'work' &&
+        turn.events.some((made) => made.type === 'tool' && made.tool.callId === callId));
+}
+/** Which line takes `event`: `turns.length` starts a new one, -1 leaves the event out. */
+function workIndex(turns, event) {
+    if (event.type === 'tool' && event.tool.phase !== undefined) {
+        // why: The call view's dialog asks a gate's question; the transcript's card would ask it twice.
+        return event.tool.phase === 'gate' ? -1 : callWorkIndex(turns, event.tool.callId);
+    }
+    const open = turns.at(-1)?.role === 'work';
+    // why: The thought guard releases a held blank tail after the speech; it is not work of its own.
+    if (event.type === 'thought' && !(open ? event.text : event.text.trim()))
+        return -1;
+    return open ? turns.length - 1 : turns.length;
+}
+/**
+ * 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 function applyLiveTurnEvent(state, event) {
+    if (event.type === 'done')
+        return state.working ? { ...state, working: false } : state;
+    if (!isWorkEvent(event))
+        return state;
+    const at = workIndex(state.turns, event);
+    if (at === -1)
+        return state;
+    const turns = [...state.turns];
+    const work = turns[at];
+    turns[at] =
+        work?.role === 'work'
+            ? { ...work, events: [...work.events, event] }
+            : { id: nextTurnId(state), role: 'work', events: [event] };
+    return { ...state, turns, working: true };
+}
+/** A line as the chat's blocks: speech is one, work is what the chat folds its events into. */
+function turnBlocks(turn) {
+    if (turn.role === 'work')
+        return foldTurnEvents(turn.events, { idPrefix: turn.id });
+    return [{ id: turn.id, kind: turn.role === 'user' ? 'user-text' : 'text', text: turn.text }];
+}
+/** How much of a broken-off line the next one must repeat to count as starting it again. */
+const RESTART_MATCH = 24;
+function sharedStart(a, b) {
+    let length = 0;
+    while (length < a.length && length < b.length && a[length] === b[length])
+        length += 1;
+    return length;
+}
+/** The later line opens with the same words as the earlier one, or with all of it when it is short. */
+function restarts(earlier, later) {
+    const start = earlier.trim();
+    return sharedStart(start, later.trim()) >= Math.min(start.length, RESTART_MATCH);
+}
+/**
+ * Drops speech the agent broke off and began again in the same reply, which a
+ * tool call mid-sentence makes it do: the line that starts over replaces it.
+ */
+function withoutRestarts(lines) {
+    return lines.filter((line, index) => {
+        if (line.role !== 'agent')
+            return true;
+        const after = lines.slice(index + 1);
+        const nextUser = after.findIndex((later) => later.role === 'user');
+        const reply = nextUser === -1 ? after : after.slice(0, nextUser);
+        return !reply.some((later) => later.role === 'agent' && restarts(line.text, later.text));
+    });
+}
+/** Captions as the chat's transcript blocks: past calls, this call, then the lines still being heard. */
+export function liveCaptionTranscript(pastCalls, { turns, interimUser, interimAgent }) {
+    const current = [...turns];
+    if (interimUser)
+        current.push({ id: 'interim-user', role: 'user', text: interimUser });
+    if (interimAgent)
+        current.push({ id: 'interim-agent', role: 'agent', text: interimAgent });
+    const calls = [
+        ...pastCalls.map((call, index) => call.map((turn) => ({ ...turn, id: `${String(index)}:${turn.id}` }))),
+        current,
+    ]
+        .map((call) => withoutRestarts(call).flatMap(turnBlocks))
+        .filter((call) => call.length > 0);
+    return {
+        blocks: calls.flat(),
+        callStarts: calls.slice(1).map((call) => call[0].id),
+    };
+}
+/** The agent is mid-reply: a line of its speech is still arriving, or it is working. */
+export function liveCaptionStreaming({ working, interimAgent }) {
+    return interimAgent !== '' || working;
+}
 /** Clear streaming partials when a live turn completes or is interrupted. */
 export function clearLiveCaptionInterim(state) {
     if (!state.interimUser && !state.interimAgent)

package/client/live/live-mic-forward.d.ts

@@ -14,6 +14,7 @@ export declare function liveTranscriptFromEvidence(event: TurnEventOf<'evidence'
     interim: boolean;
 } | null;
 export type LiveToolCallDraft = {
+    operationId?: string;
     id: string;
     name: string;
     arguments: Record<string, unknown>;

package/client/live/live-mic-forward.js

@@ -13,7 +13,11 @@ export function liveTranscriptFromEvidence(event) {
         return null;
     if (evidence.kind !== 'input_transcription' && evidence.kind !== 'output_transcription')
         return null;
-    return { text, isUser: evidence.kind === 'input_transcription', interim: evidence.interim === true };
+    return {
+        text,
+        isUser: evidence.kind === 'input_transcription',
+        interim: evidence.interim === true,
+    };
 }
 /**
  * Fold a tool turn event into cancelled-id / runnable-call lists. The model's
@@ -22,7 +26,12 @@ export function liveTranscriptFromEvidence(event) {
  */
 export function applyLiveToolTurnEvent(tool, accum) {
     if (tool.phase === undefined) {
-        accum.toolCalls.push({ id: tool.callId, name: tool.name, arguments: tool.arguments });
+        accum.toolCalls.push({
+            id: tool.callId,
+            name: tool.name,
+            arguments: tool.arguments,
+            ...(tool.operationId ? { operationId: tool.operationId } : {}),
+        });
         return;
     }
     if (tool.phase === 'cancel') {

package/client/live/live-page-tool.d.ts

@@ -0,0 +1,34 @@
+/** The page's result for a call: the tool's output schema checks it, then the model reads it. */
+export type PageToolAnswer = {
+    output: unknown;
+};
+/** One page tool: what the page does for a call the model made, and what it tells the model. */
+export type PageTool = (args: Record<string, unknown>, call: {
+    callId: string;
+    operationId: string;
+}) => PageToolAnswer | Promise<PageToolAnswer>;
+/**
+ * The page's tools, by name: each answers a tool the profile declares with
+ * `answeredBy: 'page'`. Any other tool runs on the relay, gates and all.
+ */
+export type PageTools = Record<string, PageTool>;
+/** What a host gives a live call. */
+export type LiveCallOptions = {
+    /** The value chosen for each of the profile's `inputs.slots`, read as the call starts. */
+    slots?: Record<string, string>;
+    /**
+     * What the page tells the agent: any JSON. It goes with the call's opening, and
+     * again whenever it changes, as background the agent reads without replying.
+     */
+    context?: unknown;
+    pageTools?: PageTools;
+};
+/**
+ * Where the page's tools and the profile's disagree, for the builder: a page
+ * tool with no handler here leaves the model unanswered, and a handler for a
+ * tool the profile does not give the page never runs.
+ */
+export declare function pageToolMismatch(declared: readonly string[], handled: readonly string[]): {
+    unanswered: string[];
+    unused: string[];
+};

package/client/live/live-page-tool.js

@@ -0,0 +1,11 @@
+/**
+ * Where the page's tools and the profile's disagree, for the builder: a page
+ * tool with no handler here leaves the model unanswered, and a handler for a
+ * tool the profile does not give the page never runs.
+ */
+export function pageToolMismatch(declared, handled) {
+    return {
+        unanswered: declared.filter((name) => !handled.includes(name)),
+        unused: handled.filter((name) => !declared.includes(name)),
+    };
+}