@theoremjs/react 0.0.0-stage → 0.3.1

package/client/live-errors.d.ts

@@ -0,0 +1,2 @@
+/** Whether a DOM/media error indicates the user denied microphone access. */
+export declare function isPermissionDeniedError(err: unknown): boolean;

package/client/live-errors.js

@@ -0,0 +1,9 @@
+/** Whether a DOM/media error indicates the user denied microphone access. */
+export function isPermissionDeniedError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const name = 'name' in err && typeof err.name === 'string' ? err.name : '';
+    return (name === 'NotAllowedError' ||
+        name === 'PermissionDeniedError' ||
+        /permission|not allowed|denied/i.test(err.message));
+}

package/client/live-messages.d.ts

@@ -0,0 +1,148 @@
+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
+ * back, each checked against its schema.
+ *
+ * @module
+ */
+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';
+/**
+ * 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;
+} | {
+    type: 'video';
+    data: string;
+    mimeType: string;
+} | {
+    type: 'text';
+    text: string;
+}
+/** The page's context package, replacing the last: background the model reads without replying. */
+ | {
+    type: 'context';
+    context: unknown;
+}
+/** 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 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>;
+/** The envelopes a relay sends the live client. */
+export type LiveServerEnvelope = {
+    type: 'ready';
+    profile?: string;
+    sessionId?: string;
+}
+/** The session's events; one of a kind this client does not know arrives as `unsupported`, one that fails its check as `malformed`. */
+ | {
+    type: 'events';
+    events: (TurnEvent | UnsupportedEvent | MalformedEvent)[];
+}
+/** A trace record the session wrote, from a relay that delivers its traces (the studio). */
+ | {
+    type: 'trace';
+    record: TraceRecord;
+}
+/** The relay's error body, read as a host error. */
+ | ({
+    type: 'error';
+} & HostErrorBody)
+/**
+ * The relay's answer to the browser's `executeTool`: the session settled the
+ * call (its tool events carry what happened), holds it on a gate, or refused
+ * the message (the relay's error body, read as a host error).
+ */
+ | {
+    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;
+};
+/**
+ * One envelope's text from the relay, checked: an envelope or event of a kind
+ * this client does not know is `unsupported`, and one that fails its check is
+ * `malformed`. A malformed event leaves the envelope's other events standing.
+ */
+export declare function parseLiveServerEnvelope(text: string): LiveServerEnvelope | UnsupportedEvent | MalformedEvent;
+/** What the session did with an `executeTool`: settled the call, or holds it on a gate. */
+export type LiveToolStep = {
+    status: 'settled';
+} | {
+    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 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'>;
+/** 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;
+};

package/client/live-messages.js

@@ -0,0 +1,100 @@
+import { providerCheckpointSchema } 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
+ * back, each checked against its schema.
+ *
+ * @module
+ */
+import { GATE_DECISIONS, TURN_EVENT_SCHEMAS, toolGateSchema, traceRecordSchema, turnHistoryMessageSchema, z, } from '@theoremjs/agents';
+import { hostErrorBodySchema } from "./transport.js";
+import { readWireLine, readWireValue, } from "./wire-line.js";
+const liveOpenMessage = z.object({
+    type: z.literal('open'),
+    history: z.array(turnHistoryMessageSchema).optional(),
+    slots: z.record(z.string(), z.string()).optional(),
+    context: z.unknown().optional(),
+    resume: z
+        .object({ providerState: providerCheckpointSchema, awayMs: z.number().nonnegative() })
+        .optional(),
+    host: z.record(z.string(), z.unknown()).optional(),
+});
+true;
+/** The live client's first message, as `parseLiveOpenMessage` checks it for a relay. */
+export const liveOpenMessageSchema = liveOpenMessage;
+const liveClientMessage = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('audio'), data: z.string() }),
+    z.object({ type: z.literal('video'), data: z.string(), mimeType: z.string() }),
+    z.object({ type: z.literal('text'), text: z.string() }),
+    z.object({ type: z.literal('context'), context: z.unknown() }),
+    z.object({
+        type: z.literal('executeTool'),
+        callId: z.string().min(1),
+        operationId: z.string().min(1).max(256),
+        decision: z.enum(GATE_DECISIONS).optional(),
+        input: z.unknown().optional(),
+        secret: z.string().optional(),
+        output: z.unknown().optional(),
+        grantId: z.string().min(1).optional(),
+        unanswered: z.literal(true).optional(),
+    }),
+]);
+true;
+/** The live client's messages, as `parseLiveClientMessage` checks them for a relay. */
+export const liveClientMessageSchema = liveClientMessage;
+const liveServerEnvelopeKinds = {
+    ready: z.object({
+        type: z.literal('ready'),
+        profile: z.string().optional(),
+        sessionId: z.string().optional(),
+    }),
+    events: z.object({ type: z.literal('events'), events: z.array(z.unknown()) }),
+    trace: z.object({ type: z.literal('trace'), record: traceRecordSchema }),
+    error: z.object({ type: z.literal('error') }).and(hostErrorBodySchema),
+    executeToolResult: z.discriminatedUnion('status', [
+        z.object({
+            type: z.literal('executeToolResult'),
+            callId: z.string().min(1),
+            operationId: z.string().min(1).max(256),
+            status: z.literal('dispatched'),
+            grantId: z.string().min(1),
+            arguments: z.record(z.string(), z.unknown()),
+        }),
+        z.object({
+            type: z.literal('executeToolResult'),
+            callId: z.string(),
+            status: z.literal('settled'),
+            operationId: z.string().min(1).max(256),
+        }),
+        z.object({
+            type: z.literal('executeToolResult'),
+            callId: z.string(),
+            status: z.literal('gated'),
+            operationId: z.string().min(1).max(256),
+            gate: toolGateSchema,
+        }),
+        z.object({
+            type: z.literal('executeToolResult'),
+            callId: z.string(),
+            status: z.literal('refused'),
+            operationId: z.string().min(1).max(256),
+            body: hostErrorBodySchema,
+        }),
+    ]),
+};
+true;
+const liveServerEnvelopeLines = liveServerEnvelopeKinds;
+/**
+ * One envelope's text from the relay, checked: an envelope or event of a kind
+ * this client does not know is `unsupported`, and one that fails its check is
+ * `malformed`. A malformed event leaves the envelope's other events standing.
+ */
+export function parseLiveServerEnvelope(text) {
+    const envelope = readWireLine(liveServerEnvelopeLines, text);
+    if (envelope.type !== 'events')
+        return envelope;
+    return {
+        type: 'events',
+        events: envelope.events.map((event) => readWireValue(TURN_EVENT_SCHEMAS, event)),
+    };
+}

package/client/mic-capture.d.ts

@@ -0,0 +1,4 @@
+/** The processor name `worklets/mic-capture.js` registers, for `AudioWorkletNode`. */
+export declare const MIC_CAPTURE_PROCESSOR = "mic-capture-processor";
+/** The worklet module for `audioWorklet.addModule`; bundlers ship it as an asset. */
+export declare function micCaptureWorkletUrl(): URL;

package/client/mic-capture.js

@@ -0,0 +1,6 @@
+/** The processor name `worklets/mic-capture.js` registers, for `AudioWorkletNode`. */
+export const MIC_CAPTURE_PROCESSOR = 'mic-capture-processor';
+/** The worklet module for `audioWorklet.addModule`; bundlers ship it as an asset. */
+export function micCaptureWorkletUrl() {
+    return new URL('./worklets/mic-capture.js', import.meta.url);
+}

package/client/oauth-popup.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The OAuth sign-in popup's word back to the chat that opened it.
+ *
+ * The host's callback route saves the token on the server, then its page calls
+ * `notifyOAuthComplete(slot)`. The chat takes the message only from the popup
+ * it opened, on its own origin, for the slot its gate waits for, and resumes
+ * the gate: no token ever reaches the browser.
+ *
+ * @module
+ */
+/**
+ * Tell the chat that opened this popup that `slot`'s token is saved. Call it on
+ * the callback page once the credential is in the host's credential store. On a
+ * page no chat opened, it does nothing.
+ */
+export declare function notifyOAuthComplete(slot: string): void;
+/** The message is `popup`'s, from `origin` (the chat page's own), saying `slot` is signed in. */
+export declare function isOAuthComplete(event: {
+    data: unknown;
+    source: unknown;
+    origin: string;
+}, expected: {
+    popup: unknown;
+    slot: string;
+    origin: string;
+}): boolean;

package/client/oauth-popup.js

@@ -0,0 +1,30 @@
+/**
+ * The OAuth sign-in popup's word back to the chat that opened it.
+ *
+ * The host's callback route saves the token on the server, then its page calls
+ * `notifyOAuthComplete(slot)`. The chat takes the message only from the popup
+ * it opened, on its own origin, for the slot its gate waits for, and resumes
+ * the gate: no token ever reaches the browser.
+ *
+ * @module
+ */
+import { isRecord } from '@theoremjs/agents/kernel';
+const OAUTH_COMPLETE = 'theorem.oauth_complete';
+/**
+ * Tell the chat that opened this popup that `slot`'s token is saved. Call it on
+ * the callback page once the credential is in the host's credential store. On a
+ * page no chat opened, it does nothing.
+ */
+export function notifyOAuthComplete(slot) {
+    const opener = Reflect.get(globalThis, 'opener');
+    if (!isRecord(opener) || typeof opener.postMessage !== 'function')
+        return;
+    opener.postMessage({ type: OAUTH_COMPLETE, slot }, globalThis.location.origin);
+}
+/** The message is `popup`'s, from `origin` (the chat page's own), saying `slot` is signed in. */
+export function isOAuthComplete(event, expected) {
+    if (event.source !== expected.popup || event.origin !== expected.origin)
+        return false;
+    const data = event.data;
+    return isRecord(data) && data.type === OAUTH_COMPLETE && data.slot === expected.slot;
+}

package/client/page-dispatch.d.ts

@@ -0,0 +1,15 @@
+import type { HostTransport } from './host-transport.ts';
+import type { PageTools } from './live/live-page-tool.ts';
+import type { TheoremTransport } from './transport.ts';
+export type PageDispatchResult = {
+    callId: string;
+    operationId: string;
+    grantId: string;
+    page: {
+        output: unknown;
+    } | {
+        unanswered: true;
+    };
+};
+export declare function withPageToolDispatch(transport: TheoremTransport, tools?: PageTools): TheoremTransport;
+export declare function withPageToolDispatch(transport: HostTransport, tools?: PageTools): HostTransport;

package/client/page-dispatch.js

@@ -0,0 +1,63 @@
+import { errorKind, publicError } from '@theoremjs/agents';
+export function withPageToolDispatch(transport, tools) {
+    const sink = (onEvent, signal) => {
+        const dispatched = new Set();
+        return (event) => {
+            onEvent(event);
+            if (event.type !== 'tool' || event.tool.phase !== 'dispatch')
+                return;
+            const { tool } = event;
+            if (!transport.pageResult || !tool.operationId || signal?.aborted)
+                return;
+            const key = JSON.stringify([tool.operationId, tool.grantId]);
+            if (dispatched.has(key))
+                return;
+            dispatched.add(key);
+            const callback = tools && Object.hasOwn(tools, tool.name) ? tools[tool.name] : undefined;
+            const reference = {
+                callId: tool.callId,
+                operationId: tool.operationId,
+                grantId: tool.grantId,
+            };
+            void Promise.resolve()
+                .then(async () => {
+                if (signal?.aborted)
+                    return;
+                const page = callback
+                    ? await Promise.resolve()
+                        .then(() => callback(tool.arguments, reference))
+                        .catch(() => ({ unanswered: true }))
+                    : { unanswered: true };
+                await transport.pageResult?.({ ...reference, page }, signal);
+            })
+                .catch((error) => {
+                if (!signal?.aborted)
+                    onEvent({ type: 'error', errorKind: errorKind(error), error: publicError(error) });
+            });
+        };
+    };
+    // why: A chat's stream also carries the conversation's ref, which no page tool reads.
+    const chatSink = (onLine, signal) => {
+        const events = sink(onLine, signal);
+        return (line) => (line.type === 'conversation' ? onLine(line) : events(line));
+    };
+    if ('call' in transport) {
+        const host = {
+            ...transport,
+            describe: transport.describe.bind(transport),
+            invoke: (request, onEvent, signal) => transport.invoke(request, sink(onEvent, signal), signal),
+            call: (request, onEvent, signal) => transport.call(request, sink(onEvent, signal), signal),
+        };
+        return host;
+    }
+    const chat = {
+        ...transport,
+        describe: transport.describe.bind(transport),
+        invoke: (request, onLine, signal) => transport.invoke(request, chatSink(onLine, signal), signal),
+        turn: (request, onLine, signal) => transport.turn(request, chatSink(onLine, signal), signal),
+        steer: transport.steer.bind(transport),
+        conversation: transport.conversation.bind(transport),
+        rewind: transport.rewind.bind(transport),
+    };
+    return chat;
+}

package/client/pcm-downsample.d.ts

@@ -0,0 +1,4 @@
+/** Resample Float32 audio buffer from inputRate to outputRate and convert to Int16 PCM. */
+export declare function downsampleAndConvertToInt16(inputData: Float32Array, inputRate: number, outputRate?: number): Int16Array;
+/** Decode little-endian PCM16 bytes to Float32 samples in [-1, 1]. */
+export declare function pcm16BytesToFloat32(bytes: Uint8Array<ArrayBufferLike>): Float32Array;

package/client/pcm-downsample.js

@@ -0,0 +1,45 @@
+/** Resample Float32 audio buffer from inputRate to outputRate and convert to Int16 PCM. */
+export function downsampleAndConvertToInt16(inputData, inputRate, outputRate = 16000) {
+    if (inputRate === outputRate) {
+        return float32ToInt16(inputData);
+    }
+    const ratio = inputRate / outputRate;
+    const newLength = Math.round(inputData.length / ratio);
+    const result = new Int16Array(newLength);
+    let offsetResult = 0;
+    let offsetInput = 0;
+    while (offsetResult < result.length) {
+        const nextOffsetInput = Math.round((offsetResult + 1) * ratio);
+        let accum = 0;
+        let count = 0;
+        for (let i = offsetInput; i < nextOffsetInput && i < inputData.length; i++) {
+            accum += inputData[i] ?? 0;
+            count++;
+        }
+        result[offsetResult] = floatSampleToInt16(count > 0 ? accum / count : 0);
+        offsetResult++;
+        offsetInput = nextOffsetInput;
+    }
+    return result;
+}
+function float32ToInt16(inputData) {
+    const result = new Int16Array(inputData.length);
+    for (let i = 0; i < inputData.length; i++) {
+        result[i] = floatSampleToInt16(inputData[i] ?? 0);
+    }
+    return result;
+}
+function floatSampleToInt16(val) {
+    const s = Math.max(-1, Math.min(1, val));
+    return s < 0 ? s * 0x8000 : s * 0x7fff;
+}
+/** Decode little-endian PCM16 bytes to Float32 samples in [-1, 1]. */
+export function pcm16BytesToFloat32(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const float32 = new Float32Array(bytes.byteLength / 2);
+    for (let i = 0; i < float32.length; i++) {
+        const sample = view.getInt16(i * 2, true);
+        float32[i] = sample / (sample < 0 ? 0x8000 : 0x7fff);
+    }
+    return float32;
+}

package/client/run-commit.d.ts

@@ -0,0 +1,34 @@
+import type { TheoremError, TurnEvent } from '@theoremjs/agents';
+import { type ComposerProfileInterface, type InterfaceTurnSession, type TranscriptBlock } from '@theoremjs/agents/interface';
+import type { ChatLineSink, ConversationLine } from './transport.ts';
+/**
+ * The session once a reply's events are in: a reply that waits on a gate
+ * keeps its events beside the transcript until the gate settles; any other is over.
+ */
+export declare function sessionAfter(session: InterfaceTurnSession, events: readonly TurnEvent[]): InterfaceTurnSession;
+/** Where a run shows itself as it streams: the reply so far, and each line the stream left out. */
+export type StreamView = {
+    blocks(blocks: TranscriptBlock[]): void;
+    /** A `malformed` line: left out, and the reply goes on. */
+    skipped(error: TheoremError): void;
+};
+/**
+ * Streams into `events`, which the caller owns, so a stream that fails still
+ * leaves what it delivered. A `conversation` line goes to `onConversation`. An
+ * `unsupported` line is the host's to read on its own transport, and a
+ * `malformed` one goes to `view.skipped`: neither enters the reply.
+ */
+export declare function streamFoldedTurn(args: {
+    iface: ComposerProfileInterface;
+    view: StreamView;
+    /** Seeded by the caller, and filled as the stream delivers. */
+    events: TurnEvent[];
+    /** The page adopts each ref from its transport; a run reads them only to know its message posted. */
+    onConversation?(line: ConversationLine): void;
+    stream: (onLine: ChatLineSink) => Promise<void>;
+}): Promise<void>;
+/** `blocks` with its last `turn-done` carrying the reply's work. */
+export declare function stampWorked(blocks: TranscriptBlock[], worked: {
+    workedMs: number;
+    endedAt: number;
+}): TranscriptBlock[];

package/client/run-commit.js

@@ -0,0 +1,49 @@
+import { applyTurnEventsToSession, gatedToolFromEvents, } from '@theoremjs/agents/interface';
+import { foldAssistantTurn } from "./turn-client.js";
+/**
+ * The session once a reply's events are in: a reply that waits on a gate
+ * keeps its events beside the transcript until the gate settles; any other is over.
+ */
+export function sessionAfter(session, events) {
+    const applied = applyTurnEventsToSession(session, events);
+    const gatedTool = gatedToolFromEvents(events);
+    if (gatedTool)
+        return { ...applied, gatedTool, assistantEvents: [...events] };
+    return {
+        ...applied,
+        gatedTool: null,
+        assistantEvents: [],
+        pendingUserDraft: null,
+        toolSnapshot: undefined,
+        promotedToolIds: [],
+    };
+}
+/**
+ * Streams into `events`, which the caller owns, so a stream that fails still
+ * leaves what it delivered. A `conversation` line goes to `onConversation`. An
+ * `unsupported` line is the host's to read on its own transport, and a
+ * `malformed` one goes to `view.skipped`: neither enters the reply.
+ */
+export function streamFoldedTurn(args) {
+    return args.stream((line) => {
+        if (line.type === 'conversation') {
+            args.onConversation?.(line);
+            return;
+        }
+        if (line.type === 'unsupported')
+            return;
+        if (line.type === 'malformed') {
+            args.view.skipped(line.error);
+            return;
+        }
+        args.events.push(line);
+        args.view.blocks(foldAssistantTurn(args.iface, args.events));
+    });
+}
+/** `blocks` with its last `turn-done` carrying the reply's work. */
+export function stampWorked(blocks, worked) {
+    const last = blocks.findLastIndex((block) => block.kind === 'turn-done');
+    if (last < 0)
+        return blocks;
+    return blocks.map((block, index) => (index === last ? { ...block, ...worked } : block));
+}

package/client/run-session.d.ts

@@ -0,0 +1,79 @@
+import { type TurnEvent } from '@theoremjs/agents';
+import { type ComposerProfileInterface, type InterfaceTurnSession, type TranscriptBlock, type UserTurnDraft } from '@theoremjs/agents/interface';
+import { type TurnFailure } from './failure.ts';
+import { type StreamView } from './run-commit.ts';
+import { type ToolGateResolution } from './tool-resume.ts';
+import { type TheoremTransport } from './transport.ts';
+import { type RunScope } from './turn-client.ts';
+export type { TurnFailure } from './failure.ts';
+export type { StreamView } from './run-commit.ts';
+/**
+ * Whether the host keeps this chat's conversation. A stateless profile keeps
+ * none: the page holds its transcript, and nothing goes on from a ref.
+ */
+export declare function keepsConversation(iface: ComposerProfileInterface): boolean;
+/**
+ * What one run left. A host that keeps the conversation is the truth for the
+ * rest: the page draws it again from the last ref the stream carried. A
+ * stateless chat keeps the reply as the run streamed it.
+ */
+export type RunOutcome = {
+    /** The session the run went out from, with any permission the answer granted. */
+    session: InterfaceTurnSession;
+    /** The reply's events: a gate's answer starts from the paused reply's. */
+    events: TurnEvent[];
+    /** The message reached the conversation: the host's when it keeps one (the ref marked `posted`), else the page's. */
+    posted: boolean;
+    failure?: TurnFailure;
+};
+export type StreamInterfaceTurnBaseArgs = {
+    iface: ComposerProfileInterface;
+    transport: TheoremTransport;
+    session: InterfaceTurnSession;
+    scope: RunScope;
+    view: StreamView;
+    /**
+     * Fires once the message posts, with the blocks the transcript gains: a
+     * walked-away reply's settled blocks, then the message's own (with media
+     * preview data). Walking away, it posts once the host has it.
+     */
+    onUserBlocks: (blocks: TranscriptBlock[]) => void;
+    signal?: AbortSignal;
+    /**
+     * Send while the reply waits on gates: the message walks away from every
+     * waiting call in its own request, and the host settles each one cancelled
+     * ahead of the reply. Without it, or in a chat the host keeps no
+     * conversation for, a waiting session refuses the send (`session.gate_pending`).
+     */
+    walkAway?: boolean;
+    /**
+     * The transcript before this message. Sent once, only when the host answers that it can no
+     * longer open the conversation, so a host that restores from it (the studio) goes on.
+     */
+    transcript?: readonly TranscriptBlock[];
+};
+export type StreamInterfaceTurnArgs = StreamInterfaceTurnBaseArgs & {
+    text: string;
+    pendingFiles: readonly File[];
+    pendingVoice: readonly File[];
+};
+export type StreamInterfaceDraftTurnArgs = StreamInterfaceTurnBaseArgs & {
+    draft: UserTurnDraft;
+};
+export declare function streamInterfaceTurn(args: StreamInterfaceTurnArgs): Promise<RunOutcome>;
+/** Send a turn from an already-encoded pending draft (queue drain / send now). */
+export declare function streamInterfaceDraftTurn(args: StreamInterfaceDraftTurnArgs): Promise<RunOutcome>;
+/**
+ * Send the user's answer to the gate the session waits on. The host settles
+ * the call either way (an approval runs it; a refusal records it declined), so
+ * the model and the trace read what the user chose. A host that keeps the
+ * conversation goes on with the reply in the same stream once no call waits.
+ */
+export declare function resumeInterfaceTool(args: {
+    iface: ComposerProfileInterface;
+    transport: TheoremTransport;
+    session: InterfaceTurnSession;
+    scope: RunScope;
+    resolution: ToolGateResolution;
+    view: StreamView;
+}): Promise<RunOutcome>;