@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,115 @@
+import type { TraceSink } from '../../../observability/trace-sink.js';
+import { type SpanHandle, type TraceAttributes, type TraceTree } from '../../../observability/trace-span.js';
+import type { ResolvedObservabilityPolicy } from '../../../observability/types.js';
+import { type LiveQueueItem } from '../../../providers/types.js';
+import type { TurnEventOf } from '../../turn-events.js';
+import type { ModelBinding, ModelRequest, Profile, ResolvedGeneration, SessionRequest, TurnEvent } from '../../types.js';
+type LiveCloser = 'host' | 'provider' | 'theorem';
+interface LiveTraceBinding {
+    request: ModelRequest;
+    generation: ResolvedGeneration;
+    binding: ModelBinding | undefined;
+    /** The system prompt as sent, canary bound. */
+    system: string;
+    canary: string;
+}
+interface LiveTraceEnd {
+    /** Thrown out of the session (an abort is recorded as cancelled). */
+    thrown?: unknown;
+}
+declare class LiveTrace {
+    private readonly tree;
+    private readonly out;
+    private readonly identity;
+    readonly root: SpanHandle;
+    private bound?;
+    private response?;
+    private lastResponse?;
+    private pendingFrames;
+    private pendingInput;
+    private pendingHeard;
+    /** What the provider holds from answered responses, for estimating unreported usage. */
+    private held?;
+    private readonly tokens;
+    private responses;
+    private readonly callParents;
+    private writes;
+    private failure?;
+    /** The provider closed the session after warning it would (`goAway`). */
+    private endedByGoAway;
+    private socketHasClosed;
+    private closing?;
+    /** Canaries bound by the turns this session's agent tools ran: scrubbed from every record after. */
+    readonly agentCanaries: string[];
+    constructor(tree: TraceTree, out: {
+        sink: TraceSink;
+        policy: ResolvedObservabilityPolicy;
+        metadata?: Record<string, unknown>;
+    }, identity: TraceAttributes);
+    /** Attach the resolved request; frames are recorded from here on. */
+    bind(binding: LiveTraceBinding): void;
+    /** The adapter's `tapUpstream`: every frame sent, as it is sent. */
+    readonly sent: (row: Record<string, unknown>) => void;
+    /** The pinned key was refused for quota at setup; the session reopens on the fallback slot, which its responses name. */
+    private keyFallback;
+    setup(frame: Record<string, unknown>): void;
+    /** One received queue item, before guardrails. */
+    receive(item: LiveQueueItem): void;
+    /**
+     * One event as the host received it. Output reaches the host only after
+     * `receive` opened its response, so every output part lands on the open one;
+     * a transcript of the user's speech is input, recorded where it was heard.
+     */
+    delivered(event: TurnEvent): void;
+    /** A guardrail decision on the model's output: on the open response. */
+    outbound(event: TurnEventOf<'guardrail'>): void;
+    /** A guardrail decision on the session (inbound text): on the session span. */
+    inbound(event: TurnEventOf<'guardrail'>): void;
+    /** One run of the gate on the model's output, on the open response: a decision after it is its. */
+    outboundTime(ms: number): void;
+    /** The check on text the host sent into the session, pass or decision, with its time. */
+    inboundCheck(ms: number, event: TurnEventOf<'guardrail'> | undefined): void;
+    /**
+     * Record the socket closing; the first close is the one that ended the
+     * session. A provider close carries its warning (`goAway`) and what the code
+     * means as a failure, so a warned close stays fully diagnosable.
+     */
+    socketClosed(code: number, reason: string, initiator: LiveCloser, provider?: Extract<LiveQueueItem, {
+        type: 'closed';
+    }>): void;
+    /**
+     * Close the response whose `turnComplete` arrived and write its record.
+     * Returns its one `tokens` event, reported or estimated.
+     */
+    settle(): Promise<TurnEvent | undefined>;
+    /** The span a `done` ends: the open response, else the last one. */
+    responseTraceparent(): string | undefined;
+    /**
+     * Open the record for one `executeTool` call, under the response that asked
+     * for it (the session when the call id is unknown). `finish` writes it.
+     */
+    toolRecord(callId: string): {
+        open: (name: string, attributes: TraceAttributes) => SpanHandle;
+        finish: () => void;
+    };
+    /** End the session: close what is open, write the session record, wait for every write. */
+    close(end: LiveTraceEnd): Promise<void>;
+    private finish;
+    private route;
+    private row;
+    private open;
+    /**
+     * Close the open response and write its record. A response ended by the
+     * session closing has no usage event: what was billed is unknown.
+     */
+    private endResponse;
+    /** Build and write one record, after every earlier write. */
+    private write;
+}
+/**
+ * Open a session's trace: its `invoke_agent` span under the host's `traceparent`,
+ * written under the session's profile's `observability` and cleaned with its detectors.
+ */
+declare function startLiveTrace(req: SessionRequest, profile: Pick<Profile, 'observability' | 'guardrails'> | undefined, sinkOverride?: TraceSink): LiveTrace;
+export type { LiveCloser, LiveTrace, LiveTraceBinding, LiveTraceEnd };
+export { startLiveTrace };

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

@@ -0,0 +1,500 @@
+import { errorKind, isAbortError, TheoremError } from '../../../guardrails/error.js';
+import { resolveTraceWriter } from '../../../observability/policy.js';
+import { writeTrace } from '../../../observability/trace.js';
+import { buildRecord } from '../../../observability/trace-record.js';
+import { startTrace, traceJson, } from '../../../observability/trace-span.js';
+import { liveSentInput } from '../../../providers/live.js';
+import { KEY_FALLBACK_ROW } from '../../../providers/types.js';
+import { base64ToBytes, bytesToBase64 } from '../../util/base64.js';
+import { asRecord } from '../record.js';
+import { callTokensEvent, heldAfter, observeCallEvent, startCallUsage, } from '../runner/usage.js';
+import { endThrownSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, optional, startCallTrace, traceLinks, usageAttributes, } from '../turn-trace.js';
+import { sumTokens } from '../usage.js';
+/** Events that are the model's output: they mark a response as answering. */
+const OUTPUT_EVENTS = new Set(['text', 'thought', 'media', 'tool']);
+const MS_PER_S = 1000;
+/** One user message holding exactly one inline audio part: a realtime audio chunk. */
+function audioChunk(msg) {
+    const [part, ...rest] = msg.parts ?? [];
+    if (msg.role !== 'user' || msg.content || rest.length > 0)
+        return undefined;
+    return part?.type === 'audio' && 'data' in part ? part : undefined;
+}
+/** A run's chunks as one part over their concatenated bytes; one part each when any is not base64. */
+function audioRunParts(run) {
+    try {
+        const decoded = run.chunks.map(base64ToBytes);
+        const merged = new Uint8Array(decoded.reduce((size, bytes) => size + bytes.byteLength, 0));
+        let offset = 0;
+        for (const bytes of decoded) {
+            merged.set(bytes, offset);
+            offset += bytes.byteLength;
+        }
+        return [{ type: 'audio', mimeType: run.mimeType, data: bytesToBase64(merged) }];
+    }
+    catch {
+        // why: Not base64: keep each chunk as sent, so the record labels what it holds.
+        return run.chunks.map((data) => ({ type: 'audio', mimeType: run.mimeType, data }));
+    }
+}
+/**
+ * Input sent since the previous response opened; a tool response is input to the response after the
+ * one that asked. Never the whole session: under sliding-window compression what the model read of
+ * it is unknowable. Contiguous audio of one format is one message.
+ */
+class LiveInput {
+    items = [];
+    run;
+    add(messages) {
+        for (const msg of messages) {
+            const chunk = audioChunk(msg);
+            if (chunk && this.run?.mimeType === chunk.mimeType) {
+                this.run.chunks.push(chunk.data);
+                continue;
+            }
+            this.run = chunk ? { mimeType: chunk.mimeType, chunks: [chunk.data] } : undefined;
+            this.items.push(this.run ?? msg);
+        }
+    }
+    messages() {
+        return this.items.map((item) => 'chunks' in item ? { role: 'user', parts: audioRunParts(item) } : item);
+    }
+}
+/** A frame without its resumption handle: the handle is a credential. */
+function withoutHandle(frame) {
+    const setup = asRecord(frame.setup);
+    const resumption = asRecord(setup?.sessionResumption);
+    if (setup && resumption && 'handle' in resumption) {
+        const { handle: _handle, ...rest } = resumption;
+        return { ...frame, setup: { ...setup, sessionResumption: rest } };
+    }
+    const update = asRecord(frame.sessionResumptionUpdate);
+    if (update && 'newHandle' in update) {
+        const { newHandle: _newHandle, ...rest } = update;
+        return { ...frame, sessionResumptionUpdate: rest };
+    }
+    return frame;
+}
+function stringAttribute(key, value) {
+    return typeof value === 'string' ? { [key]: value } : {};
+}
+/** A provider session signal as `theorem.session` attributes, or `undefined` for a response event. */
+function sessionSignal(event) {
+    if (event.type === 'session') {
+        const { session } = event;
+        if (session.kind === 'turn_complete')
+            return undefined;
+        return {
+            kind: session.kind,
+            ...('timeLeftMs' in session ? optional('time_left_ms', session.timeLeftMs) : {}),
+        };
+    }
+    if (event.type !== 'evidence')
+        return undefined;
+    const { evidence } = event;
+    if (evidence.kind === 'voice_activity') {
+        const raw = asRecord(evidence.raw);
+        return {
+            kind: 'voice_activity',
+            ...stringAttribute('activity', raw?.type),
+            ...stringAttribute('audio_offset', raw?.audioOffset),
+        };
+    }
+    if (evidence.kind === 'session_resumption') {
+        return {
+            kind: 'session_resumption',
+            ...optional('resumable', evidence.resumable),
+            handle_issued: Boolean(event.sessionResumptionHandle),
+        };
+    }
+    return undefined;
+}
+// why: Each record is written as soon as it is complete, so a long session never holds its whole trace.
+class LiveTrace {
+    tree;
+    out;
+    identity;
+    root;
+    bound;
+    response;
+    lastResponse;
+    pendingFrames = [];
+    pendingInput = new LiveInput();
+    pendingHeard = [];
+    /** What the provider holds from answered responses, for estimating unreported usage. */
+    held;
+    tokens = [];
+    responses = 0;
+    callParents = new Map();
+    writes = Promise.resolve();
+    failure;
+    /** The provider closed the session after warning it would (`goAway`). */
+    endedByGoAway = false;
+    socketHasClosed = false;
+    closing;
+    /** Canaries bound by the turns this session's agent tools ran: scrubbed from every record after. */
+    agentCanaries = [];
+    constructor(tree, out, identity) {
+        this.tree = tree;
+        this.out = out;
+        this.identity = identity;
+        this.root = tree.root;
+    }
+    /** Attach the resolved request; frames are recorded from here on. */
+    bind(binding) {
+        this.bound = binding;
+    }
+    /** The adapter's `tapUpstream`: every frame sent, as it is sent. */
+    sent = (row) => {
+        if (row.eventType === KEY_FALLBACK_ROW) {
+            this.keyFallback(row);
+            return;
+        }
+        if (row.direction === 'receive') {
+            const body = asRecord(row.body);
+            if (body)
+                this.row(body);
+            return;
+        }
+        const frame = asRecord(row.body);
+        if (!frame)
+            return;
+        const body = withoutHandle(frame);
+        if ('setup' in frame) {
+            this.root.event('theorem.wire.request', { body: traceJson(body) });
+            return;
+        }
+        this.pendingInput.add(liveSentInput(row));
+        this.pendingFrames.push({ timeUnixNano: this.root.nowUnixNano(), body });
+    };
+    /** The pinned key was refused for quota at setup; the session reopens on the fallback slot, which its responses name. */
+    keyFallback(row) {
+        this.root.event('theorem.session', {
+            kind: 'key_fallback',
+            key_slot: String(row.from),
+            to_key_slot: String(row.keySlot),
+            'error.type': String(row.errorKind),
+            error: String(row.error),
+        });
+        const bound = this.bound;
+        if (bound?.binding)
+            this.bound = { ...bound, binding: { ...bound.binding, keySlot: String(row.keySlot) } };
+    }
+    setup(frame) {
+        this.root.event('theorem.upstream.row', { row: traceJson(frame) });
+        this.root.event('theorem.session', { kind: 'setup_complete' });
+    }
+    /** One received queue item, before guardrails. */
+    receive(item) {
+        switch (item.type) {
+            case 'batch':
+                for (const event of item.events)
+                    this.route(event);
+                this.row(item.row);
+                return;
+            case 'row':
+                this.row(item.row);
+                return;
+            case 'error':
+                if (item.row)
+                    this.row(item.row);
+                this.failure ??= item.error;
+                return;
+            case 'closed':
+                this.socketClosed(item.code, item.reason, 'provider', item);
+                // why: A close the provider warned of ends the session; it is not the session's failure.
+                if (item.goAway)
+                    this.endedByGoAway = true;
+                else
+                    this.failure ??= item.error;
+                return;
+        }
+    }
+    /**
+     * One event as the host received it. Output reaches the host only after
+     * `receive` opened its response, so every output part lands on the open one;
+     * a transcript of the user's speech is input, recorded where it was heard.
+     */
+    delivered(event) {
+        if (event.type === 'evidence' && event.evidence.kind === 'input_transcription')
+            return;
+        this.response?.delivered.add(event, this.root.nowUnixNano());
+    }
+    /** A guardrail decision on the model's output: on the open response. */
+    outbound(event) {
+        if (this.response)
+            this.response.call.guardrail(event.guardrail);
+        else
+            this.inbound(event);
+    }
+    /** A guardrail decision on the session (inbound text): on the session span. */
+    inbound(event) {
+        this.root.event('theorem.guardrail', guardrailAttributes(event.guardrail));
+    }
+    /** One run of the gate on the model's output, on the open response: a decision after it is its. */
+    outboundTime(ms) {
+        this.response?.call.guardTime('live_output', ms);
+    }
+    /** The check on text the host sent into the session, pass or decision, with its time. */
+    inboundCheck(ms, event) {
+        this.root.event('theorem.guardrail', guardrailCheckAttributes('live_input', ms, event?.guardrail, {
+            stage: 'live_inbound',
+            trust: 'untrusted',
+        }));
+    }
+    /**
+     * Record the socket closing; the first close is the one that ended the
+     * session. A provider close carries its warning (`goAway`) and what the code
+     * means as a failure, so a warned close stays fully diagnosable.
+     */
+    socketClosed(code, reason, initiator, provider) {
+        if (this.socketHasClosed)
+            return;
+        this.socketHasClosed = true;
+        const goAway = provider?.goAway;
+        this.root.event('theorem.session', {
+            kind: 'closed',
+            code,
+            reason,
+            initiator,
+            ...(provider?.error ? { 'error.type': errorKind(provider.error) } : {}),
+            ...(goAway
+                ? {
+                    cause: 'go_away',
+                    ...optional('time_left_ms', goAway.timeLeftMs),
+                    closed_after_ms: goAway.closedAfterMs,
+                }
+                : {}),
+        });
+    }
+    /**
+     * Close the response whose `turnComplete` arrived and write its record.
+     * Returns its one `tokens` event, reported or estimated.
+     */
+    async settle() {
+        return this.response?.complete ? await this.endResponse({}) : undefined;
+    }
+    /** The span a `done` ends: the open response, else the last one. */
+    responseTraceparent() {
+        return (this.response?.call.span ?? this.lastResponse)?.traceparent();
+    }
+    /**
+     * Open the record for one `executeTool` call, under the response that asked
+     * for it (the session when the call id is unknown). `finish` writes it.
+     */
+    toolRecord(callId) {
+        let tree;
+        return {
+            open: (name, attributes) => {
+                tree = startTrace(name, {
+                    attributes: { ...this.identity, ...attributes },
+                    traceparent: this.callParents.get(callId) ?? this.root.traceparent(),
+                    clock: this.tree.clock,
+                });
+                return tree.root;
+            },
+            finish: () => {
+                if (tree)
+                    this.write(tree.collect());
+            },
+        };
+    }
+    /** End the session: close what is open, write the session record, wait for every write. */
+    close(end) {
+        this.closing ??= this.finish(end);
+        return this.closing;
+    }
+    async finish(end) {
+        const aborted = end.thrown !== undefined && isAbortError(end.thrown);
+        const thrown = aborted ? undefined : (end.thrown ?? this.failure);
+        if (this.response) {
+            await this.endResponse(thrown === undefined ? { cancelled: true } : { thrown });
+        }
+        // why: Sent after the last response: no response read it.
+        for (const frame of this.pendingFrames) {
+            this.root.event('theorem.wire.request', { body: traceJson(frame.body) }, frame.timeUnixNano);
+        }
+        this.pendingFrames = [];
+        const tokens = sumTokens(this.tokens);
+        this.root.set({
+            ...(tokens ? usageAttributes(tokens) : {}),
+            'theorem.steps': this.responses,
+            ...(aborted ? { 'theorem.stop.kind': 'cancelled' } : {}),
+            ...(!aborted && this.endedByGoAway ? { 'theorem.stop.kind': 'go_away' } : {}),
+        });
+        if (thrown !== undefined) {
+            endThrownSpan(this.root, thrown);
+        }
+        else {
+            // why: A warned close is no verdict: neither failed nor known to be fine.
+            this.root.end(aborted || this.endedByGoAway ? { code: 'UNSET' } : { code: 'OK' });
+        }
+        this.write(this.tree.collect());
+        await this.writes;
+    }
+    route(event) {
+        const signal = sessionSignal(event);
+        if (signal) {
+            this.root.event('theorem.session', signal);
+            return;
+        }
+        if (event.type === 'tool' && event.tool.phase === 'cancel') {
+            (this.response?.call.span ?? this.root).event('theorem.tool.cancel', {
+                'gen_ai.tool.call.id': event.tool.callId,
+                'gen_ai.tool.name': event.tool.name,
+            });
+            return;
+        }
+        const kind = event.type === 'evidence' ? event.evidence.kind : undefined;
+        if (kind === 'input_transcription' && !(this.response && !this.response.answering)) {
+            // why: Heard after the model began answering: input for the next response.
+            this.pendingHeard.push(event);
+            return;
+        }
+        const response = this.open();
+        if (event.type === 'session') {
+            response.complete = true;
+            return;
+        }
+        observeCallEvent(response.usage, event);
+        response.call.observe(event);
+        if (!response.answering && (OUTPUT_EVENTS.has(event.type) || kind === 'output_transcription')) {
+            // why: The reply's first chunk, from the response's first input frame: what a person waited.
+            response.call.span.set({
+                'gen_ai.response.time_to_first_chunk': response.call.span.msSinceStart() / MS_PER_S,
+            });
+            response.answering = true;
+        }
+        if (event.type === 'tool' && event.tool.phase === undefined) {
+            this.callParents.set(event.tool.callId, response.call.span.traceparent());
+        }
+        if (event.type === 'done' &&
+            response.stop?.kind !== 'interrupted' &&
+            !(event.stop.kind === 'completed' && response.stop?.kind === 'generation_complete')) {
+            response.stop = event.stop;
+        }
+    }
+    row(row) {
+        const span = this.response?.call.span ?? this.root;
+        span.event('theorem.upstream.row', { row: traceJson(withoutHandle(row)) });
+    }
+    open() {
+        if (this.response)
+            return this.response;
+        const bound = this.bound;
+        if (!bound) {
+            // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            throw new TheoremError('internal', 'Live trace received a response before it was bound');
+        }
+        const usage = startCallUsage(bound.system, { history: [], input: [] }, this.held);
+        // why: A response starts at its first input frame, so its duration includes the model's listening time.
+        const startTimeUnixNano = this.pendingFrames[0]?.timeUnixNano;
+        let tree;
+        const call = startCallTrace((name, options) => {
+            tree = startTrace(name, {
+                ...options,
+                // why: Each record stands alone (the session record may never be written): it names its agent.
+                attributes: { ...this.identity, ...options.attributes },
+                traceparent: this.root.traceparent(),
+                clock: this.tree.clock,
+                ...(startTimeUnixNano ? { startTimeUnixNano } : {}),
+            });
+            return tree.root;
+        }, {
+            req: bound.request,
+            usage,
+            binding: bound.binding,
+            transport: bound.generation.transport,
+            step: this.responses + 1,
+        });
+        if (!tree) {
+            // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            throw new TheoremError('internal', 'Live response span was not opened');
+        }
+        // why: A Live response streams over the session socket; no HTTP try says so.
+        call.span.set({ 'gen_ai.request.stream': true });
+        for (const frame of this.pendingFrames) {
+            call.span.event('theorem.wire.request', { body: traceJson(frame.body) }, frame.timeUnixNano);
+        }
+        const response = {
+            tree,
+            call,
+            usage,
+            input: this.pendingInput,
+            delivered: new OutputFold(),
+            answering: false,
+            complete: false,
+        };
+        for (const heard of this.pendingHeard)
+            call.observe(heard);
+        this.pendingFrames = [];
+        this.pendingInput = new LiveInput();
+        this.pendingHeard = [];
+        this.response = response;
+        return response;
+    }
+    /**
+     * Close the open response and write its record. A response ended by the
+     * session closing has no usage event: what was billed is unknown.
+     */
+    async endResponse(end) {
+        const response = this.response;
+        const bound = this.bound;
+        if (!(response && bound))
+            return undefined;
+        this.response = undefined;
+        this.responses += 1;
+        response.usage.conversation = { history: response.input.messages(), input: [] };
+        const answered = end.thrown === undefined && !end.cancelled;
+        const tokens = answered ? await callTokensEvent(response.usage, bound.generation) : undefined;
+        if (answered)
+            this.held = await heldAfter(response.usage);
+        // why: Beside `output.messages` (what the model produced): what the host received of it.
+        response.call.span.set({
+            'theorem.output.delivered': [{ role: 'assistant', parts: response.delivered.parts }],
+        });
+        response.call.end({
+            ...(tokens?.tokens ? { tokens: tokens.tokens } : {}),
+            stop: end.cancelled ? { kind: 'cancelled' } : response.stop,
+            ...(end.thrown === undefined ? {} : { thrown: end.thrown }),
+        });
+        if (tokens?.tokens)
+            this.tokens.push(tokens.tokens);
+        this.lastResponse = response.call.span;
+        this.write(response.tree.collect());
+        return tokens;
+    }
+    /** Build and write one record, after every earlier write. */
+    write(spans) {
+        const record = buildRecord({
+            spans,
+            policy: this.out.policy,
+            canaries: [...(this.bound ? [this.bound.canary] : []), ...this.agentCanaries],
+            ...(this.out.metadata ? { metadata: this.out.metadata } : {}),
+        });
+        this.writes = this.writes.then(() => writeTrace(this.out.sink, record, this.out.policy));
+    }
+}
+/**
+ * Open a session's trace: its `invoke_agent` span under the host's `traceparent`,
+ * written under the session's profile's `observability` and cleaned with its detectors.
+ */
+function startLiveTrace(req, profile, sinkOverride) {
+    const { sink, policy } = resolveTraceWriter({
+        override: sinkOverride,
+        observability: profile?.observability,
+        guardrails: profile?.guardrails,
+    });
+    const identity = {
+        'gen_ai.agent.name': req.profile,
+        ...optional('gen_ai.conversation.id', req.conversationId),
+    };
+    const tree = startTrace(`invoke_agent ${req.profile}`, {
+        kind: 'INTERNAL',
+        attributes: { 'gen_ai.operation.name': 'invoke_agent', ...identity },
+        links: traceLinks(req.links),
+        ...(req.traceparent ? { traceparent: req.traceparent } : {}),
+    });
+    return new LiveTrace(tree, { sink, policy, ...(req.metadata ? { metadata: req.metadata } : {}) }, identity);
+}
+export { startLiveTrace };

package/esm/src/kernel/engine/token-estimate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Text counts use a characters / 4 heuristic for all model families. Media is never estimated: a
+ * media part is reported as `unknownMedia`, and the upstream's own count is used when it gives one.
+ */
+import type { InteractionPart, TurnHistoryMessage } from '../types.js';
+/** Text estimation method; retained under this name for API compatibility. */
+export declare const TOKEN_TEXT_ENCODING = "chars/4";
+/** A token count and the number of media parts left out of it. */
+export interface TokenCount {
+    tokens: number;
+    /** Media parts left out of `tokens` because their count is unknown. */
+    unknownMedia: number;
+}
+/** Text counting is synchronous; anything with media is not. */
+export interface TokenEstimator {
+    /** Approximate tokens: UTF-16 code units divided by four, rounded up. */
+    text: (text: string) => number;
+    parts: (parts: InteractionPart[]) => TokenCount;
+    /** Content, parts, and tool-call arguments across history messages. */
+    messages: (messages: TurnHistoryMessage[]) => TokenCount;
+}
+/** Returns the heuristic estimator; async for compatibility with existing callers. */
+export declare function loadTokenEstimator(): Promise<TokenEstimator>;

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

@@ -0,0 +1,38 @@
+/**
+ * Text counts use a characters / 4 heuristic for all model families. Media is never estimated: a
+ * media part is reported as `unknownMedia`, and the upstream's own count is used when it gives one.
+ */
+import { historyMessageParts } from '../interaction-parts.js';
+/** Text estimation method; retained under this name for API compatibility. */
+export const TOKEN_TEXT_ENCODING = 'chars/4';
+function buildEstimator() {
+    const text = (value) => Math.ceil(value.length / 4);
+    const parts = (list) => {
+        const count = { tokens: 0, unknownMedia: 0 };
+        for (const part of list) {
+            if (part.type === 'text') {
+                count.tokens += text(part.text);
+                continue;
+            }
+            count.unknownMedia += 1;
+        }
+        return count;
+    };
+    const messages = (list) => {
+        const count = { tokens: 0, unknownMedia: 0 };
+        for (const msg of list) {
+            const fromParts = parts(historyMessageParts(msg));
+            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, parts, messages };
+}
+/** Returns the heuristic estimator; async for compatibility with existing callers. */
+export function loadTokenEstimator() {
+    return Promise.resolve(buildEstimator());
+}