@theoremjs/react 0.3.0 → 0.3.1

package/client/live-client.js

@@ -1,3 +1,5 @@
+// why: This is browser code; a Deno program that reaches it through `@theoremjs/react/client` checks it with the DOM.
+/// <reference lib="dom" />
 /**
  * Pure client-side SDK for THEOREM Gemini 3.1 Flash Live sessions over WebSocket relay.
  *
@@ -11,15 +13,16 @@
  *
  * @module
  */
-import { describeError, TheoremError, } from '@theoremjs/agents';
+import { describeError, labelText, TheoremError, } from '@theoremjs/agents';
 import { base64ToBytes, bytesToBase64 } from '@theoremjs/agents/kernel';
 import { float32Rms, float32RmsToLevel, timeDomainBytesToLevel } from "./audio-level.js";
-import { isPermissionDeniedError } from "./live-errors.js";
 import { applyLiveToolTurnEvent, liveTranscriptFromEvidence, shouldForwardMicFrame, } from "./live/live-mic-forward.js";
-import { parseLiveServerEnvelope, } from "./live-messages.js";
+import { isPermissionDeniedError } from "./live-errors.js";
+import { liveClientMessageSchema, parseLiveServerEnvelope, } from "./live-messages.js";
 import { MIC_CAPTURE_PROCESSOR, micCaptureWorkletUrl } from "./mic-capture.js";
 import { downsampleAndConvertToInt16, pcm16BytesToFloat32 } from "./pcm-downsample.js";
 import { hostError } from "./transport.js";
+import { issuedOperationId } from "./turn-client.js";
 /** One message to the relay, in the shape a relay checks with `parseLiveClientMessage`. */
 function clientMessage(message) {
     return JSON.stringify(message);
@@ -38,9 +41,13 @@ function emptyInboundTurnAccum() {
  * fine-grained "less choppy barge-in" knob.
  */
 const BARGE_IN_RMS_WHILE_SPEAKING = 0.05;
+/** How long the client waits before each try at taking a dropped call up again. After the last, the call fails. */
+const LIVE_RECONNECT_DELAYS_MS = [500, 1000, 2000, 4000, 8000];
 /** A caught value as an `Error`; one that is not keeps its text as `internal` detail. */
 function asError(err) {
-    return err instanceof Error ? err : new TheoremError('internal', describeError(err), { cause: err });
+    return err instanceof Error
+        ? err
+        : new TheoremError('internal', describeError(err), { cause: err });
 }
 function safeDisconnect(node) {
     if (!node || typeof node.disconnect !== 'function')
@@ -49,7 +56,7 @@ function safeDisconnect(node) {
         node.disconnect();
     }
     catch {
-        /* ignore */
+        // why: disconnect() throws for a node that is not connected; it is disconnected either way.
     }
 }
 function stopMediaTracks(stream) {
@@ -109,8 +116,23 @@ export class LiveSessionClient {
     /** Bumped on barge-in / cancel so stale audioChain work is skipped. */
     audioEpoch = 0;
     pendingExecuteResults = new Map();
+    /** The page's context package, and the JSON of the one the relay last got. */
+    context;
+    sentContext;
+    /** The provider's latest handle for taking this call up again after a drop. */
+    history = [];
+    providerState;
+    /** The session said it ended, or failed: a close after that is the end, not a drop. */
+    sessionOver = false;
+    /** When the call dropped, for the time away a resume reports. */
+    droppedAt;
+    /** When the call that could not reconnect dropped: the next call takes it up again. */
+    lostAt;
+    reconnectTries = 0;
+    reconnectTimer = null;
     constructor(options) {
         this.options = options;
+        this.context = options.context;
     }
     setStatus(newStatus) {
         this.status = newStatus;
@@ -119,6 +141,10 @@ export class LiveSessionClient {
         }
         this.options.onStatusChange?.(newStatus);
     }
+    /** Still opening: the first connect, or a try at taking a dropped call up again. */
+    get opening() {
+        return this.status === 'connecting' || this.status === 'reconnecting';
+    }
     setConnectPhase(phase) {
         this.options.onConnectPhase?.(phase);
     }
@@ -130,7 +156,7 @@ export class LiveSessionClient {
     }
     detachWebSocket() {
         for (const [callId, pending] of this.pendingExecuteResults) {
-            // lexicon-exempt: internal diagnostic; the user reads error.network
+            // labels-exempt: internal diagnostic; the user reads error.network
             pending.reject(new TheoremError('network', `live session closed before call ${callId} settled`));
         }
         this.pendingExecuteResults.clear();
@@ -144,10 +170,17 @@ export class LiveSessionClient {
             this.ws.close();
         }
         catch {
-            /* ignore */
+            // why: closing a socket that already closed throws; the connection is over either way.
         }
         this.ws = null;
     }
+    clearReconnect() {
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        this.reconnectTries = 0;
+        this.droppedAt = undefined;
+    }
     teardownConnection() {
         this.clearConnectTimeout();
         this.micActivating = false;
@@ -159,6 +192,7 @@ export class LiveSessionClient {
     failSession(error) {
         if (this.status === 'error' || this.status === 'disconnected')
             return;
+        this.clearReconnect();
         this.teardownConnection();
         this.options.onError?.(error);
         this.setStatus('error');
@@ -166,11 +200,93 @@ export class LiveSessionClient {
     createSocket(url) {
         return this.options.createSocket?.() ?? new WebSocket(url);
     }
-    // fallow-ignore-next-line unused-class-member -- called from useLiveRunnerControls via client refs
-    async connect() {
+    /**
+     * 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() {
+        const lostAt = this.lostAt;
+        this.clearReconnect();
+        this.lostAt = undefined;
+        if (lostAt === undefined) {
+            this.providerState = undefined;
+            this.history = [];
+        }
+        else
+            this.droppedAt = lostAt;
+        return this.open('connecting');
+    }
+    /** A lost call that cannot be taken up again, its handle refused or expired, starts as a new one. */
+    startOver() {
+        if (this.status !== 'connecting' || !this.providerState)
+            return false;
+        this.providerState = undefined;
+        this.droppedAt = undefined;
+        void this.open('connecting');
+        return true;
+    }
+    /** The first message: the call's values, and the handle and time away when it takes a dropped call up again. */
+    openMessage() {
+        const { slots, openMessage: host } = this.options;
+        return {
+            type: 'open',
+            ...(this.history.length ? { history: structuredClone(this.history) } : {}),
+            ...(slots ? { slots } : {}),
+            ...(this.context === undefined ? {} : { context: this.context }),
+            ...(this.providerState
+                ? {
+                    resume: {
+                        providerState: this.providerState,
+                        awayMs: this.droppedAt === undefined ? 0 : Date.now() - this.droppedAt,
+                    },
+                }
+                : {}),
+            ...(host ? { host } : {}),
+        };
+    }
+    /** The socket closed while the call was open: take it up again if the provider gave a handle, else end. */
+    handleDrop() {
+        if (!this.providerState || this.sessionOver) {
+            this.teardownConnection();
+            this.setStatus('disconnected');
+            return;
+        }
+        this.droppedAt ??= Date.now();
         this.teardownConnection();
-        this.setStatus('connecting');
-        this.setConnectPhase('socket');
+        this.setStatus('reconnecting');
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        const delay = LIVE_RECONNECT_DELAYS_MS[this.reconnectTries];
+        if (delay === undefined) {
+            const droppedAt = this.droppedAt;
+            // labels-exempt: internal diagnostic; the user reads error.network
+            this.failSession(new TheoremError('network', 'live call dropped and could not reconnect'));
+            this.lostAt = droppedAt;
+            return;
+        }
+        this.reconnectTries += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.open('reconnecting');
+        }, delay);
+    }
+    /** A try at opening failed: a reconnect waits and tries again, a first connect fails the call. */
+    failOpen(error) {
+        if (this.status !== 'reconnecting') {
+            if (!this.startOver())
+                this.failSession(error);
+            return;
+        }
+        this.teardownConnection();
+        this.scheduleReconnect();
+    }
+    async open(as) {
+        this.teardownConnection();
+        this.sessionOver = false;
+        this.setStatus(as);
+        if (as === 'connecting')
+            this.setConnectPhase('socket');
         try {
             const AudioContextClass = globalThis.AudioContext;
             this.audioContext = new AudioContextClass();
@@ -185,37 +301,39 @@ export class LiveSessionClient {
             const url = this.options.relayUrl || defaultUrl;
             this.ws = this.createSocket(url);
             this.ws.binaryType = 'arraybuffer';
-            const { openMessage } = this.options;
-            if (openMessage) {
-                this.ws.onopen = () => {
-                    this.ws?.send(JSON.stringify(openMessage));
-                };
-            }
+            this.ws.onopen = () => {
+                const open = this.openMessage();
+                this.sentContext = JSON.stringify(open.context);
+                this.ws?.send(JSON.stringify(open));
+            };
             this.connectTimeout = setTimeout(() => {
-                if (this.status === 'connecting') {
-                    // lexicon-exempt: internal diagnostic; the user reads error.timeout
-                    this.failSession(new TheoremError('timeout', 'live connect timed out'));
+                if (this.opening) {
+                    // labels-exempt: internal diagnostic; the user reads error.timeout
+                    this.failOpen(new TheoremError('timeout', 'live connect timed out'));
                 }
             }, 20_000);
             this.ws.onmessage = (event) => {
                 this.enqueueServerMessage(event.data);
             };
             this.ws.onclose = () => {
-                if (this.status === 'connecting') {
-                    // lexicon-exempt: internal diagnostic; the user reads error.network
-                    this.failSession(new TheoremError('network', 'live socket closed before ready'));
+                if (this.opening) {
+                    // labels-exempt: internal diagnostic; the user reads error.network
+                    this.failOpen(new TheoremError('network', 'live socket closed before ready'));
                     return;
                 }
-                this.teardownConnection();
-                this.setStatus('disconnected');
+                this.handleDrop();
             };
             this.ws.onerror = () => {
-                // lexicon-exempt: internal diagnostic; the user reads error.network
-                this.failSession(new TheoremError('network', 'live socket error'));
+                if (!this.opening && this.providerState && !this.sessionOver) {
+                    this.handleDrop();
+                    return;
+                }
+                // labels-exempt: internal diagnostic; the user reads error.network
+                this.failOpen(new TheoremError('network', 'live socket error'));
             };
         }
         catch (err) {
-            this.failSession(new TheoremError('internal', describeError(err), { cause: err }));
+            this.failOpen(new TheoremError('internal', describeError(err), { cause: err }));
         }
     }
     async ensureAudioContext() {
@@ -228,10 +346,11 @@ export class LiveSessionClient {
         }
     }
     async activateMicrophone() {
-        if (this.micActivating || this.status !== 'connecting')
+        if (this.micActivating || !this.opening)
             return;
         this.micActivating = true;
-        this.setConnectPhase('microphone');
+        if (this.status === 'connecting')
+            this.setConnectPhase('microphone');
         try {
             await this.ensureAudioContext();
             this.micStream = await navigator.mediaDevices.getUserMedia({
@@ -243,8 +362,7 @@ export class LiveSessionClient {
                 },
             });
             await this.setupMicrophonePipeline();
-            this.setConnectPhase(null);
-            this.setStatus('listening');
+            this.becomeReady();
         }
         catch (err) {
             const denied = isPermissionDeniedError(err);
@@ -344,7 +462,9 @@ export class LiveSessionClient {
         const runnableTools = accum.toolCalls.filter((call) => !accum.cancelledToolIds.has(call.id));
         for (const call of runnableTools) {
             this.toolChain = this.toolChain
-                .then(() => this.options.onToolCall(call.name, call.arguments, { callId: call.id,
+                .then(() => this.options.onToolCall(call.name, call.arguments, {
+                callId: call.id,
+                operationId: issuedOperationId(call),
             }))
                 .catch((err) => {
                 this.options.onError?.(asError(err));
@@ -358,7 +478,7 @@ export class LiveSessionClient {
             if (typeof data !== 'string')
                 return;
             const payload = parseLiveServerEnvelope(data);
-            // An envelope the client can't use reaches onTurnEvent like any event; the call goes on.
+            // why: An envelope the client can't use reaches onTurnEvent like any event; the call goes on.
             if (payload.type === 'unsupported' || payload.type === 'malformed') {
                 this.options.onTurnEvent?.(payload);
             }
@@ -375,21 +495,34 @@ export class LiveSessionClient {
             profile: payload.profile,
         });
         if (this.options.voiceIngress === false) {
-            this.setConnectPhase(null);
-            this.setStatus('listening');
+            this.becomeReady();
         }
         else {
             await this.activateMicrophone();
         }
     }
+    /** The call is open, first or again: the page's context catches up with what changed meanwhile. */
+    becomeReady() {
+        this.clearReconnect();
+        this.setConnectPhase(null);
+        this.setStatus('listening');
+        this.flushContext();
+    }
     handleExecuteToolResultEnvelope(payload) {
-        const pending = this.pendingExecuteResults.get(payload.callId);
-        if (!pending)
+        const pending = this.pendingExecuteResults.get(payload.operationId);
+        if (!pending || pending.callId !== payload.callId)
             return;
-        this.pendingExecuteResults.delete(payload.callId);
+        this.pendingExecuteResults.delete(payload.operationId);
         if (payload.status === 'refused') {
             pending.reject(hostError(payload.body, 'request'));
         }
+        else if (payload.status === 'dispatched') {
+            pending.resolve({
+                status: 'dispatched',
+                grantId: payload.grantId,
+                arguments: payload.arguments,
+            });
+        }
         else if (payload.status === 'gated') {
             pending.resolve({ status: 'gated', gate: payload.gate });
         }
@@ -410,7 +543,9 @@ export class LiveSessionClient {
             return true;
         }
         if (payload.type === 'error') {
-            // The relay's kind and wording when it sent them, else `unavailable`.
+            if (this.startOver())
+                return true;
+            this.sessionOver = true;
             this.options.onError?.(hostError(payload, 'unavailable'));
             this.setStatus('error');
             return true;
@@ -425,6 +560,12 @@ export class LiveSessionClient {
         return accum;
     }
     processTurnEvent(event, accum) {
+        if (event.type === 'provider_checkpoint' && event.history)
+            this.history = structuredClone(event.history);
+        if ((event.type === 'provider_checkpoint' || event.type === 'done') && event.providerState)
+            this.providerState = event.providerState;
+        if (event.type === 'provider_warning')
+            this.providerState = undefined;
         this.options.onTurnEvent?.(event);
         switch (event.type) {
             case 'evidence':
@@ -447,7 +588,8 @@ export class LiveSessionClient {
     handleEvidenceTurnEvent(event) {
         const transcript = liveTranscriptFromEvidence(event);
         if (transcript) {
-            this.options.onTranscript?.(transcript.text, transcript.isUser, { interim: transcript.interim,
+            this.options.onTranscript?.(transcript.text, transcript.isUser, {
+                interim: transcript.interim,
             });
         }
     }
@@ -467,6 +609,13 @@ export class LiveSessionClient {
         }
         if (session.kind !== 'ended')
             return false;
+        // why: The provider ends a call at its time limit. With a handle the call is taken up
+        // again, so the person is not told it ended.
+        if (this.providerState) {
+            this.handleDrop();
+            return true;
+        }
+        this.sessionOver = true;
         this.options.onSessionEnded?.(session);
         return true;
     }
@@ -510,14 +659,32 @@ export class LiveSessionClient {
     }
     /** The relay runs `LiveSession.executeTool`; see `ExecuteToolOnRelay`. */
     executeToolOnRelay(args) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
-            throw new TheoremError('request', 'live session is not connected'); // lexicon-exempt: internal diagnostic
-        }
-        const resultPromise = new Promise((resolve, reject) => {
-            this.pendingExecuteResults.set(args.callId, { resolve, reject });
+        const socket = this.ws;
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+            throw new TheoremError('request', 'live session is not connected'); // labels-exempt: internal diagnostic
+        }
+        const checked = liveClientMessageSchema.safeParse({ ...args, type: 'executeTool' });
+        if (!checked.success || checked.data.type !== 'executeTool') {
+            throw new TheoremError('request', labelText('error.request'));
+        }
+        const request = checked.data;
+        if (this.pendingExecuteResults.has(request.operationId)) {
+            throw new TheoremError('request', labelText('session.gate_expired'));
+        }
+        return new Promise((resolve, reject) => {
+            this.pendingExecuteResults.set(request.operationId, {
+                callId: request.callId,
+                resolve,
+                reject,
+            });
+            try {
+                socket.send(clientMessage(request));
+            }
+            catch (error) {
+                this.pendingExecuteResults.delete(request.operationId);
+                reject(asError(error));
+            }
         });
-        this.ws.send(clientMessage({ type: 'executeTool', ...args }));
-        return resultPromise;
     }
     async enqueueAudioChunk(base64Data, mimeType) {
         if (!this.audioContext)
@@ -533,7 +700,7 @@ export class LiveSessionClient {
                 audioBuffer = await this.audioContext.decodeAudioData(wavBuffer);
             }
             else {
-                // Raw PCM 24kHz 1-channel 16-bit LE
+                // why: Raw PCM 24kHz 1-channel 16-bit LE
                 const float32 = pcm16BytesToFloat32(bytes);
                 audioBuffer = this.audioContext.createBuffer(1, float32.length, 24000);
                 audioBuffer.getChannelData(0).set(float32);
@@ -572,7 +739,7 @@ export class LiveSessionClient {
                 node.disconnect();
             }
             catch {
-                /* ignore */
+                // why: a node that already stopped throws on stop() and disconnect(); it leaves the list either way.
             }
         }
         this.playbackNodes = [];
@@ -581,31 +748,53 @@ export class LiveSessionClient {
             this.nextPlaybackTime = this.audioContext.currentTime;
         }
     }
-    // fallow-ignore-next-line unused-class-member -- called from useLiveRunnerControls via client refs
     toggleMute() {
         this.isMuted = !this.isMuted;
         return this.isMuted;
     }
-    // fallow-ignore-next-line unused-class-member -- called from useLiveRunnerControls via client refs
     sendText(text) {
         if (this.ws && this.ws.readyState === WebSocket.OPEN) {
             this.ws.send(clientMessage({ type: 'text', text }));
         }
     }
-    // fallow-ignore-next-line unused-class-member -- called by hosts that tell the model where the visitor is
-    sendContext(text) {
-        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-            this.ws.send(clientMessage({ type: 'context', text }));
+    /**
+     * 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) {
+        if (JSON.stringify(slots) === JSON.stringify(this.options.slots))
+            return;
+        this.options = { ...this.options, slots };
+        if (this.providerState && !this.opening && this.ws?.readyState === WebSocket.OPEN) {
+            this.handleDrop();
         }
     }
-    // fallow-ignore-next-line unused-class-member -- called from useLiveRunnerControls via client refs
+    /**
+     * 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) {
+        this.context = context;
+        this.flushContext();
+    }
+    flushContext() {
+        if (this.opening || this.ws?.readyState !== WebSocket.OPEN)
+            return;
+        const next = JSON.stringify(this.context);
+        if (next === this.sentContext)
+            return;
+        this.sentContext = next;
+        this.ws.send(clientMessage({ type: 'context', context: this.context }));
+    }
     sendVideo(data, mimeType = 'image/jpeg') {
         if (this.ws && this.ws.readyState === WebSocket.OPEN) {
             this.ws.send(clientMessage({ type: 'video', data, mimeType }));
         }
     }
-    // fallow-ignore-next-line unused-class-member -- called from useLiveSessionClient teardown
     disconnect() {
+        this.clearReconnect();
+        this.lostAt = undefined;
+        this.providerState = undefined;
         this.teardownConnection();
         this.setStatus('disconnected');
     }
@@ -630,9 +819,11 @@ export class LiveSessionClient {
                 void this.audioContext.close();
             }
             catch {
-                /* ignore */
+                // why: close() throws on a context that already closed.
             }
             this.audioContext = null;
+            // why: A worklet module belongs to its context; the next context loads it again.
+            this.micWorkletModuleLoaded = false;
         }
     }
 }

package/client/live-messages.d.ts

@@ -1,3 +1,4 @@
+import { type ProviderCheckpoint } from '@theoremjs/agents';
 /**
  * The live wire between the browser and a host's relay: the messages the live
  * client sends (a relay reads them with `parseLiveClientMessage`) and the envelopes it reads
@@ -5,10 +6,31 @@
  *
  * @module
  */
-import { type GateDecision, type ToolGate, type TraceRecord, type TurnEvent, z } from '@theoremjs/agents';
+import { type GateDecision, type ToolGate, type TraceRecord, type TurnEvent, type TurnHistoryMessage, z } from '@theoremjs/agents';
 import { type HostErrorBody } from './transport.ts';
 import { type MalformedEvent, type UnsupportedEvent } from './wire-line.ts';
-/** What the live client sends its relay, besides the host's own `openMessage`. */
+/**
+ * The live client's first message, before the relay opens the session: the
+ * values the call starts with. A relay reads it with `parseLiveOpenMessage`.
+ */
+export type LiveOpenMessage = {
+    type: 'open';
+    history?: TurnHistoryMessage[];
+    /** The value chosen for each of the profile's `inputs.slots`. */
+    slots?: Record<string, string>;
+    /** What the page tells the agent as the call opens: the client's context package. */
+    context?: unknown;
+    /** A call that dropped, taken up again: the provider's handle, and how long the caller was away. */
+    resume?: {
+        providerState: ProviderCheckpoint;
+        awayMs: number;
+    };
+    /** The host's own `openMessage`, for its relay to read. */
+    host?: Record<string, unknown>;
+};
+/** The live client's first message, as `parseLiveOpenMessage` checks it for a relay. */
+export declare const liveOpenMessageSchema: z.ZodType<LiveOpenMessage>;
+/** What the live client sends its relay once the call is open. */
 export type LiveClientMessage = {
     type: 'audio';
     data: string;
@@ -20,20 +42,23 @@ export type LiveClientMessage = {
     type: 'text';
     text: string;
 }
-/** Background the model reads without replying: the page the visitor is on, say. */
+/** The page's context package, replacing the last: background the model reads without replying. */
  | {
     type: 'context';
-    text: string;
+    context: unknown;
 }
-/** Run a call the model made, by its id; the live session holds its name, input and gate. */
+/** Run a call the model made, by its id; the live session holds its name, input, and gate. */
  | {
     type: 'executeTool';
     callId: string;
+    operationId: string;
     decision?: GateDecision;
     input?: unknown;
     secret?: string;
-    /** What the browser did for a tool that runs there; a relay hands it to the tool as `host.clientOutput`. */
+    /** What the browser did for a tool that runs there; a relay hands it to the session as `page.output`. */
     output?: unknown;
+    grantId?: string;
+    unanswered?: true;
 };
 /** The live client's messages, as `parseLiveClientMessage` checks them for a relay. */
 export declare const liveClientMessageSchema: z.ZodType<LiveClientMessage>;
@@ -48,7 +73,7 @@ export type LiveServerEnvelope = {
     type: 'events';
     events: (TurnEvent | UnsupportedEvent | MalformedEvent)[];
 }
-/** A trace record the session wrote, from a relay that delivers its traces (the playground). */
+/** A trace record the session wrote, from a relay that delivers its traces (the studio). */
  | {
     type: 'trace';
     record: TraceRecord;
@@ -65,15 +90,25 @@ export type LiveServerEnvelope = {
  | {
     type: 'executeToolResult';
     callId: string;
+    operationId: string;
     status: 'settled';
 } | {
     type: 'executeToolResult';
     callId: string;
+    operationId: string;
+    status: 'dispatched';
+    grantId: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'executeToolResult';
+    callId: string;
+    operationId: string;
     status: 'gated';
     gate: ToolGate;
 } | {
     type: 'executeToolResult';
     callId: string;
+    operationId: string;
     status: 'refused';
     body: HostErrorBody;
 };
@@ -89,22 +124,25 @@ export type LiveToolStep = {
 } | {
     status: 'gated';
     gate: ToolGate;
+} | {
+    status: 'dispatched';
+    grantId: string;
+    arguments: Record<string, unknown>;
 };
 /**
  * Ask the relay to run `LiveSession.executeTool` for a call the model made.
  * `decision` answers its gate; `input` is the user's edit to an approval;
  * `secret` is the key the user typed at a sign-in gate, sent once: the
  * session makes it the credential for the gate's slot. `output` is the
- * browser's result for a tool that runs in the page (see `browserToolHandler`).
+ * browser's result for a tool the page answers (`answeredBy: 'page'`).
  */
 export type ExecuteToolOnRelay = (args: Omit<Extract<LiveClientMessage, {
     type: 'executeTool';
 }>, 'type'>) => Promise<LiveToolStep>;
 export type LiveSocket = Pick<WebSocket, 'readyState' | 'binaryType' | 'send' | 'close' | 'onopen' | 'onmessage' | 'onclose' | 'onerror'>;
-export type LiveConnection = ({
-    profile: string;
-} | {
-    openMessage: Record<string, unknown>;
-}) & {
+/** What a call connects to: a profile the relay knows by id, or the host's own message for its relay. */
+export type LiveConnection = {
+    profile?: string;
+    openMessage?: Record<string, unknown>;
     createSocket?: () => LiveSocket;
 };