@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,13 @@
+/**
+ * Optional host-application helpers, not part of the turn kernel: HTTP reply status, cutout-trace
+ * flush, and live structured-output preview.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { ClientTurnOptions } from './client-turn.js';
+export { forClient, forClientEvents } from './client-turn.js';
+export type { CutoutTape } from './mint-trace.js';
+export { flushMintTrace } from './mint-trace.js';
+export { readStreamingJsonStringField } from './readStreamingJsonStringField.js';
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json, } from './reply.js';

package/esm/src/host/mod.js

@@ -0,0 +1,11 @@
+/**
+ * Optional host-application helpers, not part of the turn kernel: HTTP reply status, cutout-trace
+ * flush, and live structured-output preview.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { forClient, forClientEvents } from './client-turn.js';
+export { flushMintTrace } from './mint-trace.js';
+export { readStreamingJsonStringField } from './readStreamingJsonStringField.js';
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json, } from './reply.js';

package/esm/src/host/readStreamingJsonStringField.d.ts

@@ -0,0 +1,2 @@
+/** The buffer may lack a closing quote; any decoded prefix is returned for live preview. */
+export declare function readStreamingJsonStringField(jsonText: string, key: string): string | null;

package/esm/src/host/readStreamingJsonStringField.js

@@ -0,0 +1,68 @@
+const JSON_ESCAPES = {
+    n: '\n',
+    t: '\t',
+    r: '\r',
+    '"': '"',
+    '\\': '\\',
+    '/': '/',
+};
+function decodeEscapedChar(ch, jsonText, index) {
+    if (ch === 'u' && index + 4 < jsonText.length) {
+        const hex = jsonText.slice(index + 1, index + 5);
+        if (/^[0-9a-fA-F]{4}$/.test(hex)) {
+            return { text: String.fromCharCode(Number.parseInt(hex, 16)), next: index + 4 };
+        }
+    }
+    const mapped = JSON_ESCAPES[ch];
+    return { text: mapped ?? ch, next: index };
+}
+/** The buffer may lack a closing quote; any decoded prefix is returned for live preview. */
+export function readStreamingJsonStringField(jsonText, key) {
+    const keyLiteral = JSON.stringify(key);
+    let keyAt = jsonText.indexOf(keyLiteral);
+    let i = -1;
+    while (keyAt >= 0) {
+        i = keyAt + keyLiteral.length;
+        while (/\s/.test(jsonText[i] ?? '')) {
+            i += 1;
+        }
+        if (jsonText[i] === ':') {
+            i += 1;
+            while (/\s/.test(jsonText[i] ?? '')) {
+                i += 1;
+            }
+            if (jsonText[i] === '"') {
+                break;
+            }
+        }
+        keyAt = jsonText.indexOf(keyLiteral, keyAt + keyLiteral.length);
+    }
+    if (keyAt < 0 || jsonText[i] !== '"') {
+        return null;
+    }
+    i += 1;
+    let result = '';
+    let escaped = false;
+    while (i < jsonText.length) {
+        const ch = jsonText[i];
+        if (escaped) {
+            const decoded = decodeEscapedChar(ch, jsonText, i);
+            result += decoded.text;
+            i = decoded.next;
+            escaped = false;
+            i += 1;
+            continue;
+        }
+        if (ch === '\\') {
+            escaped = true;
+        }
+        else if (ch === '"') {
+            return result;
+        }
+        else {
+            result += ch;
+        }
+        i += 1;
+    }
+    return result;
+}

package/esm/src/host/reply.d.ts

@@ -0,0 +1,7 @@
+declare const HTTP_OK = 200;
+declare const HTTP_NOT_FOUND = 404;
+declare const HTTP_METHOD = 405;
+declare const HTTP_BUSY = 429;
+declare function json(status: number, body: unknown, cors: Record<string, string>): Response;
+declare function caughtStatus(err: unknown): number;
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json };

package/esm/src/host/reply.js

@@ -0,0 +1,35 @@
+import { errorKind } from '../guardrails/error.js';
+const HTTP_OK = 200;
+const HTTP_NOT_FOUND = 404;
+const HTTP_METHOD = 405;
+const HTTP_BUSY = 429;
+const STATUS_BY_KIND = {
+    config: 500,
+    request: 400,
+    input: 422,
+    action: 403,
+    auth: 401,
+    rate_limit: HTTP_BUSY,
+    unsupported: 422,
+    unavailable: 503,
+    bad_response: 502,
+    network: 502,
+    timeout: 504,
+    safety: 422,
+    blocked: 403,
+    declined: 409,
+    failed: 502,
+    // Client closed request (nginx convention): the caller went away.
+    cancelled: 499,
+    internal: 500,
+};
+function json(status, body, cors) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { ...cors, 'Content-Type': 'application/json' },
+    });
+}
+function caughtStatus(err) {
+    return STATUS_BY_KIND[errorKind(err)];
+}
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json };

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

@@ -0,0 +1,8 @@
+import type { TurnEvent } from '../kernel/types.js';
+import type { FoldTurnEventsOptions, TranscriptBlock, UserTurnDraft } from './types.js';
+declare function resetBlockIds(): void;
+declare function buildUserTurnBlocks(draft: UserTurnDraft, idPrefix?: string): TranscriptBlock[];
+/** Resets only the turn id sequence, so streaming refolds keep stable `turn-*` keys. */
+declare function foldTurnEvents(events: readonly TurnEvent[], options?: FoldTurnEventsOptions): TranscriptBlock[];
+declare function foldConversationTurn(draft: UserTurnDraft, assistantEvents: readonly TurnEvent[], options?: FoldTurnEventsOptions): TranscriptBlock[];
+export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds };

package/esm/src/interface/blocks.js

@@ -0,0 +1,213 @@
+import { applyToolEvent } from './tool-calls.js';
+import { collectPromotedMediaFromToolOutput } from './tool-media.js';
+let turnBlockCounter = 0;
+/**
+ * User block ids are random: a counter restarts wherever this module loads
+ * again (a hot reload, a second bundled copy) and would reuse an id already on
+ * screen. Turn block ids count from each fold so streaming refolds keep keys.
+ */
+function nextBlockId(prefix) {
+    if (prefix === 'user')
+        return `user-${globalThis.crypto.randomUUID()}`;
+    turnBlockCounter += 1;
+    return `${prefix}-${String(turnBlockCounter)}`;
+}
+function resetBlockIds() {
+    turnBlockCounter = 0;
+}
+function isAppendableTextBlock(block, kind) {
+    return block?.kind === kind;
+}
+function appendText(blocks, kind, text, idPrefix) {
+    const last = blocks.at(-1);
+    if (isAppendableTextBlock(last, kind)) {
+        last.text += text;
+        return;
+    }
+    blocks.push({
+        id: nextBlockId(idPrefix),
+        kind,
+        text,
+    });
+}
+/** One block per call, keyed by `callId`; each event folds into it (`applyToolEvent`). */
+function upsertToolBlock(blocks, tool) {
+    const id = `tool-${tool.callId}`;
+    const existing = blocks.find((block) => block.kind === 'tool' && block.id === id);
+    const call = applyToolEvent(existing?.tool, tool);
+    if (existing) {
+        existing.tool = call;
+        return;
+    }
+    blocks.push({ id, kind: 'tool', tool: call });
+}
+/** Same source: one place, or one link. */
+function sameSource(a, b) {
+    if (a.type !== b.type)
+        return false;
+    if (a.placeId && b.placeId)
+        return a.placeId === b.placeId;
+    return a.uri === b.uri;
+}
+/**
+ * One sources row per citer: the provider's grounding (no `callId`) or one
+ * tool call. A stream cites the same places more than once (the search result
+ * lists them, then the answer's annotations cite them), so later citations
+ * fold into the row with each source listed once.
+ */
+function foldCitation(blocks, event, idPrefix) {
+    const existing = blocks.find((block) => block.kind === 'citation' && block.callId === event.callId);
+    const sources = existing ? [...existing.sources] : [];
+    for (const source of event.sources) {
+        if (!sources.some((seen) => sameSource(seen, source)))
+            sources.push(source);
+    }
+    if (existing) {
+        existing.sources = sources;
+        return;
+    }
+    blocks.push({
+        id: nextBlockId(idPrefix),
+        kind: 'citation',
+        sources,
+        ...(event.callId !== undefined ? { callId: event.callId } : {}),
+    });
+}
+function appendPromotedToolMedia(blocks, tool, idPrefix, seenUrls) {
+    if (tool.phase !== 'complete' || tool.output === undefined)
+        return;
+    for (const media of collectPromotedMediaFromToolOutput(tool.output)) {
+        if (seenUrls.has(media.url))
+            continue;
+        seenUrls.add(media.url);
+        blocks.push({
+            id: nextBlockId(idPrefix),
+            kind: 'media',
+            mimeType: media.mimeType,
+            url: media.url,
+            ...(media.previewUrl ? { previewUrl: media.previewUrl } : {}),
+        });
+    }
+}
+function buildUserTurnBlocks(draft, idPrefix = 'user') {
+    const blocks = [];
+    const text = draft.text?.trim();
+    if (text) {
+        blocks.push({
+            id: nextBlockId(idPrefix),
+            kind: 'user-text',
+            text,
+        });
+    }
+    for (const file of draft.attachments ?? []) {
+        blocks.push({
+            id: nextBlockId(idPrefix),
+            kind: 'user-attachment',
+            name: file.name,
+            mimeType: file.mimeType,
+            sizeBytes: file.sizeBytes,
+            ...(file.data !== undefined ? { data: file.data } : {}),
+        });
+    }
+    for (const file of draft.voice ?? []) {
+        blocks.push({
+            id: nextBlockId(idPrefix),
+            kind: 'user-voice',
+            name: file.name,
+            mimeType: file.mimeType,
+            sizeBytes: file.sizeBytes,
+            ...(file.data !== undefined ? { data: file.data } : {}),
+        });
+    }
+    return blocks;
+}
+/** Resets only the turn id sequence, so streaming refolds keep stable `turn-*` keys. */
+function foldTurnEvents(events, options = {}) {
+    const idPrefix = options.idPrefix ?? 'turn';
+    const showThoughts = options.showThoughts ?? true;
+    turnBlockCounter = 0;
+    const blocks = [];
+    const promotedMediaUrls = new Set();
+    for (const event of events) {
+        switch (event.type) {
+            case 'thought':
+                if (showThoughts && event.text) {
+                    appendText(blocks, 'thought', event.text, idPrefix);
+                }
+                break;
+            case 'text':
+                if (event.text) {
+                    appendText(blocks, 'text', event.text, idPrefix);
+                }
+                break;
+            case 'tool':
+                upsertToolBlock(blocks, event.tool);
+                appendPromotedToolMedia(blocks, event.tool, idPrefix, promotedMediaUrls);
+                break;
+            case 'structured':
+                blocks.push({
+                    id: nextBlockId(idPrefix),
+                    kind: 'structured',
+                    value: event.structured,
+                });
+                break;
+            case 'media':
+                if (event.media) {
+                    blocks.push({
+                        id: nextBlockId(idPrefix),
+                        kind: 'media',
+                        mimeType: event.media.mimeType,
+                        data: event.media.data,
+                    });
+                }
+                break;
+            case 'grounding':
+                blocks.push({
+                    id: nextBlockId(idPrefix),
+                    kind: 'grounding',
+                    grounding: event.grounding,
+                });
+                break;
+            case 'citation':
+                foldCitation(blocks, event, idPrefix);
+                break;
+            case 'evidence':
+                blocks.push({
+                    id: nextBlockId(idPrefix),
+                    kind: 'evidence',
+                    evidence: event.evidence,
+                });
+                break;
+            case 'error':
+                if (event.error) {
+                    blocks.push({
+                        id: nextBlockId(idPrefix),
+                        kind: 'error',
+                        message: event.error,
+                    });
+                }
+                break;
+            case 'done':
+                blocks.push({
+                    id: nextBlockId(idPrefix),
+                    kind: 'turn-done',
+                    stop: event.stop,
+                    tokens: event.tokens,
+                    interactionId: event.interactionId,
+                    compaction: event.compaction !== undefined,
+                });
+                break;
+            case 'tokens':
+            case 'session':
+            case 'stage':
+                break;
+            default:
+                break;
+        }
+    }
+    return blocks;
+}
+function foldConversationTurn(draft, assistantEvents, options = {}) {
+    return [...buildUserTurnBlocks(draft, 'user'), ...foldTurnEvents(assistantEvents, options)];
+}
+export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds };

package/esm/src/interface/composer-actions.d.ts

@@ -0,0 +1,20 @@
+import type { ComposerPendingKind } from './pending.js';
+export type ComposerRunPhase = 'idle' | 'streaming' | 'gated';
+/** Primary button / Enter target. */
+export type ComposerPrimaryAction = 'send' | 'stop' | 'queue' | 'none';
+/**
+ * Split-menu / long-press actions. `send_now` is abort+send while streaming, or
+ * abandon the tool gate (no model continue) + send while gated; not a pending kind.
+ */
+export type ComposerMenuAction = ComposerPendingKind | 'send_now';
+export type ComposerActionContext = {
+    phase: ComposerRunPhase;
+    hasPayload: boolean;
+    /** From `ProfileInterface.allowSteering` (text only; false elsewhere). */
+    allowSteering: boolean;
+    /** Composer profiles always project `canStop: true`. */
+    canStop?: boolean;
+};
+declare function resolveComposerPrimary(ctx: ComposerActionContext): ComposerPrimaryAction;
+declare function resolveComposerMenuActions(ctx: ComposerActionContext): ComposerMenuAction[];
+export { resolveComposerMenuActions, resolveComposerPrimary };

package/esm/src/interface/composer-actions.js

@@ -0,0 +1,31 @@
+function resolveComposerPrimary(ctx) {
+    const canStop = ctx.canStop !== false;
+    if (ctx.phase === 'idle') {
+        return ctx.hasPayload ? 'send' : 'none';
+    }
+    if (ctx.phase === 'streaming') {
+        if (!ctx.hasPayload)
+            return canStop ? 'stop' : 'none';
+        return 'queue';
+    }
+    // Gated is still the same run: queue only, no stream to stop.
+    return ctx.hasPayload ? 'queue' : 'none';
+}
+function resolveComposerMenuActions(ctx) {
+    if (!ctx.hasPayload)
+        return [];
+    if (ctx.phase === 'idle') {
+        return ['stash'];
+    }
+    if (ctx.phase === 'streaming') {
+        const actions = ['queue'];
+        if (ctx.allowSteering)
+            actions.push('steer');
+        actions.push('send_now', 'stash');
+        return actions;
+    }
+    // gated: no steer (not an inject stage); send_now = host ends wait + send
+    return ['queue', 'send_now', 'stash'];
+}
+// Emits semantic action keys only: English labels live in the rendering layer or the host UI.
+export { resolveComposerMenuActions, resolveComposerPrimary };

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

@@ -0,0 +1,14 @@
+import type { AttachmentValidationIssue } from '../kernel/types.js';
+import type { ProfileGuardrailsView, ProfileInputsInterface, TranscriptBlock, UserTurnDraft } from './types.js';
+declare function sanitizeUserDraft(draft: UserTurnDraft, guardrails?: ProfileGuardrailsView): UserTurnDraft;
+export type PrepareUserTurnResult = {
+    ok: true;
+    draft: UserTurnDraft;
+    blocks: TranscriptBlock[];
+} | {
+    ok: false;
+    issues: AttachmentValidationIssue[];
+};
+/** Call before appending to the thread and before `runTurn` ingress. */
+declare function prepareUserTurn(inputs: ProfileInputsInterface, draft: UserTurnDraft, guardrails?: ProfileGuardrailsView): PrepareUserTurnResult;
+export { prepareUserTurn, sanitizeUserDraft };

package/esm/src/interface/draft.js

@@ -0,0 +1,28 @@
+import { resolveGuardrailPolicy } from '../guardrails/policy.js';
+import { sanitizeText } from '../guardrails/sanitize.js';
+import { anySensitive } from '../guardrails/sensitive.js';
+import { buildUserTurnBlocks } from './blocks.js';
+import { validateProfileInputs } from './inputs.js';
+function sanitizeUserDraft(draft, guardrails) {
+    const options = guardrails ?? resolveGuardrailPolicy(undefined);
+    if (!options.sanitizeInput && !anySensitive(options.redactSensitive)) {
+        return draft;
+    }
+    if (draft.text === undefined) {
+        return draft;
+    }
+    return {
+        ...draft,
+        text: sanitizeText(draft.text, options),
+    };
+}
+/** Call before appending to the thread and before `runTurn` ingress. */
+function prepareUserTurn(inputs, draft, guardrails) {
+    const validation = validateProfileInputs(inputs, draft);
+    if (!validation.ok) {
+        return { ok: false, issues: validation.issues };
+    }
+    const safe = sanitizeUserDraft(draft, guardrails);
+    return { ok: true, draft: safe, blocks: buildUserTurnBlocks(safe) };
+}
+export { prepareUserTurn, sanitizeUserDraft };

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

@@ -0,0 +1,12 @@
+import type { ToolRegistry } from '../kernel/tools/registry.js';
+import type { LiveProfile, Profile, ProjectedProfile } from '../kernel/types.js';
+import type { ComposerProfileInterface, LiveProfileInterface, ProfileInterface } from './types.js';
+/**
+ * The interface for `input`, its tools resolved from `tools`: the registry of
+ * the scope that runs the profile.
+ */
+declare function interfaceFromProfile(input: LiveProfile, tools: ToolRegistry): LiveProfileInterface;
+declare function interfaceFromProfile(input: Exclude<Profile, LiveProfile>, tools: ToolRegistry): ComposerProfileInterface;
+declare function interfaceFromProfile(input: Profile, tools: ToolRegistry): ProfileInterface;
+declare function interfaceFromProjected(projected: ProjectedProfile): ProfileInterface;
+export { interfaceFromProfile, interfaceFromProjected };

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

@@ -0,0 +1,144 @@
+// `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';
+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 { 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);
+    return {
+        quota: policy.quota,
+        canary: policy.canary,
+        sanitizeInput: policy.sanitizeInput,
+        redactSensitive: policy.redactSensitive,
+        hasEgress: Boolean(policy.egress),
+        egressChecks: egressChecksView(egressChecksOf(policy.egress?.enforce)),
+    };
+}
+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 writeToView(writeTo) {
+    if (writeTo === undefined || writeTo === false) {
+        return writeTo;
+    }
+    if (typeof writeTo === 'string') {
+        return writeTo;
+    }
+    return 'custom';
+}
+/** `writeTo` becomes `'custom'` when it is an inline TraceSink. */
+function observabilityView(observability) {
+    if (!observability) {
+        return undefined;
+    }
+    const policy = resolveObservabilityPolicy(observability);
+    return {
+        record: policy.record,
+        writeTo: writeToView(policy.writeTo),
+        sampleRate: policy.sampleRate,
+        include: policy.include,
+        scrub: policy.scrub,
+        resource: policy.resource,
+        retainForDays: policy.retainForDays,
+        rotateAfterMiB: policy.rotateAfterMiB,
+        hasOnWriteError: Boolean(policy.onWriteError),
+    };
+}
+function toolsView(projected, profile) {
+    if (profile) {
+        const t2Loader = profileToolsSpec(profile)?.t2Loader;
+        return { allow: [...profileToolAllow(profile)], ...(t2Loader ? { t2Loader } : {}) };
+    }
+    const allow = projected.tools
+        .filter((tool) => !('type' in tool && tool.type === 'builtin'))
+        .map((tool) => tool.name);
+    return { allow };
+}
+function enrich(projected, profile) {
+    const inputs = inputsFromSpec(projected.inputs);
+    const identity = profile?.identity ?? { handle: projected.handle };
+    const guardrails = profile ? guardrailsView(profile.guardrails) : undefined;
+    const observability = profile ? observabilityView(profile.observability) : undefined;
+    const outputs = projected.outputs ?? undefined;
+    const shared = {
+        id: projected.id,
+        identity,
+        models: projected.models,
+        defaultModel: projected.defaultModel,
+        allowModelSelect: projected.allowModelSelect,
+        maxSteps: projected.maxSteps,
+        key: projected.key,
+        outputs,
+        guardrails,
+        observability,
+        lexicon: clientLexicon(profile?.lexicon),
+    };
+    switch (projected.type) {
+        case 'text':
+            return profileInterfaceSchema.parse({
+                ...shared,
+                type: 'text',
+                inputs,
+                tools: toolsView(projected, profile),
+                turnBehaviour: profile?.type === 'text' ? profile.turnBehaviour : undefined,
+                canStop: true,
+                allowSteering: profile ? profileAllowsSteering(profile) : true,
+            });
+        case 'image':
+            return profileInterfaceSchema.parse({
+                ...shared,
+                type: 'image',
+                image: projected.image ?? {},
+                inputs,
+                tools: toolsView(projected, profile),
+                turnBehaviour: profile?.type === 'image' ? profile.turnBehaviour : undefined,
+                canStop: true,
+            });
+        case 'speech':
+            return profileInterfaceSchema.parse({
+                ...shared,
+                type: 'speech',
+                speech: projected.speech ?? {},
+                inputs,
+                turnBehaviour: profile?.type === 'speech' ? profile.turnBehaviour : undefined,
+                canStop: true,
+            });
+        case 'live':
+            return profileInterfaceSchema.parse({
+                ...shared,
+                type: 'live',
+                live: projected.live ?? {},
+                tools: { allow: toolsView(projected, profile).allow },
+            });
+        default: {
+            const exhaustive = projected.type;
+            return exhaustive;
+        }
+    }
+}
+function interfaceFromProfile(input, tools) {
+    // Host profiles never run a model and have no composer surface.
+    const profile = requireModelProfile(input, 'interfaceFromProfile');
+    return enrich(projectProfileObject(tools, profile), profile);
+}
+function interfaceFromProjected(projected) {
+    return enrich(projected);
+}
+export { interfaceFromProfile, interfaceFromProjected };

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

@@ -0,0 +1,40 @@
+import { type LexiconOverrides } from '../guardrails/lexicon.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';
+/**
+ * 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.
+ */
+declare function toolReadBack(call: ToolCall): string;
+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[];
+declare function appendUserDraftToHistory(history: TurnHistoryMessage[], draft: UserTurnDraft, media?: UserTurnHistoryMedia): TurnHistoryMessage[];
+declare function appendToolExchangeToHistory(history: TurnHistoryMessage[], call: ToolCall): TurnHistoryMessage[];
+declare function appendToolDenialToHistory(history: TurnHistoryMessage[], tool: ToolCallRequest & {
+    /** Override the default deny copy. */
+    failure?: {
+        code: string;
+        message: string;
+    };
+}, lexicon: LexiconOverrides | undefined): TurnHistoryMessage[];
+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:
+ * its gated calls stay open in their step for the host to answer
+ * (`answerOpenToolCalls`) before the user's next message.
+ */
+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[];
+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
+ * step in the order the model made the calls. Throws unless `answers` names exactly the open calls.
+ */
+declare function answerOpenToolCalls(history: readonly TurnHistoryMessage[], answers: ReadonlyMap<string, string>): TurnHistoryMessage[];
+export { answerOpenToolCalls, appendAssistantEventsToHistory, appendPausedTurnToHistory, appendToolDenialToHistory, appendToolExchangeToHistory, appendUserDraftToHistory, assertOpenToolCalls, historyFromTranscriptBlocks, toolReadBack, userDraftToSteerInject, };