@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/observability/trace-span.js

@@ -1,4 +1,4 @@
-// Content is held in memory as markers the record builder resolves: `$content` is scrubbed, hashed
+// invariant: Content is held in memory as markers the record builder resolves: `$content` is scrubbed, hashed
 // and moved into `TraceRecord.content`; `$bytes` is hashed and never stored; `$json` has media
 // hashed and strings equal to recorded content replaced by their hash.
 import { TheoremError } from '../guardrails/error.js';
@@ -57,9 +57,11 @@ function parseTraceparent(value) {
 function formatTraceparent(traceId, spanId) {
     return `00-${traceId}-${spanId}-${SAMPLED_FLAGS}`;
 }
+/** Marks text as message content, which the trace stores by hash. */
 function traceContent(text) {
     return { $content: text };
 }
+/** Marks base64 data as bytes, which the trace stores by hash. */
 function traceBytes(base64) {
     return { $bytes: base64 };
 }

package/esm/src/observability/trace.d.ts

@@ -6,6 +6,8 @@ import type { ResolvedObservabilityPolicy } from './types.js';
 declare function writeTrace(sink: TraceSink, record: Promise<TraceRecord>, policy: ResolvedObservabilityPolicy): Promise<void>;
 /** Like `writeTrace`, it never fails the caller. */
 declare function writeSpans(sink: TraceSink, spans: TraceSpan[], policy: ResolvedObservabilityPolicy, metadata?: Record<string, unknown>): Promise<void>;
+/** A sink that discards every record. */
 declare function noopSink(): TraceSink;
+/** A sink that appends each trace record to the given array. */
 declare function memorySink(into: TraceRecord[]): TraceSink;
 export { memorySink, noopSink, writeSpans, writeTrace };

package/esm/src/observability/trace.js

@@ -1,4 +1,4 @@
-// Tracing is host-injected: THEOREM reads no environment variables and owns no database sink.
+// invariant: Tracing is host-injected: THEOREM reads no environment variables and owns no database sink.
 import { buildRecord } from './trace-record.js';
 /** Trace failures never fail the turn: build and write errors go to `sink.onError`, if set. */
 async function writeTrace(sink, record, policy) {
@@ -13,7 +13,7 @@ async function writeTrace(sink, record, policy) {
             sink.onError?.(err);
         }
         catch {
-            // Host onError must not fail the turn.
+            // why: Host onError must not fail the turn.
         }
     }
 }
@@ -21,9 +21,11 @@ async function writeTrace(sink, record, policy) {
 function writeSpans(sink, spans, policy, metadata) {
     return writeTrace(sink, buildRecord({ spans, policy, ...(metadata ? { metadata } : {}) }), policy);
 }
+/** A sink that discards every record. */
 function noopSink() {
     return { write: () => Promise.resolve() };
 }
+/** A sink that appends each trace record to the given array. */
 function memorySink(into) {
     return {
         write: (record) => {

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

@@ -1,3 +1,4 @@
+import type { ResolvedDetect } from '../guardrails/detectors.js';
 import type { TraceSink } from './trace-sink.js';
 import type { TraceAttributes } from './trace-span.js';
 /** Which payloads land in each TraceRecord. Omitted keys use resolved defaults. */
@@ -18,14 +19,27 @@ export interface TraceIncludeSpec {
      */
     guardrailMatchPreview?: boolean;
 }
-/** Scrubbing of stored records, independent of turn-path `profile.guardrails`. Defaults are on. */
+/**
+ * Whether a stored trace is cleaned, and whose patterns clean it. `true` cleans with what each
+ * detector reads the turn with; `false` with nothing. The object names the sides, whatever the
+ * turn reads with: Theorem's patterns, the host's (`guardrails.detect` patterns and detectors),
+ * each on when left out.
+ */
+export type ScrubSwitch = boolean | {
+    theorem?: boolean;
+    host?: boolean;
+};
+/**
+ * Scrubbing of stored records. It reads the detectors `guardrails.detect` declares and ignores
+ * their actions: a detector set to `ignore` in the turn still cleans the trace. Defaults are on.
+ */
 export interface TraceScrubSpec {
-    /** Strip credentials / PII spans in stored text. Default: true. */
-    sensitive?: boolean;
-    /** Strip injection spans in the stored request copy. Default: true. */
-    injection?: boolean;
-    /** Never persist the canary token. Default: true. */
-    canary?: boolean;
+    /** The data detectors (`ids`, `financial`, `network`, `credentials`) and the host's own. Default: true. */
+    sensitive?: ScrubSwitch;
+    /** `injection` and `tool_instructions`. Default: true. */
+    injection?: ScrubSwitch;
+    /** Never persist the canary token. It is Theorem's alone, so the host side adds nothing. Default: true. */
+    canary?: ScrubSwitch;
 }
 /** Omit the whole block for no tracing. */
 export interface ProfileObservabilitySpec {
@@ -42,7 +56,7 @@ export interface ProfileObservabilitySpec {
     include?: TraceIncludeSpec;
     /** Stamped on every record as `TraceRecord.resource`, e.g. `{ 'service.name': 'harbor' }`. */
     resource?: TraceAttributes;
-    /** Defaults stay on even when `guardrails.redactSensitive` is false. */
+    /** Defaults stay on even when `guardrails.detect` is `ignore`. */
     scrub?: TraceScrubSpec;
     /**
      * Days to keep each record, handed to every destination with the record
@@ -58,6 +72,7 @@ export interface ProfileObservabilitySpec {
     /** Called when record build or destination write fails. Must not throw. */
     onWriteError?: (err: unknown) => void;
 }
+/** Which optional content a trace record includes, each on or off. */
 export interface ResolvedTraceInclude {
     upstreamLog: boolean;
     outboundWire: boolean;
@@ -66,11 +81,18 @@ export interface ResolvedTraceInclude {
     guardrailDecisions: boolean;
     guardrailMatchPreview: boolean;
 }
+/** A `ScrubSwitch` with its sides filled in; one with both sides off is `false`. */
+export type ResolvedScrubSwitch = boolean | {
+    theorem: boolean;
+    host: boolean;
+};
+/** What is scrubbed from the text a trace stores: sensitive values, injection, and the canary. */
 export interface ResolvedTraceScrub {
-    sensitive: boolean;
-    injection: boolean;
-    canary: boolean;
+    sensitive: ResolvedScrubSwitch;
+    injection: ResolvedScrubSwitch;
+    canary: ResolvedScrubSwitch;
 }
+/** A profile's observability settings after defaults: whether and where to record, the sample rate, what to include and scrub, and retention and rotation. */
 export interface ResolvedObservabilityPolicy {
     /** False when the block is omitted or `writeTo` is `false`/absent. Sampling applies at write. */
     record: boolean;
@@ -78,6 +100,8 @@ export interface ResolvedObservabilityPolicy {
     sampleRate: number;
     include: ResolvedTraceInclude;
     scrub: ResolvedTraceScrub;
+    /** The profile's detectors, whose patterns clean the record. Absent, Theorem's patterns alone. */
+    detect?: ResolvedDetect;
     resource: TraceAttributes;
     retainForDays: number;
     rotateAfterMiB: number;

package/esm/src/observability/types.js

@@ -1,3 +1,3 @@
-// Must not import from src/kernel/: the kernel type-imports ProfileObservabilitySpec, and that
+// invariant: Must not import from src/kernel/: the kernel type-imports ProfileObservabilitySpec, and that
 // edge stays one-directional.
 export {};

package/esm/src/presets/google/speech-voices.d.ts

@@ -5,4 +5,5 @@
  */
 import "../../../_dnt.polyfills.js";
 export declare const GOOGLE_SPEECH_VOICES: readonly ["Zephyr", "Puck", "Charon", "Kore", "Fenrir", "Leda", "Orus", "Aoede", "Callirrhoe", "Autonoe", "Enceladus", "Iapetus", "Umbriel", "Algieba", "Despina", "Erinome", "Algenib", "Rasalgethi", "Laomedeia", "Achernar", "Alnilam", "Schedar", "Gacrux", "Pulcherrima", "Achird", "Zubenelgenubi", "Vindemiatrix", "Sadachbia", "Sadaltager", "Sulafat"];
+/** The name of a Gemini speech voice. */
 export type GoogleSpeechVoice = (typeof GOOGLE_SPEECH_VOICES)[number];

package/esm/src/presets/google-limits.d.ts

@@ -2,6 +2,7 @@
 declare const GOOGLE_THINKING_LEVELS: readonly ["minimal", "low", "medium", "high"];
 /** The audio format Gemini speech returns (PCM, wrapped as WAV); OpenRouter speech also takes `mp3`. */
 declare const GOOGLE_SPEECH_FORMATS: readonly ["pcm"];
+/** A thinking level Gemini takes: minimal, low, medium, or high. */
 type GoogleThinkingLevel = (typeof GOOGLE_THINKING_LEVELS)[number];
 /**
  * A `geminiInteractions` or `geminiLive` binding's `efforts`, typed to the levels Gemini takes.

package/esm/src/presets/google.d.ts

@@ -7,7 +7,9 @@ import "../../_dnt.polyfills.js";
 import type { ModelBinding, ProfileImageSpec, ProfileLiveSpec, ProfileSpeechSpec } from '../kernel/types.js';
 import { GOOGLE_SPEECH_VOICES, type GoogleSpeechVoice } from './google/speech-voices.js';
 import { GOOGLE_SPEECH_FORMATS, GOOGLE_THINKING_LEVELS, type GoogleThinkingLevel, googleEfforts } from './google-limits.js';
+/** The image MIME types a Gemini profile can take as input. */
 declare const GOOGLE_IMAGE_INPUT_MIMES: readonly ["image/png", "image/jpeg", "image/webp", "image/heic", "image/heif"];
+/** The audio MIME types a Gemini profile can take as voice input. */
 declare const GOOGLE_VOICE_INPUT_MIMES: readonly ["audio/webm", "audio/wav", "audio/mpeg", "audio/mp4"];
 /**
  * TTS models that reject any history with a model turn, so compaction's summary fails them
@@ -18,7 +20,13 @@ declare const GOOGLE_SINGLE_TURN_API_IDS: readonly ["gemini-2.5-flash-preview-tt
  * Models that reject any thinking setting, `summaries: false` included: leave
  * `efforts` and `summaries` unset (live, 30/09/2026).
  */
-declare const GOOGLE_NO_THINKING_API_IDS: readonly ["gemini-2.5-flash-image", "antigravity-preview-05-2026", "antigravity-preview-09-2026", "antigravity-preview-latest", "gemini-3.8-live"];
+declare const GOOGLE_NO_THINKING_API_IDS: readonly ["gemini-2.5-flash-image", "antigravity-preview-05-2026", "antigravity-preview-09-2026", "antigravity-preview-latest"];
+/**
+ * Models that refuse a thinking level and take `summaries`: leave `efforts` unset
+ * (live, 01/10/2026: Live closes 1007 "Thinking level is not supported for this model";
+ * 04/10/2026: setup takes `includeThoughts` either way).
+ */
+declare const GOOGLE_NO_EFFORT_API_IDS: readonly ["gemini-3.8-live"];
 /**
  * Models that refuse a session without a thinking level: pin `efforts`
  * (live, 01/10/2026: Live closes 1007 "Thinking level must be specified for this model").
@@ -31,12 +39,15 @@ interface GoogleFreeTierGrounding {
 }
 /**
  * Models with a non-zero free-tier quota, and the grounding each allows (AI Studio, Sep 2026).
+ * No model keeps free Maps quota: 3.5 Flash-Lite turns with Maps are refused as over quota
+ * (live, 13/10/2026).
  * A builtin with no quota is refused as if over quota: on Live, a close 1011 "You exceeded your
  * current quota" at setup, whatever the key's usage (live, 01/10/2026).
  */
 declare const GOOGLE_FREE_TIER_GROUNDING: Readonly<Record<string, GoogleFreeTierGrounding>>;
 /** Grounding builtins the free tier allows on `apiId`; none for a model with no free quota. */
 declare function googleFreeTierBuiltins(apiId: string): Array<'googleSearch' | 'googleMaps'>;
+/** A Gemini binding field that breaks a Gemini rule, and what is wrong with it. */
 interface GoogleBindingViolation {
     field: 'apiId' | 'efforts' | 'summaries' | 'builtInTools';
     message: string;
@@ -49,26 +60,37 @@ interface GoogleBindingViolation {
 declare function googleBindingViolation(binding: Pick<ModelBinding, 'apiId' | 'efforts' | 'summaries' | 'builtInTools'>, options?: {
     freeTier?: boolean;
 }): GoogleBindingViolation | undefined;
+/** The speech settings a Gemini profile may pin, with the voice narrowed to Gemini's. */
 type GoogleSpeechPins = Omit<ProfileSpeechSpec, 'voice'> & {
     voice?: GoogleSpeechVoice;
 };
+/** The live settings a Gemini profile may pin, with the voice narrowed to Gemini's. */
 type GoogleLivePins = Omit<ProfileLiveSpec, 'voice'> & {
     voice?: GoogleSpeechVoice;
 };
+/** The aspect ratios a Gemini image model can return. */
 declare const GOOGLE_IMAGE_ASPECT_RATIOS: readonly ["1:1", "3:2", "2:3", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"];
+/** The resolutions a Gemini image model can return. */
 declare const GOOGLE_IMAGE_RESOLUTIONS: readonly ["1K", "2K", "4K"];
 /** What a Gemini image model can be asked to return. */
 declare const GOOGLE_IMAGE_OUTPUT_MIMES: readonly ["image/png", "image/jpeg"];
+/** One of {@linkcode GOOGLE_IMAGE_INPUT_MIMES}. */
 type GoogleImageInputMime = (typeof GOOGLE_IMAGE_INPUT_MIMES)[number];
+/** One of {@linkcode GOOGLE_VOICE_INPUT_MIMES}. */
 type GoogleVoiceInputMime = (typeof GOOGLE_VOICE_INPUT_MIMES)[number];
+/** One of {@linkcode GOOGLE_IMAGE_ASPECT_RATIOS}. */
 type GoogleImageAspectRatio = (typeof GOOGLE_IMAGE_ASPECT_RATIOS)[number];
+/** One of {@linkcode GOOGLE_IMAGE_RESOLUTIONS}. */
 type GoogleImageResolution = (typeof GOOGLE_IMAGE_RESOLUTIONS)[number];
+/** One of {@linkcode GOOGLE_IMAGE_OUTPUT_MIMES}. */
 type GoogleImageOutputMime = (typeof GOOGLE_IMAGE_OUTPUT_MIMES)[number];
+/** The image settings a Gemini profile may pin, narrowed to what Gemini accepts. */
 type GoogleImagePins = Omit<ProfileImageSpec, 'aspectRatio' | 'resolution' | 'mimeType'> & {
     aspectRatio?: GoogleImageAspectRatio;
     resolution?: GoogleImageResolution;
     mimeType?: GoogleImageOutputMime;
 };
+/** The tools Gemini runs itself, as `builtin` tool definitions. */
 declare const GOOGLE_BUILTIN_TOOLS: ({
     type: "builtin";
     name: string;
@@ -78,11 +100,7 @@ declare const GOOGLE_BUILTIN_TOOLS: ({
     paths: string[];
     loadTier: "T0";
     permission: "auto";
-    wire: {
-        interactions: string;
-        openRouter: string;
-        live: string;
-    };
+    conflictsWith?: undefined;
 } | {
     type: "builtin";
     name: string;
@@ -92,13 +110,10 @@ declare const GOOGLE_BUILTIN_TOOLS: ({
     paths: string[];
     loadTier: "T0";
     permission: "auto";
-    wire: {
-        interactions: string;
-        live: string;
-        openRouter?: undefined;
-    };
+    conflictsWith: string[];
 })[];
 /** Registers into the default scope; a scope of its own takes `GOOGLE_BUILTIN_TOOLS`. */
 declare function registerGooglePreset(): void;
+export { GEMINI_MODELS_URL } from '../providers/google/urls.js';
 export type { GoogleBindingViolation, GoogleFreeTierGrounding, GoogleImageAspectRatio, GoogleImageInputMime, GoogleImageOutputMime, GoogleImagePins, GoogleImageResolution, GoogleLivePins, GoogleSpeechPins, GoogleSpeechVoice, GoogleThinkingLevel, GoogleVoiceInputMime, };
-export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, };
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_EFFORT_API_IDS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, };

package/esm/src/presets/google.js

@@ -7,6 +7,7 @@ import "../../_dnt.polyfills.js";
 import { registerTools } from '../kernel/default-scope.js';
 import { GOOGLE_SPEECH_VOICES } from './google/speech-voices.js';
 import { GOOGLE_SPEECH_FORMATS, GOOGLE_THINKING_LEVELS, googleEfforts, } from './google-limits.js';
+/** The image MIME types a Gemini profile can take as input. */
 const GOOGLE_IMAGE_INPUT_MIMES = [
     'image/png',
     'image/jpeg',
@@ -14,6 +15,7 @@ const GOOGLE_IMAGE_INPUT_MIMES = [
     'image/heic',
     'image/heif',
 ];
+/** The audio MIME types a Gemini profile can take as voice input. */
 const GOOGLE_VOICE_INPUT_MIMES = ['audio/webm', 'audio/wav', 'audio/mpeg', 'audio/mp4'];
 /**
  * TTS models that reject any history with a model turn, so compaction's summary fails them
@@ -34,9 +36,13 @@ const GOOGLE_NO_THINKING_API_IDS = [
     'antigravity-preview-05-2026',
     'antigravity-preview-09-2026',
     'antigravity-preview-latest',
-    // Live closes 1007 "Thinking level is not supported for this model" (live, 01/10/2026).
-    'gemini-3.8-live',
 ];
+/**
+ * Models that refuse a thinking level and take `summaries`: leave `efforts` unset
+ * (live, 01/10/2026: Live closes 1007 "Thinking level is not supported for this model";
+ * 04/10/2026: setup takes `includeThoughts` either way).
+ */
+const GOOGLE_NO_EFFORT_API_IDS = ['gemini-3.8-live'];
 /**
  * Models that refuse a session without a thinking level: pin `efforts`
  * (live, 01/10/2026: Live closes 1007 "Thinking level must be specified for this model").
@@ -48,18 +54,20 @@ const grounding = (googleSearch, googleMaps) => ({
 });
 /**
  * Models with a non-zero free-tier quota, and the grounding each allows (AI Studio, Sep 2026).
+ * No model keeps free Maps quota: 3.5 Flash-Lite turns with Maps are refused as over quota
+ * (live, 13/10/2026).
  * A builtin with no quota is refused as if over quota: on Live, a close 1011 "You exceeded your
  * current quota" at setup, whatever the key's usage (live, 01/10/2026).
  */
 const GOOGLE_FREE_TIER_GROUNDING = {
-    'gemini-2.5-flash-lite': grounding(true, true),
-    'gemini-2.5-flash': grounding(true, true),
+    'gemini-2.5-flash-lite': grounding(true, false),
+    'gemini-2.5-flash': grounding(true, false),
     'gemini-2.5-flash-preview-tts': grounding(true, false),
     'gemini-3-flash-preview': grounding(false, false),
-    'gemini-3.1-flash-lite': grounding(false, true),
+    'gemini-3.1-flash-lite': grounding(false, false),
     'gemini-3.1-flash-lite-image': grounding(false, false),
-    'gemini-3.1-flash-tts-preview': grounding(false, true),
-    'gemini-3.5-flash-lite': grounding(false, true),
+    'gemini-3.1-flash-tts-preview': grounding(false, false),
+    'gemini-3.5-flash-lite': grounding(false, false),
     'gemini-3.5-flash': grounding(false, false),
     'gemini-3.6-flash': grounding(false, false),
     'gemini-3.7-flash': grounding(false, false),
@@ -89,20 +97,19 @@ function pinsEffort(binding) {
 function googleBindingViolation(binding, options = {}) {
     const apiId = binding.apiId.trim();
     const noThinking = GOOGLE_NO_THINKING_API_IDS;
+    const noEffort = GOOGLE_NO_EFFORT_API_IDS;
     const thinkingRequired = GOOGLE_THINKING_REQUIRED_API_IDS;
-    if (noThinking.includes(apiId)) {
-        if (pinsEffort(binding)) {
-            return {
-                field: 'efforts',
-                message: `${apiId} takes no thinking level; leave efforts unset.`,
-            };
-        }
-        if (binding.summaries !== undefined) {
-            return {
-                field: 'summaries',
-                message: `${apiId} takes no thinking setting; leave summaries unset.`,
-            };
-        }
+    if ((noThinking.includes(apiId) || noEffort.includes(apiId)) && pinsEffort(binding)) {
+        return {
+            field: 'efforts',
+            message: `${apiId} takes no thinking level; leave efforts unset.`,
+        };
+    }
+    if (noThinking.includes(apiId) && binding.summaries !== undefined) {
+        return {
+            field: 'summaries',
+            message: `${apiId} takes no thinking setting; leave summaries unset.`,
+        };
     }
     if (thinkingRequired.includes(apiId) && !pinsEffort(binding)) {
         return { field: 'efforts', message: `${apiId} needs a thinking level; pin efforts.` };
@@ -120,6 +127,7 @@ function googleBindingViolation(binding, options = {}) {
     }
     return undefined;
 }
+/** The aspect ratios a Gemini image model can return. */
 const GOOGLE_IMAGE_ASPECT_RATIOS = [
     '1:1',
     '3:2',
@@ -132,9 +140,11 @@ const GOOGLE_IMAGE_ASPECT_RATIOS = [
     '16:9',
     '21:9',
 ];
+/** The resolutions a Gemini image model can return. */
 const GOOGLE_IMAGE_RESOLUTIONS = ['1K', '2K', '4K'];
 /** What a Gemini image model can be asked to return. */
 const GOOGLE_IMAGE_OUTPUT_MIMES = ['image/png', 'image/jpeg'];
+/** The tools Gemini runs itself, as `builtin` tool definitions. */
 const GOOGLE_BUILTIN_TOOLS = [
     {
         type: 'builtin',
@@ -145,7 +155,6 @@ const GOOGLE_BUILTIN_TOOLS = [
         paths: ['*'],
         loadTier: 'T0',
         permission: 'auto',
-        wire: { interactions: 'google_search', openRouter: 'web', live: 'googleSearch' },
     },
     {
         type: 'builtin',
@@ -156,7 +165,8 @@ const GOOGLE_BUILTIN_TOOLS = [
         paths: ['*'],
         loadTier: 'T0',
         permission: 'auto',
-        wire: { interactions: 'google_maps', live: 'googleMaps' },
+        // why: Google refuses a request that carries Maps with Search or URL context.
+        conflictsWith: ['googleSearch', 'urlContext'],
     },
     {
         type: 'builtin',
@@ -167,7 +177,6 @@ const GOOGLE_BUILTIN_TOOLS = [
         paths: ['*'],
         loadTier: 'T0',
         permission: 'auto',
-        wire: { interactions: 'url_context', live: 'urlContext' },
     },
     {
         type: 'builtin',
@@ -178,11 +187,11 @@ const GOOGLE_BUILTIN_TOOLS = [
         paths: ['*'],
         loadTier: 'T0',
         permission: 'auto',
-        wire: { interactions: 'code_execution', live: 'codeExecution' },
     },
 ];
 /** Registers into the default scope; a scope of its own takes `GOOGLE_BUILTIN_TOOLS`. */
 function registerGooglePreset() {
     registerTools(GOOGLE_BUILTIN_TOOLS);
 }
-export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, };
+export { GEMINI_MODELS_URL } from '../providers/google/urls.js';
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_EFFORT_API_IDS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, };

package/esm/src/presets/local.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Local model convenience preset.
+ *
+ * @module
+ */
+import type { ModelBinding } from '../kernel/types.js';
+/**
+ * Whether an Ollama model thinks, read from the server's `POST /api/show` reply for it:
+ * `capabilities` lists `thinking` (Ollama 0.34.0, 04/10/2026). The host fetches the reply.
+ */
+declare function ollamaModelThinks(show: unknown): boolean;
+/** A local binding field its model would refuse, and what is wrong with it. */
+interface LocalBindingViolation {
+    field: 'efforts';
+    message: string;
+}
+/**
+ * The first setting a local server would refuse on this binding, or `undefined`. A thinking
+ * level goes to the server as `reasoning_effort`; Ollama answers HTTP 400 "does not support
+ * thinking" for a model that does not think (04/10/2026).
+ */
+declare function localBindingViolation(binding: Pick<ModelBinding, 'apiId' | 'efforts'>, model: {
+    thinks: boolean;
+}): LocalBindingViolation | undefined;
+export type { LocalBindingViolation };
+export { localBindingViolation, ollamaModelThinks };

package/esm/src/presets/local.js

@@ -0,0 +1,30 @@
+/**
+ * Local model convenience preset.
+ *
+ * @module
+ */
+/**
+ * Whether an Ollama model thinks, read from the server's `POST /api/show` reply for it:
+ * `capabilities` lists `thinking` (Ollama 0.34.0, 04/10/2026). The host fetches the reply.
+ */
+function ollamaModelThinks(show) {
+    if (!show || typeof show !== 'object')
+        return false;
+    const { capabilities } = show;
+    return Array.isArray(capabilities) && capabilities.includes('thinking');
+}
+/**
+ * The first setting a local server would refuse on this binding, or `undefined`. A thinking
+ * level goes to the server as `reasoning_effort`; Ollama answers HTTP 400 "does not support
+ * thinking" for a model that does not think (04/10/2026).
+ */
+function localBindingViolation(binding, model) {
+    if (!model.thinks && Object.keys(binding.efforts ?? {}).length > 0) {
+        return {
+            field: 'efforts',
+            message: `${binding.apiId.trim()} does not think; leave efforts unset.`,
+        };
+    }
+    return undefined;
+}
+export { localBindingViolation, ollamaModelThinks };

package/esm/src/presets/mod.d.ts

@@ -1,10 +1,11 @@
 /**
- * Optional host-convenience catalogs (provider builtins, media vocabularies) kept out of the kernel.
+ * Host-convenience catalogs for first-party providers: provider builtins and media vocabularies.
  *
  * @module
  */
 import "../../_dnt.polyfills.js";
 export type { GoogleBindingViolation, GoogleFreeTierGrounding, GoogleImageAspectRatio, GoogleImageInputMime, GoogleImageOutputMime, GoogleImagePins, GoogleImageResolution, GoogleSpeechVoice, GoogleThinkingLevel, GoogleVoiceInputMime, } from './google.js';
-export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, } from './google.js';
-export { OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES } from './openrouter.js';
-export { JEV_USD_PER_MILLION_INPUT_TOKENS } from './typesafe.js';
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_EFFORT_API_IDS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, } from './google.js';
+export type { LocalBindingViolation } from './local.js';
+export { localBindingViolation, ollamaModelThinks } from './local.js';
+export { OPENROUTER_BUILTIN_TOOLS, OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES, registerOpenRouterPreset, } from './openrouter.js';

package/esm/src/presets/mod.js

@@ -1,9 +1,9 @@
 /**
- * Optional host-convenience catalogs (provider builtins, media vocabularies) kept out of the kernel.
+ * Host-convenience catalogs for first-party providers: provider builtins and media vocabularies.
  *
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, } from './google.js';
-export { OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES } from './openrouter.js';
-export { JEV_USD_PER_MILLION_INPUT_TOKENS } from './typesafe.js';
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_EFFORT_API_IDS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, } from './google.js';
+export { localBindingViolation, ollamaModelThinks } from './local.js';
+export { OPENROUTER_BUILTIN_TOOLS, OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES, registerOpenRouterPreset, } from './openrouter.js';

package/esm/src/presets/openrouter.d.ts

@@ -10,4 +10,17 @@ declare const OPENROUTER_IMAGES_INPUT_MIMES: readonly ["image/*"];
  * only. The chat path (`image.includeText`) sends the system prompt and history.
  */
 declare const OPENROUTER_IMAGES_IGNORED_INPUTS: readonly ["system", "history"];
-export { OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES };
+/** The tools OpenRouter runs itself, as `builtin` tool definitions. */
+declare const OPENROUTER_BUILTIN_TOOLS: {
+    type: "builtin";
+    name: string;
+    description: string;
+    category: string;
+    access: "read-only";
+    paths: string[];
+    loadTier: "T0";
+    permission: "auto";
+}[];
+/** Registers into the default scope; a scope of its own takes `OPENROUTER_BUILTIN_TOOLS`. */
+declare function registerOpenRouterPreset(): void;
+export { OPENROUTER_BUILTIN_TOOLS, OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES, registerOpenRouterPreset, };

package/esm/src/presets/openrouter.js

@@ -3,6 +3,7 @@
  *
  * @module
  */
+import { registerTools } from '../kernel/default-scope.js';
 /** `/images` takes image references only; a profile on it lists nothing wider in `inputs.attachments.accept`. */
 const OPENROUTER_IMAGES_INPUT_MIMES = ['image/*'];
 /**
@@ -10,4 +11,21 @@ const OPENROUTER_IMAGES_INPUT_MIMES = ['image/*'];
  * only. The chat path (`image.includeText`) sends the system prompt and history.
  */
 const OPENROUTER_IMAGES_IGNORED_INPUTS = ['system', 'history'];
-export { OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES };
+/** The tools OpenRouter runs itself, as `builtin` tool definitions. */
+const OPENROUTER_BUILTIN_TOOLS = [
+    {
+        type: 'builtin',
+        name: 'webSearch',
+        description: 'OpenRouter web search',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+    },
+];
+/** Registers into the default scope; a scope of its own takes `OPENROUTER_BUILTIN_TOOLS`. */
+function registerOpenRouterPreset() {
+    registerTools(OPENROUTER_BUILTIN_TOOLS);
+}
+export { OPENROUTER_BUILTIN_TOOLS, OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES, registerOpenRouterPreset, };

package/esm/src/providers/embedding-limits.d.ts

@@ -0,0 +1,7 @@
+import type { ModelBinding } from '../kernel/protocols/binding.js';
+import type { EmbeddingModelLimits, Protocol } from '../kernel/protocols/protocol.js';
+/**
+ * What a binding's embedding model takes, read from its protocol: one Theorem ships, or one of
+ * `protocols`. Undefined when neither has it, and the kernel then holds requests to the profile alone.
+ */
+export declare function embeddingModelLimits(binding: Pick<ModelBinding, 'protocol' | 'apiId'>, protocols?: readonly Protocol[]): EmbeddingModelLimits | undefined;

package/esm/src/providers/embedding-limits.js

@@ -0,0 +1,12 @@
+import { geminiEmbedding } from './gemini/embedding-protocol.js';
+import { ollamaEmbedding } from './local/embedding-protocol.js';
+import { openRouterEmbedding } from './openrouter/embedding-protocol.js';
+const SHIPPED = [geminiEmbedding, openRouterEmbedding, ollamaEmbedding];
+/**
+ * What a binding's embedding model takes, read from its protocol: one Theorem ships, or one of
+ * `protocols`. Undefined when neither has it, and the kernel then holds requests to the profile alone.
+ */
+export function embeddingModelLimits(binding, protocols = []) {
+    const protocol = [...protocols, ...SHIPPED].find((entry) => entry.id === binding.protocol);
+    return protocol?.embeddingLimits?.(binding.apiId);
+}

package/esm/src/providers/gemini/embedding-protocol.d.ts

@@ -0,0 +1,8 @@
+import type { Protocol } from '../../kernel/protocols/protocol.js';
+/** What a `geminiEmbedding` binding sets in `options`. */
+export interface GeminiEmbeddingOptions {
+    /** For `gemini-embedding-001`; Gemini Embedding 2 refuses it and reads the request's `task` from the text. */
+    taskType?: 'RETRIEVAL_QUERY' | 'RETRIEVAL_DOCUMENT' | 'SEMANTIC_SIMILARITY' | 'CLASSIFICATION' | 'CLUSTERING' | 'QUESTION_ANSWERING' | 'FACT_VERIFICATION' | 'CODE_RETRIEVAL_QUERY';
+    outputDimensionality?: 768 | 1536 | 3072;
+}
+export declare const geminiEmbedding: Protocol<GeminiEmbeddingOptions>;