@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/interface/history.js

@@ -0,0 +1,278 @@
+// 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 { 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
+ * come from a run and has no text the model read.
+ */
+function toolReadBack(call) {
+    const state = call.state;
+    if ((state?.phase !== 'complete' && state?.phase !== 'error') || state.readBack === undefined) {
+        throw new TheoremError('request', `Tool call '${call.name}' has no readBack: only a settled call from a run carries one.`);
+    }
+    return state.readBack;
+}
+function blobToPart(blob) {
+    const kind = mediaKindForMime(blob.mimeType) ?? 'document';
+    return { type: kind, mimeType: blob.mimeType, data: blob.data };
+}
+function draftBlobsWithData(blobs) {
+    const mapped = blobs
+        ?.filter((a) => typeof a.data === 'string' && a.data.length > 0)
+        .map((a) => ({ name: a.name, mimeType: a.mimeType, data: a.data }));
+    return mapped?.length ? mapped : undefined;
+}
+/** For `onStage` inject. Uses base64 on `draft.attachments` / `draft.voice` when present. */
+function userDraftToSteerInject(draft) {
+    const attachments = draftBlobsWithData(draft.attachments);
+    const voice = draftBlobsWithData(draft.voice);
+    return appendUserDraftToHistory([], { text: draft.text }, {
+        ...(attachments ? { attachments } : {}),
+        ...(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 = [];
+    for (const blob of media.attachments ?? []) {
+        parts.push(blobToPart(blob));
+    }
+    for (const blob of media.voice ?? []) {
+        parts.push(blobToPart(blob));
+    }
+    if (text) {
+        parts.push({ type: 'text', text });
+    }
+    if (parts.length === 0) {
+        return history;
+    }
+    if (parts.length === 1 && parts[0]?.type === 'text') {
+        return [...history, { role: 'user', content: text }];
+    }
+    return [...history, { role: 'user', parts }];
+}
+function toolCallEntry(tool) {
+    return {
+        id: tool.callId,
+        type: 'function',
+        function: { name: tool.name, arguments: JSON.stringify(tool.arguments) },
+    };
+}
+/** 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, 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));
+}
+function historyToolCall(call) {
+    return {
+        name: call.name,
+        callId: call.callId,
+        arguments: toolCallRanWith(call),
+        ...(call.reasoning ? { reasoning: call.reasoning } : {}),
+    };
+}
+/** The history with a denied tool call and the reason added. */
+function appendToolDenialToHistory(history, tool, labels) {
+    const failure = tool.failure ?? {
+        code: 'denied',
+        message: labelText('session.tool_denied', { tool: tool.name }, labels),
+    };
+    return appendToolCallPair(history, tool, formatToolResult(formatToolFailureForModel(failure)));
+}
+/** `undefined` while the call is open. */
+function settledToolContent(call) {
+    const phase = call.state?.phase;
+    return phase === 'complete' || phase === 'error' ? toolReadBack(call) : undefined;
+}
+/**
+ * One model step's settled calls: a single assistant message holding every call
+ * 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') {
+    const entries = calls.flatMap((call) => {
+        const content = settledToolContent(call);
+        if (content !== undefined)
+            return [{ tool: historyToolCall(call), content }];
+        return gated === 'open' && call.state?.phase === 'gate'
+            ? [{ tool: historyToolCall(call) }]
+            : [];
+    });
+    if (entries.length === 0)
+        return history;
+    return [
+        ...history,
+        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');
+}
+/**
+ * A reply paused on its gates, as the model reads it when the user walks away:
+ * its gated calls stay open in their step for the host to answer
+ * (`answerOpenToolCalls`) before the user's next message.
+ */
+function appendPausedTurnToHistory(history, events) {
+    return foldAssistantEvents(history, events, 'open');
+}
+function foldAssistantEvents(history, events, gated) {
+    let next = history;
+    let textBuf = '';
+    let step;
+    const calls = new Map();
+    const flushText = () => {
+        if (!textBuf) {
+            return;
+        }
+        next = [...next, { role: 'assistant', content: textBuf }];
+        textBuf = '';
+    };
+    const flushStep = () => {
+        if (!step) {
+            return;
+        }
+        const stepCalls = step.callKeys.flatMap((id) => calls.get(id) ?? []);
+        next = appendToolStepToHistory(next, stepCalls, gated);
+        step = undefined;
+    };
+    for (const event of keptReply(events)) {
+        if (event.type === 'text') {
+            flushStep();
+            textBuf += event.text;
+            continue;
+        }
+        if (event.type === 'structured' && event.structured !== undefined) {
+            flushStep();
+            // 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 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;
+        }
+        if (!step || call.stepId === undefined || step.stepId !== call.stepId) {
+            flushStep();
+            flushText();
+            step = { stepId: call.stepId, callKeys: [] };
+        }
+        step.callKeys.push(key);
+    }
+    flushStep();
+    flushText();
+    return next;
+}
+/** Attachment and voice blocks are omitted: their preview `data` is UI-only. */
+function historyFromTranscriptBlocks(blocks) {
+    let history = [];
+    let step = [];
+    const flushStep = () => {
+        history = appendToolStepToHistory(history, step);
+        step = [];
+    };
+    for (const block of blocks) {
+        if (block.kind === 'tool') {
+            const open = step[0];
+            if (open && (open.stepId === undefined || open.stepId !== block.tool.stepId))
+                flushStep();
+            step.push(block.tool);
+            continue;
+        }
+        flushStep();
+        if (block.kind === 'user-text') {
+            history = appendUserDraftToHistory(history, { text: block.text });
+            continue;
+        }
+        if (block.kind === 'text') {
+            history = [...history, { role: 'assistant', content: block.text }];
+            continue;
+        }
+        if (block.kind === 'structured') {
+            history = [...history, { role: 'assistant', content: JSON.stringify(block.value) }];
+        }
+    }
+    flushStep();
+    return history;
+}
+function lastToolStep(history) {
+    const at = history.findLastIndex((message) => message.tool_calls !== undefined);
+    const calls = history[at]?.tool_calls;
+    return calls ? { at, calls } : undefined;
+}
+/**
+ * The calls the history leaves open: those of its last step with no result
+ * after it, when nothing but results follows that step. Empty otherwise.
+ */
+function openToolCallIds(history) {
+    const step = lastToolStep(history);
+    if (!step)
+        return [];
+    const after = history.slice(step.at + 1);
+    if (after.some((message) => message.role !== 'tool'))
+        return [];
+    const answered = new Set(after.map((message) => message.tool_call_id));
+    return step.calls.flatMap((call) => (answered.has(call.id) ? [] : [call.id]));
+}
+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))) {
+        throw openCallsMismatch(history, ids);
+    }
+}
+/**
+ * `answers` holds, by call id, the text the model reads for each open call. Results follow their
+ * step in the order the model made the calls. Throws unless `answers` names exactly the open calls.
+ */
+function answerOpenToolCalls(history, answers) {
+    const ids = [...answers.keys()];
+    assertOpenToolCalls(history, ids);
+    const step = lastToolStep(history);
+    if (!step)
+        return [...history];
+    const results = new Map(history.slice(step.at + 1).map((message) => [message.tool_call_id, message]));
+    const resultOf = (call) => {
+        const result = results.get(call.id);
+        if (result)
+            return result;
+        const content = answers.get(call.id);
+        if (content === undefined)
+            throw openCallsMismatch(history, ids);
+        return { role: 'tool', tool_call_id: call.id, name: call.function.name, content };
+    };
+    return [...history.slice(0, step.at + 1), ...step.calls.map(resultOf)];
+}
+export { answerOpenToolCalls, appendAssistantEventsToHistory, appendPausedTurnToHistory, appendToolDenialToHistory, appendToolExchangeToHistory, appendUserDraftToHistory, assertOpenToolCalls, historyFromTranscriptBlocks, toolReadBack, userDraftToSteerInject, };

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

@@ -0,0 +1,11 @@
+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;
+/** Validate staged files against resolved profile `inputs`: the kernel's one attachment check. */
+declare function validateProfileInputs(inputs: ProfileInputsInterface, draft: Pick<UserTurnDraft, 'attachments' | 'voice'>): AttachmentValidationResult;
+/** The first accepted format this browser can record; undefined when it can record none. */
+declare function pickMediaRecorderMime(accept?: string[]): string | undefined;
+export { attachmentAcceptAttr, inputsFromSpec, pickMediaRecorderMime, validateProfileInputs };

package/esm/src/interface/inputs.js

@@ -0,0 +1,67 @@
+import { attachmentIssues, resolveMediaLimits } from '../kernel/registry/attachments.js';
+import { mimeAllowed } from '../kernel/registry/catalog.js';
+const RECORDER_CANDIDATES = [
+    'audio/webm;codecs=opus',
+    'audio/webm',
+    'audio/mp4',
+    'audio/wav',
+    'audio/mpeg',
+];
+/** The accepted MIME types as the value of an HTML `accept` attribute, comma-joined. */
+function attachmentAcceptAttr(accept) {
+    return accept.join(',');
+}
+/** `inputs` is null for profile types that declare none (the kernel's `profileInputs`). */
+function inputsFromSpec(inputs) {
+    const accept = inputs?.attachments?.accept;
+    const voiceAccept = inputs?.voice?.accept;
+    return {
+        text: inputs?.text !== false,
+        attachments: accept?.length ? { accept, acceptAttr: attachmentAcceptAttr(accept) } : null,
+        voice: voiceAccept?.length ? { accept: voiceAccept } : null,
+        maxFiles: inputs?.maxFiles,
+        maxBytes: inputs?.maxBytes,
+        maxTurnBytes: inputs?.maxTurnBytes,
+        limitsByMime: inputs?.limitsByMime,
+        slots: inputs?.slots,
+        context: inputs?.context,
+    };
+}
+function toProfileInputsSpec(inputs) {
+    return {
+        text: inputs.text,
+        attachments: inputs.attachments ? { accept: inputs.attachments.accept } : undefined,
+        voice: inputs.voice ? { accept: inputs.voice.accept } : undefined,
+        maxFiles: inputs.maxFiles,
+        maxBytes: inputs.maxBytes,
+        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. */
+function validateProfileInputs(inputs, draft) {
+    const facts = (files) => (files ?? []).map(({ name, mimeType, sizeBytes }) => ({ name, mimeType, sizeBytes }));
+    const issues = attachmentIssues({
+        attachments: inputs.attachments?.accept,
+        voice: inputs.voice?.accept,
+        limits: resolveMediaLimits(toProfileInputsSpec(inputs)),
+    }, facts(draft.attachments), facts(draft.voice));
+    return { ok: issues.length === 0, issues };
+}
+/** The first accepted format this browser can record; undefined when it can record none. */
+function pickMediaRecorderMime(accept) {
+    const recorder = globalThis
+        .MediaRecorder;
+    if (recorder === undefined)
+        return undefined;
+    const supported = (mime) => recorder.isTypeSupported(mime);
+    const fromCandidates = (pool) => pool.find(supported);
+    if (accept?.length) {
+        return (fromCandidates(RECORDER_CANDIDATES.filter((mime) => mimeAllowed(accept, mime))) ??
+            accept.find(supported));
+    }
+    return fromCandidates(RECORDER_CANDIDATES);
+}
+export { attachmentAcceptAttr, inputsFromSpec, pickMediaRecorderMime, validateProfileInputs };

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

@@ -0,0 +1,33 @@
+/**
+ * Headless profile-driven interface — spec, inputs, transcript folding,
+ * composer pending intents (stash / queue / steer).
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { AttachmentValidationCode, AttachmentValidationIssue, AttachmentValidationParams, } from '../kernel/types.js';
+export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds, } from './blocks.js';
+export type { ComposerActionContext, ComposerMenuAction, ComposerPrimaryAction, ComposerRunPhase, } from './composer-actions.js';
+export { resolveComposerMenuActions, resolveComposerPrimary } from './composer-actions.js';
+export type { PrepareUserTurnResult } from './draft.js';
+export { prepareUserTurn, sanitizeUserDraft } from './draft.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';
+export type { InterfaceEffortOption, InterfaceModelOption } from './models.js';
+export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, modelSelectEnabled, } from './models.js';
+export type { ComposerPendingKind, ComposerPendingMessage, CreateComposerPendingMessageArgs, } from './pending.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 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 { 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';
+export type { AttachmentValidationResult, ComposerInterfaceFields, ComposerProfileInterface, FoldTurnEventsOptions, ImageProfileInterface, LiveProfileInterface, ModelBindingView, PendingAttachment, ProfileGuardrailsView, ProfileInputsInterface, ProfileInterface, ProfileObservabilityView, ProfileOutputsView, ProfileToolsView, SpeechProfileInterface, TextProfileInterface, TranscriptBlock, TranscriptBlockKind, UserTurnDraft, } from './types.js';
+export { streamThoughtsEnabled } from './types.js';

package/esm/src/interface/mod.js

@@ -0,0 +1,22 @@
+/**
+ * Headless profile-driven interface — spec, inputs, transcript folding,
+ * composer pending intents (stash / queue / steer).
+ *
+ * @module
+ */
+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 { 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 { 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

@@ -0,0 +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

@@ -0,0 +1,50 @@
+function bindingFor(profile, modelId) {
+    if (!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);
+}
+/** `defaultEffort` when it names an alias, else the first alias. */
+function defaultInterfaceEffort(profile, modelId) {
+    const binding = bindingFor(profile, modelId);
+    if (!binding?.efforts)
+        return undefined;
+    const defaultAlias = binding.defaultEffort?.trim();
+    if (defaultAlias && binding.efforts[defaultAlias])
+        return defaultAlias;
+    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 [];
+    return Object.entries(profile.models).map(([id, binding]) => ({
+        id,
+        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 [];
+    const binding = bindingFor(profile, modelId);
+    if (!binding?.efforts)
+        return [];
+    return Object.entries(binding.efforts).map(([alias, level]) => ({ alias, level }));
+}
+export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, modelSelectEnabled, };

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

@@ -0,0 +1,57 @@
+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;
+    draft: UserTurnDraft;
+    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[];
+/** When a run ends, undelivered steers become queues ahead of the existing ones. */
+declare function convertSteersToFrontQueued(messages: readonly ComposerPendingMessage[], now?: number): ComposerPendingMessage[];
+/**
+ * Drops the steers a turn event reports as landed in the conversation. A steer
+ * 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[]): {
+    message: ComposerPendingMessage | null;
+    remaining: ComposerPendingMessage[];
+};
+/** Call only after the agent run has fully ended, not on a tool pause. */
+declare function consumeNextComposerQueue(messages: readonly ComposerPendingMessage[]): {
+    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, };