@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/interface/from-profile.js

@@ -1,38 +1,47 @@
-// `profileInterfaceSchema` keeps only the JSON it names, so host functions never reach the view.
-import { egressChecksOf } from '../guardrails/egress.js';
-import { clientLexicon } from '../guardrails/lexicon.js';
+// why: `profileInterfaceSchema` keeps only the JSON it names, so host functions never reach the view.
+import { clientLabels } from '../guardrails/labels.js';
 import { resolveGuardrailPolicy } from '../guardrails/policy.js';
 import { projectProfileObject, requireModelProfile } from '../kernel/registry/resolve.js';
 import { profileAllowsSteering } from '../kernel/stop.js';
-import { profileToolAllow, profileToolsSpec } from '../kernel/tools/resolve.js';
+import { profileToolAllow, profileToolsParallel, profileToolsSpec, } from '../kernel/tools/resolve.js';
 import { resolveObservabilityPolicy } from '../observability/resolve-policy.js';
 import { inputsFromSpec } from './inputs.js';
 import { profileInterfaceSchema } from './profile-interface.js';
 /** Resolved, not raw: a host sees what the kernel will enforce, not defaults of its own. */
 function guardrailsView(guardrails) {
     const policy = resolveGuardrailPolicy(guardrails);
+    const { sources, host, ...detect } = policy.detect;
     return {
         quota: policy.quota,
-        canary: policy.canary,
-        sanitizeInput: policy.sanitizeInput,
-        redactSensitive: policy.redactSensitive,
-        hasEgress: Boolean(policy.egress),
-        egressChecks: egressChecksView(egressChecksOf(policy.egress?.enforce)),
+        detect,
+        ...(sources
+            ? {
+                patterns: Object.fromEntries(Object.entries(sources).map(([detector, { theorem, matchers }]) => [
+                    detector,
+                    { theorem, names: matchers.map(({ name }) => name) },
+                ])),
+            }
+            : {}),
+        ...(host
+            ? {
+                host: host.map(({ id, label, actions, matchers, find }) => ({
+                    id,
+                    label,
+                    actions,
+                    names: matchers.map(({ name }) => name),
+                    find: Boolean(find),
+                })),
+            }
+            : {}),
+        allow: {
+            ungiven_images: urlAllowView(policy.allow.ungiven_images),
+            ungiven_links: urlAllowView(policy.allow.ungiven_links),
+        },
+        blockedReply: policy.blockedReply,
     };
 }
-function urlCheckView(check) {
-    return check ? { hosts: [...(check.hosts ?? [])], fromTools: check.fromTools ?? true } : false;
-}
-function egressChecksView(checks) {
-    if (!checks)
-        return null;
-    return {
-        sensitive: { ...checks.sensitive },
-        boundary: checks.boundary,
-        injection: checks.injection,
-        images: urlCheckView(checks.images),
-        links: urlCheckView(checks.links),
-    };
+function urlAllowView(allow) {
+    return { hosts: [...(allow.hosts ?? [])], fromTools: allow.fromTools ?? true };
 }
 function writeToView(writeTo) {
     if (writeTo === undefined || writeTo === false) {
@@ -61,15 +70,33 @@ function observabilityView(observability) {
         hasOnWriteError: Boolean(policy.onWriteError),
     };
 }
+/** The live settings a client reads. The greeting and resume prompts are the host's, like `identity.system`. */
+function liveView(live) {
+    const { greeting: _greeting, resumed: _resumed, ...view } = live ?? {};
+    return view;
+}
 function toolsView(projected, profile) {
+    const page = projected.tools
+        .filter((tool) => 'type' in tool && tool.type === 'function' && tool.answeredBy === 'page')
+        .map((tool) => tool.name);
     if (profile) {
-        const t2Loader = profileToolsSpec(profile)?.t2Loader;
-        return { allow: [...profileToolAllow(profile)], ...(t2Loader ? { t2Loader } : {}) };
+        const spec = profileToolsSpec(profile);
+        const parallel = profileToolsParallel(profile);
+        return {
+            allow: [...profileToolAllow(profile)],
+            page,
+            ...(spec?.t2Loader ? { t2Loader: spec.t2Loader } : {}),
+            ...(parallel !== undefined ? { parallel } : {}),
+        };
     }
     const allow = projected.tools
         .filter((tool) => !('type' in tool && tool.type === 'builtin'))
         .map((tool) => tool.name);
-    return { allow };
+    return { allow, page };
+}
+/** A call has no T2 loader. */
+function liveToolsView({ allow, page }) {
+    return { allow, page };
 }
 function enrich(projected, profile) {
     const inputs = inputsFromSpec(projected.inputs);
@@ -84,11 +111,11 @@ function enrich(projected, profile) {
         defaultModel: projected.defaultModel,
         allowModelSelect: projected.allowModelSelect,
         maxSteps: projected.maxSteps,
-        key: projected.key,
+        providerContinuation: projected.providerContinuation,
         outputs,
         guardrails,
         observability,
-        lexicon: clientLexicon(profile?.lexicon),
+        labels: clientLabels(profile?.labels),
     };
     switch (projected.type) {
         case 'text':
@@ -124,8 +151,9 @@ function enrich(projected, profile) {
             return profileInterfaceSchema.parse({
                 ...shared,
                 type: 'live',
-                live: projected.live ?? {},
-                tools: { allow: toolsView(projected, profile).allow },
+                live: liveView(projected.live),
+                ...(projected.inputs ? { inputs: { slots: inputs.slots, context: inputs.context } } : {}),
+                tools: liveToolsView(toolsView(projected, profile)),
             });
         default: {
             const exhaustive = projected.type;
@@ -133,12 +161,19 @@ function enrich(projected, profile) {
         }
     }
 }
+/** The interface for any profile. */
 function interfaceFromProfile(input, tools) {
-    // Host profiles never run a model and have no composer surface.
+    // why: Host profiles never run a model and have no composer surface.
     const profile = requireModelProfile(input, 'interfaceFromProfile');
     return enrich(projectProfileObject(tools, profile), profile);
 }
+/** The interface for a profile the host has already projected, without resolving its tools again. */
 function interfaceFromProjected(projected) {
     return enrich(projected);
 }
-export { interfaceFromProfile, interfaceFromProjected };
+/** The client-safe interface for any profile. */
+function clientProfileInterface(input, tools) {
+    const iface = interfaceFromProfile(input, tools);
+    return { ...iface, identity: { handle: iface.identity.handle } };
+}
+export { clientProfileInterface, interfaceFromProfile, interfaceFromProjected };

package/esm/src/interface/history.d.ts

@@ -1,5 +1,5 @@
-import { type LexiconOverrides } from '../guardrails/lexicon.js';
-import type { ToolCallRequest } from '../kernel/turn-events.js';
+import { type LabelOverrides } from '../guardrails/labels.js';
+import { type ToolCallRequest } from '../kernel/turn-events.js';
 import type { TurnBlob, TurnEvent, TurnHistoryMessage } from '../kernel/types.js';
 import type { ToolCall, TranscriptBlock, UserTurnDraft } from './types.js';
 /**
@@ -7,21 +7,26 @@ import type { ToolCall, TranscriptBlock, UserTurnDraft } from './types.js';
  * come from a run and has no text the model read.
  */
 declare function toolReadBack(call: ToolCall): string;
+/** The files a user turn adds to the history beside its text. */
 export type UserTurnHistoryMedia = {
     attachments?: TurnBlob[];
     voice?: TurnBlob[];
 };
 /** For `onStage` inject. Uses base64 on `draft.attachments` / `draft.voice` when present. */
 declare function userDraftToSteerInject(draft: UserTurnDraft): TurnHistoryMessage[];
+/** The history with the user's draft added as a user message. */
 declare function appendUserDraftToHistory(history: TurnHistoryMessage[], draft: UserTurnDraft, media?: UserTurnHistoryMedia): TurnHistoryMessage[];
+/** The history with a tool call and its result added. */
 declare function appendToolExchangeToHistory(history: TurnHistoryMessage[], call: ToolCall): TurnHistoryMessage[];
+/** The history with a denied tool call and the reason added. */
 declare function appendToolDenialToHistory(history: TurnHistoryMessage[], tool: ToolCallRequest & {
     /** Override the default deny copy. */
     failure?: {
         code: string;
         message: string;
     };
-}, lexicon: LexiconOverrides | undefined): TurnHistoryMessage[];
+}, labels: LabelOverrides | undefined): TurnHistoryMessage[];
+/** The history with the assistant's reply from the turn events added. */
 declare function appendAssistantEventsToHistory(history: TurnHistoryMessage[], events: readonly TurnEvent[]): TurnHistoryMessage[];
 /**
  * A reply paused on its gates, as the model reads it when the user walks away:
@@ -31,6 +36,7 @@ declare function appendAssistantEventsToHistory(history: TurnHistoryMessage[], e
 declare function appendPausedTurnToHistory(history: TurnHistoryMessage[], events: readonly TurnEvent[]): TurnHistoryMessage[];
 /** Attachment and voice blocks are omitted: their preview `data` is UI-only. */
 declare function historyFromTranscriptBlocks(blocks: readonly TranscriptBlock[]): TurnHistoryMessage[];
+/** Throws unless the history's open tool calls are exactly these ids. */
 declare function assertOpenToolCalls(history: readonly TurnHistoryMessage[], ids: readonly string[]): void;
 /**
  * `answers` holds, by call id, the text the model reads for each open call. Results follow their

package/esm/src/interface/history.js

@@ -1,9 +1,10 @@
-// A settled tool call replays its `readBack`, the text the model read, so provider continuation
+// invariant: A settled tool call replays its `readBack`, the text the model read, so provider continuation
 // matches `runTurn` / `invokeTool`.
 import { TheoremError } from '../guardrails/error.js';
-import { lexiconText } from '../guardrails/lexicon.js';
+import { labelText } from '../guardrails/labels.js';
 import { mediaKindForMime } from '../kernel/registry/catalog.js';
 import { formatToolFailureForModel, formatToolResult } from '../kernel/tools/model-text.js';
+import { keptReply } from '../kernel/turn-events.js';
 import { applyToolEvent, toolCallRanWith } from './tool-calls.js';
 /**
  * The kernel sets `readBack` on every `complete` and `error` event, so a call without it did not
@@ -35,6 +36,7 @@ function userDraftToSteerInject(draft) {
         ...(voice ? { voice } : {}),
     });
 }
+/** The history with the user's draft added as a user message. */
 function appendUserDraftToHistory(history, draft, media = {}) {
     const text = draft.text?.trim();
     const parts = [];
@@ -60,19 +62,24 @@ function toolCallEntry(tool) {
         id: tool.callId,
         type: 'function',
         function: { name: tool.name, arguments: JSON.stringify(tool.arguments) },
-        ...(tool.thoughtSignature ? { thoughtSignature: tool.thoughtSignature } : {}),
+    };
+}
+/** The assistant message holding a step's calls, with the reasoning the model wrote before them. */
+function assistantCalls(tools) {
+    const reasoning = tools.flatMap((tool) => tool.reasoning ?? []);
+    return {
+        role: 'assistant',
+        tool_calls: tools.map(toolCallEntry),
+        ...(reasoning.length ? { reasoning } : {}),
     };
 }
 function toolResultMessage(tool, content) {
     return { role: 'tool', tool_call_id: tool.callId, name: tool.name, content };
 }
 function appendToolCallPair(history, tool, content) {
-    return [
-        ...history,
-        { role: 'assistant', tool_calls: [toolCallEntry(tool)] },
-        toolResultMessage(tool, content),
-    ];
+    return [...history, assistantCalls([tool]), toolResultMessage(tool, content)];
 }
+/** The history with a tool call and its result added. */
 function appendToolExchangeToHistory(history, call) {
     return appendToolCallPair(history, historyToolCall(call), toolReadBack(call));
 }
@@ -81,13 +88,14 @@ function historyToolCall(call) {
         name: call.name,
         callId: call.callId,
         arguments: toolCallRanWith(call),
-        ...(call.thoughtSignature ? { thoughtSignature: call.thoughtSignature } : {}),
+        ...(call.reasoning ? { reasoning: call.reasoning } : {}),
     };
 }
-function appendToolDenialToHistory(history, tool, lexicon) {
+/** The history with a denied tool call and the reason added. */
+function appendToolDenialToHistory(history, tool, labels) {
     const failure = tool.failure ?? {
         code: 'denied',
-        message: lexiconText('session.tool_denied', { tool: tool.name }, lexicon),
+        message: labelText('session.tool_denied', { tool: tool.name }, labels),
     };
     return appendToolCallPair(history, tool, formatToolResult(formatToolFailureForModel(failure)));
 }
@@ -98,8 +106,8 @@ function settledToolContent(call) {
 }
 /**
  * One model step's settled calls: a single assistant message holding every call
- * the step made, then each result. Google replays a step's calls only this way,
- * with the step's thought signature on its first call. With `gated: 'open'`, a
+ * the step made, with the reasoning written before them, then each result. Google replays a
+ * step's calls only this way. With `gated: 'open'`, a
  * call waiting on its gate joins the message too, left without a result.
  */
 function appendToolStepToHistory(history, calls, gated = 'omit') {
@@ -115,10 +123,11 @@ function appendToolStepToHistory(history, calls, gated = 'omit') {
         return history;
     return [
         ...history,
-        { role: 'assistant', tool_calls: entries.map(({ tool }) => toolCallEntry(tool)) },
+        assistantCalls(entries.map(({ tool }) => tool)),
         ...entries.flatMap(({ tool, content }) => content === undefined ? [] : [toolResultMessage(tool, content)]),
     ];
 }
+/** The history with the assistant's reply from the turn events added. */
 function appendAssistantEventsToHistory(history, events) {
     return foldAssistantEvents(history, events, 'omit');
 }
@@ -133,7 +142,6 @@ function appendPausedTurnToHistory(history, events) {
 function foldAssistantEvents(history, events, gated) {
     let next = history;
     let textBuf = '';
-    // The calls of the step being read, in the order the model made them.
     let step;
     const calls = new Map();
     const flushText = () => {
@@ -147,11 +155,11 @@ function foldAssistantEvents(history, events, gated) {
         if (!step) {
             return;
         }
-        const stepCalls = step.callIds.flatMap((id) => calls.get(id) ?? []);
+        const stepCalls = step.callKeys.flatMap((id) => calls.get(id) ?? []);
         next = appendToolStepToHistory(next, stepCalls, gated);
         step = undefined;
     };
-    for (const event of events) {
+    for (const event of keptReply(events)) {
         if (event.type === 'text') {
             flushStep();
             textBuf += event.text;
@@ -159,25 +167,26 @@ function foldAssistantEvents(history, events, gated) {
         }
         if (event.type === 'structured' && event.structured !== undefined) {
             flushStep();
-            flushText();
+            // why: The streamed text is this reply's JSON as the model wrote it; the structured output is the reply as kept.
+            textBuf = '';
             next = [...next, { role: 'assistant', content: JSON.stringify(event.structured) }];
             continue;
         }
         if (event.type !== 'tool') {
             continue;
         }
-        const call = applyToolEvent(calls.get(event.tool.callId), event.tool);
-        calls.set(call.callId, call);
+        const key = event.tool.operationId ?? event.tool.callId;
+        const call = applyToolEvent(calls.get(key), event.tool);
+        calls.set(key, call);
         if (event.tool.phase !== undefined) {
             continue;
         }
-        // A call opens its step, or joins the one it was made with.
         if (!step || call.stepId === undefined || step.stepId !== call.stepId) {
             flushStep();
             flushText();
-            step = { stepId: call.stepId, callIds: [] };
+            step = { stepId: call.stepId, callKeys: [] };
         }
-        step.callIds.push(call.callId);
+        step.callKeys.push(key);
     }
     flushStep();
     flushText();
@@ -186,7 +195,6 @@ function foldAssistantEvents(history, events, gated) {
 /** Attachment and voice blocks are omitted: their preview `data` is UI-only. */
 function historyFromTranscriptBlocks(blocks) {
     let history = [];
-    // Consecutive tool blocks from one model step replay together.
     let step = [];
     const flushStep = () => {
         history = appendToolStepToHistory(history, step);
@@ -238,6 +246,7 @@ function openToolCallIds(history) {
 function openCallsMismatch(history, ids) {
     return new TheoremError('request', `the history leaves open [${openToolCallIds(history).join(', ')}], not [${ids.join(', ')}]`);
 }
+/** Throws unless the history's open tool calls are exactly these ids. */
 function assertOpenToolCalls(history, ids) {
     const open = openToolCallIds(history);
     if (open.length !== ids.length || open.some((id) => !ids.includes(id))) {

package/esm/src/interface/inputs.d.ts

@@ -1,5 +1,6 @@
 import type { ProfileInputsSpec } from '../kernel/types.js';
 import type { AttachmentValidationResult, ProfileInputsInterface, UserTurnDraft } from './types.js';
+/** The accepted MIME types as the value of an HTML `accept` attribute, comma-joined. */
 declare function attachmentAcceptAttr(accept: string[]): string;
 /** `inputs` is null for profile types that declare none (the kernel's `profileInputs`). */
 declare function inputsFromSpec(inputs: ProfileInputsSpec | null | undefined): ProfileInputsInterface;

package/esm/src/interface/inputs.js

@@ -7,6 +7,7 @@ const RECORDER_CANDIDATES = [
     'audio/wav',
     'audio/mpeg',
 ];
+/** The accepted MIME types as the value of an HTML `accept` attribute, comma-joined. */
 function attachmentAcceptAttr(accept) {
     return accept.join(',');
 }
@@ -23,6 +24,7 @@ function inputsFromSpec(inputs) {
         maxTurnBytes: inputs?.maxTurnBytes,
         limitsByMime: inputs?.limitsByMime,
         slots: inputs?.slots,
+        context: inputs?.context,
     };
 }
 function toProfileInputsSpec(inputs) {
@@ -35,6 +37,7 @@ function toProfileInputsSpec(inputs) {
         maxTurnBytes: inputs.maxTurnBytes,
         limitsByMime: inputs.limitsByMime,
         slots: inputs.slots,
+        context: inputs.context,
     };
 }
 /** Validate staged files against resolved profile `inputs`: the kernel's one attachment check. */

package/esm/src/interface/mod.d.ts

@@ -11,7 +11,7 @@ export type { ComposerActionContext, ComposerMenuAction, ComposerPrimaryAction,
 export { resolveComposerMenuActions, resolveComposerPrimary } from './composer-actions.js';
 export type { PrepareUserTurnResult } from './draft.js';
 export { prepareUserTurn, sanitizeUserDraft } from './draft.js';
-export { interfaceFromProfile, interfaceFromProjected } from './from-profile.js';
+export { clientProfileInterface, interfaceFromProfile, interfaceFromProjected, } from './from-profile.js';
 export type { UserTurnHistoryMedia } from './history.js';
 export { answerOpenToolCalls, appendAssistantEventsToHistory, appendPausedTurnToHistory, appendToolDenialToHistory, appendToolExchangeToHistory, appendUserDraftToHistory, assertOpenToolCalls, historyFromTranscriptBlocks, toolReadBack, userDraftToSteerInject, } from './history.js';
 export { attachmentAcceptAttr, inputsFromSpec, pickMediaRecorderMime, validateProfileInputs, } from './inputs.js';
@@ -22,8 +22,10 @@ export { COMPOSER_PENDING_KINDS, cloneUserTurnDraft, composerPendingPreview, con
 export { profileInterfaceSchema } from './profile-interface.js';
 export type { AwaitingToolContext, GatedToolContext, InterfaceTurnSession, ToolGateAuth, } from './session.js';
 export { applyTurnEventsToSession, awaitingFromEvents, branchInterfaceTurnSession, emptyInterfaceTurnSession, gatedToolFromEvents, gatedToolsFromEvents, } from './session.js';
+export type { WordedStopKind } from './stop.js';
+export { stopText, WORDED_STOP_KINDS } from './stop.js';
 export type { SettledToolCallEvent } from './tool-calls.js';
-export { settlesToolCall, toolCallRanWith, toolCallsOf } from './tool-calls.js';
+export { argumentsSoFar, settlesToolCall, toolCallRanWith, toolCallsOf } from './tool-calls.js';
 export { promotedToolIdsFromEvents, toolSnapshotFromEvents } from './tool-invoke.js';
 export type { PromotedToolMedia } from './tool-media.js';
 export { collectPromotedMediaFromToolOutput, promotedMediaFromUrlString, } from './tool-media.js';

package/esm/src/interface/mod.js

@@ -8,14 +8,15 @@ import "../../_dnt.polyfills.js";
 export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds, } from './blocks.js';
 export { resolveComposerMenuActions, resolveComposerPrimary } from './composer-actions.js';
 export { prepareUserTurn, sanitizeUserDraft } from './draft.js';
-export { interfaceFromProfile, interfaceFromProjected } from './from-profile.js';
+export { clientProfileInterface, interfaceFromProfile, interfaceFromProjected, } from './from-profile.js';
 export { answerOpenToolCalls, appendAssistantEventsToHistory, appendPausedTurnToHistory, appendToolDenialToHistory, appendToolExchangeToHistory, appendUserDraftToHistory, assertOpenToolCalls, historyFromTranscriptBlocks, toolReadBack, userDraftToSteerInject, } from './history.js';
 export { attachmentAcceptAttr, inputsFromSpec, pickMediaRecorderMime, validateProfileInputs, } from './inputs.js';
 export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, modelSelectEnabled, } from './models.js';
 export { COMPOSER_PENDING_KINDS, cloneUserTurnDraft, composerPendingPreview, consumeNextComposerQueue, consumeNextComposerSteer, convertSteersToFrontQueued, createComposerPendingMessage, moveComposerPendingWithinKind, orderComposerPendingMessages, promoteComposerPendingKind, removeComposerPendingMessage, removeLandedSteers, updateComposerPendingDraft, userDraftHasPayload, } from './pending.js';
 export { profileInterfaceSchema } from './profile-interface.js';
 export { applyTurnEventsToSession, awaitingFromEvents, branchInterfaceTurnSession, emptyInterfaceTurnSession, gatedToolFromEvents, gatedToolsFromEvents, } from './session.js';
-export { settlesToolCall, toolCallRanWith, toolCallsOf } from './tool-calls.js';
+export { stopText, WORDED_STOP_KINDS } from './stop.js';
+export { argumentsSoFar, settlesToolCall, toolCallRanWith, toolCallsOf } from './tool-calls.js';
 export { promotedToolIdsFromEvents, toolSnapshotFromEvents } from './tool-invoke.js';
 export { collectPromotedMediaFromToolOutput, promotedMediaFromUrlString, } from './tool-media.js';
 export { streamThoughtsEnabled } from './types.js';

package/esm/src/interface/models.d.ts

@@ -1,19 +1,26 @@
 import type { ModelId } from '../kernel/types.js';
 import type { ComposerProfileInterface } from './types.js';
 export type ModelSelectProfile = Pick<ComposerProfileInterface, 'id' | 'models' | 'defaultModel' | 'allowModelSelect'>;
+/** One model a user can pick from. */
 export type InterfaceModelOption = {
     id: ModelId;
     label: string;
 };
+/** One effort level a user can pick from, by alias. */
 export type InterfaceEffortOption = {
     alias: string;
     level: string;
 };
+/** True when the profile lets the user pick between two or more models. */
 declare function modelSelectEnabled(profile: ModelSelectProfile): boolean;
+/** True when the model lets the user pick between two or more effort levels. */
 declare function effortSelectEnabled(profile: ModelSelectProfile, modelId: ModelId | undefined): boolean;
+/** True when the user has any model or effort choice to make. */
 declare function generationSelectEnabled(profile: ModelSelectProfile, modelId: ModelId | undefined): boolean;
 /** `defaultEffort` when it names an alias, else the first alias. */
 declare function defaultInterfaceEffort(profile: ModelSelectProfile, modelId: ModelId | undefined): string | undefined;
+/** The models the user can pick from, or none when the choice is off. */
 declare function interfaceModelOptions(profile: ModelSelectProfile): InterfaceModelOption[];
+/** The effort levels the user can pick from for this model, or none when the choice is off. */
 declare function interfaceEffortOptions(profile: ModelSelectProfile, modelId: ModelId | undefined): InterfaceEffortOption[];
 export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, modelSelectEnabled, };

package/esm/src/interface/models.js

@@ -3,15 +3,18 @@ function bindingFor(profile, modelId) {
         return undefined;
     return profile.models[modelId];
 }
+/** True when the profile lets the user pick between two or more models. */
 function modelSelectEnabled(profile) {
     return Boolean(profile.allowModelSelect && Object.keys(profile.models).length >= 2);
 }
+/** True when the model lets the user pick between two or more effort levels. */
 function effortSelectEnabled(profile, modelId) {
     const binding = bindingFor(profile, modelId);
     if (!binding?.allowEffortSelect)
         return false;
     return Object.keys(binding.efforts ?? {}).length >= 2;
 }
+/** True when the user has any model or effort choice to make. */
 function generationSelectEnabled(profile, modelId) {
     return modelSelectEnabled(profile) || effortSelectEnabled(profile, modelId);
 }
@@ -26,6 +29,7 @@ function defaultInterfaceEffort(profile, modelId) {
     const keys = Object.keys(binding.efforts);
     return keys[0];
 }
+/** The models the user can pick from, or none when the choice is off. */
 function interfaceModelOptions(profile) {
     if (!modelSelectEnabled(profile))
         return [];
@@ -34,6 +38,7 @@ function interfaceModelOptions(profile) {
         label: binding.apiId,
     }));
 }
+/** The effort levels the user can pick from for this model, or none when the choice is off. */
 function interfaceEffortOptions(profile, modelId) {
     if (!effortSelectEnabled(profile, modelId))
         return [];

package/esm/src/interface/pending.d.ts

@@ -2,7 +2,9 @@ import type { TurnEvent } from '../kernel/types.js';
 import type { UserTurnDraft } from './types.js';
 /** Display order: steers, then queues, then stashes. */
 export declare const COMPOSER_PENDING_KINDS: readonly ["steer", "queue", "stash"];
+/** One of {@linkcode COMPOSER_PENDING_KINDS}. */
 export type ComposerPendingKind = (typeof COMPOSER_PENDING_KINDS)[number];
+/** A message the user has set aside while a turn runs. */
 export interface ComposerPendingMessage {
     id: string;
     kind: ComposerPendingKind;
@@ -10,17 +12,20 @@ export interface ComposerPendingMessage {
     createdAt: number;
     updatedAt: number;
 }
+/** What `createComposerPendingMessage` takes: the kind and the draft. */
 export type CreateComposerPendingMessageArgs = {
     kind: ComposerPendingKind;
     draft: UserTurnDraft;
     id?: string;
     now?: number;
 };
+/** True when the draft holds text, an attachment, or voice. */
 declare function userDraftHasPayload(draft: UserTurnDraft): boolean;
 /** Short preview for pending bars (text, else attachment hint). */
 declare function composerPendingPreview(message: ComposerPendingMessage): string;
 /** Throws on an empty draft. */
 declare function createComposerPendingMessage(args: CreateComposerPendingMessageArgs): ComposerPendingMessage;
+/** A copy of the draft that shares nothing with the original. */
 declare function cloneUserTurnDraft(draft: UserTurnDraft): UserTurnDraft;
 /** Steer, then queue, then stash; FIFO within a kind. */
 declare function orderComposerPendingMessages(messages: readonly ComposerPendingMessage[]): ComposerPendingMessage[];
@@ -31,8 +36,11 @@ declare function convertSteersToFrontQueued(messages: readonly ComposerPendingMe
  * it never names stays pending, so the run's end requeues it.
  */
 declare function removeLandedSteers(messages: readonly ComposerPendingMessage[], event: TurnEvent): ComposerPendingMessage[];
+/** The messages without the one with this id. */
 declare function removeComposerPendingMessage(messages: readonly ComposerPendingMessage[], id: string): ComposerPendingMessage[];
+/** The messages with this id's draft replaced; throws when the new draft is empty. */
 declare function updateComposerPendingDraft(messages: readonly ComposerPendingMessage[], id: string, draft: UserTurnDraft, now?: number): ComposerPendingMessage[];
+/** The messages with this id moved one place up or down among those of its kind. */
 declare function moveComposerPendingWithinKind(messages: readonly ComposerPendingMessage[], id: string, direction: 'up' | 'down'): ComposerPendingMessage[];
 /** One steer per safe boundary: call once per `onStage` inject site. */
 declare function consumeNextComposerSteer(messages: readonly ComposerPendingMessage[]): {
@@ -44,5 +52,6 @@ declare function consumeNextComposerQueue(messages: readonly ComposerPendingMess
     message: ComposerPendingMessage | null;
     remaining: ComposerPendingMessage[];
 };
+/** The messages with this id changed to another kind. */
 declare function promoteComposerPendingKind(messages: readonly ComposerPendingMessage[], id: string, kind: ComposerPendingKind, now?: number): ComposerPendingMessage[];
 export { cloneUserTurnDraft, composerPendingPreview, consumeNextComposerQueue, consumeNextComposerSteer, convertSteersToFrontQueued, createComposerPendingMessage, moveComposerPendingWithinKind, orderComposerPendingMessages, promoteComposerPendingKind, removeComposerPendingMessage, removeLandedSteers, updateComposerPendingDraft, userDraftHasPayload, };

package/esm/src/interface/pending.js

@@ -1,4 +1,4 @@
-// `steer` injects at `onStage` boundaries of the same run; `queue` sends after the run fully ends
+// invariant: `steer` injects at `onStage` boundaries of the same run; `queue` sends after the run fully ends
 // (not on tool pause); `stash` never auto-sends. `send_now` is an action, not a pending kind.
 /** Display order: steers, then queues, then stashes. */
 export const COMPOSER_PENDING_KINDS = ['steer', 'queue', 'stash'];
@@ -7,6 +7,7 @@ function createPendingId() {
         ? crypto.randomUUID()
         : `pending-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
+/** True when the draft holds text, an attachment, or voice. */
 function userDraftHasPayload(draft) {
     return Boolean(draft.text?.trim() ||
         (draft.attachments && draft.attachments.length > 0) ||
@@ -25,7 +26,7 @@ function composerPendingPreview(message) {
 /** Throws on an empty draft. */
 function createComposerPendingMessage(args) {
     if (!userDraftHasPayload(args.draft)) {
-        throw new Error('Composer pending message requires a non-empty draft'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error('Composer pending message requires a non-empty draft'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const now = args.now ?? Date.now();
     return {
@@ -36,6 +37,7 @@ function createComposerPendingMessage(args) {
         updatedAt: now,
     };
 }
+/** A copy of the draft that shares nothing with the original. */
 function cloneUserTurnDraft(draft) {
     return {
         ...(draft.text !== undefined ? { text: draft.text } : {}),
@@ -74,12 +76,14 @@ function removeLandedSteers(messages, event) {
     const landed = new Set(event.injected.map((steer) => steer.id));
     return messages.filter((m) => !(m.kind === 'steer' && landed.has(m.id)));
 }
+/** The messages without the one with this id. */
 function removeComposerPendingMessage(messages, id) {
     return messages.filter((m) => m.id !== id);
 }
+/** The messages with this id's draft replaced; throws when the new draft is empty. */
 function updateComposerPendingDraft(messages, id, draft, now = Date.now()) {
     if (!userDraftHasPayload(draft)) {
-        throw new Error('Composer pending message requires a non-empty draft'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error('Composer pending message requires a non-empty draft'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return messages.map((m) => m.id === id
         ? {
@@ -89,6 +93,7 @@ function updateComposerPendingDraft(messages, id, draft, now = Date.now()) {
         }
         : m);
 }
+/** The messages with this id moved one place up or down among those of its kind. */
 function moveComposerPendingWithinKind(messages, id, direction) {
     const message = messages.find((m) => m.id === id);
     if (!message)
@@ -133,6 +138,7 @@ function consumeNextComposerQueue(messages) {
         remaining: messages.filter((m) => m.id !== message.id),
     };
 }
+/** The messages with this id changed to another kind. */
 function promoteComposerPendingKind(messages, id, kind, now = Date.now()) {
     const updated = messages.map((m) => m.id === id
         ? {