@theoremjs/web 0.3.4-next.757.gde44a4d → 0.3.4-next.761.g22f8dca

package/README.md

@@ -147,7 +147,7 @@ for await (const event of session.events()) {
 }
 ```
 
-- `prepareLiveOpen` returns validated history, slots, context, native state, and absence duration. It removes system-role history.
+- `prepareLiveOpen` returns validated history, options, context, native state, and absence duration. It removes system-role history.
 - Its second argument supplies server context. Browser context stays under `client`.
 - Save checkpoint ownership before you send the event. If storage fails, close the session without advertising that checkpoint.
 - The boundary refuses native resumption while a saved operation is ready, running, or uncertain. It does not repeat the operation.
@@ -203,8 +203,8 @@ 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. Until the first subscribe or send, the chat asks nothing of the host. Then it reads a resumed conversation that came without its `conversationView`, and answers a restored page gate as unanswered.
-- `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`, `initialText`, `initialFiles`, `initialVoice`, and `initialPending` are read only when the controller is created.
-- A live call takes `stated` in its options, and `setStated(stated)` changes it during the call. As with `setSlots`, the call is taken up again with the prompt lines the new value chooses.
+- `update(options)` gives the controller your latest options, such as a new `context`, `options`, or `pageTools`. Each turn reads the options as they are when it is sent. `conversation`, `conversationView`, `initialText`, `initialFiles`, `initialVoice`, and `initialPending` are read only when the controller is created.
+- A live call takes `stated` in its options, and `setStated(stated)` changes it during the call. As with `setOptions`, the call is taken up again with the prompt lines the new value chooses.
 - 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:

package/client/chat.d.ts

@@ -1,3 +1,4 @@
+import { type ProfileOptions } from '@theoremjs/agents';
 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';
@@ -37,15 +38,15 @@ export type ChatOptions = {
      */
     onConversationChange?: (ref: string | undefined) => void;
     /**
-     * The value chosen for each of the profile's `inputs.slots`. Sent with every turn. A slot you
+     * The value chosen for each of the profile's `inputs.options`. Sent with every turn. An option you
      * name here is fixed to that value; one you leave out is the visitor's to pick (the chat's
-     * `pickSlot`), starting at its first allowed value.
+     * `pickOption`), starting at its first allowed value.
      */
-    slots?: Record<string, string>;
+    options?: Record<string, string>;
     /** Which prompt lines each turn gets, for a host that lets its page choose (`pageStatesTurn`). */
     stated?: StatedTurn;
-    /** Told each time the visitor picks a slot, with every slot's value. */
-    onSlotsChange?: (slots: Record<string, string>) => void;
+    /** Told each time the visitor picks an option, with every option's value. */
+    onOptionsChange?: (options: 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'`. */
@@ -61,17 +62,9 @@ export type ChatOptions = {
  * (`sent`), reached the model (`delivered`), answered (`read`).
  */
 export type MessageDelivery = 'sending' | 'sent' | 'delivered' | 'read';
-/** One declared slot as the composer shows it (group label + choices with optional blurbs). */
-export type ChatSlotDecl = {
-    label?: string;
-    choices: readonly {
-        value: string;
-        description?: string;
-    }[];
-};
-/** 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, ChatSlotDecl>;
+/** The options the profile declares, and the value of each: the page's, else the picked one, else the first allowed. */
+export type ChatOptionPicks = {
+    declared: ProfileOptions;
     values: Record<string, string>;
 };
 /** Everything a chat shows. A new object on each change, the same one between changes. */
@@ -97,8 +90,8 @@ export type ChatState = {
     /** 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;
+    /** `undefined` when the profile declares no options. */
+    options: ChatOptionPicks | undefined;
 };
 /** What `sendText` hands back: the blocks the turn added, its user message, and the reply. */
 export type SentTurn = {
@@ -170,7 +163,7 @@ export type ChatController = {
         modelId: string;
         effort?: string;
     }): void;
-    pickSlot(name: string, value: string): void;
+    pickOption(name: string, value: string): void;
     /**
      * 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).

package/client/chat.js

@@ -1,4 +1,4 @@
-import { TheoremError } from '@theoremjs/agents';
+import { TheoremError, } from '@theoremjs/agents';
 import { branchInterfaceTurnSession, consumeNextComposerQueue, convertSteersToFrontQueued, createComposerPendingMessage, defaultInterfaceEffort, emptyInterfaceTurnSession, moveComposerPendingWithinKind, orderComposerPendingMessages, promoteComposerPendingKind, removeComposerPendingMessage, removeLandedSteers, userDraftHasPayload, userDraftToSteerInject, } from '@theoremjs/agents/interface';
 import { composerHasPayload } from "./composer-primary.js";
 import { composerFieldsFromDraft } from "./decode-composer-draft.js";
@@ -45,8 +45,8 @@ function withTurnError(blocks, error) {
         return blocks;
     return [...blocks, { id: crypto.randomUUID(), kind: 'error', message: error }];
 }
-function slotsOf(iface, fixed, picked) {
-    const declared = iface?.inputs.slots ?? {};
+function picksOf(iface, fixed, picked) {
+    const declared = iface?.inputs.options ?? {};
     const values = { ...fixed };
     for (const [name, decl] of Object.entries(declared)) {
         const first = decl.choices[0]?.value;
@@ -57,10 +57,10 @@ function slotsOf(iface, fixed, picked) {
     const chosen = Object.keys(declared).length > 0;
     return {
         values: chosen || fixed ? values : undefined,
-        slots: chosen ? { declared, values } : undefined,
+        options: chosen ? { declared, values } : undefined,
     };
 }
-function sameSlots(a, b) {
+function samePicks(a, b) {
     if (a === undefined || b === undefined)
         return a === b;
     const keys = Object.keys(a.values);
@@ -136,7 +136,7 @@ class Chat {
             session: emptyInterfaceTurnSession(),
             delivery: null,
             streaming: false,
-            slots: slotsOf(options.iface, options.slots, {}).slots,
+            options: picksOf(options.iface, options.options, {}).options,
         };
         this.#notified = this.#state;
         this.#warnPageTools();
@@ -241,12 +241,12 @@ class Chat {
     update = (options) => {
         this.#options = options;
         this.#warnPageTools();
-        const { slots } = slotsOf(options.iface, options.slots, this.#picked);
+        const { options: picks } = picksOf(options.iface, options.options, this.#picked);
         const patch = {};
         if (options.iface !== this.#state.iface)
             patch.iface = options.iface;
-        if (!sameSlots(slots, this.#state.slots))
-            patch.slots = slots;
+        if (!samePicks(picks, this.#state.options))
+            patch.options = picks;
         if (Object.keys(patch).length > 0)
             this.#set(patch);
     };
@@ -425,11 +425,13 @@ class Chat {
             session: { ...this.#state.session, selectedModel: next.modelId, selectedEffort: effort },
         });
     };
-    pickSlot = (name, value) => {
-        const before = slotsOf(this.#options.iface, this.#options.slots, this.#picked).values;
+    pickOption = (name, value) => {
+        const before = picksOf(this.#options.iface, this.#options.options, 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 });
+        this.#set({
+            options: picksOf(this.#options.iface, this.#options.options, this.#picked).options,
+        });
+        this.#options.onOptionsChange?.({ ...before, [name]: value });
     };
     sendText = async (text, options = {}) => {
         if (!this.#options.iface || this.#state.phase !== 'idle')
@@ -755,7 +757,7 @@ class Chat {
     }
     /**
      * 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
+     * page's options 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).
      */
@@ -773,16 +775,16 @@ class Chat {
         };
     }
     #withValues(request) {
-        const { iface, slots: fixed, context, stated } = this.#options;
-        const slots = slotsOf(iface, fixed, this.#picked).values;
-        if (slots === undefined && context === undefined && stated === undefined)
+        const { iface, options: fixed, context, stated } = this.#options;
+        const options = picksOf(iface, fixed, this.#picked).values;
+        if (options === undefined && context === undefined && stated === undefined)
             return request;
         return {
             ...request,
             ...(stated === undefined ? {} : { stated }),
             input: {
                 ...request.input,
-                ...(slots === undefined ? {} : { slots }),
+                ...(options === undefined ? {} : { options }),
                 ...(context === undefined ? {} : { context }),
             },
         };

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 SendTextOptions, type SentTurn, } from './chat.ts';
+export { type ChatController, type ChatOptionPicks, type ChatOptions, 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';

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

@@ -15,8 +15,8 @@ export type PageTool = (args: Record<string, unknown>, call: {
 export type PageTools = Record<string, PageTool>;
 /** What a host gives a live call. */
 export type LiveCallOptions = {
-    /** The value chosen for each of the profile's `inputs.slots`, read as the call starts. */
-    slots?: Record<string, string>;
+    /** The value chosen for each of the profile's `inputs.options`, read as the call starts. */
+    options?: Record<string, string>;
     /** Which prompt lines the call gets, for a host that lets its page choose (`pageStatesTurn`). */
     stated?: StatedTurn;
     /** The model picked for the call, read as the call starts, when the profile allows it. */

package/client/live-client.d.ts

@@ -22,8 +22,8 @@ export interface LiveClientOptions {
     profile?: string;
     /** The host's own JSON for its relay, sent as the open message's `host`. */
     openMessage?: Record<string, unknown>;
-    /** The value chosen for each of the profile's `inputs.slots`, fixed for the call. */
-    slots?: Record<string, string>;
+    /** The value chosen for each of the profile's `inputs.options`, fixed for the call. */
+    options?: Record<string, string>;
     /** Which prompt lines the call gets, for a host that lets its page choose (`pageStatesTurn`). */
     stated?: StatedTurn;
     /** The model picked for the call, when the profile allows it. */
@@ -183,11 +183,11 @@ export declare class LiveSessionClient {
     toggleMute(): boolean;
     sendText(text: string): void;
     /**
-     * The call's slot values. An open call is taken up again with them when the provider gave a
+     * The call's option values. An open call is taken up again with them when the provider gave a
      * handle; with none, the next call has them.
      */
-    setSlots(slots: Record<string, string> | undefined): void;
-    /** The call's prompt lines, as `setSlots` takes its slots. */
+    setOptions(options: Record<string, string> | undefined): void;
+    /** The call's prompt lines, as `setOptions` takes its options. */
     setStated(stated: StatedTurn | undefined): void;
     private takeUpAgain;
     /**

package/client/live-client.js

@@ -228,11 +228,11 @@ export class LiveSessionClient {
     }
     /** The first message: the call's values, and the handle and time away when it takes a dropped call up again. */
     openMessage() {
-        const { slots, stated, model, effort, openMessage: host } = this.options;
+        const { options, stated, model, effort, openMessage: host } = this.options;
         return {
             type: 'open',
             ...(this.history.length ? { history: structuredClone(this.history) } : {}),
-            ...(slots ? { slots } : {}),
+            ...(options ? { options } : {}),
             ...(stated ? { stated } : {}),
             ...(model ? { model } : {}),
             ...(effort ? { effort } : {}),
@@ -767,16 +767,16 @@ export class LiveSessionClient {
         }
     }
     /**
-     * The call's slot values. An open call is taken up again with them when the provider gave a
+     * The call's option values. An open call is taken up again with them when the provider gave a
      * handle; with none, the next call has them.
      */
-    setSlots(slots) {
-        if (JSON.stringify(slots) === JSON.stringify(this.options.slots))
+    setOptions(options) {
+        if (JSON.stringify(options) === JSON.stringify(this.options.options))
             return;
-        this.options = { ...this.options, slots };
+        this.options = { ...this.options, options };
         this.takeUpAgain();
     }
-    /** The call's prompt lines, as `setSlots` takes its slots. */
+    /** The call's prompt lines, as `setOptions` takes its options. */
     setStated(stated) {
         if (JSON.stringify(stated) === JSON.stringify(this.options.stated))
             return;

package/client/live-messages.d.ts

@@ -16,8 +16,8 @@ import { type MalformedEvent, type UnsupportedEvent } from './wire-line.ts';
 export type LiveOpenMessage = {
     type: 'open';
     history?: TurnHistoryMessage[];
-    /** The value chosen for each of the profile's `inputs.slots`. */
-    slots?: Record<string, string>;
+    /** The value chosen for each of the profile's `inputs.options`. */
+    options?: Record<string, string>;
     /** What the page tells the agent as the call opens: the client's context package. */
     context?: unknown;
     /** Which prompt lines the call gets, for a host that lets its page choose (`pageStatesTurn`). */

package/client/live-messages.js

@@ -12,7 +12,7 @@ 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(),
+    options: z.record(z.string(), z.string()).optional(),
     context: z.unknown().optional(),
     stated: statedTurnSchema.optional(),
     model: z.string().optional(),

package/client/transport.d.ts

@@ -27,8 +27,8 @@ export type TheoremTurnInput = {
     text?: string;
     attachments?: EncodedBlob[];
     voice?: EncodedBlob[];
-    /** The value chosen for each of the profile's `inputs.slots`. */
-    slots?: Record<string, string>;
+    /** The value chosen for each of the profile's `inputs.options`. */
+    options?: Record<string, string>;
     /** What the page wants the agent to know: any JSON. The host reads it as untrusted. */
     context?: unknown;
 };
@@ -49,10 +49,10 @@ export type TheoremReplay = {
 };
 /** For a host that reads the studio's client-held state. */
 export declare const theoremReplaySchema: z.ZodType<TheoremReplay>;
-/** Which prompt lines a turn gets: the path it says it came by, and its `identity.conditions`. */
+/** Which prompt lines a turn gets: the path it says it came by, and its `identity.options`. */
 export type StatedTurn = {
     path?: string;
-    conditions?: Record<string, string>;
+    options?: Record<string, string>;
 };
 /** A stated turn off the wire. */
 export declare const statedTurnSchema: z.ZodType<StatedTurn>;

package/client/transport.js

@@ -17,7 +17,7 @@ import { checkWire, parseWireJson, readWireLine, } from "./wire-line.js";
 const encodedBlob = z.object({ name: z.string(), mimeType: z.string(), data: z.string() });
 true;
 const theoremTurnInput = z.object({
-    slots: z.record(z.string(), z.string()).optional(),
+    options: z.record(z.string(), z.string()).optional(),
     context: z.unknown().optional(),
     text: z.string().optional(),
     attachments: z.array(encodedBlob).optional(),
@@ -41,7 +41,7 @@ export const theoremReplaySchema = theoremReplay;
 const clientId = z.string().trim().min(1);
 const statedTurn = z.object({
     path: z.string().optional(),
-    conditions: z.record(z.string(), z.string()).optional(),
+    options: z.record(z.string(), z.string()).optional(),
 });
 true;
 /** A stated turn off the wire. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.757.gde44a4d",
+  "version": "0.3.4-next.761.g22f8dca",
   "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.757.gde44a4d"
+    "@theoremjs/agents": "^0.3.4-next.761.g22f8dca"
   }
 }

package/server/conversation.d.ts

@@ -146,7 +146,7 @@ export type PostedMessage = {
     /** The message's blocks (`prepareUserTurn`), with their media inline. */
     blocks: TranscriptBlock[];
     media: UserTurnHistoryMedia;
-    /** The kernel input without history: the message's text as the transcript shows it, its media, slots, and context. */
+    /** The kernel input without history: the message's text as the transcript shows it, its media, options, and context. */
     input: TurnInput;
 };
 /**

package/server/session-boundary.d.ts

@@ -14,7 +14,7 @@ export interface SessionBoundaryOptions {
     /** How long the page has to answer a tool call it runs, in milliseconds. Unset, it waits. */
     pageToolTimeoutMs?: number;
 }
-export type PreparedLiveOpen = Pick<SessionRequest, 'history' | 'slots' | 'context' | 'providerState' | 'awayMs' | 'path' | 'conditions'>;
+export type PreparedLiveOpen = Pick<SessionRequest, 'history' | 'inputOptions' | 'context' | 'providerState' | 'awayMs' | 'path' | 'options'>;
 export interface TheoremSessionBoundary {
     sessionId: string;
     setCookie?: string;

package/server/session-store.js

@@ -28,7 +28,7 @@ const blobSchema = z.strictObject({
 const inputSchema = z.strictObject({
     text: z.string().optional(),
     role: z.string().optional(),
-    slots: z.record(z.string(), z.string()).optional(),
+    options: z.record(z.string(), z.string()).optional(),
     context: z
         .strictObject({ client: jsonValueSchema.optional(), server: jsonValueSchema.optional() })
         .optional(),

package/server/turn-input.d.ts

@@ -7,4 +7,4 @@ export declare function kernelTurnInput(input: TheoremTurnInput, server?: unknow
  * What a live call's first message asks of the session, as `runSession` takes
  * it: the page's context is the client's, and `server` is the host's own.
  */
-export declare function liveSessionOpen(open: LiveOpenMessage, server?: unknown): Pick<SessionRequest, 'slots' | 'context' | 'providerState' | 'awayMs' | 'history' | 'path' | 'conditions' | 'model' | 'effort'>;
+export declare function liveSessionOpen(open: LiveOpenMessage, server?: unknown): Pick<SessionRequest, 'inputOptions' | 'context' | 'providerState' | 'awayMs' | 'history' | 'path' | 'options' | 'model' | 'effort'>;

package/server/turn-input.js

@@ -20,7 +20,7 @@ export function liveSessionOpen(open, server) {
     const context = turnContext(open.context, server);
     return {
         ...(open.history ? { history: open.history } : {}),
-        ...(open.slots ? { slots: open.slots } : {}),
+        ...(open.options ? { inputOptions: open.options } : {}),
         ...(context ? { context } : {}),
         ...open.stated,
         ...(open.model ? { model: open.model } : {}),