@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/interface/tool-calls.js

@@ -0,0 +1,127 @@
+// invariant: The model's raw call is the one owner of a call's arguments. The transcript, the interface
+// session and history read calls through this fold only.
+import { TheoremError } from '../guardrails/error.js';
+import { labelText } from '../guardrails/labels.js';
+import { partialJsonObject } from '../kernel/util/partial-json.js';
+/**
+ * The raw call comes first for every call (`turnEventSchema`); a phase for a call never made is a
+ * broken stream.
+ */
+function applyToolEvent(call, tool) {
+    if (tool.phase === undefined) {
+        return {
+            name: tool.name,
+            callId: tool.callId,
+            ...(tool.operationId ? { operationId: tool.operationId } : {}),
+            arguments: tool.arguments,
+            ...(tool.reasoning ? { reasoning: tool.reasoning } : {}),
+            ...(tool.stepId ? { stepId: tool.stepId } : {}),
+            artifacts: [],
+        };
+    }
+    if (call === undefined) {
+        throw new TheoremError('bad_response', `Tool event '${tool.phase}' for call '${tool.callId}' arrived before the call.`);
+    }
+    if (call.callId !== tool.callId || call.name !== tool.name) {
+        throw new TheoremError('bad_response', labelText('error.bad_response'));
+    }
+    switch (tool.phase) {
+        case 'running': {
+            // why: A resumed call runs again: it is open until its next settle.
+            const { endedAt: _settled, outputDraft: _drafted, ...open } = call;
+            return {
+                ...open,
+                state: tool,
+                startedAt: tool.at,
+                ...(tool.edited ? { edited: tool.edited } : {}),
+                ...(tool.activity ? { activity: tool.activity } : {}),
+            };
+        }
+        case 'complete':
+            return {
+                ...settled(call),
+                state: tool,
+                endedAt: tool.at,
+                ...(tool.activityPast ? { activityPast: tool.activityPast } : {}),
+            };
+        case 'error':
+            return {
+                ...settled(call),
+                state: tool,
+                endedAt: tool.at,
+                ...(tool.activityPast ? { activityPast: tool.activityPast } : {}),
+            };
+        case 'cancel':
+        case 'gate':
+            return { ...settled(call), state: tool, endedAt: tool.at };
+        case 'draft':
+            return { ...call, outputDraft: (call.outputDraft ?? '') + tool.text };
+        case 'artifact':
+            return { ...call, artifacts: [...call.artifacts, tool.artifact] };
+        case 'dispatch':
+        case 'progress':
+        case 'trace':
+        case 'warning':
+            return call;
+    }
+}
+/** `call` without the preview of its output: it settled, and its output is whole. */
+function settled(call) {
+    const { outputDraft: _drafted, ...rest } = call;
+    return rest;
+}
+/**
+ * A call the model is still writing, with the next piece of its draft added. The call that arrives
+ * whole replaces it (`applyToolEvent` builds the call from the request alone).
+ */
+function applyToolDraft(call, draft) {
+    return {
+        arguments: {},
+        artifacts: [],
+        ...call,
+        name: draft.name,
+        callId: draft.callId,
+        draft: (call?.draft ?? '') + draft.text,
+    };
+}
+/** Every call in `events`, in the order the model made them. */
+function toolCallsOf(events) {
+    const calls = new Map();
+    for (const event of events) {
+        if (event.type === 'tool_draft') {
+            calls.set(event.callId, applyToolDraft(calls.get(event.callId), event));
+            continue;
+        }
+        if (event.type !== 'tool')
+            continue;
+        const { tool } = event;
+        const key = tool.operationId ?? tool.callId;
+        // why: The draft is keyed by the model's callId; the call that replaces it may carry an operation ID.
+        if (tool.phase === undefined && calls.get(tool.callId)?.draft !== undefined) {
+            calls.delete(tool.callId);
+        }
+        calls.set(key, applyToolEvent(calls.get(key), tool));
+    }
+    return [...calls.values()];
+}
+/** The arguments shown for approval, or the user's edit, or the model's original call. */
+function toolCallRanWith(call) {
+    return ((call.state?.phase === 'gate' ? call.state.gate.preparedArguments : undefined) ??
+        call.edited?.to ??
+        call.arguments);
+}
+/** True when the event is the complete or error event of the tool call with this id. */
+function settlesToolCall(event, callId) {
+    if (event.type !== 'tool' || event.tool.callId !== callId)
+        return false;
+    return event.tool.phase === 'complete' || event.tool.phase === 'error';
+}
+/**
+ * A call's arguments as far as the model has written them: the whole arguments once the call has
+ * arrived, else what `partialJsonObject` reads of its draft. For a preview: a field still being
+ * written is not its final value.
+ */
+function argumentsSoFar(call) {
+    return call.draft === undefined ? call.arguments : partialJsonObject(call.draft);
+}
+export { applyToolDraft, applyToolEvent, argumentsSoFar, settlesToolCall, toolCallRanWith, toolCallsOf, };

package/esm/src/interface/tool-invoke.d.ts

@@ -0,0 +1,6 @@
+import type { ToolId, TurnEvent, TurnToolSnapshot } from '../kernel/types.js';
+/** The ids of the tools a turn loaded, read from the loaded ids in its completed tool events. */
+declare function promotedToolIdsFromEvents(events: readonly TurnEvent[]): ToolId[];
+/** The tool snapshot on the last `done` event that carries one, which only a turn stopped on a tool or gate does. */
+declare function toolSnapshotFromEvents(events: readonly TurnEvent[]): TurnToolSnapshot | undefined;
+export { promotedToolIdsFromEvents, toolSnapshotFromEvents };

package/esm/src/interface/tool-invoke.js

@@ -0,0 +1,22 @@
+import { extractLoadedIds } from '../kernel/tools/resolve.js';
+import { findLast } from '../kernel/util/find-last.js';
+/** The ids of the tools a turn loaded, read from the loaded ids in its completed tool events. */
+function promotedToolIdsFromEvents(events) {
+    const ids = new Set();
+    for (const event of events) {
+        if (event.type !== 'tool' || event.tool.phase !== 'complete') {
+            continue;
+        }
+        for (const id of extractLoadedIds(event.tool.output) ?? []) {
+            ids.add(id);
+        }
+    }
+    return [...ids];
+}
+/** The tool snapshot on the last `done` event that carries one, which only a turn stopped on a tool or gate does. */
+function toolSnapshotFromEvents(events) {
+    // why: Only a `done` that stopped on `tool` or `gate` carries one (`DoneEvent`).
+    const done = findLast(events, (event) => event.type === 'done' && event.tools !== undefined);
+    return done?.type === 'done' ? done.tools : undefined;
+}
+export { promotedToolIdsFromEvents, toolSnapshotFromEvents };

package/esm/src/interface/tool-media.d.ts

@@ -0,0 +1,11 @@
+/** A media file a tool's output points to: its URL, MIME type and, when the output carried one, a smaller preview URL. */
+export type PromotedToolMedia = {
+    url: string;
+    mimeType: string;
+    /** A smaller copy of the same file, when the output also carried one. */
+    previewUrl?: string;
+};
+/** Reads an http(s) URL string as promoted media, with the MIME type taken from its file extension; returns undefined for an empty or invalid string, another scheme, or an extension it does not know. */
+export declare function promotedMediaFromUrlString(raw: string): PromotedToolMedia | undefined;
+/** One file at several sizes is promoted once: `url` its largest copy, `previewUrl` its smallest. */
+export declare function collectPromotedMediaFromToolOutput(output: unknown): PromotedToolMedia[];

package/esm/src/interface/tool-media.js

@@ -0,0 +1,113 @@
+const EXT_MIME = {
+    avif: 'image/avif',
+    gif: 'image/gif',
+    heic: 'image/heic',
+    heif: 'image/heif',
+    jpeg: 'image/jpeg',
+    jpg: 'image/jpeg',
+    png: 'image/png',
+    svg: 'image/svg+xml',
+    webp: 'image/webp',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mov: 'video/quicktime',
+    ogv: 'video/ogg',
+    mp3: 'audio/mpeg',
+    m4a: 'audio/mp4',
+    ogg: 'audio/ogg',
+    wav: 'audio/wav',
+};
+function mimeForPathname(pathname) {
+    const base = pathname.split('/').pop() ?? pathname;
+    const dot = base.lastIndexOf('.');
+    if (dot <= 0 || dot === base.length - 1)
+        return undefined;
+    const ext = base.slice(dot + 1).toLowerCase();
+    return EXT_MIME[ext];
+}
+/** Reads an http(s) URL string as promoted media, with the MIME type taken from its file extension; returns undefined for an empty or invalid string, another scheme, or an extension it does not know. */
+export function promotedMediaFromUrlString(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return undefined;
+    const mimeType = mimeForPathname(parsed.pathname);
+    if (!mimeType)
+        return undefined;
+    return { url: parsed.href, mimeType };
+}
+/** MediaWiki resizes: `…/thumb/<a>/<ab>/<File>/<N>px-<File>` is `<N>` wide; the original is `…/<a>/<ab>/<File>`. */
+const MEDIAWIKI_THUMB = /^(.*)\/thumb(\/.+\/([^/]+))\/(\d+)px-\3(?:\.[a-z0-9]+)?$/i;
+/**
+ * The underlying file, so one picture at several sizes counts once (Wikipedia
+ * summaries carry `thumbnail` and `originalimage`, sometimes on different
+ * wikimedia.org hosts). `width` ranks copies; the original ranks highest.
+ */
+function mediaAsset(url) {
+    const parsed = new URL(url);
+    const site = parsed.hostname.split('.').slice(-2).join('.');
+    // why: Tracking parameters never change the file; other query parameters may.
+    for (const name of [...parsed.searchParams.keys()]) {
+        if (name.startsWith('utm_'))
+            parsed.searchParams.delete(name);
+    }
+    const thumb = MEDIAWIKI_THUMB.exec(parsed.pathname);
+    const pathname = thumb ? `${thumb[1]}${thumb[2]}` : parsed.pathname;
+    return {
+        key: `${site}${pathname}${parsed.search}`,
+        width: thumb ? Number(thumb[4]) : Number.POSITIVE_INFINITY,
+    };
+}
+/** One file at several sizes is promoted once: `url` its largest copy, `previewUrl` its smallest. */
+export function collectPromotedMediaFromToolOutput(output) {
+    const seen = new Map();
+    const out = [];
+    const visit = (value) => {
+        if (typeof value === 'string') {
+            const media = promotedMediaFromUrlString(value);
+            if (!media)
+                return;
+            const asset = mediaAsset(media.url);
+            const prior = seen.get(asset.key);
+            if (!prior) {
+                seen.set(asset.key, { index: out.length, largest: asset.width, smallest: asset.width });
+                out.push(media);
+                return;
+            }
+            const current = out[prior.index];
+            if (asset.width > prior.largest) {
+                prior.largest = asset.width;
+                out[prior.index] = {
+                    ...current,
+                    url: media.url,
+                    previewUrl: current.previewUrl ?? current.url,
+                };
+            }
+            else if (asset.width < prior.smallest) {
+                prior.smallest = asset.width;
+                out[prior.index] = { ...current, previewUrl: media.url };
+            }
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (value !== null && typeof value === 'object') {
+            for (const nested of Object.values(value)) {
+                visit(nested);
+            }
+        }
+    };
+    visit(output);
+    return out;
+}

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

@@ -0,0 +1,278 @@
+import type { Boundary } from '../guardrails/boundaries.js';
+import type { DetectAction, DetectMatrix, Detector, UrlDetector } from '../guardrails/detectors.js';
+import type { GuardrailEvent } from '../guardrails/event-schemas.js';
+import type { LabelOverrides } from '../guardrails/labels.js';
+import type { ResolvedGuardrailPolicy } from '../guardrails/types.js';
+import type { ProfileToolsSpec, ToolCallEdit, ToolPhaseEvent } from '../kernel/tools/types.js';
+import type { ReasoningPart } from '../kernel/turn-events.js';
+import type { AttachmentValidationIssue, CompactionSpec, GroundingEvent, ImageProfile, LiveProfile, ModelBinding, ModelId, ProfileContextSpec, ProfileOutputsSpec, ProviderEvidence, Source, SpeechProfile, TextProfile, TurnStop, TurnTokens } from '../kernel/types.js';
+import type { ResolvedObservabilityPolicy } from '../observability/types.js';
+/** What a URL detector lets through besides the given URLs, with its defaults applied. */
+export interface UrlAllowView {
+    hosts: string[];
+    fromTools: boolean;
+}
+/** Whose patterns one detector reads with: the host's are named, never shown. */
+export interface DetectorPatternsView {
+    /** Whether Theorem's own patterns run. */
+    theorem: boolean;
+    /** The names of the host's patterns. */
+    names: string[];
+}
+/** A detector of the host's own: what it is called and where it applies, never what it matches. */
+export interface HostDetectorView {
+    /** Its key in `guardrails.detect`, as in `acme.record`. Its rule is `detect.<id>`. */
+    id: string;
+    label: string;
+    /** Its action at every boundary. */
+    actions: Record<Boundary, DetectAction>;
+    /** The names of its patterns. */
+    names: string[];
+    /** Whether it also reads with a function of the host's. */
+    find: boolean;
+}
+/** Guardrails visible to UI — a host detector's `find` is told of, not sent. */
+export type ProfileGuardrailsView = Pick<ResolvedGuardrailPolicy, 'quota' | 'blockedReply'> & {
+    /** Every detector's action at every boundary. */
+    detect: DetectMatrix;
+    /** Whose patterns a detector reads with, for each one the profile changed it for. */
+    patterns?: Partial<Record<Detector, DetectorPatternsView>>;
+    /** The host's own detectors, in the order the profile lists them. The kernel reads with them. */
+    host?: HostDetectorView[];
+    /** What `ungiven_images` and `ungiven_links` let through. */
+    allow: Record<UrlDetector, UrlAllowView>;
+};
+/** Observability visible to UI — TraceSink / onWriteError functions are omitted. */
+export type ProfileObservabilityView = Pick<ResolvedObservabilityPolicy, 'record' | 'sampleRate' | 'include' | 'scrub' | 'resource' | 'retainForDays' | 'rotateAfterMiB'> & {
+    /** false | registered id | 'custom' when writeTo is an inline TraceSink; absent when unset. */
+    writeTo?: false | string;
+    hasOnWriteError: boolean;
+};
+/** Resolved `inputs` — `ProfileInputsSpec` plus `acceptAttr` for file pickers. */
+export interface ProfileInputsInterface {
+    text: boolean;
+    attachments: {
+        accept: string[];
+        acceptAttr: string;
+    } | null;
+    voice: {
+        accept: string[];
+    } | null;
+    maxFiles?: number;
+    maxBytes?: number;
+    maxTurnBytes?: number;
+    limitsByMime?: Record<string, number>;
+    slots?: Record<string, string[]>;
+    context?: ProfileContextSpec;
+}
+/**
+ * A tool's definition (handler, schemas, endpoint, headers) stays on the host; `t1Policy` too.
+ * `page` names the tools the page answers (`answeredBy: 'page'`): the page needs a function for each.
+ */
+export type ProfileToolsView = Pick<ProfileToolsSpec, 'allow' | 't2Loader' | 'parallel'> & {
+    page: string[];
+};
+/** A model binding as the interface carries it: a compaction `trigger` is a host function. */
+export type ModelBindingView = Omit<ModelBinding, 'compaction'> & {
+    compaction?: Omit<CompactionSpec, 'trigger'>;
+};
+/** `profile.outputs` as the interface carries it: validators are host functions. */
+export type ProfileOutputsView = Omit<ProfileOutputsSpec, 'validation'>;
+/** What the text, image, and speech interfaces carry in place of their profile's own fields. */
+export type ComposerInterfaceFields = {
+    models: Record<ModelId, ModelBindingView>;
+    outputs?: ProfileOutputsView;
+    /** Client keys' overrides (`CLIENT_LABEL_KEYS`), resolved on the host; pass to `labelText`. */
+    labels: LabelOverrides;
+    inputs: ProfileInputsInterface;
+    guardrails?: ProfileGuardrailsView;
+    observability?: ProfileObservabilityView;
+    /** Always true — composer turns cancel via `TurnRequest.signal`. */
+    canStop: true;
+};
+/** A text profile as a client sees it, without its server-only fields. */
+export type TextProfileInterface = Omit<TextProfile, 'inputs' | 'tools' | 'guardrails' | 'observability' | 'labels' | 'models' | 'outputs'> & ComposerInterfaceFields & {
+    tools: ProfileToolsView;
+    /** From `turnBehaviour.allowSteering` (default true on text). */
+    allowSteering: boolean;
+};
+/** An image profile as a client sees it, without its server-only fields. */
+export type ImageProfileInterface = Omit<ImageProfile, 'inputs' | 'tools' | 'guardrails' | 'observability' | 'labels' | 'models' | 'outputs'> & ComposerInterfaceFields & {
+    tools: ProfileToolsView;
+};
+/** A speech profile as a client sees it, without its server-only fields. */
+export type SpeechProfileInterface = Omit<SpeechProfile, 'guardrails' | 'observability' | 'labels' | 'models' | 'outputs'> & ComposerInterfaceFields;
+/** A live profile as a client sees it, without its server-only fields. */
+export type LiveProfileInterface = Omit<LiveProfile, 'tools' | 'guardrails' | 'observability' | 'labels' | 'models' | 'live'> & {
+    /** Without `greeting` and `resumed`: the prompts stay on the host. */
+    live: Omit<LiveProfile['live'], 'greeting' | 'resumed'>;
+    models: Record<ModelId, ModelBindingView>;
+    /** Client keys' overrides (`CLIENT_LABEL_KEYS`), resolved on the host; pass to `labelText`. */
+    labels: LabelOverrides;
+    tools: Pick<ProfileToolsView, 'allow' | 'page'>;
+    guardrails?: ProfileGuardrailsView;
+    observability?: ProfileObservabilityView;
+};
+/** Any profile as a client sees it. */
+export type ProfileInterface = TextProfileInterface | ImageProfileInterface | SpeechProfileInterface | LiveProfileInterface;
+/** Turn/chat composer profiles — excludes live (realtime streams, no turn inputs block). */
+export type ComposerProfileInterface = Exclude<ProfileInterface, LiveProfileInterface>;
+/** The kinds of block a transcript holds. */
+export type TranscriptBlockKind = 'user-text' | 'user-attachment' | 'user-voice' | 'thought' | 'text' | 'tool' | 'structured' | 'media' | 'grounding' | 'citation' | 'evidence' | 'guardrail' | 'error' | 'turn-done';
+export interface TranscriptBlockBase {
+    id: string;
+    kind: TranscriptBlockKind;
+}
+export interface UserTextBlock extends TranscriptBlockBase {
+    kind: 'user-text';
+    text: string;
+}
+export interface UserAttachmentBlock extends TranscriptBlockBase {
+    kind: 'user-attachment' | 'user-voice';
+    name: string;
+    mimeType: string;
+    sizeBytes: number;
+    /** Optional base64 payload for inline image/audio preview in the host UI. */
+    data?: string;
+}
+export interface ThoughtBlock extends TranscriptBlockBase {
+    kind: 'thought';
+    text: string;
+}
+export interface TextBlock extends TranscriptBlockBase {
+    kind: 'text';
+    text: string;
+}
+/** Where a call stands: the latest phase that changes its status. */
+export type ToolCallState = Extract<ToolPhaseEvent, {
+    phase: 'running' | 'gate' | 'complete' | 'error' | 'cancel';
+}>;
+/** invariant: An issued operation joins its request and phases; historical calls use callId. */
+export interface ToolCall {
+    operationId?: string;
+    name: string;
+    callId: string;
+    /** What the model proposed. `{}` while the model is still writing the call (`draft`). */
+    arguments: Record<string, unknown>;
+    /**
+     * While the model is still writing the call: its arguments' JSON text so far, from its
+     * `tool_draft` events. Gone once the call arrives whole; `argumentsSoFar` reads it.
+     */
+    draft?: string;
+    /** The call's `ToolCallRequest.reasoning`: history replays the call with it. */
+    reasoning?: ReasoningPart[];
+    /** The call's `ToolCallRequest.stepId`: calls sharing it replay as one assistant message. */
+    stepId?: string;
+    /** The user's edit on approval; `to` is what ran. */
+    edited?: ToolCallEdit;
+    /** What the call is doing, in the tool's words, from its last `running` phase. */
+    activity?: string;
+    /** What the call did, from its `complete` phase, or that it failed, from its `error` phase. */
+    activityPast?: string;
+    /**
+     * While the call runs: what the tool has written of its output so far, from its `draft` phases
+     * (an agent tool's: its agent's reply). Gone once the call settles; `state` has the output.
+     */
+    outputDraft?: string;
+    /** Absent while the call has only been made. */
+    state?: ToolCallState;
+    /** When it last started running (epoch ms). */
+    startedAt?: number;
+    /** When it last settled: complete, failed, cancelled, or gated (epoch ms). */
+    endedAt?: number;
+    artifacts: unknown[];
+}
+export interface ToolBlock extends TranscriptBlockBase {
+    kind: 'tool';
+    tool: ToolCall;
+}
+export interface StructuredBlock extends TranscriptBlockBase {
+    kind: 'structured';
+    /** The reply; while `draft` is set, what of it the model has written so far (`partialJsonObject`). */
+    value: unknown;
+    /**
+     * The JSON the model has written so far, from `structured_draft` events. Gone once the
+     * `structured` event arrives, which owns the reply.
+     */
+    draft?: string;
+}
+export interface MediaBlock extends TranscriptBlockBase {
+    kind: 'media';
+    mimeType: string;
+    /** Base64 for model-generated or attached media. Absent when `url` is set. */
+    data?: string;
+    /** Remote http(s) URL promoted from completed tool output. Absent when `data` is set. */
+    url?: string;
+    /** A smaller copy of `url` for previews, when the tool output offered one. */
+    previewUrl?: string;
+}
+export interface GroundingBlock extends TranscriptBlockBase {
+    kind: 'grounding';
+    grounding: GroundingEvent;
+}
+/** Sources a provider or a tool cited; `callId` names the tool call when a tool did. */
+export interface CitationBlock extends TranscriptBlockBase {
+    kind: 'citation';
+    sources: Source[];
+    callId?: string;
+}
+export interface EvidenceBlock extends TranscriptBlockBase {
+    kind: 'evidence';
+    evidence: ProviderEvidence;
+}
+/**
+ * A guardrail's decision on the turn: a flag, a redaction, or a block. It names the rule and where
+ * it matched (`hits[].span`), never the matched text. It comes before the text it was read from.
+ * Theorem's own transcript shows nothing for it; a host reads it to show its own notice.
+ */
+export interface GuardrailBlock extends TranscriptBlockBase {
+    kind: 'guardrail';
+    guardrail: GuardrailEvent;
+}
+export interface ErrorBlock extends TranscriptBlockBase {
+    kind: 'error';
+    message: string;
+}
+export interface TurnDoneBlock extends TranscriptBlockBase {
+    kind: 'turn-done';
+    stop?: TurnStop;
+    tokens?: TurnTokens;
+    interactionId?: string;
+    compaction?: boolean;
+    /**
+     * How long the reply has worked so far (ms), approval waits excluded. The host
+     * client stamps it when a run ends, so the time travels with the transcript.
+     */
+    workedMs?: number;
+    /** When the reply last stopped (epoch ms), stamped with `workedMs`. */
+    endedAt?: number;
+}
+/** One block of a transcript: a message, an attachment, a thought, a tool call, or a notice. */
+export type TranscriptBlock = UserTextBlock | UserAttachmentBlock | ThoughtBlock | TextBlock | ToolBlock | StructuredBlock | MediaBlock | GroundingBlock | CitationBlock | EvidenceBlock | GuardrailBlock | ErrorBlock | TurnDoneBlock;
+/** A file the user has picked but not yet sent. */
+export interface PendingAttachment {
+    name: string;
+    mimeType: string;
+    sizeBytes: number;
+    /** Optional base64 payload copied onto the transcript block for UI preview. */
+    data?: string;
+}
+/** Whether the pending attachments pass the profile's limits, and the issues if not. */
+export interface AttachmentValidationResult {
+    ok: boolean;
+    issues: AttachmentValidationIssue[];
+}
+/** What the user has composed and not yet sent. */
+export interface UserTurnDraft {
+    text?: string;
+    attachments?: PendingAttachment[];
+    voice?: PendingAttachment[];
+}
+/** Options for folding turn events into transcript blocks. */
+export interface FoldTurnEventsOptions {
+    showThoughts?: boolean;
+    idPrefix?: string;
+}
+/** True unless the profile turns thought streaming off. */
+declare function streamThoughtsEnabled(outputs?: ProfileOutputsSpec): boolean;
+export { streamThoughtsEnabled };

package/esm/src/interface/types.js

@@ -0,0 +1,5 @@
+/** True unless the profile turns thought streaming off. */
+function streamThoughtsEnabled(outputs) {
+    return outputs?.streaming?.streamThoughts !== false;
+}
+export { streamThoughtsEnabled };

package/esm/src/kernel/api-catalog.d.ts

@@ -0,0 +1,85 @@
+/** labels-exempt-file: authoring request-field and export meta — not runtime user or model copy (P2) */
+import type { FieldMeta } from './schema.js';
+import type { TurnInput, TurnRequest } from './types.js';
+/** The catalog of the fields a `runTurn` request takes, keyed `runTurn.<field>`. */
+export declare const REQUEST_FIELDS: Record<`runTurn.${keyof TurnRequest | `input.${keyof TurnInput}`}`, FieldMeta>;
+/** What the catalog records about one export: what it is and what it does. */
+export type ApiExportMeta = {
+    kind: 'function' | 'class';
+    doc: string;
+};
+/** The catalog of the exports a builder calls by name, keyed by that name. */
+export declare const API_EXPORTS: {
+    readonly defineProfile: {
+        readonly kind: "function";
+        readonly doc: "Checks a profile and returns it; a field the profile type cannot take is a config error.";
+    };
+    readonly registerProfile: {
+        readonly kind: "function";
+        readonly doc: "Stores a profile under its id, so that a request can name it.";
+    };
+    readonly registerTool: {
+        readonly kind: "function";
+        readonly doc: "Stores a tool under its name, so that a profile can list it in tools.allow.";
+    };
+    readonly registerStructured: {
+        readonly kind: "function";
+        readonly doc: "Stores a JSON Schema under an id, so that a profile can name it in outputs.structured.";
+    };
+    readonly registerTraceDestination: {
+        readonly kind: "function";
+        readonly doc: "Stores a place to write traces under an id, so that a profile can name it in observability.";
+    };
+    readonly defineProvider: {
+        readonly kind: "function";
+        readonly doc: "Validates a provider definition and supplies its typed model helper.";
+    };
+    readonly registerProvider: {
+        readonly kind: "function";
+        readonly doc: "Registers a provider instance before profiles reference its ID.";
+    };
+    readonly runTurn: {
+        readonly kind: "function";
+        readonly doc: "Runs one turn of a text, image, or speech profile and yields its events.";
+    };
+    readonly runSession: {
+        readonly kind: "function";
+        readonly doc: "Runs a realtime voice or video session of a live profile.";
+    };
+    readonly runDecision: {
+        readonly kind: "function";
+        readonly doc: "Asks a decision profile its questions about your JSON state and returns checked answers.";
+    };
+    readonly invokeTool: {
+        readonly kind: "function";
+        readonly doc: "Runs one registered tool through a profile, with no model.";
+    };
+    readonly runTool: {
+        readonly kind: "function";
+        readonly doc: "Runs one registered tool through a profile, with no model, and returns how the call settled.";
+    };
+    readonly compactHistory: {
+        readonly kind: "function";
+        readonly doc: "Shortens a conversation history with the compaction the profile sets.";
+    };
+    readonly takeSlot: {
+        readonly kind: "function";
+        readonly doc: "Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.";
+    };
+    readonly releaseSlot: {
+        readonly kind: "function";
+        readonly doc: "Frees the turn slot that takeSlot gave.";
+    };
+    readonly overrideLabels: {
+        readonly kind: "function";
+        readonly doc: "Replaces status lines for every profile in the process; a profile's own labels wins.";
+    };
+    readonly resetLabels: {
+        readonly kind: "function";
+        readonly doc: "Removes every replacement that overrideLabels made.";
+    };
+    readonly TheoremError: {
+        readonly kind: "class";
+        readonly doc: "The error Theorem throws; its kind tells your host which status and wording to use.";
+    };
+};