@theoremjs/agents 0.3.0 → 0.3.1

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

@@ -1,16 +1,14 @@
 import type { TraceSink } from '../../../observability/trace-sink.js';
 import { type SpanHandle, type TraceAttributes, type TraceTree } from '../../../observability/trace-span.js';
-import type { ProfileObservabilitySpec, ResolvedObservabilityPolicy } from '../../../observability/types.js';
-import type { SessionQueueItem } from '../../../providers/google/live/stream.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, ProviderCompleteRequest, ResolvedGeneration, SessionRequest, TurnEvent } from '../../types.js';
-import type { MediaTokenFamily } from '../token-estimate.js';
+import type { ModelBinding, ModelRequest, Profile, ResolvedGeneration, SessionRequest, TurnEvent } from '../../types.js';
 type LiveCloser = 'host' | 'provider' | 'theorem';
 interface LiveTraceBinding {
-    request: ProviderCompleteRequest;
+    request: ModelRequest;
     generation: ResolvedGeneration;
     binding: ModelBinding | undefined;
-    family: MediaTokenFamily | undefined;
     /** The system prompt as sent, canary bound. */
     system: string;
     canary: string;
@@ -41,6 +39,8 @@ declare class LiveTrace {
     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;
@@ -54,7 +54,7 @@ declare class LiveTrace {
     private keyFallback;
     setup(frame: Record<string, unknown>): void;
     /** One received queue item, before guardrails. */
-    receive(item: SessionQueueItem): void;
+    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;
@@ -74,7 +74,7 @@ declare class LiveTrace {
      * 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<SessionQueueItem, {
+    socketClosed(code: number, reason: string, initiator: LiveCloser, provider?: Extract<LiveQueueItem, {
         type: 'closed';
     }>): void;
     /**
@@ -108,8 +108,8 @@ declare class LiveTrace {
 }
 /**
  * Open a session's trace: its `invoke_agent` span under the host's `traceparent`,
- * written under `observability`, the session's profile's block.
+ * written under the session's profile's `observability` and cleaned with its detectors.
  */
-declare function startLiveTrace(req: SessionRequest, observability: ProfileObservabilitySpec | undefined, sinkOverride?: TraceSink): LiveTrace;
+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

@@ -3,8 +3,8 @@ 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 { liveFrameInput } from '../../../providers/google/live/framing.js';
-import { LIVE_FALLBACK_ROW } from '../../../providers/google/live/session.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';
@@ -33,7 +33,7 @@ function audioRunParts(run) {
         return [{ type: 'audio', mimeType: run.mimeType, data: bytesToBase64(merged) }];
     }
     catch {
-        // Not base64: keep each chunk as sent, so the record labels what it holds.
+        // 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 }));
     }
 }
@@ -109,7 +109,7 @@ function sessionSignal(event) {
     }
     return undefined;
 }
-// Each record is written as soon as it is complete, so a long session never holds its whole trace.
+// why: Each record is written as soon as it is complete, so a long session never holds its whole trace.
 class LiveTrace {
     tree;
     out;
@@ -132,6 +132,8 @@ class LiveTrace {
     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;
@@ -144,10 +146,16 @@ class LiveTrace {
     }
     /** The adapter's `tapUpstream`: every frame sent, as it is sent. */
     sent = (row) => {
-        if (row.eventType === LIVE_FALLBACK_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;
@@ -156,22 +164,21 @@ class LiveTrace {
             this.root.event('theorem.wire.request', { body: traceJson(body) });
             return;
         }
-        this.pendingInput.add(liveFrameInput(frame));
+        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) {
-        const to = String(row.keySlot);
         this.root.event('theorem.session', {
             kind: 'key_fallback',
             key_slot: String(row.from),
-            to_key_slot: to,
+            to_key_slot: String(row.keySlot),
             'error.type': String(row.errorKind),
             error: String(row.error),
         });
         const bound = this.bound;
-        if (bound)
-            this.bound = { ...bound, request: { ...bound.request, keySlot: to } };
+        if (bound?.binding)
+            this.bound = { ...bound, binding: { ...bound.binding, keySlot: String(row.keySlot) } };
     }
     setup(frame) {
         this.root.event('theorem.upstream.row', { row: traceJson(frame) });
@@ -195,7 +202,7 @@ class LiveTrace {
                 return;
             case 'closed':
                 this.socketClosed(item.code, item.reason, 'provider', item);
-                // A close the provider warned of ends the session; it is not the session's failure.
+                // why: A close the provider warned of ends the session; it is not the session's failure.
                 if (item.goAway)
                     this.endedByGoAway = true;
                 else
@@ -303,7 +310,7 @@ class LiveTrace {
         if (this.response) {
             await this.endResponse(thrown === undefined ? { cancelled: true } : { thrown });
         }
-        // Sent after the last response: no response read it.
+        // 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);
         }
@@ -319,7 +326,7 @@ class LiveTrace {
             endThrownSpan(this.root, thrown);
         }
         else {
-            // A warned close is no verdict: neither failed nor known to be fine.
+            // 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());
@@ -340,7 +347,7 @@ class LiveTrace {
         }
         const kind = event.type === 'evidence' ? event.evidence.kind : undefined;
         if (kind === 'input_transcription' && !(this.response && !this.response.answering)) {
-            // Heard after the model began answering: input for the next response.
+            // why: Heard after the model began answering: input for the next response.
             this.pendingHeard.push(event);
             return;
         }
@@ -352,7 +359,7 @@ class LiveTrace {
         observeCallEvent(response.usage, event);
         response.call.observe(event);
         if (!response.answering && (OUTPUT_EVENTS.has(event.type) || kind === 'output_transcription')) {
-            // The reply's first chunk, from the response's first input frame: what a person waited.
+            // 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,
             });
@@ -361,7 +368,9 @@ class LiveTrace {
         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') {
+        if (event.type === 'done' &&
+            response.stop?.kind !== 'interrupted' &&
+            !(event.stop.kind === 'completed' && response.stop?.kind === 'generation_complete')) {
             response.stop = event.stop;
         }
     }
@@ -374,17 +383,17 @@ class LiveTrace {
             return this.response;
         const bound = this.bound;
         if (!bound) {
-            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            // 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);
-        // A response starts at its first input frame, so its duration includes the model's listening time.
+        // 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,
-                // Each record stands alone (the session record may never be written): it names its agent.
+                // 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,
@@ -399,10 +408,10 @@ class LiveTrace {
             step: this.responses + 1,
         });
         if (!tree) {
-            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             throw new TheoremError('internal', 'Live response span was not opened');
         }
-        // A Live response streams over the session socket; no HTTP try says so.
+        // 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);
@@ -437,12 +446,10 @@ class LiveTrace {
         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, bound.family)
-            : undefined;
+        const tokens = answered ? await callTokensEvent(response.usage, bound.generation) : undefined;
         if (answered)
-            this.held = await heldAfter(response.usage, bound.family);
-        // Beside `output.messages` (what the model produced): what the host received of it.
+            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 }],
         });
@@ -462,7 +469,7 @@ class LiveTrace {
         const record = buildRecord({
             spans,
             policy: this.out.policy,
-            canaries: this.bound ? [this.bound.canary] : [],
+            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));
@@ -470,10 +477,14 @@ class LiveTrace {
 }
 /**
  * Open a session's trace: its `invoke_agent` span under the host's `traceparent`,
- * written under `observability`, the session's profile's block.
+ * written under the session's profile's `observability` and cleaned with its detectors.
  */
-function startLiveTrace(req, observability, sinkOverride) {
-    const { sink, policy } = resolveTraceWriter({ override: sinkOverride, observability });
+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),

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

@@ -1,77 +1,23 @@
 /**
- * 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
+ * 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 Provider } from '../schema.js';
 import type { InteractionPart, TurnHistoryMessage } from '../types.js';
-export declare const TOKEN_TEXT_ENCODING = "o200k_base";
-/** Model families with a verified media rule. */
-export type MediaTokenFamily = 'gemini-3';
-export type MediaPayload = {
-    mimeType: string;
-    data: string;
-} | {
-    mimeType: string;
-    uri: string;
-};
+/** 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;
 }
-/** Loaded estimator. Text counting is synchronous; anything with media is not. */
+/** Text counting is synchronous; anything with media is not. */
 export interface TokenEstimator {
-    /** o200k token count of `text`. */
+    /** Approximate tokens: UTF-16 code units divided by four, rounded up. */
     text: (text: string) => number;
-    /** Token count of one media payload, or `undefined` when unknown. */
-    media: (payload: MediaPayload, family: MediaTokenFamily | undefined) => Promise<number | undefined>;
-    parts: (parts: InteractionPart[], family: MediaTokenFamily | undefined) => Promise<TokenCount>;
+    parts: (parts: InteractionPart[]) => TokenCount;
     /** Content, parts, and tool-call arguments across history messages. */
-    messages: (messages: TurnHistoryMessage[], family: MediaTokenFamily | undefined) => Promise<TokenCount>;
+    messages: (messages: TurnHistoryMessage[]) => TokenCount;
 }
-/**
- * Media family for a model binding — `undefined` when no verified rule covers
- * it. OpenRouter uses the routed model's family (`google/gemini-3…`).
- */
-export declare function mediaTokenFamily(binding: {
-    provider: Provider;
-    apiId: string;
-}): MediaTokenFamily | undefined;
+/** Returns the heuristic estimator; async for compatibility with existing callers. */
 export declare function loadTokenEstimator(): Promise<TokenEstimator>;

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

@@ -1,206 +1,27 @@
 /**
- * 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
+ * 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';
-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) => {
+/** 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;
             }
-            const n = await media(part, family);
-            if (n === undefined)
-                count.unknownMedia += 1;
-            else
-                count.tokens += n;
+            count.unknownMedia += 1;
         }
         return count;
     };
-    const messages = async (list, family) => {
+    const messages = (list) => {
         const count = { tokens: 0, unknownMedia: 0 };
         for (const msg of list) {
-            const fromParts = await parts(historyMessageParts(msg), family);
+            const fromParts = parts(historyMessageParts(msg));
             count.tokens += fromParts.tokens;
             count.unknownMedia += fromParts.unknownMedia;
             for (const tc of msg.tool_calls ?? []) {
@@ -209,10 +30,9 @@ function buildEstimator(encode) {
         }
         return count;
     };
-    return { text, media, parts, messages };
+    return { text, 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);
+/** Returns the heuristic estimator; async for compatibility with existing callers. */
+export function loadTokenEstimator() {
+    return Promise.resolve(buildEstimator());
 }

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

@@ -4,8 +4,8 @@ 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'>;
+/** A check at the tool boundary: the call's arguments, the remote-content gate, its destinations, the result, or the network target. */
+type ToolCheck = Extract<GuardrailCheck, 'tool_arguments' | 'taint' | 'destination' | '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.
@@ -49,7 +49,7 @@ interface ToolCallTrace {
 }
 declare function toolSpanName(name: string): string;
 /**
- * Spans from before `pre_tool` to settlement, so it covers the hooks, the gates and the body.
+ * 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.
  */

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

@@ -5,6 +5,7 @@ import { guardrailAttributes, guardrailCheckAttributes, optional, recordExceptio
 const TOOL_CHECK_STAGE = {
     tool_arguments: 'tool_call',
     taint: 'tool_call',
+    destination: 'tool_call',
     tool_result: 'tool_result',
     tool_failure: 'tool_result',
     network: 'network',
@@ -73,7 +74,7 @@ const OUTCOME_STATUS = {
     cancelled: 'UNSET',
 };
 /**
- * Spans from before `pre_tool` to settlement, so it covers the hooks, the gates and the body.
+ * 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.
  */