@theoremjs/web 0.0.0-stage → 0.3.4-next.373.gab46e23

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-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/index.d.ts

@@ -0,0 +1,33 @@
+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, outlierThreshold, 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 { encodeFiles, filesToPending, pendingAttachmentsToFiles } from './encode-files.ts';
+export { type ClientFailure, clientFailure, type TurnFailure, turnFailure } from './failure.ts';
+export { followGenerationDefaults } from './generation-selection.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 { pageToolMismatch } from './live/live-page-tool.ts';
+export { type LiveConnectPhase, type LiveSessionStatus, type LiveState, liveState, } from './live/live-state.ts';
+export type { LiveGateAnswer, LiveToolGatePrompt } from './live/live-tool.ts';
+export type { LiveConnection } from './live-client.ts';
+export { LiveSessionClient } from './live-client.ts';
+export type { ExecuteToolOnRelay, LiveSocket } from './live-messages.ts';
+export { isOAuthComplete, notifyOAuthComplete } from './oauth-popup.ts';
+export { type PageDispatchResult, withPageToolDispatch } from './page-dispatch.ts';
+export { sessionAfter, stampWorked } from './run-commit.ts';
+export { keepsConversation, type RunOutcome, resumeInterfaceTool, type StreamView, streamInterfaceDraftTurn, streamInterfaceTurn, } from './run-session.ts';
+export { blankRow, type JsonSchema, missingFields, type SchemaControl, type SchemaField, sampleFromSchema, schemaControl, schemaFields, withField, } from './schema-fields.ts';
+export { fieldLabel, fieldReading, humanize, isPlain, isProse, isRow, json, type ListRow, MAX_ROWS, type PlainReading, plainReading, type Row, rowHeading, type Section, type Shape, shapeOf, splitFields, unpacked, withUnit, } from './shaped-data.ts';
+export { citationsFromBlock, type SourceCitation, type SourceCitationBlock, } from './source-citations.ts';
+export type { QueryMatch } from './space-geometry.ts';
+export { DOT_FLOATS, FRAME_SLOT, queryGeometry, SEGMENT_FLOATS, type SpaceGeometry, spaceGeometry, } from './space-geometry.ts';
+export { hasLead, layoutResult, type ResultChart, type ResultFigure, type ResultImage, type ResultLayout, type ResultMedia, returnedMedia, timeFormats, } from './tool-result.ts';
+export type { AnsweringGate, ToolDecisionAction, ToolGateResolution, } from './tool-resume.ts';
+export { continueGatedToolInvocation, type PersonGateResolution } 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, foldAssistantTurn, issuedOperationId, type RunScope, type WalkAway, } from './turn-client.ts';

package/client/index.js

@@ -0,0 +1,27 @@
+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, outlierThreshold, placeQuery, } from "./embedding-space.js";
+export { createEmbeddingTransport, embeddingInterface, postEmbedding, readEmbeddingReply, } from "./embedding-transport.js";
+export { encodeComposerDraft } from "./encode-composer-draft.js";
+export { encodeFiles, filesToPending, pendingAttachmentsToFiles } from "./encode-files.js";
+export { clientFailure, turnFailure } from "./failure.js";
+export { followGenerationDefaults } from "./generation-selection.js";
+export { createHostTransport, HOST_TOOL_KINDS, hostInterface, } from "./host-transport.js";
+export { pageToolMismatch } from "./live/live-page-tool.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 { sessionAfter, stampWorked } from "./run-commit.js";
+export { keepsConversation, resumeInterfaceTool, streamInterfaceDraftTurn, streamInterfaceTurn, } from "./run-session.js";
+export { blankRow, missingFields, sampleFromSchema, schemaControl, schemaFields, withField, } from "./schema-fields.js";
+export { fieldLabel, fieldReading, humanize, isPlain, isProse, isRow, json, MAX_ROWS, plainReading, rowHeading, shapeOf, splitFields, unpacked, withUnit, } from "./shaped-data.js";
+export { citationsFromBlock, } from "./source-citations.js";
+export { DOT_FLOATS, FRAME_SLOT, queryGeometry, SEGMENT_FLOATS, spaceGeometry, } from "./space-geometry.js";
+export { hasLead, layoutResult, returnedMedia, timeFormats, } 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, foldAssistantTurn, issuedOperationId, } from "./turn-client.js";

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

@@ -0,0 +1,30 @@
+import type { ToolCallEvent, TurnEventOf } from '@theoremjs/agents';
+/** Whether a mic frame should be sent upstream given mute / socket / barge-in gates. */
+export declare function shouldForwardMicFrame(args: {
+    isMuted: boolean;
+    socketOpen: boolean;
+    modelPlaying: boolean;
+    rms: number;
+    bargeInRmsWhileSpeaking: number;
+}): boolean;
+/** Classify live evidence transcription into a UI transcript callback payload. */
+export declare function liveTranscriptFromEvidence(event: TurnEventOf<'evidence'>): {
+    text: string;
+    isUser: boolean;
+    interim: boolean;
+} | null;
+export type LiveToolCallDraft = {
+    operationId?: string;
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+};
+/**
+ * Fold a tool turn event into cancelled-id / runnable-call lists. The model's
+ * call is runnable; a failure in the same batch (a name or arguments the
+ * provider could not use) is not: the session answered the model with it.
+ */
+export declare function applyLiveToolTurnEvent(tool: ToolCallEvent, accum: {
+    cancelledToolIds: Set<string>;
+    toolCalls: LiveToolCallDraft[];
+}): void;

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

@@ -0,0 +1,46 @@
+/** Whether a mic frame should be sent upstream given mute / socket / barge-in gates. */
+export function shouldForwardMicFrame(args) {
+    if (args.isMuted || !args.socketOpen)
+        return false;
+    if (args.modelPlaying && args.rms < args.bargeInRmsWhileSpeaking)
+        return false;
+    return true;
+}
+/** Classify live evidence transcription into a UI transcript callback payload. */
+export function liveTranscriptFromEvidence(event) {
+    const { evidence, text } = event;
+    if (!text)
+        return null;
+    if (evidence.kind !== 'input_transcription' && evidence.kind !== 'output_transcription')
+        return null;
+    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
+ * call is runnable; a failure in the same batch (a name or arguments the
+ * provider could not use) is not: the session answered the model with it.
+ */
+export function applyLiveToolTurnEvent(tool, accum) {
+    if (tool.phase === undefined) {
+        accum.toolCalls.push({
+            id: tool.callId,
+            name: tool.name,
+            arguments: tool.arguments,
+            ...(tool.operationId ? { operationId: tool.operationId } : {}),
+        });
+        return;
+    }
+    if (tool.phase === 'cancel') {
+        accum.cancelledToolIds.add(tool.callId);
+        return;
+    }
+    if (tool.phase !== 'error')
+        return;
+    const failed = accum.toolCalls.findIndex((draft) => draft.id === tool.callId);
+    if (failed !== -1)
+        accum.toolCalls.splice(failed, 1);
+}

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)),
+    };
+}

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

@@ -0,0 +1,13 @@
+export type LiveSessionStatus = 'disconnected' | 'connecting'
+/** The call dropped and the client is taking it up again. */
+ | 'reconnecting' | 'ready' | 'listening' | 'speaking' | 'working' | 'error';
+export type LiveConnectPhase = 'socket' | 'microphone';
+/** What a live call is doing, for its status line; the UI words it. */
+export type LiveState = 'calling_tool' | 'connecting' | 'reconnecting' | 'requesting_mic' | 'speaking' | 'connected' | 'muted' | 'listening' | 'error' | 'ended';
+export declare function liveState(args: {
+    status: LiveSessionStatus;
+    connectPhase: LiveConnectPhase | null;
+    toolName: string | null;
+    isMuted: boolean;
+    voiceEnabled?: boolean;
+}): LiveState;

package/client/live/live-state.js

@@ -0,0 +1,22 @@
+export function liveState(args) {
+    if (args.status === 'reconnecting')
+        return 'reconnecting';
+    if (args.toolName)
+        return 'calling_tool';
+    if (args.connectPhase === 'socket')
+        return 'connecting';
+    if (args.connectPhase === 'microphone')
+        return 'requesting_mic';
+    if (args.status === 'speaking')
+        return 'speaking';
+    if (args.status === 'listening' || args.status === 'ready') {
+        if (args.voiceEnabled === false)
+            return 'connected';
+        return args.isMuted ? 'muted' : 'listening';
+    }
+    if (args.status === 'connecting')
+        return 'connecting';
+    if (args.status === 'error')
+        return 'error';
+    return 'ended';
+}

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

@@ -0,0 +1,11 @@
+import type { ToolGate } from '@theoremjs/agents/kernel';
+import type { ToolGateResolution } from '../tool-resume.ts';
+/** A gate the user is asked to answer, for the model's call `callId`. */
+export type LiveToolGatePrompt = {
+    callId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    gate: ToolGate;
+};
+/** The user's answer to a live gate, or `withdrawn`: the model cancelled the call, so nothing is asked. */
+export type LiveGateAnswer = ToolGateResolution | 'withdrawn';

package/client/live/live-tool.js

@@ -0,0 +1 @@
+export {};

package/client/live-client.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Pure client-side SDK for THEOREM Gemini 3.1 Flash Live sessions over WebSocket relay.
+ *
+ * Handles:
+ * - Bidirectional WebSocket connection to `/api/live/relay`.
+ * - 16-bit 16kHz PCM microphone audio recording & streaming.
+ * - Gapless 24kHz PCM / WAV model voice playback scheduling.
+ * - Barge-in interruption cancellation (instant audio queue flush).
+ * - Quiet-mic gate while model audio plays (reduces false barge-in from speaker bleed).
+ * - UI tool execution and response routing.
+ *
+ * @module
+ */
+import { type SessionEventOf, type TraceRecord } from '@theoremjs/agents';
+import type { LiveConnectPhase, LiveSessionStatus } from './live/live-state.ts';
+import { type ExecuteToolOnRelay, type LiveToolStep } from './live-messages.ts';
+import { type ClientTurnEvent } from './transport.ts';
+export type { LiveConnection, LiveSocket } from './live-messages.ts';
+import type { LiveSocket } from './live-messages.ts';
+export interface LiveClientOptions {
+    profile?: string;
+    /** The host's own JSON for its relay, sent as the open message's `host`. */
+    openMessage?: Record<string, unknown>;
+    /** The value chosen for each of the profile's `inputs.slots`, fixed for the call. */
+    slots?: Record<string, string>;
+    /** What the page tells the agent as the call opens; `setContext` replaces it during the call. */
+    context?: unknown;
+    relayUrl?: string;
+    /** In-process connections reuse the same microphone, playback, and tool client. */
+    createSocket?: () => LiveSocket;
+    /** When false, skip microphone capture; session still receives model audio. */
+    voiceIngress?: boolean;
+    onStatusChange?: (status: LiveSessionStatus) => void;
+    onConnectPhase?: (phase: LiveConnectPhase | null) => void;
+    onTranscript?: (text: string, isUser: boolean, meta?: {
+        interim?: boolean;
+    }) => void;
+    /**
+     * Every event the session sends, `unsupported` for a kind this client does
+     * not know, and `malformed` for one that failed its check (left out; the call goes on).
+     */
+    onTurnEvent?: (event: ClientTurnEvent) => void;
+    /** A trace record the session wrote, when the relay delivers them. */
+    onTrace?: (record: TraceRecord) => void;
+    /** A failure, typed by kind; word it with `clientFailure` and the interface's `labels`. */
+    onError?: (error: Error) => void;
+    /** Provider signalled the upstream session is draining (e.g. goAway). */
+    onSessionClosing?: (timeLeftMs?: number) => void;
+    /**
+     * The provider ended the session after warning it would: not a failure.
+     * `session.message` is the user's line; `session.ended` the close, for the builder.
+     */
+    onSessionEnded?: (session: SessionEventOf<'ended'>) => void;
+    /**
+     * The model called a tool. The host runs it with `executeToolOnRelay` and
+     * answers its gates; the session answers the model. A throw reaches `onError`.
+     */
+    onToolCall: (name: string, args: Record<string, unknown>, meta: {
+        callId: string;
+        operationId: string;
+    }) => Promise<void>;
+    /** The relay opened the call: the id it gave the call, and the profile it runs. */
+    onSessionReady?: (info: {
+        sessionId?: string;
+        profile?: string;
+    }) => void;
+    onVolumeLevel?: (level: number, isUser: boolean) => void;
+}
+export declare class LiveSessionClient {
+    private ws;
+    private audioContext;
+    private micStream;
+    private micSource;
+    private micWorklet;
+    private micWorkletModuleLoaded;
+    private playbackNodes;
+    private playbackBus;
+    private playbackAnalyser;
+    private playbackMeterFrame;
+    private playbackMeterBuffer;
+    private nextPlaybackTime;
+    private status;
+    /** Server reported background work (reasoning / async tools) still in flight. */
+    private serverWorking;
+    private micActivating;
+    private connectTimeout;
+    private isMuted;
+    private options;
+    /** Serialize control-plane handling (tools / status) without waiting on audio decode. */
+    private inboundChain;
+    /** Ordered model-audio playback queue (separate so tools are not stuck behind decode). */
+    private audioChain;
+    /**
+     * Tool calls, one at a time in the order the model made them. Apart from
+     * `inboundChain`: a call waits on the relay's reply, which arrives inbound.
+     */
+    private toolChain;
+    /** Bumped on barge-in / cancel so stale audioChain work is skipped. */
+    private audioEpoch;
+    private pendingExecuteResults;
+    /** The page's context package, and the JSON of the one the relay last got. */
+    private context;
+    private sentContext;
+    /** The provider's latest handle for taking this call up again after a drop. */
+    private history;
+    private providerState;
+    /** The session said it ended, or failed: a close after that is the end, not a drop. */
+    private sessionOver;
+    /** When the call dropped, for the time away a resume reports. */
+    private droppedAt;
+    /** When the call that could not reconnect dropped: the next call takes it up again. */
+    private lostAt;
+    private reconnectTries;
+    private reconnectTimer;
+    constructor(options: LiveClientOptions);
+    private setStatus;
+    /** Still opening: the first connect, or a try at taking a dropped call up again. */
+    private get opening();
+    private setConnectPhase;
+    private clearConnectTimeout;
+    private detachWebSocket;
+    private clearReconnect;
+    private teardownConnection;
+    /** End the session on `error`: a failed connect or a lost socket. */
+    private failSession;
+    private createSocket;
+    /**
+     * Start a call. After one that dropped and could not reconnect, it takes that call up again,
+     * so the agent neither greets twice nor forgets; after a hang-up it is a new call.
+     */
+    connect(): Promise<void>;
+    /** A lost call that cannot be taken up again, its handle refused or expired, starts as a new one. */
+    private startOver;
+    /** The first message: the call's values, and the handle and time away when it takes a dropped call up again. */
+    private openMessage;
+    /** The socket closed while the call was open: take it up again if the provider gave a handle, else end. */
+    private handleDrop;
+    private scheduleReconnect;
+    /** A try at opening failed: a reconnect waits and tries again, a first connect fails the call. */
+    private failOpen;
+    private open;
+    private ensureAudioContext;
+    private activateMicrophone;
+    private sendMicFrame;
+    private reportMicVolume;
+    private forwardMicBuffer;
+    private setupMicrophonePipeline;
+    private ensurePlaybackBus;
+    private stopPlaybackMeter;
+    private startPlaybackMeter;
+    private processServerEnvelope;
+    private enqueueServerMessage;
+    private handleReadyEnvelope;
+    /** The call is open, first or again: the page's context catches up with what changed meanwhile. */
+    private becomeReady;
+    private handleExecuteToolResultEnvelope;
+    private tryHandleControlEnvelope;
+    private collectInboundTurn;
+    private processTurnEvent;
+    private handleEvidenceTurnEvent;
+    private handleSessionTurnEvent;
+    /** Hand the session's closing and end to the host; `true` when it was one of them. */
+    private notifySessionLifecycle;
+    /** Status to settle into once model speech stops. */
+    private restingStatus;
+    private collectMediaTurnEvent;
+    private handleDoneTurnEvent;
+    private scheduleMediaChunks;
+    /** The relay runs `LiveSession.executeTool`; see `ExecuteToolOnRelay`. */
+    executeToolOnRelay(args: Parameters<ExecuteToolOnRelay>[0]): Promise<LiveToolStep>;
+    private enqueueAudioChunk;
+    cancelPlayback(): void;
+    toggleMute(): boolean;
+    sendText(text: string): void;
+    /**
+     * The call's slot values. An open call is taken up again with them when the provider gave a
+     * handle; with none, the next call has them.
+     */
+    setSlots(slots: Record<string, string> | undefined): void;
+    /**
+     * Replace the page's context package. In a call it reaches the agent as
+     * background, with no reply; before one, it goes with the call's opening.
+     */
+    setContext(context: unknown): void;
+    private flushContext;
+    sendVideo(data: string, mimeType?: string): void;
+    disconnect(): void;
+    private cleanupAudio;
+}