@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/interface/blocks.js

@@ -0,0 +1,283 @@
+import { keptReply } from '../kernel/turn-events.js';
+import { partialJsonObject } from '../kernel/util/partial-json.js';
+import { applyToolDraft, 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)}`;
+}
+/** Restarts block id numbering at zero. */
+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,
+    });
+}
+/**
+ * A decision made while text streams goes ahead of that text's block, so the block stays last and
+ * the rest of the text joins it.
+ */
+function addGuardrailBlock(blocks, block) {
+    const last = blocks.at(-1);
+    const streaming = last?.kind === 'text' || last?.kind === 'thought';
+    blocks.splice(streaming ? blocks.length - 1 : blocks.length, 0, block);
+}
+function findToolBlock(blocks, id) {
+    return blocks.find((block) => block.kind === 'tool' && block.id === id);
+}
+/** invariant: Issued operation IDs separate action blocks; historical events use callId. */
+function upsertToolBlock(blocks, tool) {
+    const id = `tool-${tool.operationId ?? tool.callId}`;
+    const existing = findToolBlock(blocks, id);
+    const call = applyToolEvent(existing?.tool, tool);
+    if (existing) {
+        existing.tool = call;
+        return;
+    }
+    // why: The call the model was drafting arrives whole where its draft stood.
+    const draft = tool.phase === undefined ? findToolBlock(blocks, `tool-${tool.callId}`) : undefined;
+    if (draft?.tool.draft !== undefined) {
+        draft.id = id;
+        draft.tool = call;
+        return;
+    }
+    blocks.push({ id, kind: 'tool', tool: call });
+}
+/** The call the model is still writing, as far as its draft has come. */
+function upsertToolDraft(blocks, draft) {
+    const id = `tool-${draft.callId}`;
+    const existing = findToolBlock(blocks, id);
+    const call = applyToolDraft(existing?.tool, draft);
+    if (existing) {
+        existing.tool = call;
+        return;
+    }
+    blocks.push({ id, kind: 'tool', tool: call });
+}
+/** The structured reply the model is still writing, if one is showing. */
+function openStructuredDraft(blocks) {
+    return blocks.findLast((block) => block.kind === 'structured' && block.draft !== undefined);
+}
+/** The structured reply the model is still writing, as far as its draft has come. */
+function upsertStructuredDraft(blocks, text, idPrefix) {
+    const open = openStructuredDraft(blocks);
+    const draft = (open?.draft ?? '') + text;
+    if (open) {
+        open.draft = draft;
+        open.value = partialJsonObject(draft);
+        return;
+    }
+    blocks.push({
+        id: nextBlockId(idPrefix),
+        kind: 'structured',
+        value: partialJsonObject(draft),
+        draft,
+    });
+}
+/** The structured reply, in its draft's place when one is showing. */
+function settleStructured(blocks, value, idPrefix) {
+    const open = openStructuredDraft(blocks);
+    if (open) {
+        open.value = value;
+        delete open.draft;
+        return;
+    }
+    blocks.push({ id: nextBlockId(idPrefix), kind: 'structured', value });
+}
+/** 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 } : {}),
+        });
+    }
+}
+/** Turns a user draft into transcript blocks: a `user-text` block for the trimmed text, then one block per attachment and per voice clip. */
+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 keptReply(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_draft':
+                upsertToolDraft(blocks, event);
+                break;
+            case 'tool':
+                upsertToolBlock(blocks, event.tool);
+                appendPromotedToolMedia(blocks, event.tool, idPrefix, promotedMediaUrls);
+                break;
+            case 'structured_draft':
+                upsertStructuredDraft(blocks, event.text, idPrefix);
+                break;
+            case 'structured':
+                settleStructured(blocks, event.structured, idPrefix);
+                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 'guardrail':
+                addGuardrailBlock(blocks, {
+                    id: nextBlockId(idPrefix),
+                    kind: 'guardrail',
+                    guardrail: event.guardrail,
+                });
+                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;
+            default:
+                break;
+        }
+    }
+    return blocks;
+}
+/** One conversation turn as blocks: the user draft's blocks followed by the assistant events folded into 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,24 @@
+import type { ComposerPendingKind } from './pending.js';
+/** Where a run is: idle, streaming, or held at a tool gate. */
+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';
+/** What decides the composer's actions: the run phase, whether there is something to send, and whether steering and stop are allowed. */
+export type ComposerActionContext = {
+    phase: ComposerRunPhase;
+    hasPayload: boolean;
+    /** From `ProfileInterface.allowSteering` (text only; false elsewhere). */
+    allowSteering: boolean;
+    /** Composer profiles always project `canStop: true`. */
+    canStop?: boolean;
+};
+/** The action of the primary button and Enter: `send` when idle with a draft, `queue` mid-run with one, `stop` while streaming with none (when stop is allowed), else `none`. */
+declare function resolveComposerPrimary(ctx: ComposerActionContext): ComposerPrimaryAction;
+/** The split menu's actions: none without a draft; `stash` when idle; mid-run `queue`, `steer` while streaming when steering is allowed, `send_now` and `stash`. */
+declare function resolveComposerMenuActions(ctx: ComposerActionContext): ComposerMenuAction[];
+export { resolveComposerMenuActions, resolveComposerPrimary };

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

@@ -0,0 +1,33 @@
+/** The action of the primary button and Enter: `send` when idle with a draft, `queue` mid-run with one, `stop` while streaming with none (when stop is allowed), else `none`. */
+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';
+    }
+    // why: Gated is still the same run: queue only, no stream to stop.
+    return ctx.hasPayload ? 'queue' : 'none';
+}
+/** The split menu's actions: none without a draft; `stash` when idle; mid-run `queue`, `steer` while streaming when steering is allowed, `send_now` and `stash`. */
+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;
+    }
+    // why: gated: no steer (not an inject stage); send_now = host ends wait + send
+    return ['queue', 'send_now', 'stash'];
+}
+// invariant: 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,20 @@
+import type { AttachmentValidationIssue } from '../kernel/types.js';
+import type { ProfileGuardrailsView, ProfileInputsInterface, TranscriptBlock, UserTurnDraft } from './types.js';
+/**
+ * Reads a draft's text at the `user` boundary with Theorem's patterns, as the kernel will: a
+ * match set to redact shows as its placeholder. A match set to block leaves the draft as typed;
+ * the kernel refuses the turn. A match of the host's own patterns is the kernel's to find.
+ */
+declare function sanitizeUserDraft(draft: UserTurnDraft, guardrails?: ProfileGuardrailsView): UserTurnDraft;
+/** The result of preparing a user turn: the sanitized draft with its transcript blocks, or the attachment issues that rejected it. */
+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,39 @@
+import { detectAt } from '../guardrails/detect-at.js';
+import { DETECT_DEFAULTS } from '../guardrails/detectors.js';
+import { buildUserTurnBlocks } from './blocks.js';
+import { validateProfileInputs } from './inputs.js';
+/** The view's matrix with Theorem's patterns off where the profile turned them off. The host's own patterns stay with the kernel. */
+function detectOf(guardrails) {
+    if (!guardrails)
+        return DETECT_DEFAULTS;
+    const { detect, patterns } = guardrails;
+    if (!patterns)
+        return detect;
+    const sources = Object.fromEntries(Object.entries(patterns).map(([detector, { theorem }]) => [
+        detector,
+        { theorem, matchers: [] },
+    ]));
+    return { ...detect, sources };
+}
+/**
+ * Reads a draft's text at the `user` boundary with Theorem's patterns, as the kernel will: a
+ * match set to redact shows as its placeholder. A match set to block leaves the draft as typed;
+ * the kernel refuses the turn. A match of the host's own patterns is the kernel's to find.
+ */
+function sanitizeUserDraft(draft, guardrails) {
+    if (draft.text === undefined) {
+        return draft;
+    }
+    const detected = detectAt(draft.text, 'user', detectOf(guardrails));
+    return { ...draft, text: detected.text ?? draft.text };
+}
+/** 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,24 @@
+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;
+/** The interface for a profile that is not live. */
+declare function interfaceFromProfile(input: Exclude<Profile, LiveProfile>, tools: ToolRegistry): ComposerProfileInterface;
+/** The interface for any profile. */
+declare function interfaceFromProfile(input: Profile, tools: ToolRegistry): ProfileInterface;
+/** The interface for a profile the host has already projected, without resolving its tools again. */
+declare function interfaceFromProjected(projected: ProjectedProfile): ProfileInterface;
+/**
+ * The interface a browser may read: {@linkcode interfaceFromProfile} without `identity.system` and
+ * `systemByRole`, which stay on the server. Labels, turn behaviour, guardrails, and observability are kept.
+ */
+declare function clientProfileInterface(input: LiveProfile, tools: ToolRegistry): LiveProfileInterface;
+/** The client-safe interface for a profile that is not live. */
+declare function clientProfileInterface(input: Exclude<Profile, LiveProfile>, tools: ToolRegistry): ComposerProfileInterface;
+/** The client-safe interface for any profile. */
+declare function clientProfileInterface(input: Profile, tools: ToolRegistry): ProfileInterface;
+export { clientProfileInterface, interfaceFromProfile, interfaceFromProjected };

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

@@ -0,0 +1,179 @@
+// 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, 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,
+        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 urlAllowView(allow) {
+    return { hosts: [...(allow.hosts ?? [])], fromTools: allow.fromTools ?? true };
+}
+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),
+    };
+}
+/** 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 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, page };
+}
+/** A call has no T2 loader. */
+function liveToolsView({ allow, page }) {
+    return { allow, page };
+}
+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,
+        providerContinuation: projected.providerContinuation,
+        outputs,
+        guardrails,
+        observability,
+        labels: clientLabels(profile?.labels),
+    };
+    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: liveView(projected.live),
+                ...(projected.inputs ? { inputs: { slots: inputs.slots, context: inputs.context } } : {}),
+                tools: liveToolsView(toolsView(projected, profile)),
+            });
+        default: {
+            const exhaustive = projected.type;
+            return exhaustive;
+        }
+    }
+}
+/** The interface for any profile. */
+function interfaceFromProfile(input, tools) {
+    // 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);
+}
+/** 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

@@ -0,0 +1,46 @@
+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';
+/**
+ * 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;
+/** 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;
+    };
+}, 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:
+ * 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[];
+/** 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
+ * 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, };