@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,201 @@
+// 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';
+import { isRecord } from '../kernel/util/record.js';
+const TRACE_ID_BYTES = 16;
+const SPAN_ID_BYTES = 8;
+const NANOS_PER_MS = 1_000_000;
+const HEX_PAD = 2;
+const HEX_RADIX = 16;
+const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+const ALL_ZERO = /^0+$/;
+const SAMPLED_FLAGS = '01';
+const UNCLOSED = 'unclosed';
+function randomHex(bytes) {
+    for (;;) {
+        const buf = crypto.getRandomValues(new Uint8Array(bytes));
+        const hex = [...buf].map((b) => b.toString(HEX_RADIX).padStart(HEX_PAD, '0')).join('');
+        if (!ALL_ZERO.test(hex)) {
+            return hex;
+        }
+    }
+}
+/** On Cloudflare Workers both clocks advance only at I/O; the root carries `theorem.clock=io`. */
+function systemClock() {
+    const epochMs = Date.now();
+    const perfStart = performance.now();
+    return {
+        nowUnixNano: () => BigInt(epochMs) * BigInt(NANOS_PER_MS) +
+            BigInt(Math.round((performance.now() - perfStart) * NANOS_PER_MS)),
+    };
+}
+function clockAdvancesOnlyAtIo() {
+    return globalThis.navigator?.userAgent === 'Cloudflare-Workers';
+}
+/**
+ * The trace and span ids of a W3C `traceparent` THEOREM accepts (version 00,
+ * lowercase hex, non-zero ids), or `undefined`. For a host checking a value from
+ * a request before handing it to a turn, which throws on anything else.
+ */
+function readTraceparent(value) {
+    const match = TRACEPARENT.exec(value.trim());
+    const traceId = match?.[1];
+    const spanId = match?.[2];
+    if (!traceId || !spanId || ALL_ZERO.test(traceId) || ALL_ZERO.test(spanId))
+        return undefined;
+    return { traceId, spanId };
+}
+/** Throws on a malformed value: a host bug, not a runtime state. */
+function parseTraceparent(value) {
+    const parsed = readTraceparent(value);
+    if (!parsed) {
+        throw new TheoremError('request', `traceparent is not a valid W3C trace context: '${value}'`);
+    }
+    return parsed;
+}
+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 };
+}
+/** `undefined` members and non-JSON values are dropped the way `JSON.stringify` drops them. */
+function traceJson(value) {
+    return { $json: toAttributeValue(value) ?? null };
+}
+function toAttributeValue(value) {
+    if (typeof value === 'string' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (value === null) {
+        return null;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => toAttributeValue(item) ?? null);
+    }
+    if (typeof value === 'object') {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            const mapped = toAttributeValue(nested);
+            if (mapped !== undefined) {
+                out[key] = mapped;
+            }
+        }
+        return out;
+    }
+    return undefined;
+}
+function isMarker(value, key) {
+    return isRecord(value) && key in value;
+}
+function isTraceContent(value) {
+    return isMarker(value, '$content') && typeof value.$content === 'string';
+}
+function isTraceBytes(value) {
+    return isMarker(value, '$bytes') && typeof value.$bytes === 'string';
+}
+function isTraceJson(value) {
+    return isMarker(value, '$json');
+}
+function linkFrom(input) {
+    const { traceId, spanId } = parseTraceparent(input.traceparent);
+    return { traceId, spanId, attributes: { ...(input.attributes ?? {}) } };
+}
+function msBetween(fromUnixNano, clock) {
+    return Number(clock.nowUnixNano() - BigInt(fromUnixNano)) / NANOS_PER_MS;
+}
+function openHandle(state, traceId, parentSpanId, name, options) {
+    const entry = {
+        span: {
+            traceId,
+            spanId: randomHex(SPAN_ID_BYTES),
+            ...(parentSpanId ? { parentSpanId } : {}),
+            name,
+            kind: options?.kind ?? 'INTERNAL',
+            startTimeUnixNano: options?.startTimeUnixNano ?? String(state.clock.nowUnixNano()),
+            endTimeUnixNano: '',
+            attributes: { ...(options?.attributes ?? {}) },
+            events: [],
+            links: (options?.links ?? []).map(linkFrom),
+            status: { code: 'UNSET' },
+        },
+        ended: false,
+        order: state.open.length,
+    };
+    state.open.push(entry);
+    const { span } = entry;
+    return {
+        traceId,
+        spanId: span.spanId,
+        get ended() {
+            return entry.ended;
+        },
+        traceparent: () => formatTraceparent(traceId, span.spanId),
+        child: (childName, childOptions) => openHandle(state, traceId, span.spanId, childName, childOptions),
+        set: (attributes) => {
+            if (!entry.ended) {
+                Object.assign(span.attributes, attributes);
+            }
+        },
+        event: (eventName, attributes, timeUnixNano) => {
+            if (!entry.ended) {
+                span.events.push({
+                    name: eventName,
+                    timeUnixNano: timeUnixNano ?? String(state.clock.nowUnixNano()),
+                    attributes: { ...(attributes ?? {}) },
+                });
+            }
+        },
+        end: (status) => {
+            if (entry.ended) {
+                return;
+            }
+            entry.ended = true;
+            span.endTimeUnixNano = String(state.clock.nowUnixNano());
+            span.status = status ?? { code: 'OK' };
+        },
+        msSinceStart: () => msBetween(span.startTimeUnixNano, state.clock),
+        msSinceEnd: () => (entry.ended ? msBetween(span.endTimeUnixNano, state.clock) : undefined),
+        nowUnixNano: () => String(state.clock.nowUnixNano()),
+    };
+}
+/**
+ * Open a root span. With `traceparent`, the root joins that trace as a child of
+ * the named span; without it, the root starts a new trace.
+ */
+function startTrace(name, options = {}) {
+    const parent = options.traceparent ? parseTraceparent(options.traceparent) : undefined;
+    const state = { clock: options.clock ?? systemClock(), open: [] };
+    const root = openHandle(state, parent?.traceId ?? randomHex(TRACE_ID_BYTES), parent?.spanId, name, {
+        ...options,
+        attributes: {
+            ...(clockAdvancesOnlyAtIo() ? { 'theorem.clock': 'io' } : {}),
+            ...(options.attributes ?? {}),
+        },
+    });
+    return {
+        root,
+        clock: state.clock,
+        collect: () => {
+            const now = String(state.clock.nowUnixNano());
+            for (const entry of state.open) {
+                if (!entry.ended) {
+                    entry.ended = true;
+                    entry.span.endTimeUnixNano = now;
+                    entry.span.status = { code: 'ERROR', message: UNCLOSED };
+                }
+            }
+            return [...state.open].sort((a, b) => a.order - b.order).map((entry) => entry.span);
+        },
+    };
+}
+export { formatTraceparent, isTraceBytes, isTraceContent, isTraceJson, parseTraceparent, readTraceparent, startTrace, traceBytes, traceContent, traceJson, };

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

@@ -0,0 +1,13 @@
+import { type TraceRecord } from './trace-record.js';
+import type { TraceSink } from './trace-sink.js';
+import type { TraceSpan } from './trace-span.js';
+import type { ResolvedObservabilityPolicy } from './types.js';
+/** Trace failures never fail the turn: build and write errors go to `sink.onError`, if set. */
+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

@@ -0,0 +1,37 @@
+// 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) {
+    try {
+        await sink.write(await record, {
+            retainForDays: policy.retainForDays,
+            rotateAfterMiB: policy.rotateAfterMiB,
+        });
+    }
+    catch (err) {
+        try {
+            sink.onError?.(err);
+        }
+        catch {
+            // why: 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);
+}
+/** 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) => {
+            into.push(record);
+            return Promise.resolve();
+        },
+    };
+}
+export { memorySink, noopSink, writeSpans, writeTrace };

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

@@ -0,0 +1,109 @@
+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. */
+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;
+}
+/**
+ * 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 {
+    /** 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 {
+    /**
+     * `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.detect` is `ignore`. */
+    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;
+}
+/** Which optional content a trace record includes, each on or off. */
+export interface ResolvedTraceInclude {
+    upstreamLog: boolean;
+    outboundWire: boolean;
+    evidenceRaw: boolean;
+    usage: boolean;
+    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: 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;
+    writeTo: false | string | TraceSink | undefined;
+    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;
+    onWriteError?: (err: unknown) => void;
+}

package/esm/src/observability/types.js

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

@@ -0,0 +1,9 @@
+/**
+ * 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"];
+/** The name of a Gemini speech voice. */
+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,13 @@
+/** 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"];
+/** 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.
+ * 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,119 @@
+/**
+ * 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';
+/** 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
+ * (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"];
+/**
+ * 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").
+ */
+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).
+ * 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;
+}
+/**
+ * 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;
+/** 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;
+    description: string;
+    category: string;
+    access: "read-only";
+    paths: string[];
+    loadTier: "T0";
+    permission: "auto";
+    conflictsWith?: undefined;
+} | {
+    type: "builtin";
+    name: string;
+    description: string;
+    category: string;
+    access: "read-only";
+    paths: string[];
+    loadTier: "T0";
+    permission: "auto";
+    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_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, };