@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/observability/trace.js

@@ -0,0 +1,35 @@
+// 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) {
+    try {
+        await sink.write(await record, {
+            retainForDays: policy.retainForDays,
+            rotateAfterMiB: policy.rotateAfterMiB,
+        });
+    }
+    catch (err) {
+        try {
+            sink.onError?.(err);
+        }
+        catch {
+            // Host onError must not fail the turn.
+        }
+    }
+}
+/** Like `writeTrace`, it never fails the caller. */
+function writeSpans(sink, spans, policy, metadata) {
+    return writeTrace(sink, buildRecord({ spans, policy, ...(metadata ? { metadata } : {}) }), policy);
+}
+function noopSink() {
+    return { write: () => Promise.resolve() };
+}
+function memorySink(into) {
+    return {
+        write: (record) => {
+            into.push(record);
+            return Promise.resolve();
+        },
+    };
+}
+export { memorySink, noopSink, writeSpans, writeTrace };

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

@@ -0,0 +1,85 @@
+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. */
+export interface TraceIncludeSpec {
+    /** Scrubbed provider rows and frames (`theorem.upstream.row` events). Default: true. */
+    upstreamLog?: boolean;
+    /** Scrubbed outbound request bodies (`theorem.wire.request` events). Default: false. */
+    outboundWire?: boolean;
+    /** The provider's raw grounding payload (`raw` on `theorem.grounding` events). Default: false. */
+    evidenceRaw?: boolean;
+    /** Usage attributes (`gen_ai.usage.*`, `theorem.usage.*`). Default: true. */
+    usage?: boolean;
+    /** Guardrail decisions (`theorem.guardrail` events). Default: true. */
+    guardrailDecisions?: boolean;
+    /**
+     * Keep `GuardrailHit.match` (the exact matched text) on guardrail events. Default: false;
+     * debugging only, so treat the store like server logs when enabled.
+     */
+    guardrailMatchPreview?: boolean;
+}
+/** Scrubbing of stored records, independent of turn-path `profile.guardrails`. 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;
+}
+/** Omit the whole block for no tracing. */
+export interface ProfileObservabilitySpec {
+    /**
+     * `false` is off, a string is a `registerTraceDestination` id, a TraceSink is an inline writer.
+     * `runTurn(..., sink)` still overrides this for one call.
+     */
+    writeTo?: false | string | TraceSink;
+    /**
+     * Fraction of traces to record, 0–1 inclusive. Default: 1. Decided by trace id, so every
+     * record of one trace is kept or dropped together.
+     */
+    sampleRate?: number;
+    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. */
+    scrub?: TraceScrubSpec;
+    /**
+     * Days to keep each record, handed to every destination with the record
+     * (`TraceWriteContext`): the JSONL writer prunes by it, a host store computes
+     * its own expiry from it. `<= 0` keeps records forever. Default: 14.
+     */
+    retainForDays?: number;
+    /**
+     * File size in MiB at which a file-based destination starts a new file, handed to every
+     * destination with the record (`TraceWriteContext`). Default: 32.
+     */
+    rotateAfterMiB?: number;
+    /** Called when record build or destination write fails. Must not throw. */
+    onWriteError?: (err: unknown) => void;
+}
+export interface ResolvedTraceInclude {
+    upstreamLog: boolean;
+    outboundWire: boolean;
+    evidenceRaw: boolean;
+    usage: boolean;
+    guardrailDecisions: boolean;
+    guardrailMatchPreview: boolean;
+}
+export interface ResolvedTraceScrub {
+    sensitive: boolean;
+    injection: boolean;
+    canary: boolean;
+}
+export interface ResolvedObservabilityPolicy {
+    /** False when the block is omitted or `writeTo` is `false`/absent. Sampling applies at write. */
+    record: boolean;
+    writeTo: false | string | TraceSink | undefined;
+    sampleRate: number;
+    include: ResolvedTraceInclude;
+    scrub: ResolvedTraceScrub;
+    resource: TraceAttributes;
+    retainForDays: number;
+    rotateAfterMiB: number;
+    onWriteError?: (err: unknown) => void;
+}

package/esm/src/observability/types.js

@@ -0,0 +1,3 @@
+// 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

@@ -0,0 +1,8 @@
+/**
+ * Gemini TTS voice names for `speech.voice`. No imports, so docs UIs can load it alone.
+ *
+ * @module
+ */
+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"];
+export type GoogleSpeechVoice = (typeof GOOGLE_SPEECH_VOICES)[number];

package/esm/src/presets/google/speech-voices.js

@@ -0,0 +1,38 @@
+/**
+ * Gemini TTS voice names for `speech.voice`. No imports, so docs UIs can load it alone.
+ *
+ * @module
+ */
+import "../../../_dnt.polyfills.js";
+export const GOOGLE_SPEECH_VOICES = [
+    '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',
+];

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

@@ -0,0 +1,12 @@
+/** The thinking levels Gemini's `thinkingLevel` takes; OpenRouter models take them all. */
+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"];
+type GoogleThinkingLevel = (typeof GOOGLE_THINKING_LEVELS)[number];
+/**
+ * A `geminiInteractions` or `geminiLive` binding's `efforts`, typed to the levels Gemini takes.
+ * The runtime check refuses an untyped host's level when the binding is built, not when a turn runs.
+ */
+declare function googleEfforts<Efforts extends Record<string, GoogleThinkingLevel>>(efforts: Efforts): Efforts;
+export type { GoogleThinkingLevel };
+export { GOOGLE_SPEECH_FORMATS, GOOGLE_THINKING_LEVELS, googleEfforts };

package/esm/src/presets/google-limits.js

@@ -0,0 +1,18 @@
+import { TheoremError } from '../guardrails/theorem-error.js';
+/** The thinking levels Gemini's `thinkingLevel` takes; OpenRouter models take them all. */
+const GOOGLE_THINKING_LEVELS = ['minimal', 'low', 'medium', 'high'];
+/** The audio format Gemini speech returns (PCM, wrapped as WAV); OpenRouter speech also takes `mp3`. */
+const GOOGLE_SPEECH_FORMATS = ['pcm'];
+/**
+ * A `geminiInteractions` or `geminiLive` binding's `efforts`, typed to the levels Gemini takes.
+ * The runtime check refuses an untyped host's level when the binding is built, not when a turn runs.
+ */
+function googleEfforts(efforts) {
+    for (const [alias, level] of Object.entries(efforts)) {
+        if (!GOOGLE_THINKING_LEVELS.includes(level)) {
+            throw new TheoremError('config', `Effort '${alias}': Gemini does not take '${level}' (${GOOGLE_THINKING_LEVELS.join(', ')})`);
+        }
+    }
+    return efforts;
+}
+export { GOOGLE_SPEECH_FORMATS, GOOGLE_THINKING_LEVELS, googleEfforts };

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

@@ -0,0 +1,104 @@
+/**
+ * Google / Gemini convenience preset.
+ *
+ * @module
+ */
+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';
+declare const GOOGLE_IMAGE_INPUT_MIMES: readonly ["image/png", "image/jpeg", "image/webp", "image/heic", "image/heif"];
+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
+ * (live, 29/09/2026).
+ */
+declare const GOOGLE_SINGLE_TURN_API_IDS: readonly ["gemini-2.5-flash-preview-tts", "gemini-3.1-flash-tts-preview", "gemini-3.8-flash-tts", "gemini-3.8-flash-lite-tts"];
+/**
+ * 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"];
+/**
+ * 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").
+ */
+declare const GOOGLE_THINKING_REQUIRED_API_IDS: readonly ["gemini-3.8-live-extended-thinking"];
+/** Which grounding builtins a model's free-tier quota allows. */
+interface GoogleFreeTierGrounding {
+    googleSearch: boolean;
+    googleMaps: boolean;
+}
+/**
+ * Models with a non-zero free-tier quota, and the grounding each allows (AI Studio, Sep 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'>;
+interface GoogleBindingViolation {
+    field: 'apiId' | 'efforts' | 'summaries' | 'builtInTools';
+    message: string;
+}
+/**
+ * The first setting Google would refuse on this binding, or `undefined`. With `freeTier`, it
+ * also holds the binding to the free-tier table: a listed model, and only the grounding its
+ * quota allows.
+ */
+declare function googleBindingViolation(binding: Pick<ModelBinding, 'apiId' | 'efforts' | 'summaries' | 'builtInTools'>, options?: {
+    freeTier?: boolean;
+}): GoogleBindingViolation | undefined;
+type GoogleSpeechPins = Omit<ProfileSpeechSpec, 'voice'> & {
+    voice?: GoogleSpeechVoice;
+};
+type GoogleLivePins = Omit<ProfileLiveSpec, 'voice'> & {
+    voice?: GoogleSpeechVoice;
+};
+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"];
+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"];
+type GoogleImageInputMime = (typeof GOOGLE_IMAGE_INPUT_MIMES)[number];
+type GoogleVoiceInputMime = (typeof GOOGLE_VOICE_INPUT_MIMES)[number];
+type GoogleImageAspectRatio = (typeof GOOGLE_IMAGE_ASPECT_RATIOS)[number];
+type GoogleImageResolution = (typeof GOOGLE_IMAGE_RESOLUTIONS)[number];
+type GoogleImageOutputMime = (typeof GOOGLE_IMAGE_OUTPUT_MIMES)[number];
+type GoogleImagePins = Omit<ProfileImageSpec, 'aspectRatio' | 'resolution' | 'mimeType'> & {
+    aspectRatio?: GoogleImageAspectRatio;
+    resolution?: GoogleImageResolution;
+    mimeType?: GoogleImageOutputMime;
+};
+declare const GOOGLE_BUILTIN_TOOLS: ({
+    type: "builtin";
+    name: string;
+    description: string;
+    category: string;
+    access: "read-only";
+    paths: string[];
+    loadTier: "T0";
+    permission: "auto";
+    wire: {
+        interactions: string;
+        openRouter: string;
+        live: string;
+    };
+} | {
+    type: "builtin";
+    name: string;
+    description: string;
+    category: string;
+    access: "read-only";
+    paths: string[];
+    loadTier: "T0";
+    permission: "auto";
+    wire: {
+        interactions: string;
+        live: string;
+        openRouter?: undefined;
+    };
+})[];
+/** Registers into the default scope; a scope of its own takes `GOOGLE_BUILTIN_TOOLS`. */
+declare function registerGooglePreset(): void;
+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, };

package/esm/src/presets/google.js

@@ -0,0 +1,188 @@
+/**
+ * Google / Gemini convenience preset.
+ *
+ * @module
+ */
+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';
+const GOOGLE_IMAGE_INPUT_MIMES = [
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/heic',
+    'image/heif',
+];
+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
+ * (live, 29/09/2026).
+ */
+const GOOGLE_SINGLE_TURN_API_IDS = [
+    'gemini-2.5-flash-preview-tts',
+    'gemini-3.1-flash-tts-preview',
+    'gemini-3.8-flash-tts',
+    'gemini-3.8-flash-lite-tts',
+];
+/**
+ * Models that reject any thinking setting, `summaries: false` included: leave
+ * `efforts` and `summaries` unset (live, 30/09/2026).
+ */
+const GOOGLE_NO_THINKING_API_IDS = [
+    'gemini-2.5-flash-image',
+    '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 session without a thinking level: pin `efforts`
+ * (live, 01/10/2026: Live closes 1007 "Thinking level must be specified for this model").
+ */
+const GOOGLE_THINKING_REQUIRED_API_IDS = ['gemini-3.8-live-extended-thinking'];
+const grounding = (googleSearch, googleMaps) => ({
+    googleSearch,
+    googleMaps,
+});
+/**
+ * Models with a non-zero free-tier quota, and the grounding each allows (AI Studio, Sep 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-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-image': grounding(false, false),
+    'gemini-3.1-flash-tts-preview': grounding(false, true),
+    'gemini-3.5-flash-lite': grounding(false, true),
+    'gemini-3.5-flash': grounding(false, false),
+    'gemini-3.6-flash': grounding(false, false),
+    'gemini-3.7-flash': grounding(false, false),
+    'gemini-3.8-flash-tts': grounding(false, false),
+    'gemini-3.8-flash-lite-tts': grounding(false, false),
+    'gemma-4-26b-a4b-it': grounding(false, false),
+    'gemma-4-31b-it': grounding(false, false),
+    'gemini-3.1-flash-live-preview': grounding(false, false),
+    'gemini-3.8-live': grounding(false, false),
+    'gemini-3.8-live-extended-thinking': grounding(false, false),
+};
+/** Grounding builtins the free tier allows on `apiId`; none for a model with no free quota. */
+function googleFreeTierBuiltins(apiId) {
+    const allowed = GOOGLE_FREE_TIER_GROUNDING[apiId.trim()];
+    if (!allowed)
+        return [];
+    return ['googleSearch', 'googleMaps'].filter((id) => allowed[id]);
+}
+function pinsEffort(binding) {
+    return Object.keys(binding.efforts ?? {}).length > 0;
+}
+/**
+ * The first setting Google would refuse on this binding, or `undefined`. With `freeTier`, it
+ * also holds the binding to the free-tier table: a listed model, and only the grounding its
+ * quota allows.
+ */
+function googleBindingViolation(binding, options = {}) {
+    const apiId = binding.apiId.trim();
+    const noThinking = GOOGLE_NO_THINKING_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 (thinkingRequired.includes(apiId) && !pinsEffort(binding)) {
+        return { field: 'efforts', message: `${apiId} needs a thinking level; pin efforts.` };
+    }
+    if (!options.freeTier)
+        return undefined;
+    if (!GOOGLE_FREE_TIER_GROUNDING[apiId]) {
+        return { field: 'apiId', message: `${apiId} has no free-tier quota.` };
+    }
+    const allowed = googleFreeTierBuiltins(apiId);
+    for (const builtin of binding.builtInTools ?? []) {
+        if ((builtin === 'googleSearch' || builtin === 'googleMaps') && !allowed.includes(builtin)) {
+            return { field: 'builtInTools', message: `${apiId} has no free-tier quota for ${builtin}.` };
+        }
+    }
+    return undefined;
+}
+const GOOGLE_IMAGE_ASPECT_RATIOS = [
+    '1:1',
+    '3:2',
+    '2:3',
+    '3:4',
+    '4:3',
+    '4:5',
+    '5:4',
+    '9:16',
+    '16:9',
+    '21:9',
+];
+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'];
+const GOOGLE_BUILTIN_TOOLS = [
+    {
+        type: 'builtin',
+        name: 'googleSearch',
+        description: 'Google Search grounding',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        wire: { interactions: 'google_search', openRouter: 'web', live: 'googleSearch' },
+    },
+    {
+        type: 'builtin',
+        name: 'googleMaps',
+        description: 'Google Maps grounding',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        wire: { interactions: 'google_maps', live: 'googleMaps' },
+    },
+    {
+        type: 'builtin',
+        name: 'urlContext',
+        description: 'Fetch URL context',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        wire: { interactions: 'url_context', live: 'urlContext' },
+    },
+    {
+        type: 'builtin',
+        name: 'codeExecution',
+        description: 'Google code execution',
+        category: 'grounding',
+        access: 'read-only',
+        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, };

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

@@ -0,0 +1,10 @@
+/**
+ * Optional host-convenience catalogs (provider builtins, media vocabularies) kept out of the kernel.
+ *
+ * @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';

package/esm/src/presets/mod.js

@@ -0,0 +1,9 @@
+/**
+ * Optional host-convenience catalogs (provider builtins, media vocabularies) kept out of the kernel.
+ *
+ * @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';

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

@@ -0,0 +1,13 @@
+/**
+ * OpenRouter convenience preset.
+ *
+ * @module
+ */
+/** `/images` takes image references only; a profile on it lists nothing wider in `inputs.attachments.accept`. */
+declare const OPENROUTER_IMAGES_INPUT_MIMES: readonly ["image/*"];
+/**
+ * What `/images` never sends the model: it reads the prompt text and the reference images
+ * 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 };

package/esm/src/presets/openrouter.js

@@ -0,0 +1,13 @@
+/**
+ * OpenRouter convenience preset.
+ *
+ * @module
+ */
+/** `/images` takes image references only; a profile on it lists nothing wider in `inputs.attachments.accept`. */
+const OPENROUTER_IMAGES_INPUT_MIMES = ['image/*'];
+/**
+ * What `/images` never sends the model: it reads the prompt text and the reference images
+ * 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 };

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

@@ -0,0 +1,2 @@
+/** TypeSafe's Jev input price; output tokens are free (28 September 2026). */
+export declare const JEV_USD_PER_MILLION_INPUT_TOKENS = 0.042;

package/esm/src/presets/typesafe.js

@@ -0,0 +1,2 @@
+/** TypeSafe's Jev input price; output tokens are free (28 September 2026). */
+export const JEV_USD_PER_MILLION_INPUT_TOKENS = 0.042;

package/esm/src/providers/create-provider.d.ts

@@ -0,0 +1,21 @@
+import type { KeyVault, ModelId, ModelProvider, Profile } from '../kernel/types.js';
+import type { GeminiOptions } from './google/keys.js';
+import type { LocalProviderConfig, OpenAiGatewayConfig } from './types.js';
+export interface CreateProviderOptions {
+    /**
+     * The host's keys by slot, for every provider. A model's calls use the slot its profile names
+     * (`key`, `fallbackKey`); a slot holds whatever secret the host put there.
+     */
+    vault?: KeyVault;
+    gemini?: GeminiOptions;
+    /** `voice` is the fallback when a speech profile omits `speech.voice`. */
+    openAiGateway?: OpenAiGatewayConfig & {
+        voice?: string;
+    };
+    /** Required for `local` profiles. */
+    local?: LocalProviderConfig;
+}
+export declare function isSpeechRole(profile: Profile): boolean;
+export declare function isImageRole(profile: Profile): boolean;
+/** Live profiles use `runSession`. `modelId` picks the binding; default `defaultModel`. */
+export declare function createProvider(profile: Profile, options?: CreateProviderOptions, modelId?: ModelId): ModelProvider;