@theoremjs/web 0.3.4-next.649.gf83cea1 → 0.3.4-next.671.gfa09ab2

package/README.md

@@ -150,6 +150,27 @@ 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 })`.
 
+### The live client
+
+`LiveSessionClient` opens the call from the page. It runs each call the model makes on the relay:
+
+```ts
+import { LiveSessionClient } from '@theoremjs/web/client';
+
+const client = new LiveSessionClient({
+  profile: 'guide',
+  pageTools: {
+    highlight: (args) => ({ output: { highlighted: String(args.target) } }),
+  },
+});
+await client.connect();
+```
+
+- A call dispatched to the page runs the `pageTools` function of the same name. Its `output` goes to the model.
+- A page tool with no function, or a function that throws, answers with no answer. The console names a page tool that has no function. The call does not wait.
+- `onGate` answers every other gate: ask the user, then return what `continueGatedToolInvocation` makes of the answer. Without `onGate`, the client refuses every gate.
+- When the connection closes, the calls still open fail, and the relay closes the session.
+
 ## 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:
@@ -188,13 +209,14 @@ await chat.submit();
 | `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`, and joins the transcript there, between the reply before it and the reply after. 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. |
+| `pend(message)` | Steers, queues, or stashes a message you made with `createComposerPendingMessage`, as `enqueue` does the draft. A message queued on an idle chat sends at once. A composer shared by several chats gives each the same message, so its id names it in all of them. |
 | `sendNow(message?)` | Sends a pending message, or the draft, at once. A streaming reply is stopped first, as `stop()` stops it. A reply that waits on gates is left. |
 | `movePending(id, direction)` | Moves a pending message one place `'up'` or `'down'` among the messages of its kind. `composerPendingMoves(messages, id)` from `@theoremjs/agents/interface` says which ways it can go, so a control that can do nothing is not drawn. |
 | `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 with `transport.stop`. What the reply said before the stop stays in the transcript and the history, closed as cancelled. A queued message stays queued. When the host refuses the stop, the controller drops the stream instead, and a host that keeps the conversation keeps the stopped reply where the page can't read it. |
 | `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. |
+| `sendText(text, options?)` | Sends a message from your code. `options` can add `files`, `voice`, a `model` and its `effort`. The model becomes the chat's pick, as if chosen in the composer. An `effort` without a `model` applies to the chat's current model. A model the profile does not have is refused by the turn, not replaced by the default. 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`, `stop`, `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.
 
@@ -245,7 +267,7 @@ const transport = withPageToolDispatch(
 | `authorizationUrl` | Returns the sign-in URL for an OAuth gate. Without it, an OAuth gate has no URL. |
 | `gateTtlMs` | How long a gate waits for an answer. A later answer fails with `session.gate_expired`. Unset, a gate waits until it is answered. |
 | `maxRequestBytes` | The largest browser request body, in bytes. Unset, a body of any size is read. |
-| `pageToolTimeoutMs` | How long the page has to answer a tool call it runs. A call it has not answered by then settles as timed out. Unset, the call waits until the page answers or the turn stops. |
+| `pageToolTimeoutMs` | How long the page has to answer a tool call it runs. A call it has not answered by then settles as timed out. Unset, the call waits until the page answers or the turn stops. The browser clients answer every call they get, so only a page function that never returns holds a turn. |
 | `operationRetentionMs` | How long a settled tool result is kept. Default: 24 hours. |
 | `clientEvents` | Options for `forClient` and `clientError`, which prepare each event and each caught failure for the browser. `reader: 'builder'` sends the raw reason in place of the wording of the profile. Use it only in a development tool on your own machine. |
 | `onError` | Receives each error that the handler catches. A visitor sees the wording of the profile for that kind of error, never the error. |
@@ -334,6 +356,7 @@ interface ConversationDatabase {
 - A null `ref` creates a conversation. Return a new opaque `ref` and `revision`.
 - Otherwise, write only while the stored revision is still `expectedRevision`, as one atomic operation. Return `{ written: false }` on a conflict.
 - Check what you read back with `storedConversationSchema`.
+- Keep `id` as the handler gives it. It names the conversation in each turn's trace as `gen_ai.conversation.id`, and stays the same through every save and rewind.
 
 ### Share session authority
 
@@ -429,7 +452,7 @@ Forward live page results to `answerPageResult`. Preserve checkpoint ownership t
 The default `PageToolBroker` keeps active result waiters in process memory. Several workers need a shared broker or request affinity.
 Use `pageToolBroker` to supply that broker. It carries results; the atomic session store retains execution authority.
 Lost result delivery does not permit another dispatch. The operation retains its claim or an uncertain outcome.
-Set `pageToolTimeoutMs` to give the page a deadline for a result. Unset, a dispatch waits until the page answers or the turn stops. An expired or interrupted result cannot reopen approval.
+Set `pageToolTimeoutMs` to give the page a deadline for a result. Unset, a dispatch waits until the page answers or the turn stops. The browser clients answer every dispatch they get, with no answer when the page has no function for the tool, so only a page function that never returns holds a turn. An expired or interrupted result cannot reopen approval.
 
 ## Build your own server
 

package/client/chat.d.ts

@@ -131,6 +131,11 @@ export type ChatController = {
     stop(): void;
     /** Steers, queues, or stashes the composer's draft. A steer goes to the running turn. */
     enqueue(kind: 'queue' | 'steer' | 'stash'): Promise<void>;
+    /**
+     * Steers, queues, or stashes a message made elsewhere, as `enqueue` does the draft: a composer
+     * shared by several chats gives each the same message, so its id names it in all of them.
+     */
+    pend(message: ComposerPendingMessage): 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.
@@ -159,10 +164,21 @@ export type ChatController = {
     }): 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).
+     * Sends `text`, and what `options` adds, 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>;
+    sendText(text: string, options?: SendTextOptions): Promise<SentTurn | null>;
+};
+/**
+ * What `sendText` sends with its text. A `model` becomes the chat's pick, as if chosen in the
+ * composer; one the profile doesn't have is refused by the turn, not swapped for its default.
+ */
+export type SendTextOptions = {
+    files?: readonly File[];
+    voice?: readonly File[];
+    model?: string;
+    /** The model's effort. Left out, the model's default. */
+    effort?: string;
 };
 /** A chat for `options`. Framework-free: see `ChatController`. */
 export declare function createChatController(options: ChatOptions): ChatController;

package/client/chat.js

@@ -199,23 +199,35 @@ class Chat {
         if (!composerHasPayload(draftText, pendingFiles, pendingVoice))
             return;
         this.#set({ issues: [] });
+        let message;
         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;
+            message = createComposerPendingMessage({ kind, draft });
+        }
+        catch (err) {
+            this.#set({ failure: clientFailure(err, this.#options.iface?.labels) });
+            return;
+        }
+        this.#set(this.#clearedComposer());
+        await this.pend(message);
+    };
+    pend = async (message) => {
+        this.#set({
+            pendingMessages: orderComposerPendingMessages([...this.#state.pendingMessages, message]),
+        });
+        if (message.kind === 'queue' && this.#state.phase === 'idle')
+            this.#drainArmed = true;
+        if (message.kind !== 'steer')
+            return;
+        const turnId = this.#turnId;
+        if (!turnId) {
+            this.#steerAfterTurnEnded();
+            return;
+        }
+        const inject = userDraftToSteerInject(message.draft);
+        if (inject.length === 0)
+            return;
+        try {
             await this.#options.transport.steer({ turnId, id: message.id, inject });
         }
         catch (err) {
@@ -327,11 +339,20 @@ class Chat {
         this.#set({ slots: slotsOf(this.#options.iface, this.#options.slots, this.#picked).slots });
         this.#options.onSlotsChange?.({ ...before, [name]: value });
     };
-    sendText = async (text, files = []) => {
+    sendText = async (text, options = {}) => {
         if (!this.#options.iface || this.#state.phase !== 'idle')
             return null;
+        // invariant: the turn reads the pick from the session, before `#followDefaults` next runs.
+        const modelId = options.model ??
+            (options.effort === undefined ? undefined : this.#state.session.selectedModel);
+        if (modelId !== undefined)
+            this.setGeneration({ modelId, effort: options.effort });
         const before = this.#state.blocks.length;
-        await this.#sendFields({ text, files: [...files], voice: [] });
+        await this.#sendFields({
+            text,
+            files: [...(options.files ?? [])],
+            voice: [...(options.voice ?? [])],
+        });
         return { blocks: this.#state.blocks.slice(before) };
     };
     #set(patch) {
@@ -396,6 +417,14 @@ class Chat {
         });
     }
     /** Draws the conversation as the host shows it: its transcript, and the reply that waits on gates. */
+    /**
+     * The session a run leaves, with the model and effort picked now.
+     * why: the run carries the pick it started with; one made while it ran must outlast it.
+     */
+    #sessionAfter(session, events) {
+        const { selectedModel, selectedEffort } = this.#state.session;
+        return { ...sessionAfter(session, events), selectedModel, selectedEffort };
+    }
     #draw(view, session, events) {
         const shown = [...this.#state.blocks, ...this.#state.streamBlocks];
         const blocks = keepIds(shown, view.transcript);
@@ -403,15 +432,19 @@ class Chat {
             blocks,
             streamBlocks: keepIds(shown.slice(blocks.length), 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),
+            session: this.#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.
+     * invariant: judged only when the interface changes. A pick made under this one stays, and a
+     * model it does not have is refused by the turn, not swapped for the default.
      */
     #followDefaults(iface) {
+        if (iface === this.#defaultsFrom)
+            return;
         const { session } = this.#state;
         const next = followGenerationDefaults(iface, { model: session.selectedModel, effort: session.selectedEffort }, this.#defaultsFrom);
         this.#defaultsFrom = iface;
@@ -789,7 +822,7 @@ class Chat {
      * Returns whether it waits.
      */
     #settleLocal(iface, outcome, worked) {
-        const session = sessionAfter(outcome.session, outcome.events);
+        const session = this.#sessionAfter(outcome.session, outcome.events);
         const { failure } = outcome;
         const reply = stampWorked(foldAssistantTurn(iface, outcome.events), worked);
         if (session.gatedTool !== null) {

package/client/index.d.ts

@@ -1,5 +1,5 @@
 export { float32Rms, float32RmsToLevel, INPUT_LEVEL_GAIN, timeDomainBytesToLevel, } from './audio-level.ts';
-export { type ChatController, type ChatOptions, type ChatSlotDecl, type ChatSlots, type ChatState, type ChatUpdate, createChatController, type MessageDelivery, type SentTurn, } from './chat.ts';
+export { type ChatController, type ChatOptions, type ChatSlotDecl, type ChatSlots, type ChatState, type ChatUpdate, createChatController, type MessageDelivery, type SendTextOptions, 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';
@@ -16,7 +16,7 @@ export { createHostTransport, HOST_TOOL_KINDS, type HostInterface, type HostTool
 export type { LiveCallOptions, PageTool, PageToolAnswer, PageTools, } 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 { LiveGateAnswer, LiveGateReply, LiveToolGatePrompt } from './live/live-tool.ts';
 export type { LiveConnection } from './live-client.ts';
 export { LiveSessionClient } from './live-client.ts';
 export type { ExecuteToolOnRelay, LiveSocket } from './live-messages.ts';

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

@@ -9,3 +9,14 @@ export type LiveToolGatePrompt = {
 };
 /** The user's answer to a live gate, or `withdrawn`: the model cancelled the call, so nothing is asked. */
 export type LiveGateAnswer = ToolGateResolution | 'withdrawn';
+/**
+ * What the host sends for a gate: a refusal, or an approval (with the key the user typed at a
+ * sign-in gate), or `withdrawn` when the model cancelled the call. `continueGatedToolInvocation`
+ * turns the user's answer into one.
+ */
+export type LiveGateReply = {
+    decision: 'deny';
+} | {
+    decision: 'approve';
+    secret?: string;
+} | 'withdrawn';

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

@@ -0,0 +1,18 @@
+import type { ExecuteToolOnRelay } from '../live-messages.ts';
+import type { PageTools } from './live-page-tool.ts';
+import type { LiveGateReply, LiveToolGatePrompt } from './live-tool.ts';
+/**
+ * One call the model made, run to its end: the relay checks it, the page answers a call
+ * dispatched to it, and `onGate` answers any other gate. Every step is answered: a page tool
+ * with no handler, or one that throws, answers with no answer, and with no `onGate` a gate is
+ * refused. A call the model cancels while its gate is open is gone: nothing is sent.
+ */
+export declare function runLiveToolCall(args: {
+    executeToolOnRelay: ExecuteToolOnRelay;
+    pageTools?: PageTools;
+    onGate?: (prompt: LiveToolGatePrompt) => Promise<LiveGateReply>;
+    name: string;
+    toolArgs: Record<string, unknown>;
+    callId: string;
+    operationId: string;
+}): Promise<void>;

package/client/live/run-live-tool-call.js

@@ -0,0 +1,65 @@
+/** Page tools already said to have no handler, so the console says it once for each name. */
+const unhandled = new Set();
+/**
+ * One call the model made, run to its end: the relay checks it, the page answers a call
+ * dispatched to it, and `onGate` answers any other gate. Every step is answered: a page tool
+ * with no handler, or one that throws, answers with no answer, and with no `onGate` a gate is
+ * refused. A call the model cancels while its gate is open is gone: nothing is sent.
+ */
+export async function runLiveToolCall(args) {
+    const { executeToolOnRelay, name, toolArgs, callId, operationId } = args;
+    // why: A name from the model is looked up among the host's own keys only.
+    const pageTool = args.pageTools && Object.hasOwn(args.pageTools, name) ? args.pageTools[name] : undefined;
+    let step = await executeToolOnRelay({ callId, operationId });
+    const dispatched = new Set();
+    while (step.status !== 'settled') {
+        if (step.status === 'dispatched') {
+            if (dispatched.has(step.grantId))
+                return;
+            dispatched.add(step.grantId);
+            const grantId = step.grantId;
+            const input = step.arguments;
+            if (!pageTool && !unhandled.has(name)) {
+                unhandled.add(name);
+                // labels-exempt: builder diagnostic
+                console.warn(`Theorem: page tool '${name}' has no handler in pageTools; the agent gets no answer.`);
+            }
+            const answer = pageTool
+                ? await Promise.resolve()
+                    .then(() => pageTool(input, { callId, operationId }))
+                    .catch(() => undefined)
+                : undefined;
+            step = await executeToolOnRelay({
+                callId,
+                operationId,
+                grantId,
+                ...(answer ? { output: answer.output } : { unanswered: true }),
+            });
+            continue;
+        }
+        const { gate } = step;
+        // why: The page answers only a dispatched call; an old page gate is refused.
+        const reply = gate.kind === 'page' || !args.onGate
+            ? { decision: 'deny' }
+            : await args.onGate({
+                callId,
+                toolName: name,
+                input: gate.preparedArguments ?? toolArgs,
+                gate,
+            });
+        if (reply === 'withdrawn')
+            return;
+        if (reply.decision === 'deny') {
+            // why: The session settles the refusal; its tool event tells the user.
+            await executeToolOnRelay({ callId, operationId, decision: 'deny' });
+            return;
+        }
+        // why: Signed in: a typed key goes once, with the approval; after an OAuth callback there is none.
+        step = await executeToolOnRelay({
+            callId,
+            decision: 'approve',
+            operationId,
+            ...(reply.secret !== undefined ? { secret: reply.secret } : {}),
+        });
+    }
+}

package/client/live-client.d.ts

@@ -12,8 +12,9 @@
  * @module
  */
 import { type SessionEventOf, type TraceRecord } from '@theoremjs/agents';
+import type { PageTools } from './live/live-page-tool.ts';
 import type { LiveConnectPhase, LiveSessionStatus } from './live/live-state.ts';
-import { type ExecuteToolOnRelay, type LiveToolStep } from './live-messages.ts';
+import type { LiveGateReply, LiveToolGatePrompt } from './live/live-tool.ts';
 import { type ClientTurnEvent } from './transport.ts';
 export type { LiveConnection, LiveSocket } from './live-messages.ts';
 import type { LiveSocket } from './live-messages.ts';
@@ -52,13 +53,16 @@ export interface LiveClientOptions {
      */
     onSessionEnded?: (session: SessionEventOf<'ended'>) => void;
     /**
-     * The model called a tool. The host runs it with `executeToolOnRelay` and
-     * answers its gates; the session answers the model. A throw reaches `onError`.
+     * The page's tools, by name. The client runs each call the model makes on the relay, and
+     * answers a call dispatched to the page with the tool of that name. A call the page has no
+     * tool for, or whose tool throws, is answered with no answer, so the turn never waits on it.
      */
-    onToolCall: (name: string, args: Record<string, unknown>, meta: {
-        callId: string;
-        operationId: string;
-    }) => Promise<void>;
+    pageTools?: PageTools;
+    /**
+     * The host's answer to a gate on a call: ask the user, then send what
+     * `continueGatedToolInvocation` makes of their answer. Without it, every gate is refused.
+     */
+    onGate?: (prompt: LiveToolGatePrompt) => Promise<LiveGateReply>;
     /** The relay opened the call: the id it gave the call, and the profile it runs. */
     onSessionReady?: (info: {
         sessionId?: string;
@@ -167,7 +171,7 @@ export declare class LiveSessionClient {
     private handleDoneTurnEvent;
     private scheduleMediaChunks;
     /** The relay runs `LiveSession.executeTool`; see `ExecuteToolOnRelay`. */
-    executeToolOnRelay(args: Parameters<ExecuteToolOnRelay>[0]): Promise<LiveToolStep>;
+    private executeToolOnRelay;
     private enqueueAudioChunk;
     cancelPlayback(): void;
     toggleMute(): boolean;

package/client/live-client.js

@@ -17,6 +17,7 @@ import { describeError, labelText, TheoremError, } from '@theoremjs/agents';
 import { base64ToBytes, bytesToBase64 } from '@theoremjs/agents/kernel';
 import { float32Rms, float32RmsToLevel, timeDomainBytesToLevel } from "./audio-level.js";
 import { applyLiveToolTurnEvent, liveTranscriptFromEvidence, shouldForwardMicFrame, } from "./live/live-mic-forward.js";
+import { runLiveToolCall } from "./live/run-live-tool-call.js";
 import { isPermissionDeniedError } from "./live-errors.js";
 import { liveClientMessageSchema, parseLiveServerEnvelope, } from "./live-messages.js";
 import { MIC_CAPTURE_PROCESSOR, micCaptureWorkletUrl } from "./mic-capture.js";
@@ -462,7 +463,12 @@ 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, {
+                .then(() => runLiveToolCall({
+                executeToolOnRelay: (args) => this.executeToolOnRelay(args),
+                pageTools: this.options.pageTools,
+                onGate: this.options.onGate,
+                name: call.name,
+                toolArgs: call.arguments,
                 callId: call.id,
                 operationId: issuedOperationId(call),
             }))

package/client/turn-client.js

@@ -1,5 +1,5 @@
 import { labelText, TheoremError } from '@theoremjs/agents';
-import { foldTurnEvents, prepareUserTurn, streamThoughtsEnabled, } from '@theoremjs/agents/interface';
+import { defaultInterfaceEffort, foldTurnEvents, prepareUserTurn, streamThoughtsEnabled, } from '@theoremjs/agents/interface';
 import { filesToPending } from "./encode-files.js";
 import { defaultModel } from "./generation-selection.js";
 export function issuedOperationId(call) {
@@ -11,17 +11,22 @@ function resolveModelId(iface, session) {
     return session.selectedModel ?? defaultModel(iface);
 }
 function resolveEffort(iface, session, modelId) {
+    const picked = session.selectedEffort;
     if (!modelId || !Object.hasOwn(iface.models, modelId))
-        return undefined;
+        return picked;
     const binding = iface.models[modelId];
-    if (!binding.allowEffortSelect)
-        return undefined;
-    return session.selectedEffort ?? binding.defaultEffort;
+    if (binding.allowEffortSelect)
+        return picked ?? binding.defaultEffort;
+    return picked === defaultInterfaceEffort(iface, modelId) ? undefined : picked;
 }
-/** Model / effort selection the host should honour for this session. */
+/**
+ * Model / effort selection the host should honour for this session.
+ * invariant: a pick the profile cannot honour goes to the host, which refuses the turn; it is
+ * never dropped for the default. Its own defaults go unsaid where it lets no one pick.
+ */
 function generationFields(iface, session) {
     const modelId = resolveModelId(iface, session);
-    const model = iface.allowModelSelect ? modelId : undefined;
+    const model = iface.allowModelSelect || modelId !== defaultModel(iface) ? modelId : undefined;
     const effort = resolveEffort(iface, session, modelId);
     return { ...(model ? { model } : {}), ...(effort ? { effort } : {}) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.649.gf83cea1",
+  "version": "0.3.4-next.671.gfa09ab2",
   "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.649.gf83cea1"
+    "@theoremjs/agents": "^0.3.4-next.671.gfa09ab2"
   }
 }

package/server/conversation-store.d.ts

@@ -29,7 +29,12 @@ export type PausedReply = {
 };
 /** One conversation as the host stores it. */
 export type StoredConversation = {
-    version: 1;
+    version: 2;
+    /**
+     * The conversation's own id, kept through its rewinds. Each turn carries it as
+     * `conversationId`, which its trace records as `gen_ai.conversation.id`.
+     */
+    id: string;
     /** What the person reads, without the paused reply. */
     transcript: TranscriptBlock[];
     /** What the model reads on the next turn, compacted when the profile compacts. */

package/server/conversation-store.js

@@ -24,7 +24,8 @@ const pausedReply = z.object({
 });
 true;
 const storedConversation = z.object({
-    version: z.literal(1),
+    version: z.literal(2),
+    id: z.string().min(1),
     transcript: z.array(transcriptBlockSchema),
     history: z.array(turnHistoryMessageSchema),
     providerState: providerCheckpointSchema.optional(),
@@ -37,7 +38,7 @@ true;
 export const storedConversationSchema = storedConversation;
 /** An empty conversation: what a chat with no ref starts from. */
 export function emptyConversation() {
-    return { version: 1, transcript: [], history: [] };
+    return { version: 2, id: crypto.randomUUID(), transcript: [], history: [] };
 }
 /** Refuses a ref the store does not know or cannot open: the browser reads `session.conversation_unknown`. */
 export function unknownConversation(cause) {

package/server/conversation.d.ts

@@ -114,6 +114,8 @@ export declare function conversationView(host: ConversationHost, conversation: S
 /** One model run of a reply: the kernel's turn input, the checkpoint it continues, and the generation. */
 export type ReplyTurn = {
     input: TurnInput;
+    /** The stored conversation's id; a run with no conversation has none. */
+    conversationId?: string;
     providerState?: ProviderCheckpoint;
     model?: string;
     effort?: string;

package/server/conversation.js

@@ -230,6 +230,7 @@ async function* runReply(host, opened, reply, runner, input, withMessage) {
     try {
         const events = runner.run({
             input,
+            conversationId: conversation.id,
             providerState: conversation.providerState,
             model: runner.model,
             effort: runner.effort,
@@ -519,7 +520,8 @@ export async function rewindConversation(args) {
     }
     const transcript = conversation.transcript.slice(0, at + 1);
     return save(host, opened, {
-        version: 1,
+        version: 2,
+        id: conversation.id,
         transcript,
         history: historyFromTranscriptBlocks(transcript),
     });

package/server/handler.js

@@ -411,6 +411,7 @@ async function* chatTurn(ctx, request, session, turn, key, stop) {
             execution: sessionToolCoordinator(ctx.sessions, session.id),
             pageExecution: sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker, ctx.options.pageToolTimeoutMs).execution,
             input: turn.input,
+            ...(turn.conversationId ? { conversationId: turn.conversationId } : {}),
             ...(turn.providerState ? { providerState: turn.providerState } : {}),
             sessionPermissions: state.permissions,
             signal: AbortSignal.any([request.signal, stop.signal]),