@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/kernel/engine/token-estimate.js

@@ -0,0 +1,218 @@
+/**
+ * o200k is not every model's tokenizer, so text counts are an estimate for all families. Media is
+ * counted only by a rule the family's billed usage was measured to follow; a family without one
+ * reports media as `unknownMedia`, never a borrowed rate.
+ *
+ * Gemini 3 (`gemini-3*` flash / pro text models, direct or via OpenRouter).
+ * Measured 22/09/2026 against the usage Gemini bills — Interactions `usage`
+ * and `generateContent` `usageMetadata` agree exactly — on gemini-3.8-flash
+ * at the default media resolution (THEOREM never sets `media_resolution`).
+ * `countTokens` is not the oracle: it reports 560 per PDF page and 32 tokens
+ * per audio second, and neither is what is billed.
+ * - image: a patch grid inside a 1120-token budget that keeps the aspect
+ *   ratio — `⌊√(1120·w/h)⌋ × ⌊√(1120·h/w)⌋` (1024×1024 → 1089, 1920×1080 →
+ *   1100, 4032×3024 HEIC → 1064). Needs the pixel size from the image header.
+ * - audio: `⌈seconds × 25⌉`, seconds being decoded samples ÷ rate
+ *   (`audioSeconds`): 2.2 s → 56, 0.5 s → 13. Sample rate, channels and
+ *   silence do not matter. Raw PCM: bare `audio/pcm` is 16 kHz mono 16-bit;
+ *   `audio/L16` needs both `rate` and `channels`. `audio/pcm` with parameters,
+ *   `audio/alaw`, and `audio/mulaw` are refused by Interactions — unknown.
+ *   Mono `audio/L16` is unknown: Gemini converts it first and adds text tokens
+ *   no rule reproduces (about 31–33, plus 2 per second, plus 1 audio token
+ *   away from 16 kHz).
+ * - video: `frames × ⌊√(70·w/h)⌋ × ⌊√(70·h/w)⌋ + ⌈min(audio, frames) × 25⌉`,
+ *   `frames` = the video track's seconds rounded half up (66 per frame at
+ *   16:9, 63 at 4:3; fps, codec and container do not matter). Under half a
+ *   second rounds to no frames, which Gemini refuses — unknown. MP4 / MOV /
+ *   3GP and WebM only (`videoInfo`); other containers are unknown.
+ * - PDF: 520 tokens per page. Text on the page adds nothing.
+ * - text documents (plain, Markdown, CSV, JSON, HTML, CSS, XML, RTF,
+ *   JavaScript, Python) as their UTF-8 text. `text/md` and
+ *   `application/x-python` are unknown: Gemini converts them first, adding
+ *   about 30 text tokens no rule reproduces.
+ * - Provider file references (`uri`): unknown — the bytes are not here.
+ *
+ * Known gap: ADTS AAC. Gemini estimates its length from the bitrate; the
+ * decoded length here runs 2–3 tokens over at 10 s.
+ *
+ * Not yet checked against billed usage: video in WebM / MOV / 3GP, anamorphic
+ * video, and Gemini 3 models other than gemini-3.8-flash. The full probe and
+ * open decisions: https://github.com/masudl-hub/theoremai/issues/18
+ */
+import { historyMessageParts } from '../interaction-parts.js';
+import { MEDIA_INPUT_KINDS } from '../schema.js';
+import { base64ToBytes } from '../util/base64.js';
+import { mimeEssence } from '../util/mime.js';
+import { audioSeconds } from './media-probe/audio.js';
+import { imageSize } from './media-probe/image.js';
+import { pdfPageCount } from './media-probe/pdf.js';
+import { videoInfo } from './media-probe/video.js';
+export const TOKEN_TEXT_ENCODING = 'o200k_base';
+const GEMINI_3_TEXT_MODEL = /^gemini-3(?:\.\d+)?-(?:flash|pro)(?:-lite)?(?:-preview)?$/;
+const OPENROUTER_GOOGLE_PREFIX = 'google/';
+const GEMINI_3_IMAGE_BUDGET = 1120;
+const GEMINI_3_VIDEO_FRAME_BUDGET = 70;
+const GEMINI_3_AUDIO_PER_SECOND = 25;
+const GEMINI_3_PDF_PER_PAGE = 520;
+/** Bare `audio/pcm`: 16-bit mono at 16 kHz. */
+const PCM_DEFAULT_RATE = 16_000;
+const PCM_BYTES_PER_SAMPLE = 2;
+/** Document types Gemini reads as their own text. */
+const GEMINI_3_TEXT_DOCUMENTS = new Set([
+    'text/plain',
+    'text/csv',
+    'text/markdown',
+    'text/html',
+    'text/css',
+    'text/xml',
+    'text/rtf',
+    'text/javascript',
+    'application/x-javascript',
+    'text/x-python',
+    'application/json',
+]);
+/**
+ * Media family for a model binding — `undefined` when no verified rule covers
+ * it. OpenRouter uses the routed model's family (`google/gemini-3…`).
+ */
+export function mediaTokenFamily(binding) {
+    const modelId = binding.provider === 'google'
+        ? binding.apiId
+        : binding.provider === 'openrouter' && binding.apiId.startsWith(OPENROUTER_GOOGLE_PREFIX)
+            ? binding.apiId.slice(OPENROUTER_GOOGLE_PREFIX.length)
+            : undefined;
+    if (modelId === undefined)
+        return undefined;
+    return GEMINI_3_TEXT_MODEL.test(modelId) ? 'gemini-3' : undefined;
+}
+function mimeParam(mimeType, name) {
+    for (const piece of mimeType.split(';').slice(1)) {
+        const [key, value] = piece.split('=').map((s) => s.trim().toLowerCase());
+        if (key === name) {
+            const n = Number(value);
+            return Number.isInteger(n) && n > 0 ? n : undefined;
+        }
+    }
+    return undefined;
+}
+function hasParams(mimeType) {
+    return mimeType.includes(';');
+}
+/** Seconds of raw 16-bit PCM, or `undefined` when Gemini refuses how it is declared. */
+function pcmSeconds(mimeType, bytes) {
+    const essence = mimeEssence(mimeType);
+    let rate;
+    let channels;
+    if (essence === 'audio/pcm') {
+        if (hasParams(mimeType))
+            return undefined;
+        rate = PCM_DEFAULT_RATE;
+        channels = 1;
+    }
+    else {
+        rate = mimeParam(mimeType, 'rate');
+        channels = mimeParam(mimeType, 'channels');
+        // Mono L16 is converted before it is counted.
+        if (channels === 1)
+            return undefined;
+    }
+    if (!rate || !channels)
+        return undefined;
+    return Math.floor(bytes.length / (PCM_BYTES_PER_SAMPLE * channels)) / rate;
+}
+function gemini3Audio(mimeType, bytes) {
+    const essence = mimeEssence(mimeType);
+    const seconds = essence === 'audio/pcm' || essence === 'audio/l16'
+        ? pcmSeconds(mimeType, bytes)
+        : essence === 'audio/alaw' || essence === 'audio/mulaw'
+            ? undefined
+            : audioSeconds(bytes);
+    return seconds === undefined ? undefined : Math.ceil(seconds * GEMINI_3_AUDIO_PER_SECOND);
+}
+function patchGrid(budget, w, h) {
+    return Math.floor(Math.sqrt((budget * w) / h)) * Math.floor(Math.sqrt((budget * h) / w));
+}
+function gemini3Video(bytes) {
+    const info = videoInfo(bytes);
+    if (!info || info.audioSeconds === undefined)
+        return undefined;
+    const frames = Math.floor(info.seconds + 0.5);
+    if (frames === 0)
+        return undefined;
+    return (frames * patchGrid(GEMINI_3_VIDEO_FRAME_BUDGET, info.width, info.height) +
+        Math.ceil(Math.min(info.audioSeconds, frames) * GEMINI_3_AUDIO_PER_SECOND));
+}
+function utf8(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        // Not UTF-8: what Gemini reads from it is unknown.
+        return undefined;
+    }
+}
+async function gemini3Media(payload, text) {
+    if (!('data' in payload))
+        return undefined;
+    const essence = mimeEssence(payload.mimeType);
+    const bytes = base64ToBytes(payload.data);
+    switch (MEDIA_INPUT_KINDS[essence]) {
+        case 'image': {
+            const size = imageSize(bytes);
+            return size ? patchGrid(GEMINI_3_IMAGE_BUDGET, size.width, size.height) : undefined;
+        }
+        case 'audio':
+            return gemini3Audio(payload.mimeType, bytes);
+        case 'video':
+            return gemini3Video(bytes);
+        case 'document': {
+            if (essence === 'application/pdf') {
+                const pages = await pdfPageCount(bytes);
+                return pages === undefined ? undefined : pages * GEMINI_3_PDF_PER_PAGE;
+            }
+            if (!GEMINI_3_TEXT_DOCUMENTS.has(essence))
+                return undefined;
+            const decoded = utf8(bytes);
+            return decoded === undefined ? undefined : text(decoded);
+        }
+    }
+    return undefined;
+}
+let encodePromise = null;
+function buildEstimator(encode) {
+    const text = (value) => (value ? encode(value).length : 0);
+    const media = async (payload, family) => family === 'gemini-3' ? await gemini3Media(payload, text) : undefined;
+    const parts = async (list, family) => {
+        const count = { tokens: 0, unknownMedia: 0 };
+        for (const part of list) {
+            if (part.type === 'text') {
+                count.tokens += text(part.text);
+                continue;
+            }
+            const n = await media(part, family);
+            if (n === undefined)
+                count.unknownMedia += 1;
+            else
+                count.tokens += n;
+        }
+        return count;
+    };
+    const messages = async (list, family) => {
+        const count = { tokens: 0, unknownMedia: 0 };
+        for (const msg of list) {
+            const fromParts = await parts(historyMessageParts(msg), family);
+            count.tokens += fromParts.tokens;
+            count.unknownMedia += fromParts.unknownMedia;
+            for (const tc of msg.tool_calls ?? []) {
+                count.tokens += text(tc.function.name) + text(tc.function.arguments);
+            }
+        }
+        return count;
+    };
+    return { text, media, parts, messages };
+}
+// The ranks import lazily, so hosts that never estimate never pay for them.
+export async function loadTokenEstimator() {
+    encodePromise ??= import('gpt-tokenizer/encoding/o200k_base').then((m) => m.encode);
+    return buildEstimator(await encodePromise);
+}

package/esm/src/kernel/engine/tool-trace.d.ts

@@ -0,0 +1,58 @@
+import type { GuardrailEvent, ToolOrigin } from '../../guardrails/types.js';
+import { type SpanHandle, type TraceAttributes } from '../../observability/trace-span.js';
+import type { ToolPermission } from '../schema.js';
+import type { ToolFailure } from '../tools/types.js';
+import type { InteractionPart, TurnEvent } from '../types.js';
+import { type GuardrailCheck, type SentToolCall } from './turn-trace.js';
+/** A check at the tool boundary: the call's arguments, the remote-content gate, the result, or the network target. */
+type ToolCheck = Extract<GuardrailCheck, 'tool_arguments' | 'taint' | 'tool_result' | 'tool_failure' | 'network' | 'network_request'>;
+/**
+ * Records one tool-boundary check on the tool's span with the time it took:
+ * its decision, or a pass (`allow`) when it let the call or result through.
+ * Trace only; the host still hears about decisions alone. An untraced call has no span.
+ */
+declare function recordToolCheck(span: SpanHandle | undefined, check: ToolCheck, durationMs: number, guardrail: GuardrailEvent | undefined): void;
+/** How a tool call ended. Only `error` is a failure; the rest were stopped or finished. */
+type ToolOutcome = 'ok' | 'error' | 'denied' | 'gated' | 'paused' | 'cancelled';
+interface ToolCallStart {
+    name: string;
+    callId: string;
+    call: SentToolCall;
+    /** Absent when the tool is not registered. */
+    origin?: ToolOrigin;
+    permission?: ToolPermission;
+    /** The host's answer to an earlier gate, when this call resumes one. */
+    approved?: boolean;
+    /** The turn step whose model call asked for this tool. */
+    step?: number;
+}
+interface ToolCallEnd {
+    outcome: ToolOutcome;
+    /** What the model reads back: its text and any media. Absent when nothing is read back. */
+    result?: {
+        text: string;
+        parts?: readonly InteractionPart[];
+    };
+    /** The tool's raw output, present only when its body completed. */
+    data?: {
+        value: unknown;
+    };
+    /** The failure, on `error`: its kind (`error.type`) and the tool's code for it. */
+    failure?: Pick<ToolFailure, 'code' | 'kind'>;
+    /** Thrown out of the call (not an abort). */
+    thrown?: unknown;
+}
+interface ToolCallTrace {
+    span: SpanHandle;
+    observe: (event: TurnEvent) => void;
+    end: (end: ToolCallEnd) => void;
+}
+declare function toolSpanName(name: string): string;
+/**
+ * Spans from before `pre_tool` to settlement, so it covers the hooks, the gates and the body.
+ * Provider-run tools (search, maps, code execution) get no span: Theorem did not run them.
+ * `open` places it: a child of the turn's root, or the root of a host-invoked tool's own record.
+ */
+declare function startToolTrace(open: (name: string, attributes: TraceAttributes) => SpanHandle, start: ToolCallStart): ToolCallTrace;
+export type { ToolCallEnd, ToolCallStart, ToolCallTrace, ToolCheck, ToolOutcome };
+export { recordToolCheck, startToolTrace, toolSpanName };

package/esm/src/kernel/engine/tool-trace.js

@@ -0,0 +1,131 @@
+import { errorKind } from '../../guardrails/error.js';
+import { traceContent, traceJson, } from '../../observability/trace-span.js';
+import { authScopeRefusedSchema } from '../auth/scope-refusal.js';
+import { guardrailAttributes, guardrailCheckAttributes, optional, recordException, toolArgumentsText, tracePart, } from './turn-trace.js';
+const TOOL_CHECK_STAGE = {
+    tool_arguments: 'tool_call',
+    taint: 'tool_call',
+    tool_result: 'tool_result',
+    tool_failure: 'tool_result',
+    network: 'network',
+    network_request: 'network',
+};
+/** Decisions already recorded with their check's time, so `observe` does not record them twice. */
+const timedDecisions = new WeakSet();
+/**
+ * Records one tool-boundary check on the tool's span with the time it took:
+ * its decision, or a pass (`allow`) when it let the call or result through.
+ * Trace only; the host still hears about decisions alone. An untraced call has no span.
+ */
+function recordToolCheck(span, check, durationMs, guardrail) {
+    if (!span)
+        return;
+    if (guardrail)
+        timedDecisions.add(guardrail);
+    span.event('theorem.guardrail', guardrailCheckAttributes(check, durationMs, guardrail, {
+        stage: TOOL_CHECK_STAGE[check],
+        trust: 'untrusted',
+    }));
+}
+function toolSpanName(name) {
+    return name ? `execute_tool ${name}` : 'execute_tool';
+}
+function toolSpanAttributes(start) {
+    return {
+        'gen_ai.operation.name': 'execute_tool',
+        'gen_ai.tool.name': start.name,
+        'gen_ai.tool.call.id': start.callId,
+        'gen_ai.tool.type': 'function',
+        'gen_ai.tool.call.arguments': traceContent(toolArgumentsText(start.call)),
+        ...optional('theorem.tool.origin', start.origin),
+        ...optional('theorem.tool.permission', start.permission),
+        ...optional('theorem.tool.approved', start.approved),
+        ...optional('theorem.step', start.step),
+    };
+}
+/** A gate as `theorem.gate` event attributes. The auth `state` is a secret and never recorded. */
+function gateAttributes(gate) {
+    const auth = gate.kind === 'auth' ? gate.authChallenge : undefined;
+    return {
+        kind: gate.kind,
+        ...optional('permission', gate.permission),
+        ...(gate.summary ? { summary: traceContent(gate.summary) } : {}),
+        ...(auth
+            ? {
+                auth: {
+                    slot: auth.slot,
+                    type: auth.authType,
+                    service: auth.service,
+                    ...optional('issuer', auth.issuer),
+                    ...optional('resource', auth.resource),
+                    ...optional('required_scopes', auth.requiredScopes),
+                },
+            }
+            : {}),
+    };
+}
+const OUTCOME_STATUS = {
+    ok: 'OK',
+    error: 'ERROR',
+    denied: 'UNSET',
+    gated: 'UNSET',
+    paused: 'UNSET',
+    cancelled: 'UNSET',
+};
+/**
+ * Spans from before `pre_tool` to settlement, so it covers the hooks, the gates and the body.
+ * Provider-run tools (search, maps, code execution) get no span: Theorem did not run them.
+ * `open` places it: a child of the turn's root, or the root of a host-invoked tool's own record.
+ */
+function startToolTrace(open, start) {
+    const span = open(toolSpanName(start.name), toolSpanAttributes(start));
+    return {
+        span,
+        observe: (event) => {
+            if (event.type === 'guardrail' && !timedDecisions.has(event.guardrail)) {
+                span.event('theorem.guardrail', guardrailAttributes(event.guardrail));
+            }
+            if (event.type === 'tool' && event.tool.phase === 'gate') {
+                span.event('theorem.gate', gateAttributes(event.tool.gate));
+            }
+            if (event.type === 'tool' && event.tool.phase === 'progress') {
+                const refused = authScopeRefusedSchema.safeParse(event.tool.data);
+                if (refused.success) {
+                    const { slot, requested, declared } = refused.data;
+                    span.event('theorem.auth.scope_refused', { slot, requested, declared });
+                }
+            }
+            if (event.type === 'tool' && event.tool.phase === 'warning') {
+                const { code, message, severity } = event.tool.warning;
+                span.event('theorem.tool.warning', {
+                    code,
+                    message: traceContent(message),
+                    ...optional('severity', severity),
+                });
+            }
+            if (event.type === 'citation') {
+                span.event('theorem.grounding', { sources: traceJson(event.sources) });
+            }
+        },
+        end: (end) => {
+            if (end.thrown !== undefined)
+                recordException(span, end.thrown);
+            const errorType = end.outcome === 'error'
+                ? (end.failure?.kind ?? (end.thrown === undefined ? undefined : errorKind(end.thrown)))
+                : undefined;
+            span.set({
+                ...(end.result ? { 'gen_ai.tool.call.result': traceContent(end.result.text) } : {}),
+                ...(end.result?.parts?.length
+                    ? { 'theorem.tool.call.result.parts': end.result.parts.map(tracePart) }
+                    : {}),
+                ...(end.data ? { 'theorem.tool.data': traceJson(end.data.value) } : {}),
+                'theorem.tool.outcome': end.outcome,
+                ...optional('theorem.tool.failure.code', end.failure?.code),
+                ...optional('error.type', errorType),
+            });
+            const code = OUTCOME_STATUS[end.outcome];
+            span.end(code === 'ERROR' && errorType ? { code, message: errorType } : { code });
+        },
+    };
+}
+export { recordToolCheck, startToolTrace, toolSpanName };

package/esm/src/kernel/engine/tree.d.ts

@@ -0,0 +1,2 @@
+declare function mapStrings(value: unknown, map: (text: string) => string): unknown;
+export { mapStrings };

package/esm/src/kernel/engine/tree.js

@@ -0,0 +1,17 @@
+function mapStrings(value, map) {
+    if (typeof value === 'string') {
+        return map(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => mapStrings(item, map));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            out[key] = mapStrings(nested, map);
+        }
+        return out;
+    }
+    return value;
+}
+export { mapStrings };

package/esm/src/kernel/engine/turn-trace.d.ts

@@ -0,0 +1,118 @@
+import type { GuardrailEvent, GuardrailStage, TrustLevel } from '../../guardrails/types.js';
+import { type SpanHandle, type SpanLinkInput, type SpanOptions, type TraceAttributes, type TraceAttributeValue } from '../../observability/trace-span.js';
+import type { ToolFailure } from '../tools/types.js';
+import type { InteractionPart, ModelBinding, ProviderCompleteRequest, ProviderEvent, ProviderTransport, TurnEvent, TurnRequest, TurnStop, TurnTokens, TurnTraceLink } from '../types.js';
+import type { CallUsage } from './runner/usage.js';
+type TracePart = {
+    [key: string]: TraceAttributeValue;
+};
+declare function tracePart(part: InteractionPart): TracePart;
+/** Output parts folded from provider events: adjacent deltas of one kind merge. */
+declare class OutputFold {
+    readonly parts: TracePart[];
+    private open?;
+    /** Each call's `tool_call` part by `callId`, for the failure that follows a malformed one. */
+    private readonly calls;
+    add(event: ProviderEvent, nowUnixNano: string): void;
+    private appendText;
+    /**
+     * The model's call as a `tool_call` part. A malformed call's failure follows
+     * it from the provider; the part then records the text the model sent.
+     */
+    private addTool;
+    private push;
+}
+interface SentToolCall {
+    arguments: Record<string, unknown>;
+    failure?: ToolFailure;
+}
+/**
+ * A tool call's arguments as the model sent them. Malformed arguments keep the
+ * provider's raw text; parsed ones are the same JSON the kernel sends back in
+ * history, so both hash alike.
+ */
+declare function toolArgumentsText(call: SentToolCall): string;
+/**
+ * A guardrail decision as `theorem.guardrail` event attributes. The matched
+ * substring stays exact (not scrubbed: scrubbing it would erase what it shows);
+ * the record drops it unless the profile includes `guardrailMatchPreview`.
+ */
+declare function guardrailAttributes(guardrail: GuardrailEvent): TraceAttributes;
+/**
+ * A guardrail check whose time the trace records: the turn's input and output,
+ * each tool boundary, the checks that run on streamed output, and a live
+ * session's own gates.
+ */
+type GuardrailCheck = 'input' | 'egress' | 'tool_arguments' | 'taint' | 'tool_result' | 'tool_failure' | 'network' | 'network_request' | StreamCheck | 'live_input';
+/**
+ * A check that runs many times on one model call's streamed output: the
+ * progressive gate on each piece of reply text, the canary scan of every other
+ * streamed event, and a live session's gate on each batch it sends.
+ */
+type StreamCheck = 'output_stream' | 'stream_canary' | 'live_output';
+/**
+ * One timed guardrail check as `theorem.guardrail` attributes: its decision,
+ * or a pass (`allow`, no hits) when it let the text through. Trace only; the
+ * host still hears about hits alone.
+ */
+declare function guardrailCheckAttributes(check: GuardrailCheck, durationMs: number, guardrail: GuardrailEvent | undefined, passed: {
+    stage: GuardrailStage;
+    trust: TrustLevel;
+}): TraceAttributes;
+declare function optional(key: string, value: TraceAttributeValue | undefined): TraceAttributes;
+declare function usageAttributes(tokens: TurnTokens): TraceAttributes;
+declare function urlAttributes(url: unknown): TraceAttributes;
+declare function recordException(span: SpanHandle, err: unknown): void;
+/** Close a root that a throw ended: the exception, its kind as `error.type`, and ERROR. */
+declare function endThrownSpan(span: SpanHandle, err: unknown): void;
+interface CallEnd {
+    /** The call's one usage report (estimated sides filled), when there is one. */
+    tokens?: TurnTokens;
+    stop?: TurnStop;
+    /** Thrown out of the stream (not an abort). */
+    thrown?: unknown;
+}
+interface CallTrace {
+    span: SpanHandle;
+    /** Pass as the adapter's `tapUpstream`. */
+    tap: (row: Record<string, unknown>) => void;
+    /** Every provider event, before guardrails. */
+    observe: (event: ProviderEvent) => void;
+    /** A stream check's decision; it carries the time that check has spent on the call so far. */
+    guardrail: (event: GuardrailEvent) => void;
+    /** Add one run of a stream check to this call. */
+    guardTime: (check: StreamCheck, ms: number) => void;
+    end: (end: CallEnd) => void;
+}
+/**
+ * `open` places the span: a child of the turn's root, or the root of a Live response's own record.
+ * `usage.conversation` is read again at the end, since a Live response sets it only when it closes.
+ */
+declare function startCallTrace(open: (name: string, options: SpanOptions) => SpanHandle, args: {
+    req: ProviderCompleteRequest;
+    usage: CallUsage;
+    binding: ModelBinding | undefined;
+    transport: ProviderTransport;
+    step: number;
+    /** The runner's validation attempt; Live has none. */
+    attempt?: number;
+}): CallTrace;
+declare function traceLinks(links: readonly TurnTraceLink[] | undefined): SpanLinkInput[];
+declare function turnSpanOptions(req: TurnRequest): SpanOptions;
+interface TurnEnd {
+    seen: readonly TurnEvent[];
+    /** Those events as output parts, folded as they were delivered. */
+    delivered: OutputFold;
+    /** Validation / egress attempts that made a model call. */
+    attempts: number;
+    calls: number;
+    /** Thrown out of the turn (not an abort). */
+    thrown?: unknown;
+}
+/**
+ * Close a turn's `invoke_agent` span. Usage is the sum of this turn's own
+ * calls; a nested turn (compaction) carries its own.
+ */
+declare function endTurnSpan(root: SpanHandle, end: TurnEnd): void;
+export type { CallEnd, CallTrace, GuardrailCheck, SentToolCall, StreamCheck, TracePart, TurnEnd };
+export { endThrownSpan, endTurnSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, optional, recordException, startCallTrace, toolArgumentsText, traceLinks, tracePart, turnSpanOptions, urlAttributes, usageAttributes, };