@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/interface/history.js

@@ -0,0 +1,269 @@
+// 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 { mediaKindForMime } from '../kernel/registry/catalog.js';
+import { formatToolFailureForModel, formatToolResult } from '../kernel/tools/model-text.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 } : {}),
+    });
+}
+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) },
+        ...(tool.thoughtSignature ? { thoughtSignature: tool.thoughtSignature } : {}),
+    };
+}
+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),
+    ];
+}
+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.thoughtSignature ? { thoughtSignature: call.thoughtSignature } : {}),
+    };
+}
+function appendToolDenialToHistory(history, tool, lexicon) {
+    const failure = tool.failure ?? {
+        code: 'denied',
+        message: lexiconText('session.tool_denied', { tool: tool.name }, lexicon),
+    };
+    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, 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
+ * 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,
+        { role: 'assistant', tool_calls: entries.map(({ tool }) => toolCallEntry(tool)) },
+        ...entries.flatMap(({ tool, content }) => content === undefined ? [] : [toolResultMessage(tool, content)]),
+    ];
+}
+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 = '';
+    // The calls of the step being read, in the order the model made them.
+    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.callIds.flatMap((id) => calls.get(id) ?? []);
+        next = appendToolStepToHistory(next, stepCalls, gated);
+        step = undefined;
+    };
+    for (const event of events) {
+        if (event.type === 'text') {
+            flushStep();
+            textBuf += event.text;
+            continue;
+        }
+        if (event.type === 'structured' && event.structured !== undefined) {
+            flushStep();
+            flushText();
+            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);
+        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.callIds.push(call.callId);
+    }
+    flushStep();
+    flushText();
+    return next;
+}
+/** 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);
+        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(', ')}]`);
+}
+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,10 @@
+import type { ProfileInputsSpec } from '../kernel/types.js';
+import type { AttachmentValidationResult, ProfileInputsInterface, UserTurnDraft } from './types.js';
+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,64 @@
+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',
+];
+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,
+    };
+}
+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,
+    };
+}
+/** 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,31 @@
+/**
+ * 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 { 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 { SettledToolCallEvent } from './tool-calls.js';
+export { 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,21 @@
+/**
+ * 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 { 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 { 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,19 @@
+import type { ModelId } from '../kernel/types.js';
+import type { ComposerProfileInterface } from './types.js';
+export type ModelSelectProfile = Pick<ComposerProfileInterface, 'id' | 'models' | 'defaultModel' | 'allowModelSelect'>;
+export type InterfaceModelOption = {
+    id: ModelId;
+    label: string;
+};
+export type InterfaceEffortOption = {
+    alias: string;
+    level: string;
+};
+declare function modelSelectEnabled(profile: ModelSelectProfile): boolean;
+declare function effortSelectEnabled(profile: ModelSelectProfile, modelId: ModelId | undefined): boolean;
+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;
+declare function interfaceModelOptions(profile: ModelSelectProfile): InterfaceModelOption[];
+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,45 @@
+function bindingFor(profile, modelId) {
+    if (!modelId)
+        return undefined;
+    return profile.models[modelId];
+}
+function modelSelectEnabled(profile) {
+    return Boolean(profile.allowModelSelect && Object.keys(profile.models).length >= 2);
+}
+function effortSelectEnabled(profile, modelId) {
+    const binding = bindingFor(profile, modelId);
+    if (!binding?.allowEffortSelect)
+        return false;
+    return Object.keys(binding.efforts ?? {}).length >= 2;
+}
+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];
+}
+function interfaceModelOptions(profile) {
+    if (!modelSelectEnabled(profile))
+        return [];
+    return Object.entries(profile.models).map(([id, binding]) => ({
+        id,
+        label: binding.apiId,
+    }));
+}
+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,48 @@
+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"];
+export type ComposerPendingKind = (typeof COMPOSER_PENDING_KINDS)[number];
+export interface ComposerPendingMessage {
+    id: string;
+    kind: ComposerPendingKind;
+    draft: UserTurnDraft;
+    createdAt: number;
+    updatedAt: number;
+}
+export type CreateComposerPendingMessageArgs = {
+    kind: ComposerPendingKind;
+    draft: UserTurnDraft;
+    id?: string;
+    now?: number;
+};
+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;
+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[];
+declare function removeComposerPendingMessage(messages: readonly ComposerPendingMessage[], id: string): ComposerPendingMessage[];
+declare function updateComposerPendingDraft(messages: readonly ComposerPendingMessage[], id: string, draft: UserTurnDraft, now?: number): ComposerPendingMessage[];
+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[];
+};
+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

@@ -0,0 +1,146 @@
+// `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'];
+function createPendingId() {
+    return typeof crypto !== 'undefined' && 'randomUUID' in crypto
+        ? crypto.randomUUID()
+        : `pending-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function userDraftHasPayload(draft) {
+    return Boolean(draft.text?.trim() ||
+        (draft.attachments && draft.attachments.length > 0) ||
+        (draft.voice && draft.voice.length > 0));
+}
+/** Short preview for pending bars (text, else attachment hint). */
+function composerPendingPreview(message) {
+    const text = message.draft.text?.trim();
+    if (text)
+        return text;
+    const files = (message.draft.attachments?.length ?? 0) + (message.draft.voice?.length ?? 0);
+    if (files > 0)
+        return files === 1 ? '(attachment)' : `(${files} attachments)`;
+    return '';
+}
+/** 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)
+    }
+    const now = args.now ?? Date.now();
+    return {
+        id: args.id ?? createPendingId(),
+        kind: args.kind,
+        draft: cloneUserTurnDraft(args.draft),
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+function cloneUserTurnDraft(draft) {
+    return {
+        ...(draft.text !== undefined ? { text: draft.text } : {}),
+        ...(draft.attachments ? { attachments: draft.attachments.map((a) => ({ ...a })) } : {}),
+        ...(draft.voice ? { voice: draft.voice.map((a) => ({ ...a })) } : {}),
+    };
+}
+/** Steer, then queue, then stash; FIFO within a kind. */
+function orderComposerPendingMessages(messages) {
+    return [
+        ...messages.filter((m) => m.kind === 'steer'),
+        ...messages.filter((m) => m.kind === 'queue'),
+        ...messages.filter((m) => m.kind === 'stash'),
+    ];
+}
+/** When a run ends, undelivered steers become queues ahead of the existing ones. */
+function convertSteersToFrontQueued(messages, now = Date.now()) {
+    const steers = messages
+        .filter((m) => m.kind === 'steer')
+        .map((m) => ({
+        ...m,
+        kind: 'queue',
+        updatedAt: now,
+    }));
+    const queues = messages.filter((m) => m.kind === 'queue');
+    const stashes = messages.filter((m) => m.kind === 'stash');
+    return [...steers, ...queues, ...stashes];
+}
+/**
+ * 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.
+ */
+function removeLandedSteers(messages, event) {
+    if (event.type !== 'stage' || !event.injected?.length)
+        return [...messages];
+    const landed = new Set(event.injected.map((steer) => steer.id));
+    return messages.filter((m) => !(m.kind === 'steer' && landed.has(m.id)));
+}
+function removeComposerPendingMessage(messages, id) {
+    return messages.filter((m) => m.id !== id);
+}
+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)
+    }
+    return messages.map((m) => m.id === id
+        ? {
+            ...m,
+            draft: cloneUserTurnDraft(draft),
+            updatedAt: now,
+        }
+        : m);
+}
+function moveComposerPendingWithinKind(messages, id, direction) {
+    const message = messages.find((m) => m.id === id);
+    if (!message)
+        return [...messages];
+    const sameKind = messages.filter((m) => m.kind === message.kind);
+    const currentIndex = sameKind.findIndex((m) => m.id === id);
+    if (currentIndex < 0)
+        return orderComposerPendingMessages(messages);
+    const nextIndex = direction === 'up' ? currentIndex - 1 : currentIndex + 1;
+    if (nextIndex < 0 || nextIndex >= sameKind.length) {
+        return orderComposerPendingMessages(messages);
+    }
+    const reordered = [...sameKind];
+    const [removed] = reordered.splice(currentIndex, 1);
+    if (!removed)
+        return orderComposerPendingMessages(messages);
+    reordered.splice(nextIndex, 0, removed);
+    const byKind = {
+        steer: message.kind === 'steer' ? reordered : messages.filter((m) => m.kind === 'steer'),
+        queue: message.kind === 'queue' ? reordered : messages.filter((m) => m.kind === 'queue'),
+        stash: message.kind === 'stash' ? reordered : messages.filter((m) => m.kind === 'stash'),
+    };
+    return [...byKind.steer, ...byKind.queue, ...byKind.stash];
+}
+/** One steer per safe boundary: call once per `onStage` inject site. */
+function consumeNextComposerSteer(messages) {
+    const message = messages.find((m) => m.kind === 'steer') ?? null;
+    if (!message)
+        return { message: null, remaining: [...messages] };
+    return {
+        message,
+        remaining: messages.filter((m) => m.id !== message.id),
+    };
+}
+/** Call only after the agent run has fully ended, not on a tool pause. */
+function consumeNextComposerQueue(messages) {
+    const message = messages.find((m) => m.kind === 'queue') ?? null;
+    if (!message)
+        return { message: null, remaining: [...messages] };
+    return {
+        message,
+        remaining: messages.filter((m) => m.id !== message.id),
+    };
+}
+function promoteComposerPendingKind(messages, id, kind, now = Date.now()) {
+    const updated = messages.map((m) => m.id === id
+        ? {
+            ...m,
+            kind,
+            updatedAt: now,
+        }
+        : m);
+    return orderComposerPendingMessages(updated);
+}
+export { cloneUserTurnDraft, composerPendingPreview, consumeNextComposerQueue, consumeNextComposerSteer, convertSteersToFrontQueued, createComposerPendingMessage, moveComposerPendingWithinKind, orderComposerPendingMessages, promoteComposerPendingKind, removeComposerPendingMessage, removeLandedSteers, updateComposerPendingDraft, userDraftHasPayload, };

package/esm/src/interface/profile-interface.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+import type { ProfileInterface } from './types.js';
+/** `ProfileInterface`, checked: unnamed fields are dropped, a malformed one fails. */
+export declare const profileInterfaceSchema: z.ZodType<ProfileInterface>;