theorum 0.1.14 → 1.0.0

package/esm/src/kernel/engine/session/mod.js

@@ -0,0 +1,205 @@
+/**
+ * `runSession` — long-lived live profile execution.
+ *
+ * Shares resolve / tools / canary / system / outbound gate with `runTurn`.
+ * Does not use `ModelProvider.complete()` — live is a session, not one turn.
+ *
+ * @module
+ */
+import { bindCanary } from '../../../guardrails/canary.js';
+import { publicError, TheorumError, throwIfAborted, toErrorEvent, } from '../../../guardrails/error.js';
+import { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, } from '../../../guardrails/live-outbound-gate.js';
+import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
+import { buildGeminiLiveRealtimeInput, buildGeminiLiveRealtimeText, buildGeminiLiveToolResponse, buildGeminiLiveToolResponses, } from '../../../providers/google/live/framing.js';
+import { openGoogleLiveSession } from '../../../providers/google/live/session.js';
+import { providerCompleteRequest } from '../../registry/provider-request.js';
+import { pickSystemRole, resolveTurn } from '../../registry/resolve.js';
+import { expandT1Policy } from '../../tools/resolve.js';
+import { prepareLiveInboundText } from '../live-inbound.js';
+import { systemFromProfile } from '../runner/stream.js';
+function assertLiveProfile(profile) {
+    if (profile.type !== 'live') {
+        throw new TheorumError(`runSession requires profile.type 'live' (got '${profile.type}' for ${profile.id})`);
+    }
+}
+function toTurnRequest(req) {
+    return {
+        profile: req.profile,
+        system: req.system,
+        path: req.path,
+        sessionPermissions: req.sessionPermissions,
+        sessionResumptionHandle: req.sessionResumptionHandle,
+        signal: req.signal,
+        metadata: req.metadata,
+        input: {
+            text: '',
+            history: req.history,
+            sessionResumptionHandle: req.sessionResumptionHandle,
+        },
+    };
+}
+function applyVoiceOverride(generation, voice) {
+    if (!voice || !generation.live) {
+        return generation;
+    }
+    return {
+        ...generation,
+        live: {
+            ...generation.live,
+            voice,
+        },
+    };
+}
+function applyInitialInput(generation, input) {
+    if (!input || input.length === 0) {
+        return generation;
+    }
+    return { ...generation, input };
+}
+async function applyOutbound(gate, events, turnPhase, onWithhold) {
+    if (turnPhase === 'abort') {
+        abortLiveOutboundTurn(gate);
+        // Keep tool calls + interrupted marker; drop buffered speech via abortLiveOutboundTurn.
+        return events.filter((ev) => ev.type === 'tool' ||
+            ev.type === 'session' ||
+            (ev.type === 'done' && ev.interrupted === true));
+    }
+    const batch = processLiveOutboundBatch(gate, events);
+    const out = [];
+    if (batch.action === 'withhold') {
+        onWithhold(batch.error);
+        return [{ type: 'error', error: batch.error }];
+    }
+    if (batch.action === 'emit') {
+        out.push(...batch.events);
+    }
+    if (turnPhase === 'complete') {
+        const finalized = await finalizeLiveOutboundTurn(gate);
+        if (finalized.action === 'withhold') {
+            onWithhold(finalized.error);
+            return [...out, { type: 'error', error: finalized.error }];
+        }
+        if (finalized.action === 'emit') {
+            out.push(...finalized.events);
+        }
+        // Conversational turn boundary — session stays open.
+        out.push({ type: 'done', stop: { kind: 'completed' } });
+    }
+    return out;
+}
+function buildLiveSession(args) {
+    const { profile, canary, connection, gate, signal } = args;
+    let closed = false;
+    let withholdClose;
+    const sendJson = (payload) => {
+        if (closed) {
+            throw new TheorumError('Live session is closed');
+        }
+        connection.send(JSON.stringify(payload));
+    };
+    return {
+        profileId: profile.id,
+        canary,
+        async *events() {
+            try {
+                for await (const item of connection.batches()) {
+                    throwIfAborted(signal);
+                    if (item.type === 'closed') {
+                        break;
+                    }
+                    if (item.type === 'error') {
+                        yield toErrorEvent(item.error);
+                        break;
+                    }
+                    const gated = await applyOutbound(gate, item.events, item.turnPhase, (error) => {
+                        withholdClose = error;
+                    });
+                    for (const ev of gated) {
+                        if (ev.type === 'error') {
+                            yield {
+                                ...ev,
+                                error: publicError(ev.error ?? withholdClose ?? 'guardrail withheld'),
+                            };
+                        }
+                        else {
+                            yield ev;
+                        }
+                    }
+                    if (withholdClose) {
+                        connection.close(1011, 'guardrail withheld');
+                        break;
+                    }
+                }
+            }
+            finally {
+                closed = true;
+                connection.close();
+            }
+        },
+        sendAudio(audio) {
+            sendJson(buildGeminiLiveRealtimeInput({
+                type: 'audio',
+                mimeType: audio.mimeType ?? 'audio/pcm;rate=16000',
+                data: audio.data,
+            }));
+        },
+        sendVideo(video) {
+            sendJson(buildGeminiLiveRealtimeInput({
+                type: 'video',
+                mimeType: video.mimeType ?? 'image/jpeg',
+                data: video.data,
+            }));
+        },
+        sendText(text) {
+            const safeText = prepareLiveInboundText(profile, text);
+            sendJson(buildGeminiLiveRealtimeText(safeText));
+        },
+        sendToolResponse(id, name, output) {
+            sendJson(buildGeminiLiveToolResponse(id, name, output));
+        },
+        sendToolResponses(responses) {
+            sendJson(buildGeminiLiveToolResponses(responses));
+        },
+        close(reason = 'session-closed') {
+            if (closed)
+                return Promise.resolve();
+            closed = true;
+            connection.close(1000, reason);
+            return Promise.resolve();
+        },
+    };
+}
+/**
+ * Open a gated Gemini Live session for a `type: 'live'` profile.
+ *
+ * Hosts bridge browser sockets and tool dispatch; THEORUM owns Gemini WS,
+ * framing, inbound prep, and outbound canary/egress gates.
+ */
+export async function runSession(req, options) {
+    const turnReq = toTurnRequest(req);
+    const safe = sanitizeTurnRequest(turnReq);
+    throwIfAborted(safe.signal);
+    const { profile, generation: gen0 } = resolveTurn(safe);
+    assertLiveProfile(profile);
+    await expandT1Policy(gen0.tools, profile, safe);
+    gen0.builtins = gen0.tools.builtins;
+    let generation = applyVoiceOverride(gen0, req.voice);
+    generation = applyInitialInput(generation, req.input);
+    const role = pickSystemRole(profile, safe.input?.role);
+    const combinedSys = [systemFromProfile(profile, role), safe.system].filter(Boolean).join('\n\n');
+    const system = bindCanary(combinedSys, generation.canary);
+    const completeReq = {
+        ...providerCompleteRequest(generation, system),
+        ...(req.wireTools ? { wireTools: req.wireTools } : {}),
+        signal: safe.signal,
+    };
+    const gate = createLiveOutboundGateSession(profile, generation.canary || undefined);
+    const connection = await openGoogleLiveSession(completeReq, options.gemini, options.openWebSocket);
+    return buildLiveSession({
+        profile,
+        canary: generation.canary,
+        connection,
+        gate,
+        signal: safe.signal,
+    });
+}

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

@@ -1,22 +1,21 @@
 /**
  * Profile, turn, tool, provider, egress, and event contracts for THEORUM.
  *
- * This entrypoint is type-first. Host applications import from here when they
- * want to declare profiles, tool schemas, provider adapters, turn requests, or
- * trace-safe event handlers without importing provider implementations.
- *
  * @module
  */
 import "../../_dnt.polyfills.js";
 export type { CompactionSplit, CompactionTokens } from './engine/compaction.js';
 export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './engine/compaction.js';
 export { runTurn } from './engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
-export type { ProfileDefinition } from './registry/profiles.js';
+export type { RunSessionOptions } from './engine/session/mod.js';
+export { runSession } from './engine/session/mod.js';
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelSpec, } from './registry/catalog.js';
+export type { ImageProfileDefinition, LiveProfileDefinition, ProfileDefinition, ProfileDefinitionBase, SpeechProfileDefinition, TextProfileDefinition, } from './registry/profiles.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
-export { projectProfile, resolveTurn } from './registry/resolve.js';
+export { projectProfile, projectProfileObject, resolveTurn } from './registry/resolve.js';
 export { getStructured, registerStructured } from './registry/schemas.js';
-export { executeTool } from './registry/tools.js';
-export type { ProfileResumeSpec, TurnContinueFrom, TurnStop, TurnStopKind } from './stop.js';
-export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION, DEFAULT_AUTO_CONTINUE, GenerationStopError, isGenerationStopError, isResumeableStop, isUserCancelledStop, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenRouter, } from './stop.js';
+export { ATTACHMENT_ACCEPT_MIMES, COMPACTION_METERS, COMPACTION_TIMINGS, CONTROL_IDS, catalogPathFor, coerceProtocol, coerceProvider, EGRESS_ON_BLOCK, EXTRA_FIELDS, fieldMeta, isValidPair, isValidProfileProtocol, KEY_SLOTS, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, OVERFLOW_KEY_SLOTS, PROFILE_FIELDS, PROFILE_TYPE_PROTOCOLS, PROFILE_TYPES, PROTOCOL_PROVIDERS, PROTOCOLS, PROVIDERS, protocolsFor, protocolsForProfileType, providersFor, SCHEMA_ENFORCEMENTS, SPEECH_AUDIO_FORMATS, STREAM_MODES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
+export type { ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop } from './stop.js';
+export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION, DEFAULT_AUTO_CONTINUE, GenerationStopError, isGenerationStopError, isResumeableStop, isUserCancelledStop, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './stop.js';
+export { formatToolResult, getTool, hasTool, invokeTool, listBuiltinIds, listFunctionIds, listTools, prepareTurnToolSnapshot, registerHarnessTools, registerTool, registerTools, requireTool, resetTools, } from './tools/mod.js';
 export type * from './types.js';

package/esm/src/kernel/mod.js

@@ -1,18 +1,16 @@
 /**
  * Profile, turn, tool, provider, egress, and event contracts for THEORUM.
  *
- * This entrypoint is type-first. Host applications import from here when they
- * want to declare profiles, tool schemas, provider adapters, turn requests, or
- * trace-safe event handlers without importing provider implementations.
- *
  * @module
  */
 import "../../_dnt.polyfills.js";
 export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './engine/compaction.js';
 export { runTurn } from './engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export { runSession } from './engine/session/mod.js';
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelSpec, } from './registry/catalog.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
-export { projectProfile, resolveTurn } from './registry/resolve.js';
+export { projectProfile, projectProfileObject, resolveTurn } from './registry/resolve.js';
 export { getStructured, registerStructured } from './registry/schemas.js';
-export { executeTool } from './registry/tools.js';
-export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION, DEFAULT_AUTO_CONTINUE, GenerationStopError, isGenerationStopError, isResumeableStop, isUserCancelledStop, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenRouter, } from './stop.js';
+export { ATTACHMENT_ACCEPT_MIMES, COMPACTION_METERS, COMPACTION_TIMINGS, CONTROL_IDS, catalogPathFor, coerceProtocol, coerceProvider, EGRESS_ON_BLOCK, EXTRA_FIELDS, fieldMeta, isValidPair, isValidProfileProtocol, KEY_SLOTS, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, OVERFLOW_KEY_SLOTS, PROFILE_FIELDS, PROFILE_TYPE_PROTOCOLS, PROFILE_TYPES, PROTOCOL_PROVIDERS, PROTOCOLS, PROVIDERS, protocolsFor, protocolsForProfileType, providersFor, SCHEMA_ENFORCEMENTS, SPEECH_AUDIO_FORMATS, STREAM_MODES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
+export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION, DEFAULT_AUTO_CONTINUE, GenerationStopError, isGenerationStopError, isResumeableStop, isUserCancelledStop, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './stop.js';
+export { formatToolResult, getTool, hasTool, invokeTool, listBuiltinIds, listFunctionIds, listTools, prepareTurnToolSnapshot, registerHarnessTools, registerTool, registerTools, requireTool, resetTools, } from './tools/mod.js';

package/esm/src/kernel/registry/attachments.d.ts

@@ -1,7 +1,9 @@
-import type { MediaLimits, Profile, TurnBlob } from '../types.js';
+import type { MediaLimits, MimeInputs, Profile, TurnBlob } from '../types.js';
 declare function tooManyFilesMessage(maxFiles: number): string;
 declare function fileTooLargeMessage(maxBytes: number): string;
 declare function turnTooLargeMessage(maxTurnBytes: number): string;
+declare function resolveMediaLimits(inputs: MimeInputs): MediaLimits | undefined;
+declare function maxBytesForMime(mimeType: string, limits: MediaLimits): number;
 declare function requireMediaLimits(profile: Profile): MediaLimits;
 declare function sanitizeCsvText(text: string): string;
 declare function assertAttachmentLimits(blobs: TurnBlob[], limits: MediaLimits): void;
@@ -13,4 +15,4 @@ declare function sanitizeTurnBlobsForProfile(profileId: string, attachments: Tur
     attachments?: TurnBlob[];
     voice?: TurnBlob[];
 };
-export { assertAttachmentLimits, fileTooLargeMessage, requireMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };
+export { assertAttachmentLimits, fileTooLargeMessage, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };

package/esm/src/kernel/registry/attachments.js

@@ -25,7 +25,7 @@ function fileTooLargeMessage(maxBytes) {
 function turnTooLargeMessage(maxTurnBytes) {
     return `Those files together are too large for one message (${formatMb(maxTurnBytes)} max).`;
 }
-function mediaLimits(inputs) {
+function resolveMediaLimits(inputs) {
     const { maxFiles, maxBytes, maxTurnBytes, limitsByMime } = inputs;
     if (maxFiles && maxBytes && maxTurnBytes) {
         return { maxFiles, maxBytes, maxTurnBytes, limitsByMime };
@@ -47,7 +47,10 @@ function maxBytesForMime(mimeType, limits) {
     return limits.maxBytes;
 }
 function requireMediaLimits(profile) {
-    const limits = mediaLimits(profile.inputs);
+    if (profile.type === 'speech') {
+        throw new TheorumError(`Profile ${profile.id} (speech) does not accept media input`);
+    }
+    const limits = resolveMediaLimits(profile.inputs ?? {});
     if (!limits) {
         throw new TheorumError(`Profile ${profile.id} must set maxFiles, maxBytes, and maxTurnBytes`);
     }
@@ -153,4 +156,4 @@ function sanitizeTurnBlobsForProfile(profileId, attachments, voice) {
     const limits = requireMediaLimits(getProfile(profileId));
     return sanitizeTurnBlobs(attachments, voice, limits);
 }
-export { assertAttachmentLimits, fileTooLargeMessage, requireMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };
+export { assertAttachmentLimits, fileTooLargeMessage, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };

package/esm/src/kernel/registry/catalog.d.ts

@@ -1,22 +1,9 @@
 /**
- * Tool catalog and MIME helpers.
- *
- * Model wire metadata is host-owned on `profile.model.config`. This module only
- * keeps builtin/custom tool descriptors and shared MIME utilities.
+ * MIME helpers and model spec utilities.
  *
  * @module
  */
-import type { BuiltinToolId, Catalog, MediaInputKind, ModelId, ModelSpec, Profile, ThinkingLevel, ToolCatalogEntry, ToolId } from '../types.js';
-/** Live tool catalog. Starts with harness tools; presets/hosts register more. */
-declare const CATALOG: Catalog;
-/** Register or replace tool descriptors (idempotent per id). */
-declare function registerTools(entries: Record<string, ToolCatalogEntry>): void;
-/** Look up one registered tool descriptor. */
-declare function getTool(id: ToolId): ToolCatalogEntry | undefined;
-/** Ids of all registered provider builtins. */
-declare function listBuiltinIds(): BuiltinToolId[];
-/** Restore harness-only tools (tests / host reloads). */
-declare function resetTools(): void;
+import type { MediaInputKind, ModelId, ModelSpec, Profile, ThinkingLevel } from '../types.js';
 declare function mimeEssence(mime: string): string;
 declare function mimeAllowed(accept: string[], mime: string): boolean;
 declare function mediaKindForMime(mime: string): MediaInputKind | undefined;
@@ -28,4 +15,4 @@ declare function clampThinkingLevel(spec: ModelSpec, level: ThinkingLevel): Thin
 declare function modelEntryByApiId(specs: Record<string, ModelSpec>, apiId: string): ModelSpec | undefined;
 /** Clamp thinking level using a provider-native API id within a host specs map. */
 declare function clampThinkingLevelForApiId(specs: Record<string, ModelSpec>, apiId: string, level: ThinkingLevel): ThinkingLevel;
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelSpec, };

package/esm/src/kernel/registry/catalog.js

@@ -1,86 +1,10 @@
 /**
- * Tool catalog and MIME helpers.
- *
- * Model wire metadata is host-owned on `profile.model.config`. This module only
- * keeps builtin/custom tool descriptors and shared MIME utilities.
+ * MIME helpers and model spec utilities.
  *
  * @module
  */
 import { TheorumError } from '../../guardrails/error.js';
-const ASK_USER_SCHEMA = {
-    type: 'object',
-    properties: {
-        kind: { type: 'string', enum: ['confirm', 'choice', 'text'] },
-        prompt: { type: 'string' },
-        options: { type: 'array', items: { type: 'string' } },
-    },
-    required: ['kind', 'prompt'],
-};
-/** Harness tools that always ship with THEORUM. */
-const HARNESS_TOOLS = {
-    askUser: { kind: 'custom', ui: true, schema: ASK_USER_SCHEMA },
-};
-/** Live tool catalog. Starts with harness tools; presets/hosts register more. */
-const CATALOG = {
-    tools: { ...HARNESS_TOOLS },
-};
-/** Register or replace tool descriptors (idempotent per id). */
-function registerTools(entries) {
-    Object.assign(CATALOG.tools, entries);
-}
-/** Look up one registered tool descriptor. */
-function getTool(id) {
-    return CATALOG.tools[id];
-}
-/** Ids of all registered provider builtins. */
-function listBuiltinIds() {
-    return Object.entries(CATALOG.tools)
-        .filter(([, entry]) => entry.kind === 'builtin')
-        .map(([id]) => id);
-}
-/** Restore harness-only tools (tests / host reloads). */
-function resetTools() {
-    for (const id of Object.keys(CATALOG.tools)) {
-        delete CATALOG.tools[id];
-    }
-    Object.assign(CATALOG.tools, HARNESS_TOOLS);
-}
-/** MIME essence → normalized media part category (shared ingress map). */
-const MEDIA_INPUT_KINDS = {
-    'image/png': 'image',
-    'image/jpeg': 'image',
-    'image/jpg': 'image',
-    'image/webp': 'image',
-    'image/heic': 'image',
-    'image/heif': 'image',
-    'audio/wav': 'audio',
-    'audio/x-wav': 'audio',
-    'audio/mpeg': 'audio',
-    'audio/mp3': 'audio',
-    'audio/aiff': 'audio',
-    'audio/aac': 'audio',
-    'audio/ogg': 'audio',
-    'audio/flac': 'audio',
-    'audio/webm': 'audio',
-    'audio/mp4': 'audio',
-    'audio/pcm': 'audio',
-    'video/mp4': 'video',
-    'video/mpeg': 'video',
-    'video/quicktime': 'video',
-    'video/x-msvideo': 'video',
-    'video/x-flv': 'video',
-    'video/mpg': 'video',
-    'video/webm': 'video',
-    'video/wmv': 'video',
-    'video/x-ms-wmv': 'video',
-    'video/3gpp': 'video',
-    'application/pdf': 'document',
-    'text/plain': 'document',
-    'text/csv': 'document',
-    'text/markdown': 'document',
-    'text/html': 'document',
-    'application/json': 'document',
-};
+import { MEDIA_INPUT_KINDS } from '../schema.js';
 function mimeEssence(mime) {
     const [base] = mime.split(';');
     return (base ?? '').trim().toLowerCase();
@@ -113,8 +37,8 @@ function clampLevels(entry, level) {
     if (entry.thinkingLevels.includes(level)) {
         return level;
     }
-    const fallback = entry.thinking.off;
-    if (entry.thinkingLevels.includes(fallback)) {
+    const fallback = entry.thinking?.off;
+    if (fallback && entry.thinkingLevels.includes(fallback)) {
         return fallback;
     }
     const first = entry.thinkingLevels[0];
@@ -132,4 +56,4 @@ function modelEntryByApiId(specs, apiId) {
 function clampThinkingLevelForApiId(specs, apiId, level) {
     return clampLevels(modelEntryByApiId(specs, apiId), level);
 }
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelSpec, };

package/esm/src/kernel/registry/ingress.d.ts

@@ -5,9 +5,14 @@
  *
  * @module
  */
-import type { BuiltinToolId, ImageResponseFormat, InteractionPart, ModelId, Profile, TurnRequest } from '../types.js';
+import type { ImageResponseFormat, InteractionPart, ModelId, Profile, TurnRequest } from '../types.js';
+/**
+ * Provider wire formats (JSON schema, image, speech) are mutually exclusive.
+ * Typed profiles make illegal mixes unrepresentable; this remains a safety net
+ * for responseFormat structured on text vs accidental dual modes.
+ */
+declare function assertOutputMode(profile: Profile, structuredId: string | null): void;
 declare function assertSpeechRole(profile: Profile): void;
-declare function resolveImageFormat(profile: Profile, _model: ModelId, slots?: Record<string, string>): ImageResponseFormat | null;
+declare function resolveImageFormat(profile: Profile): ImageResponseFormat | null;
 declare function resolveInputParts(profile: Profile, model: ModelId, req: TurnRequest): InteractionPart[];
-declare function assertImageGrounding(profile: Profile, model: ModelId, builtins: BuiltinToolId[]): void;
-export { assertImageGrounding, assertSpeechRole, resolveImageFormat, resolveInputParts };
+export { assertOutputMode, assertSpeechRole, resolveImageFormat, resolveInputParts };