@theoremjs/web 0.3.4-next.373.gab46e23 → 0.3.4-next.377.g4dbec64

package/README.md

@@ -150,6 +150,62 @@ for await (const event of session.events()) {
 - `open.host` is the `openMessage` that the page's `connection` returned.
 - Read later messages with `parseLiveClientMessage`. Give context messages to `session.sendContext({ client: message.context })`.
 
+## A chat with no framework
+
+Use `createChatController` when you draw the chat yourself, in any framework or none. It holds all of the chat's logic, and it draws nothing:
+
+- the transcript, and the reply as it streams;
+- the composer's draft, files, and voice note;
+- the pending messages: steer, queue, and stash;
+- the gates, branching, and resuming a conversation.
+
+`useTheoremChat` from `@theoremjs/react` is this controller, bound to React.
+
+```ts
+import { createChatController, createHttpTransport } from '@theoremjs/web/client';
+
+const transport = createHttpTransport({ endpoint: '/api/theorem' });
+const iface = await transport.describe();
+if (iface.type === 'live') throw new Error('Use LiveSessionClient for a live profile.');
+
+const chat = createChatController({ transport, iface });
+chat.subscribe(() => draw(chat.getState()));
+
+chat.setDraftText('What is in my cart?');
+await chat.submit();
+```
+
+- `getState()` returns a `ChatState`. It is a new object after each change, and the same object between changes. So you can compare it by reference, as React's `useSyncExternalStore` does.
+- `subscribe(listener)` calls the listener once for each group of changes, after the code that made them has run. It returns the function that unsubscribes.
+- `update(options)` gives the controller your latest options, such as a new `context`, `slots`, or `pageTools`. Each turn reads the options as they are when it is sent. `conversation`, `conversationView`, and `initialText` are read only when the controller is created.
+- Each method is bound to the controller. Pass it as a callback as it is.
+
+`state.phase` is `'idle'`, `'streaming'`, or `'gated'`. The methods for the composer depend on it:
+
+| Method | What it does |
+| --- | --- |
+| `submit()` | At `idle`, sends the draft. Otherwise, queues it. |
+| `enqueue('steer')` | Sends the draft to the running turn with `transport.steer`. The steer leaves `pendingMessages` when the turn's `stage` event names it in `injected`. A steer the turn never takes waits at the front of the queue. |
+| `enqueue('queue')` | Keeps the draft to send after the reply. When the reply ends without a failure and no gate waits, the first queued message is sent. |
+| `enqueue('stash')` | Keeps the draft without sending it. `queuePending(id)` moves it to the queue. |
+| `sendNow(message?)` | Sends a pending message, or the draft, at once. A streaming reply is stopped first. A reply that waits on gates is left. |
+| `restorePending(id)` | Puts a pending message back in the composer. The draft that was there is stashed first, so the user loses nothing. |
+| `stop()` | Stops the streaming reply. |
+| `decide(action)`, `authenticate(secret?)` | Answer the gate that the reply waits on. |
+| `branch(index)` | Cuts the conversation after transcript block `index`. |
+| `sendText(text, files?)` | Sends a message from your code. It resolves with the blocks the turn added, or `null` when the chat cannot take a message now. |
+
+The controller uses these methods of the transport: `turn`, `invoke` (to answer a gate), `steer`, `conversation`, and `rewind`. `conversation` and `rewind` are called only for a profile whose host keeps the conversation. `pageResult` is called when the reply hands a tool to the page.
+
+The controller writes no English text. The helpers below give the composer's controls as values, and you choose the words:
+
+| Helper | What it gives |
+| --- | --- |
+| `composerActionState(args)` | The primary button (`send`, `queue`, `stop`, or `none`), the send menu, and whether the button is off. |
+| `composerDrawerSummary(args)` | The count of waiting messages by kind, for a collapsed drawer. |
+| `resolveComposerHint(args)` | The stash hint, when the whole draft is selected. |
+| `isStashShortcut(event)` | Whether a key press is the stash shortcut, `STASH_SHORTCUT`. |
+
 ## A custom browser transport
 
 Use `withPageToolDispatch` when your screen consumes turn events through a custom transport.

package/client/chat.d.ts

@@ -0,0 +1,147 @@
+import { type AttachmentValidationIssue, type ComposerMenuAction, type ComposerPendingMessage, type ComposerProfileInterface, type ComposerRunPhase, type InterfaceTurnSession, type TranscriptBlock } from '@theoremjs/agents/interface';
+import { type ClientFailure } from './failure.ts';
+import { type PageTools } from './live/live-page-tool.ts';
+import type { AnsweringGate, ToolDecisionAction } from './tool-resume.ts';
+import type { ConversationView, TheoremTransport, TurnEventSink } from './transport.ts';
+export type ChatOptions = {
+    transport: TheoremTransport;
+    /** The profile's composer interface, as `transport.describe()` returns it. `null` while it loads. */
+    iface: ComposerProfileInterface | null;
+    /**
+     * The ref of a conversation to resume, as `onConversationChange` reported it. Read once, when
+     * the chat is created: the chat draws the conversation as the host keeps it. A stateless profile
+     * keeps no conversation, so it has no ref.
+     */
+    conversation?: string;
+    /**
+     * The conversation under `conversation` as the host showed it with the ref, as
+     * `startConversation` returns it. Read once, when the chat is created: the chat draws it at
+     * once, and does not read it from the host again.
+     */
+    conversationView?: ConversationView;
+    /** The text the composer starts with. Read once, when the chat is created. */
+    initialText?: string;
+    /**
+     * Each new ref the host issues for the conversation: once the message posts, and again as the
+     * reply's runs are saved. Keep the latest to resume the chat later.
+     */
+    onConversationChange?: (ref: string) => void;
+    /**
+     * The value chosen for each of the profile's `inputs.slots`. Sent with every turn. A slot you
+     * name here is fixed to that value; one you leave out is chosen with `pickSlot`, starting at
+     * its first allowed value.
+     */
+    slots?: Record<string, string>;
+    /** Told each time the visitor picks a slot, with every slot's value. */
+    onSlotsChange?: (slots: Record<string, string>) => void;
+    /** What the page wants the agent to know: any JSON. The latest value goes with every turn. */
+    context?: unknown;
+    /** The page's tools, by name: each answers a tool the profile declares with `answeredBy: 'page'`. */
+    pageTools?: PageTools;
+    /**
+     * Every event of every turn, as it arrives and before the transcript takes it: the ones the
+     * transcript shows, and the ones it does not (a stage, a session, a guardrail decision).
+     */
+    onTurnEvent?: TurnEventSink;
+};
+/**
+ * How far the latest message has got: posted (`sending`), taken by the server
+ * (`sent`), reached the model (`delivered`), answered (`read`).
+ */
+export type MessageDelivery = 'sending' | 'sent' | 'delivered' | 'read';
+/** The slots the profile declares, and the value of each: the page's, else the picked one, else the first allowed. */
+export type ChatSlots = {
+    declared: Record<string, string[]>;
+    values: Record<string, string>;
+};
+/** Everything a chat shows. A new object on each change, the same one between changes. */
+export type ChatState = {
+    iface: ComposerProfileInterface | null;
+    /** The transcript. */
+    blocks: TranscriptBlock[];
+    /** The reply as it streams, or the reply that waits on a gate. */
+    streamBlocks: TranscriptBlock[];
+    chatStarted: boolean;
+    draftText: string;
+    pendingFiles: File[];
+    pendingVoice: File[];
+    /** Steered, queued, and stashed messages. */
+    pendingMessages: ComposerPendingMessage[];
+    issues: AttachmentValidationIssue[];
+    /** The failure the composer shows. */
+    failure: ClientFailure | null;
+    /** The answer on its way to a gate, shown on it until the answer settles or fails. */
+    answering: AnsweringGate | null;
+    phase: ComposerRunPhase;
+    session: InterfaceTurnSession;
+    /** The latest message's delivery; `null` before the first and once its turn failed. */
+    delivery: MessageDelivery | null;
+    streaming: boolean;
+    /** `undefined` when the profile declares no slots. */
+    slots: ChatSlots | undefined;
+};
+/** What `sendText` hands back: the blocks the turn added, its user message, and the reply. */
+export type SentTurn = {
+    blocks: TranscriptBlock[];
+};
+/** A new value, or a function of the current one. */
+export type ChatUpdate<T> = T | ((prev: T) => T);
+/**
+ * A chat with no UI framework: transcript, streaming, the composer's draft, the pending
+ * steer / queue / stash, gates, branching, and resuming a conversation. Read it with `getState`,
+ * follow it with `subscribe`, and act through its methods. Every method is bound, so pass them
+ * as callbacks as they are.
+ */
+export type ChatController = {
+    getState(): ChatState;
+    /**
+     * Called after each change, once per batch of changes. Returns the unsubscribe. A conversation
+     * resumed without its `conversationView` is read from the host once the first listener subscribes.
+     */
+    subscribe(listener: () => void): () => void;
+    /** The latest options. `conversation`, `conversationView` and `initialText` are read only at creation. */
+    update(options: ChatOptions): void;
+    setDraftText(value: ChatUpdate<string>): void;
+    setPendingFiles(value: ChatUpdate<File[]>): void;
+    setPendingVoice(value: ChatUpdate<File[]>): void;
+    setPendingMessages(value: ChatUpdate<ComposerPendingMessage[]>): void;
+    setIssues(value: ChatUpdate<AttachmentValidationIssue[]>): void;
+    /** Sends the composer's draft when idle; queues it while a reply streams or waits on a gate. */
+    submit(): Promise<void>;
+    /** Stops the reply that is streaming. */
+    stop(): void;
+    /** Steers, queues, or stashes the composer's draft. A steer goes to the running turn. */
+    enqueue(kind: 'queue' | 'steer' | 'stash'): Promise<void>;
+    /**
+     * Sends a pending message, or the composer's draft, now: a streaming reply stops first, and a
+     * reply that waits on gates is walked away from.
+     */
+    sendNow(source?: ComposerPendingMessage): Promise<void>;
+    menuAction(action: ComposerMenuAction): void;
+    /** Puts a pending message back in the composer. What the composer holds is stashed first. */
+    restorePending(id: string): Promise<void>;
+    /** Moves a stashed message into the queue. At idle, the queue starts sending. */
+    queuePending(id: string): void;
+    /** Answers the gate the reply waits on. */
+    decide(action: ToolDecisionAction): Promise<void>;
+    /** The visitor signed in for the gated call, or gave its secret. */
+    authenticate(secret?: string): Promise<void>;
+    /**
+     * Cuts the conversation after transcript block `index`. A host that keeps the conversation
+     * cuts it (walking away from a reply that waits on gates); a stateless chat cuts its own.
+     */
+    branch(index: number): Promise<void>;
+    /** The model, and its effort (its default when left out), for the next turn. */
+    setGeneration(next: {
+        modelId: string;
+        effort?: string;
+    }): void;
+    pickSlot(name: string, value: string): void;
+    /**
+     * Sends `text` and optional files as the composer would, and resolves once the reply is done;
+     * `null` when it can't go now (a reply is streaming, or waits on a gate).
+     */
+    sendText(text: string, files?: readonly File[]): Promise<SentTurn | null>;
+};
+/** A chat for `options`. Framework-free: see `ChatController`. */
+export declare function createChatController(options: ChatOptions): ChatController;

package/client/chat.js

@@ -0,0 +1,765 @@
+import { TheoremError } from '@theoremjs/agents';
+import { branchInterfaceTurnSession, consumeNextComposerQueue, convertSteersToFrontQueued, createComposerPendingMessage, defaultInterfaceEffort, emptyInterfaceTurnSession, orderComposerPendingMessages, promoteComposerPendingKind, removeComposerPendingMessage, removeLandedSteers, userDraftHasPayload, userDraftToSteerInject, } from '@theoremjs/agents/interface';
+import { composerHasPayload } from "./composer-primary.js";
+import { composerFieldsFromDraft } from "./decode-composer-draft.js";
+import { encodeComposerDraft } from "./encode-composer-draft.js";
+import { clientFailure, turnFailure } from "./failure.js";
+import { followGenerationDefaults } from "./generation-selection.js";
+import { warnPageToolMismatch } from "./live/live-page-tool.js";
+import { withPageToolDispatch } from "./page-dispatch.js";
+import { sessionAfter, stampWorked } from "./run-commit.js";
+import { keepsConversation, resumeInterfaceTool, streamInterfaceDraftTurn, streamInterfaceTurn, } from "./run-session.js";
+import { foldAssistantTurn, issuedOperationId } from "./turn-client.js";
+const DELIVERY_ORDER = ['sending', 'sent', 'delivered', 'read'];
+/** The server's own reports (bookkeeping, a failure, the end), which say nothing of the model having the message. */
+const SERVER_EVENTS = new Set(['stage', 'guardrail', 'session', 'error', 'done']);
+/** The reply itself (its thinking and tool calls come before it). */
+const REPLY_EVENTS = new Set(['text', 'structured', 'media']);
+/**
+ * How far a line shows the message got: the host saving it, or any event,
+ * means the server took it; one from the model (thinking, a tool call) means
+ * the model has it, and the reply means it was read. A save without the
+ * message (a walk settling calls) says nothing of it.
+ */
+function deliveryOf(line) {
+    if (line.type === 'conversation')
+        return line.posted ? 'sent' : undefined;
+    if (REPLY_EVENTS.has(line.type))
+        return 'read';
+    return SERVER_EVENTS.has(line.type) ? 'sent' : 'delivered';
+}
+/** The streamed blocks, ending on the turn's error unless the stream already carried it. */
+function withTurnError(blocks, error) {
+    if (blocks.some((block) => block.kind === 'error'))
+        return blocks;
+    return [...blocks, { id: crypto.randomUUID(), kind: 'error', message: error }];
+}
+function slotsOf(iface, fixed, picked) {
+    const declared = iface?.inputs.slots ?? {};
+    const values = { ...fixed };
+    for (const [name, allowed] of Object.entries(declared)) {
+        const value = fixed?.[name] ?? picked[name] ?? allowed[0];
+        if (value !== undefined)
+            values[name] = value;
+    }
+    const chosen = Object.keys(declared).length > 0;
+    return {
+        values: chosen || fixed ? values : undefined,
+        slots: chosen ? { declared, values } : undefined,
+    };
+}
+function sameSlots(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    const keys = Object.keys(a.values);
+    return (a.declared === b.declared &&
+        keys.length === Object.keys(b.values).length &&
+        keys.every((key) => a.values[key] === b.values[key]));
+}
+/** One frame later in a browser; a timer's tick elsewhere. Returns the cancel. */
+function nextFrame(run) {
+    // why: The client also runs where there are no frames (a server, a test), so it asks before it uses them.
+    const frames = globalThis;
+    if (frames.requestAnimationFrame && frames.cancelAnimationFrame) {
+        const id = frames.requestAnimationFrame(run);
+        return () => frames.cancelAnimationFrame?.(id);
+    }
+    const id = setTimeout(run, 16);
+    return () => clearTimeout(id);
+}
+function newTurnId() {
+    return crypto.randomUUID();
+}
+class Chat {
+    #options;
+    #state;
+    #notified;
+    #listeners = new Set();
+    #flushQueued = false;
+    #busy = false;
+    #abort = null;
+    #turnId = null;
+    /** The run in flight; it settles, never rejects. */
+    #run = null;
+    // why: A stateless reply's work across its runs: a gate splits a reply into runs, and the wait between doesn't count.
+    #replyWorkedMs = 0;
+    /** The run that ended let the queue send its next message. */
+    #drainArmed = false;
+    #draining = false;
+    #conversation;
+    // why: One object per posted message, so a run can tell whether it posted one.
+    #delivery = null;
+    #picked = {};
+    #resumed = false;
+    #defaultsFrom;
+    #answeredPage = null;
+    #pageToolsWarned;
+    #frame = null;
+    #frameBlocks = null;
+    constructor(options) {
+        this.#options = options;
+        this.#conversation = options.conversation;
+        this.#state = {
+            iface: options.iface,
+            blocks: [],
+            streamBlocks: [],
+            chatStarted: false,
+            draftText: options.initialText ?? '',
+            pendingFiles: [],
+            pendingVoice: [],
+            pendingMessages: [],
+            issues: [],
+            failure: null,
+            answering: null,
+            phase: 'idle',
+            session: emptyInterfaceTurnSession(),
+            delivery: null,
+            streaming: false,
+            slots: slotsOf(options.iface, options.slots, {}).slots,
+        };
+        this.#notified = this.#state;
+        this.#warnPageTools();
+        this.#settle();
+    }
+    getState = () => this.#state;
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        if (this.#listeners.size === 1)
+            this.#settle();
+        return () => this.#listeners.delete(listener);
+    };
+    update = (options) => {
+        this.#options = options;
+        this.#warnPageTools();
+        const { slots } = slotsOf(options.iface, options.slots, this.#picked);
+        const patch = {};
+        if (options.iface !== this.#state.iface)
+            patch.iface = options.iface;
+        if (!sameSlots(slots, this.#state.slots))
+            patch.slots = slots;
+        if (Object.keys(patch).length > 0)
+            this.#set(patch);
+    };
+    setDraftText = (value) => this.#apply('draftText', value);
+    setPendingFiles = (value) => this.#apply('pendingFiles', value);
+    setPendingVoice = (value) => this.#apply('pendingVoice', value);
+    setPendingMessages = (value) => this.#apply('pendingMessages', value);
+    setIssues = (value) => this.#apply('issues', value);
+    submit = async () => {
+        const { phase, draftText, pendingFiles, pendingVoice } = this.#state;
+        if (phase !== 'idle') {
+            await this.enqueue('queue');
+            return;
+        }
+        this.#set({ issues: [] });
+        await this.#sendFields({ text: draftText, files: [...pendingFiles], voice: [...pendingVoice] });
+    };
+    stop = () => {
+        this.#abort?.abort();
+    };
+    enqueue = async (kind) => {
+        const { draftText, pendingFiles, pendingVoice } = this.#state;
+        if (!composerHasPayload(draftText, pendingFiles, pendingVoice))
+            return;
+        this.#set({ issues: [] });
+        try {
+            const draft = await encodeComposerDraft({ text: draftText, pendingFiles, pendingVoice });
+            const message = createComposerPendingMessage({ kind, draft });
+            this.#set({
+                pendingMessages: orderComposerPendingMessages([...this.#state.pendingMessages, message]),
+                ...this.#clearedComposer(),
+            });
+            if (kind !== 'steer')
+                return;
+            const turnId = this.#turnId;
+            if (!turnId) {
+                this.#steerAfterTurnEnded();
+                return;
+            }
+            const inject = userDraftToSteerInject(draft);
+            if (inject.length === 0)
+                return;
+            await this.#options.transport.steer({ turnId, id: message.id, inject });
+        }
+        catch (err) {
+            this.#set({ failure: clientFailure(err, this.#options.iface?.labels) });
+        }
+    };
+    sendNow = async (source) => {
+        if (!this.#options.iface)
+            return;
+        const draft = source ? source.draft : await this.#composerDraft();
+        if (!draft)
+            return;
+        if (this.#busy) {
+            this.#abort?.abort();
+            await this.#run;
+        }
+        this.#set({ pendingMessages: convertSteersToFrontQueued(this.#state.pendingMessages) });
+        this.#drainArmed = false;
+        // why: Sent while the reply waits on gates, the message walks away from them in its own request.
+        await this.#sendDraft(draft, {
+            walkAway: this.#state.session.gatedTool !== null,
+            // why: The sent message leaves the queue, or the composer it came from.
+            onPosted: () => this.#set(source
+                ? {
+                    pendingMessages: removeComposerPendingMessage(this.#state.pendingMessages, source.id),
+                }
+                : this.#clearedComposer()),
+        });
+    };
+    menuAction = (action) => {
+        if (action === 'queue' || action === 'steer' || action === 'stash') {
+            void this.enqueue(action);
+            return;
+        }
+        if (action === 'send_now')
+            void this.sendNow();
+    };
+    restorePending = async (id) => {
+        const message = this.#state.pendingMessages.find((m) => m.id === id);
+        if (!message)
+            return;
+        try {
+            await this.#restore(composerFieldsFromDraft(message.draft));
+            this.#set({
+                pendingMessages: removeComposerPendingMessage(this.#state.pendingMessages, id),
+            });
+        }
+        catch (err) {
+            this.#set({ failure: clientFailure(err, this.#options.iface?.labels) });
+        }
+    };
+    queuePending = (id) => {
+        const message = this.#state.pendingMessages.find((m) => m.id === id);
+        if (message?.kind !== 'stash')
+            return;
+        if (this.#state.phase === 'idle')
+            this.#drainArmed = true;
+        this.#set({
+            pendingMessages: promoteComposerPendingKind(this.#state.pendingMessages, id, 'queue'),
+        });
+    };
+    decide = (action) => this.#answerGate({ action });
+    authenticate = (secret) => this.#answerGate({ action: 'auth', ...(secret === undefined ? {} : { secret }) });
+    branch = async (index) => {
+        const { iface } = this.#options;
+        if (!iface || this.#busy)
+            return;
+        const ref = this.#conversation;
+        if (!keepsConversation(iface) || ref === undefined) {
+            const kept = [...this.#state.blocks, ...this.#state.streamBlocks].slice(0, index + 1);
+            // why: The kept transcript's last message isn't the one whose delivery was tracked.
+            this.#setDelivery(null);
+            this.#set({
+                blocks: kept,
+                streamBlocks: [],
+                chatStarted: kept.length > 0,
+                session: branchInterfaceTurnSession(this.#state.session, kept),
+            });
+            return;
+        }
+        this.#set({ failure: null });
+        try {
+            // why: The paused reply is not in the host's transcript; a cut inside it keeps the transcript whole.
+            const at = Math.min(index, this.#state.blocks.length - 1);
+            const rewound = await this.#options.transport.rewind({ conversation: ref, at });
+            this.#adopt(rewound.conversation);
+            this.#draw(rewound.view, this.#state.session, []);
+            this.#setDelivery(null);
+        }
+        catch (err) {
+            this.#showFailure(turnFailure(err, iface.labels));
+        }
+    };
+    setGeneration = (next) => {
+        const { iface } = this.#options;
+        const effort = next.effort ?? (iface ? defaultInterfaceEffort(iface, next.modelId) : undefined);
+        this.#set({
+            session: { ...this.#state.session, selectedModel: next.modelId, selectedEffort: effort },
+        });
+    };
+    pickSlot = (name, value) => {
+        const before = slotsOf(this.#options.iface, this.#options.slots, this.#picked).values;
+        this.#picked = { ...this.#picked, [name]: value };
+        this.#set({ slots: slotsOf(this.#options.iface, this.#options.slots, this.#picked).slots });
+        this.#options.onSlotsChange?.({ ...before, [name]: value });
+    };
+    sendText = async (text, files = []) => {
+        if (!this.#options.iface || this.#state.phase !== 'idle')
+            return null;
+        const before = this.#state.blocks.length;
+        await this.#sendFields({ text, files: [...files], voice: [] });
+        return { blocks: this.#state.blocks.slice(before) };
+    };
+    #set(patch) {
+        const next = { ...this.#state, ...patch };
+        next.phase = this.#busy ? 'streaming' : next.session.gatedTool ? 'gated' : 'idle';
+        this.#state = next;
+        if (this.#flushQueued)
+            return;
+        this.#flushQueued = true;
+        // why: Changes made together reach listeners once, after the code that made them has run.
+        queueMicrotask(() => this.#flush());
+    }
+    #apply(key, value) {
+        const next = typeof value === 'function'
+            ? value(this.#state[key])
+            : value;
+        this.#set({ [key]: next });
+    }
+    #flush() {
+        this.#flushQueued = false;
+        this.#settle();
+        if (this.#flushQueued || this.#notified === this.#state)
+            return;
+        this.#notified = this.#state;
+        for (const listener of [...this.#listeners])
+            listener();
+    }
+    /**
+     * What follows from the state as it now stands: the profile's default model, the conversation
+     * the chat resumes, a page gate that has no answer, and the queue's next message. Each is done
+     * once, so settling again changes nothing.
+     */
+    #settle() {
+        const { iface } = this.#options;
+        if (!iface)
+            return;
+        this.#followDefaults(iface);
+        this.#resume(iface);
+        this.#answerPageGate();
+        this.#drain();
+    }
+    #clearedComposer() {
+        return { draftText: '', pendingFiles: [], pendingVoice: [] };
+    }
+    #setDelivery(next) {
+        this.#delivery = next;
+        this.#set({ delivery: next?.status ?? null });
+    }
+    #adopt(ref) {
+        if (this.#conversation === ref)
+            return;
+        this.#conversation = ref;
+        this.#options.onConversationChange?.(ref);
+    }
+    #showFailure(failure) {
+        if (!failure || failure.aborted)
+            return;
+        const { error, errorKind, errorInternal } = failure;
+        this.#set({
+            failure: { error, errorKind, ...(errorInternal ? { errorInternal } : {}) },
+            ...(failure.issues ? { issues: failure.issues } : {}),
+        });
+    }
+    /** Draws the conversation as the host shows it: its transcript, and the reply that waits on gates. */
+    #draw(view, session, events) {
+        this.#set({
+            blocks: view.transcript,
+            streamBlocks: view.paused?.blocks ?? [],
+            // why: A reply at rest leaves the run's own events (tokens, an ask); a paused one, the host's.
+            session: sessionAfter(session, view.paused?.events ?? events),
+            chatStarted: view.transcript.length > 0 || view.paused !== undefined,
+        });
+    }
+    /**
+     * Keeps the model and effort valid as the interface changes: a pick still on the old defaults
+     * follows the new ones, and a pick the profile no longer has falls back to them.
+     */
+    #followDefaults(iface) {
+        const { session } = this.#state;
+        const next = followGenerationDefaults(iface, { model: session.selectedModel, effort: session.selectedEffort }, this.#defaultsFrom);
+        this.#defaultsFrom = iface;
+        if (next.model === session.selectedModel && next.effort === session.selectedEffort)
+            return;
+        this.#set({ session: { ...session, selectedModel: next.model, selectedEffort: next.effort } });
+    }
+    /** Draws the conversation the chat resumes, once. A run that starts first draws it itself. */
+    #resume(iface) {
+        if (this.#resumed)
+            return;
+        const ref = this.#conversation;
+        const shown = this.#options.conversationView;
+        // why: A chat no one follows yet (one React's strict mode builds and drops) reads nothing from the host.
+        if (ref !== undefined && !shown && this.#listeners.size === 0)
+            return;
+        this.#resumed = true;
+        if (ref === undefined || !keepsConversation(iface))
+            return;
+        if (shown) {
+            this.#draw(shown, this.#state.session, []);
+            return;
+        }
+        const before = this.#state.blocks;
+        void this.#options.transport.conversation({ conversation: ref }).then((view) => {
+            // why: A message sent while it loaded posted onto the host's conversation; its run draws it.
+            if (this.#state.blocks !== before || this.#busy)
+                return;
+            this.#draw(view, this.#state.session, []);
+        }, (err) => this.#showFailure(turnFailure(err, iface.labels)));
+    }
+    /**
+     * Settles a restored page gate as unanswered.
+     * invariant: A restored page gate cannot authorize callback execution. Only active dispatch grants do.
+     */
+    #answerPageGate() {
+        const gated = this.#state.phase === 'gated' ? this.#state.session.gatedTool : null;
+        if (gated?.gateKind !== 'page' || !gated.operationId)
+            return;
+        if (this.#answeredPage === gated.operationId)
+            return;
+        this.#answeredPage = gated.operationId;
+        void this.#answerGate({ action: 'page', page: { unanswered: true } });
+    }
+    /** Sends the next queued message once the chat is idle, when the run that ended allowed it. */
+    #drain() {
+        if (this.#state.phase !== 'idle' || !this.#drainArmed)
+            return;
+        this.#drainArmed = false;
+        if (this.#draining)
+            return;
+        const { message } = consumeNextComposerQueue(this.#state.pendingMessages);
+        if (!message)
+            return;
+        this.#draining = true;
+        // why: The message leaves the queue once it posts; one that never starts stays queued.
+        void this.#sendDraft(message.draft, {
+            onPosted: () => this.#set({
+                pendingMessages: removeComposerPendingMessage(this.#state.pendingMessages, message.id),
+            }),
+        }).finally(() => {
+            this.#draining = false;
+        });
+    }
+    /** Says in the console, once for each set of names, where the page's tools and the profile's disagree. */
+    #warnPageTools() {
+        const { iface, pageTools } = this.#options;
+        const declared = iface && 'tools' in iface ? iface.tools.page : undefined;
+        if (declared === undefined)
+            return;
+        const handled = Object.keys(pageTools ?? {}).sort();
+        const key = JSON.stringify([declared, handled]);
+        if (key === this.#pageToolsWarned)
+            return;
+        this.#pageToolsWarned = key;
+        warnPageToolMismatch(declared, handled);
+    }
+    /** The composer's draft, when it holds something to send. */
+    async #composerDraft() {
+        const { draftText, pendingFiles, pendingVoice } = this.#state;
+        const draft = await encodeComposerDraft({ text: draftText, pendingFiles, pendingVoice });
+        return userDraftHasPayload(draft) ? draft : undefined;
+    }
+    /** Puts a message back in the composer. What the composer holds now is stashed first, so nothing typed is lost. */
+    async #restore(fields) {
+        const { draftText, pendingFiles, pendingVoice } = this.#state;
+        if (composerHasPayload(draftText, pendingFiles, pendingVoice)) {
+            const draft = await encodeComposerDraft({ text: draftText, pendingFiles, pendingVoice });
+            const stash = createComposerPendingMessage({ kind: 'stash', draft });
+            this.#set({
+                pendingMessages: orderComposerPendingMessages([...this.#state.pendingMessages, stash]),
+            });
+        }
+        this.#set({
+            draftText: fields.text,
+            pendingFiles: fields.files,
+            pendingVoice: fields.voice,
+            issues: [],
+        });
+    }
+    /** A steer with no running turn: the visitor reads `session.turn_ended`; steers, this one too, move to the front of the queue. */
+    #steerAfterTurnEnded() {
+        this.#set({
+            failure: clientFailure(
+            // labels-exempt: internal diagnostic; the user reads session.turn_ended
+            new TheoremError('request', 'steer: no active turn', {
+                copy: { key: 'session.turn_ended' },
+            }), this.#options.iface?.labels),
+            // why: The composer already gave the message up, so it waits as the next to send, not lost.
+            pendingMessages: orderComposerPendingMessages(convertSteersToFrontQueued(this.#state.pendingMessages)),
+        });
+    }
+    /** The message posted: it joins the transcript, and the reply starts streaming. */
+    #posted(blocks, patch) {
+        this.#setDelivery({ status: 'sending' });
+        this.#set({
+            blocks: [...this.#state.blocks, ...blocks],
+            chatStarted: true,
+            streaming: true,
+            ...patch,
+        });
+    }
+    #sendFields(fields) {
+        return this.#runTurn(({ iface, view, transport, scope, signal }) => streamInterfaceTurn({
+            iface,
+            transport,
+            session: this.#state.session,
+            text: fields.text,
+            pendingFiles: fields.files,
+            pendingVoice: fields.voice,
+            signal,
+            scope,
+            view,
+            transcript: this.#state.blocks,
+            onUserBlocks: (blocks) => this.#posted(blocks, this.#clearedComposer()),
+        }), { turn: true, message: { restore: () => this.#restore(fields) } });
+    }
+    #sendDraft(draft, options) {
+        return this.#runTurn(({ iface, view, transport, scope, signal }) => streamInterfaceDraftTurn({
+            iface,
+            transport,
+            session: this.#state.session,
+            draft,
+            signal,
+            scope,
+            view,
+            transcript: this.#state.blocks,
+            walkAway: options.walkAway === true,
+            onUserBlocks: (blocks) => {
+                this.#posted(blocks, { streamBlocks: [] });
+                options.onPosted();
+            },
+        }), { turn: true, message: { restore: () => this.#restore(composerFieldsFromDraft(draft)) } });
+    }
+    async #answerGate(resolution) {
+        // why: Set once the run starts (not while another runs), and cleared once it has ended.
+        let started = false;
+        try {
+            await this.#runTurn(({ iface, view, transport, scope }) => {
+                started = true;
+                const { session } = this.#state;
+                // why: A person's answer shows on its gate while it settles; the page's has no gate to show on.
+                if (session.gatedTool && resolution.action !== 'page') {
+                    this.#set({
+                        answering: {
+                            callId: session.gatedTool.callId,
+                            operationId: issuedOperationId(session.gatedTool),
+                            action: resolution.action,
+                        },
+                    });
+                }
+                return resumeInterfaceTool({ iface, transport, session, scope, resolution, view });
+            });
+        }
+        finally {
+            if (started)
+                this.#set({ answering: null });
+        }
+    }
+    /**
+     * The transport each run uses: the page's tools answer their calls, each turn carries the
+     * page's slots and context as they are when it is sent, and each line lands the steers it
+     * reports, moves the message's delivery on, and hands the chat the conversation's new ref
+     * (so a page that reloads mid-reply keeps the posted message).
+     */
+    #runTransport() {
+        const { transport, pageTools } = this.#options;
+        const base = withPageToolDispatch(transport, pageTools);
+        const tap = (onLine) => (line) => {
+            this.#took(line);
+            onLine(line);
+        };
+        return {
+            ...base,
+            turn: (request, onLine, signal) => base.turn(this.#withValues(request), tap(onLine), signal),
+            invoke: (request, onLine, signal) => base.invoke(request, tap(onLine), signal),
+        };
+    }
+    #withValues(request) {
+        const { iface, slots: fixed, context } = this.#options;
+        const slots = slotsOf(iface, fixed, this.#picked).values;
+        if (slots === undefined && context === undefined)
+            return request;
+        return {
+            ...request,
+            input: {
+                ...request.input,
+                ...(slots === undefined ? {} : { slots }),
+                ...(context === undefined ? {} : { context }),
+            },
+        };
+    }
+    /** One line of a run's stream, before the run folds it. */
+    #took(line) {
+        if (line.type === 'stage' && line.injected?.length) {
+            this.#set({ pendingMessages: removeLandedSteers(this.#state.pendingMessages, line) });
+        }
+        const reached = deliveryOf(line);
+        const delivery = this.#delivery;
+        if (delivery &&
+            reached &&
+            DELIVERY_ORDER.indexOf(reached) > DELIVERY_ORDER.indexOf(delivery.status)) {
+            this.#setDelivery({ status: reached });
+        }
+        if (line.type === 'conversation')
+            this.#adopt(line.ref);
+        else
+            this.#options.onTurnEvent?.(line);
+    }
+    #streamFrame(partial) {
+        this.#frameBlocks = partial;
+        if (this.#frame)
+            return;
+        // why: A stream can carry many lines a frame; the chat draws the latest once per frame.
+        this.#frame = nextFrame(() => {
+            this.#frame = null;
+            const next = this.#frameBlocks;
+            this.#frameBlocks = null;
+            if (next)
+                this.#set({ streamBlocks: next });
+        });
+    }
+    /**
+     * Runs one stream into the transcript: live partials while it streams, then what the run left
+     * (or its failure) and the queue's next step. Does nothing while another run is in flight.
+     */
+    async #runTurn(run, options = {}) {
+        const { iface } = this.#options;
+        if (!iface || this.#busy)
+            return;
+        const { message } = options;
+        const priorDelivery = this.#delivery;
+        const abort = options.turn ? new AbortController() : null;
+        const turnId = options.turn ? newTurnId() : undefined;
+        this.#busy = true;
+        this.#abort = abort;
+        this.#turnId = turnId ?? null;
+        this.#drainArmed = false;
+        // why: A message streams once it posts, so the previous reply never shows as streaming before it.
+        this.#set({ failure: null, ...(message ? {} : { streaming: true }) });
+        const start = { blocks: this.#state.blocks, streamBlocks: this.#state.streamBlocks };
+        // why: A run that answers a gate continues its reply; any other starts one.
+        if (!this.#state.session.gatedTool)
+            this.#replyWorkedMs = 0;
+        const startedAt = Date.now();
+        const done = (async () => {
+            try {
+                const outcome = await run({
+                    iface,
+                    transport: this.#runTransport(),
+                    scope: { conversation: this.#conversation, turnId },
+                    signal: abort?.signal,
+                    view: {
+                        blocks: (partial) => this.#streamFrame(partial),
+                        // why: The reply goes on; the composer names what it left out.
+                        skipped: (error) => this.#set({ failure: clientFailure(error, iface.labels) }),
+                    },
+                });
+                const endedAt = Date.now();
+                this.#replyWorkedMs += endedAt - startedAt;
+                this.#endRun();
+                const unposted = message !== undefined && !outcome.posted;
+                // why: A message that posts itself (onUserBlocks) gets a fresh delivery.
+                if (unposted && this.#delivery !== priorDelivery)
+                    await this.#takeBack(start, message);
+                let waits;
+                if (keepsConversation(iface)) {
+                    waits = await this.#settleHosted(outcome, start);
+                }
+                else if (unposted) {
+                    this.#showFailure(outcome.failure);
+                    waits = this.#state.session.gatedTool !== null;
+                }
+                else {
+                    waits = this.#settleLocal(iface, outcome, { workedMs: this.#replyWorkedMs, endedAt });
+                }
+                this.#runEnded(!outcome.failure && !waits);
+            }
+            catch (err) {
+                // why: The run left no view to draw; the composer says so, and the chat stays as it stood.
+                this.#endRun();
+                this.#showFailure(turnFailure(err, iface.labels));
+                this.#runEnded(false);
+            }
+        })();
+        this.#run = done;
+        await done;
+        if (this.#run === done)
+            this.#run = null;
+    }
+    /** The run is over: nothing streams, and nothing can stop or steer it. */
+    #endRun() {
+        this.#frame?.();
+        this.#frame = null;
+        this.#frameBlocks = null;
+        this.#busy = false;
+        this.#abort = null;
+        this.#turnId = null;
+        this.#set({ streaming: false });
+    }
+    /** Steers the reply never took wait at the front of the queue; the queue sends on when `drain`. */
+    #runEnded(drain) {
+        this.#drainArmed = drain;
+        this.#set({
+            pendingMessages: orderComposerPendingMessages(convertSteersToFrontQueued(this.#state.pendingMessages)),
+        });
+    }
+    /** A message that never reached the conversation leaves the transcript and goes back in the composer. */
+    async #takeBack(start, message) {
+        this.#setDelivery(null);
+        this.#set({
+            blocks: start.blocks,
+            streamBlocks: start.streamBlocks,
+            chatStarted: start.blocks.length > 0 || start.streamBlocks.length > 0,
+        });
+        await message.restore();
+    }
+    /**
+     * A host that keeps the conversation is the truth: the chat draws it again from its ref, even
+     * after a message that never posted (a walk can settle calls before it fails). A failure shows
+     * in the composer unless the host's transcript closed on it. Returns whether the reply waits
+     * on gates.
+     */
+    async #settleHosted(outcome, start) {
+        const { failure } = outcome;
+        if (failure)
+            this.#setDelivery(null);
+        const ref = this.#conversation;
+        if (ref === undefined) {
+            this.#set({ streamBlocks: start.streamBlocks });
+            this.#showFailure(failure);
+            return this.#state.session.gatedTool !== null;
+        }
+        const view = await this.#options.transport.conversation({ conversation: ref });
+        this.#draw(view, outcome.session, outcome.events);
+        if (!view.transcript.slice(start.blocks.length).some((b) => b.kind === 'error')) {
+            this.#showFailure(failure);
+        }
+        return view.paused !== undefined;
+    }
+    /**
+     * A stateless chat keeps the reply as the run streamed it: in the transcript once it ends
+     * (closed by its failure, or by the visitor's stop), or beside it while it waits on a gate.
+     * Returns whether it waits.
+     */
+    #settleLocal(iface, outcome, worked) {
+        const session = sessionAfter(outcome.session, outcome.events);
+        const { failure } = outcome;
+        const reply = stampWorked(foldAssistantTurn(iface, outcome.events), worked);
+        if (session.gatedTool !== null) {
+            this.#set({ session, streamBlocks: reply });
+            this.#showFailure(failure);
+            return true;
+        }
+        if (!failure) {
+            this.#set({ session, streamBlocks: [], blocks: [...this.#state.blocks, ...reply] });
+            return false;
+        }
+        this.#setDelivery(null);
+        const closing = failure.aborted
+            ? [{ id: crypto.randomUUID(), kind: 'turn-done', stop: { kind: 'cancelled' } }]
+            : withTurnError(reply, failure.error);
+        this.#set({
+            session,
+            streamBlocks: [],
+            blocks: [...this.#state.blocks, ...closing],
+            ...(failure.issues ? { issues: failure.issues } : {}),
+        });
+        return false;
+    }
+}
+/** A chat for `options`. Framework-free: see `ChatController`. */
+export function createChatController(options) {
+    return new Chat(options);
+}

package/client/composer-drawer.d.ts

@@ -0,0 +1,19 @@
+import type { ComposerPendingMessage } from '@theoremjs/agents/interface';
+/** What waits in the composer, by kind; the UI words each kind. */
+export type ComposerDrawerKind = 'steer' | 'queue' | 'stash' | 'attached';
+/** Collapsed-drawer header: the total, then each waiting kind's count, in display order. */
+export type ComposerDrawerSummary = {
+    count: number;
+    parts: {
+        kind: ComposerDrawerKind;
+        n: number;
+    }[];
+};
+/**
+ * What's waiting in the composer, by kind: steering, queued, stashed, attached
+ * (files and voice notes). Null when nothing waits.
+ */
+export declare function composerDrawerSummary(args: {
+    pendingMessages: readonly Pick<ComposerPendingMessage, 'kind'>[];
+    attachmentCount: number;
+}): ComposerDrawerSummary | null;

package/client/composer-drawer.js

@@ -0,0 +1,15 @@
+/**
+ * What's waiting in the composer, by kind: steering, queued, stashed, attached
+ * (files and voice notes). Null when nothing waits.
+ */
+export function composerDrawerSummary(args) {
+    const countOf = (kind) => args.pendingMessages.filter((message) => message.kind === kind).length;
+    const parts = [
+        { kind: 'steer', n: countOf('steer') },
+        { kind: 'queue', n: countOf('queue') },
+        { kind: 'stash', n: countOf('stash') },
+        { kind: 'attached', n: args.attachmentCount },
+    ].filter((part) => part.n > 0);
+    const count = parts.reduce((sum, part) => sum + part.n, 0);
+    return count === 0 ? null : { count, parts };
+}

package/client/composer-hints.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Composer hints — ephemeral guidance about the current composer interaction
+ * (not pending-message state). Mirrors seance's `stash-selected-draft` hint.
+ */
+/** Stash shortcut in Astryx `Kbd` notation (`mod` is ⌘ on macOS, Ctrl elsewhere). */
+export declare const STASH_SHORTCUT = "mod+shift+s";
+/** Which hint applies, and its shortcut; the UI words it. */
+export type ComposerHint = {
+    id: 'stash-selected-draft';
+    shortcut: string;
+};
+/** Whether a keydown is the stash shortcut (⌘⇧S / Ctrl+Shift+S). */
+export declare function isStashShortcut(event: {
+    code: string;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+}): boolean;
+/** The stash hint — shown while the whole draft is selected in the focused input and it can be stashed. */
+export declare function resolveComposerHint(args: {
+    draftText: string;
+    selectedText: string;
+    canStash: boolean;
+}): ComposerHint | null;

package/client/composer-hints.js

@@ -0,0 +1,20 @@
+/**
+ * Composer hints — ephemeral guidance about the current composer interaction
+ * (not pending-message state). Mirrors seance's `stash-selected-draft` hint.
+ */
+/** Stash shortcut in Astryx `Kbd` notation (`mod` is ⌘ on macOS, Ctrl elsewhere). */
+export const STASH_SHORTCUT = 'mod+shift+s';
+/** Whether a keydown is the stash shortcut (⌘⇧S / Ctrl+Shift+S). */
+export function isStashShortcut(event) {
+    return (event.code === 'KeyS' && event.shiftKey && !event.altKey && (event.metaKey || event.ctrlKey));
+}
+/** The stash hint — shown while the whole draft is selected in the focused input and it can be stashed. */
+export function resolveComposerHint(args) {
+    const draft = args.draftText.trim();
+    if (!args.canStash || !draft || args.selectedText.trim() !== draft)
+        return null;
+    return {
+        id: 'stash-selected-draft',
+        shortcut: STASH_SHORTCUT,
+    };
+}

package/client/composer-primary.d.ts

@@ -0,0 +1,18 @@
+import { type ComposerMenuAction, type ComposerPrimaryAction, type ComposerProfileInterface, type ComposerRunPhase } from '@theoremjs/agents/interface';
+/** Whether the composer holds something to send: text that isn't blank, a file, or a voice note. */
+export declare function composerHasPayload(draftText: string, pendingFiles: readonly File[], pendingVoice: readonly File[]): boolean;
+export type ComposerActionState = {
+    primary: ComposerPrimaryAction;
+    menuActions: ComposerMenuAction[];
+    /** Send is off while recording, with nothing to act on, or with an empty draft to send or queue. */
+    primaryDisabled: boolean;
+};
+/** The composer's primary button and send menu for the current draft and run phase. */
+export declare function composerActionState(args: {
+    iface: ComposerProfileInterface;
+    phase: ComposerRunPhase;
+    draftText: string;
+    pendingFiles: readonly File[];
+    pendingVoice: readonly File[];
+    recording: boolean;
+}): ComposerActionState;

package/client/composer-primary.js

@@ -0,0 +1,29 @@
+import { resolveComposerMenuActions, resolveComposerPrimary, userDraftHasPayload, } from '@theoremjs/agents/interface';
+function fileSpecs(files) {
+    return files.map((file) => ({
+        name: file.name,
+        mimeType: file.type || 'application/octet-stream',
+        sizeBytes: file.size,
+    }));
+}
+/** Whether the composer holds something to send: text that isn't blank, a file, or a voice note. */
+export function composerHasPayload(draftText, pendingFiles, pendingVoice) {
+    return userDraftHasPayload({
+        ...(draftText.trim() ? { text: draftText } : {}),
+        ...(pendingFiles.length ? { attachments: fileSpecs(pendingFiles) } : {}),
+        ...(pendingVoice.length ? { voice: fileSpecs(pendingVoice) } : {}),
+    });
+}
+/** The composer's primary button and send menu for the current draft and run phase. */
+export function composerActionState(args) {
+    const allowSteering = 'allowSteering' in args.iface && Boolean(args.iface.allowSteering);
+    const hasPayload = composerHasPayload(args.draftText, args.pendingFiles, args.pendingVoice);
+    const context = { phase: args.phase, hasPayload, allowSteering };
+    const primary = resolveComposerPrimary(context);
+    const needsPayload = primary === 'send' || primary === 'queue';
+    return {
+        primary,
+        menuActions: resolveComposerMenuActions(context),
+        primaryDisabled: args.recording || primary === 'none' || (needsPayload && !hasPayload),
+    };
+}

package/client/index.d.ts

@@ -1,4 +1,8 @@
 export { float32Rms, float32RmsToLevel, INPUT_LEVEL_GAIN, timeDomainBytesToLevel, } from './audio-level.ts';
+export { type ChatController, type ChatOptions, type ChatSlots, type ChatState, type ChatUpdate, createChatController, type MessageDelivery, type SentTurn, } from './chat.ts';
+export { type ComposerDrawerKind, type ComposerDrawerSummary, composerDrawerSummary, } from './composer-drawer.ts';
+export { type ComposerHint, isStashShortcut, resolveComposerHint, STASH_SHORTCUT, } from './composer-hints.ts';
+export { type ComposerActionState, composerActionState, composerHasPayload, } from './composer-primary.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';
@@ -10,7 +14,7 @@ export { type ClientFailure, clientFailure, type TurnFailure, turnFailure } from
 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 { pageToolMismatch, warnPageToolMismatch } 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';

package/client/index.js

@@ -1,4 +1,8 @@
 export { float32Rms, float32RmsToLevel, INPUT_LEVEL_GAIN, timeDomainBytesToLevel, } from "./audio-level.js";
+export { createChatController, } from "./chat.js";
+export { composerDrawerSummary, } from "./composer-drawer.js";
+export { isStashShortcut, resolveComposerHint, STASH_SHORTCUT, } from "./composer-hints.js";
+export { composerActionState, composerHasPayload, } from "./composer-primary.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";
@@ -9,7 +13,7 @@ export { encodeFiles, filesToPending, pendingAttachmentsToFiles } from "./encode
 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 { pageToolMismatch, warnPageToolMismatch } 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";

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

@@ -32,3 +32,8 @@ export declare function pageToolMismatch(declared: readonly string[], handled: r
     unanswered: string[];
     unused: string[];
 };
+/**
+ * Says in the console where the page's tools and the profile's disagree. A wrong name is the
+ * builder's to fix, so it is never said to the visitor.
+ */
+export declare function warnPageToolMismatch(declared: readonly string[], handled: readonly string[]): void;

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

@@ -9,3 +9,18 @@ export function pageToolMismatch(declared, handled) {
         unused: handled.filter((name) => !declared.includes(name)),
     };
 }
+/**
+ * Says in the console where the page's tools and the profile's disagree. A wrong name is the
+ * builder's to fix, so it is never said to the visitor.
+ */
+export function warnPageToolMismatch(declared, handled) {
+    const { unanswered, unused } = pageToolMismatch(declared, handled);
+    for (const name of unanswered) {
+        // labels-exempt: builder diagnostic
+        console.warn(`Theorem: page tool '${name}' has no handler in pageTools; the agent gets no answer.`);
+    }
+    for (const name of unused) {
+        // labels-exempt: builder diagnostic
+        console.warn(`Theorem: pageTools has '${name}', which the profile does not declare answeredBy: 'page'.`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.373.gab46e23",
+  "version": "0.3.4-next.377.g4dbec64",
   "description": "Theorem on the web platform, with no UI framework: Web-standard server handlers that serve a profile, and the browser client that talks to them.",
   "license": "MIT",
   "type": "module",
@@ -25,6 +25,6 @@
   },
   "peerDependencies": {
     "zod": "^4.6.5",
-    "@theoremjs/agents": "^0.3.4-next.373.gab46e23"
+    "@theoremjs/agents": "^0.3.4-next.377.g4dbec64"
   }
 }