theorum 0.1.13 → 0.1.15

package/docs/presets-google.md

@@ -0,0 +1,91 @@
+# Google preset (`theorum/presets/google`)
+
+Google / Gemini convenience pack: grounding builtins plus typed vocabularies
+for image and speech-adjacent profile fields.
+
+## Export
+
+| Field | Value |
+| --- | --- |
+| Import | `theorum/presets/google` / `jsr:@theorum/core/presets/google` |
+| Module | `src/presets/google.ts` |
+
+## Ownership
+
+| Path | Role |
+| --- | --- |
+| `src/presets/google.ts` | Google builtins + vocabularies |
+
+## Builtins
+
+`registerGooglePreset()` registers:
+
+| Id | Notes |
+| --- | --- |
+| `googleSearch` | Interactions `google_search`; OpenRouter plugin `web` |
+| `googleMaps` | Interactions `google_maps`; conflicts with `googleSearch` and `urlContext` |
+| `urlContext` | Interactions `url_context` |
+
+All are `kind: 'builtin'` with `ui: true`. Profiles must allowlist ids they use;
+`conflictsWith` drops maps when search/urlContext are also requested.
+
+## Vocabularies
+
+Constants (and matching types) for host profile authoring:
+
+| Constant | Purpose |
+| --- | --- |
+| `GOOGLE_IMAGE_INPUT_MIMES` | png / jpeg / webp / heic / heif |
+| `GOOGLE_VOICE_INPUT_MIMES` | webm / wav / mpeg / mp4 |
+| `GOOGLE_IMAGE_ASPECT_RATIOS` / `GOOGLE_IMAGE_SIZES` | Image output pins |
+| `GOOGLE_SPEECH_VOICES` | TTS voice names for `outputs.speech.voice` |
+| `GoogleImageAspectRatio`, `GoogleImageInputMime`, `GoogleImageSize`, `GoogleVoiceInputMime` | Typed vocabulary unions |
+| `GoogleImagePins`, `GoogleSpeechPins`, `GoogleSpeechVoice` | Typed pins assignable to kernel specs |
+
+Kernel types stay stringly; these packs make Google hosts typed when they opt in.
+
+## Exported API
+
+| Export | Role |
+| --- | --- |
+| `registerGooglePreset` | Register builtins into catalog |
+| `GOOGLE_BUILTIN_TOOLS` | Static catalog entries |
+| `GOOGLE_IMAGE_ASPECT_RATIOS`, `GOOGLE_IMAGE_INPUT_MIMES`, `GOOGLE_IMAGE_SIZES`, `GOOGLE_VOICE_INPUT_MIMES`, `GOOGLE_SPEECH_VOICES` | Typed profile authoring constants |
+| `GoogleImageAspectRatio`, `GoogleImageInputMime`, `GoogleImageSize`, `GoogleVoiceInputMime`, `GoogleImagePins`, `GoogleSpeechPins`, `GoogleSpeechVoice` | Typed pins and vocabularies |
+
+```theorum-evidence
+{
+  "sections": {
+    "Export": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "config", "path": "package.json" }
+      ]
+    },
+    "Ownership": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "graph", "path": "docs/_map.mjs" }
+      ]
+    },
+    "Builtins": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "contract_test", "path": "tests/kernel/theorum.test.ts" }
+      ]
+    },
+    "Vocabularies": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "contract_test", "path": "tests/kernel/theorum.test.ts" }
+      ]
+    },
+    "Exported API": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "source", "path": "src/presets/mod.ts" }
+      ]
+    }
+  }
+}
+```

package/docs/presets.md

@@ -0,0 +1,88 @@
+# Presets (`theorum/presets`)
+
+Optional convenience packs. Presets register host-convenience catalogs
+(provider builtins, media vocabularies) without baking product opinions into the
+kernel.
+
+## Export
+
+| Field | Value |
+| --- | --- |
+| Import | `theorum/presets` / `jsr:@theorum/core/presets` |
+| Module | `src/presets/mod.ts` |
+
+## Ownership
+
+| Path | Role |
+| --- | --- |
+| `src/presets/mod.ts` | Barrel re-exporting the Google pack |
+| `src/presets/google.ts` | Documented in [`GOOGLE.md`](./GOOGLE.md) |
+
+## Role in the package
+
+| Concern | Kernel | Preset |
+| --- | --- | --- |
+| Tool ids | `string` allowlist | Registers `googleSearch`, `googleMaps`, `urlContext` |
+| Image/speech pins | Open `string` fields | Typed constants (`GOOGLE_IMAGE_SIZES`, voices, …) |
+| Registration | `registerTools` API | `registerGooglePreset()` at host startup |
+
+Call preset registration **before** registering profiles that allowlist preset
+builtins. Import `theorum/presets/google` when you only need the Google pack.
+
+Presets are optional — the kernel runs without them when hosts register their
+own tools and vocabularies directly via `registerTools`.
+
+## When to use
+
+| Use preset | Skip preset |
+| --- | --- |
+| Google Gemini hosts wanting typed pins + search/maps/url builtins | Custom tool catalog entirely host-owned |
+| Quick start matching Google Interactions wire types | Non-Google providers only |
+
+## Exported API
+
+This barrel re-exports the Google pack:
+
+| Export | Role |
+| --- | --- |
+| `registerGooglePreset` | Register Google builtins into `CATALOG` |
+| `GOOGLE_BUILTIN_TOOLS` | Catalog entries |
+| `GOOGLE_IMAGE_ASPECT_RATIOS`, `GOOGLE_IMAGE_INPUT_MIMES`, `GOOGLE_IMAGE_SIZES`, `GOOGLE_VOICE_INPUT_MIMES` | Profile authoring constants |
+| `GoogleImageAspectRatio`, `GoogleImageInputMime`, `GoogleImagePins`, `GoogleImageSize`, `GoogleVoiceInputMime` | Typed pins and vocabularies |
+
+```theorum-evidence
+{
+  "sections": {
+    "Export": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/mod.ts" },
+        { "kind": "config", "path": "package.json" }
+      ]
+    },
+    "Ownership": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/mod.ts" },
+        { "kind": "graph", "path": "docs/_map.mjs" }
+      ]
+    },
+    "Role in the package": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/mod.ts" },
+        { "kind": "contract_test", "path": "tests/kernel/theorum.test.ts" }
+      ]
+    },
+    "When to use": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "contract_test", "path": "tests/kernel/theorum.test.ts" }
+      ]
+    },
+    "Exported API": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/mod.ts" },
+        { "kind": "doc", "path": "src/presets/GOOGLE.md" }
+      ]
+    }
+  }
+}
+```

package/docs/providers.md

@@ -0,0 +1,202 @@
+# Providers (`theorum/providers`)
+
+Single door for constructing a `ModelProvider` bound to a profile. Credentials
+and runtime endpoints are always host-supplied arguments — THEORUM does not read
+environment variables and does not ship `.env` files.
+
+## Export
+
+| Field | Value |
+| --- | --- |
+| Import | `theorum/providers` / `jsr:@theorum/core/providers` |
+| Module | `src/providers/mod.ts` |
+| Also on | Root `theorum` re-exports `createProvider` |
+
+## Ownership
+
+Owns every module under `src/providers/` **except** OpenRouter-specific modules
+in [`OPENROUTER.md`](./OPENROUTER.md).
+
+| Module | Role (internal) |
+| --- | --- |
+| `create-provider.ts` | Public factory + lazy OpenRouter chat wrapper |
+| `provider.ts` | Google Interactions streaming adapter |
+| `interactions.ts` | Interactions payload / step wiring |
+| `speech.ts` | OpenRouter `/audio/speech` + Interactions audio paths |
+| `local.ts` | OpenAI-compat SSE for Ollama / llama.cpp / vLLM / LM Studio |
+| `keys.ts` | Gemini vault transport types |
+| `sse.ts` | Shared SSE line parser |
+| `pcm.ts` | PCM → WAV for Interactions speech output |
+| `gemini-tape.ts` / `google-tap.ts` | Test / tap hooks (not public exports) |
+| `expose-for-tests.ts` | `THEORUM_TEST_INTERNALS=1` gated test surface |
+
+## Package boundary
+
+| Rule | Detail |
+| --- | --- |
+| No `.env` in repo | Hosts pass credentials explicitly |
+| No ambient env reads | `OLLAMA_HOST` resolved by host → `local.baseUrl` |
+| No key templates | Business apps own secret storage |
+| Traces | Host-injected on `runTurn`, not here |
+
+## createProvider
+
+```ts
+const provider = createProvider(profile, {
+  gemini: { vault: { freeA, freeB, freeC, paid }, fetch? },
+  openRouter: { apiKey, baseUrl?, siteUrl?, siteName?, fetch?, modelMap?, voice? },
+  local: { baseUrl?, fetch? },
+})
+```
+
+Routing table:
+
+| protocol | provider | Requires | Transport |
+| --- | --- | --- | --- |
+| `geminiInteractions` | `google` | `options.gemini` | Interactions API (chat / image / speech) |
+| `openAi` | `openrouter` | `options.openRouter` | Lazy chat adapter or `speech.ts` when `outputs.speech` |
+| `openAi` | `local` | optional `options.local` | `POST /v1/chat/completions` SSE |
+
+Errors:
+
+- Missing credential block → `TheorumError` naming the required option.
+- Unsupported pair → `TheorumError` with protocol/provider in the message.
+
+OpenRouter Vercel AI SDK loads **only** on first `complete` for `openAi` +
+`openrouter` chat. Google and local never import it.
+
+## Google Interactions
+
+`createInteractionsProvider(geminiTransport)` streams normalized `TurnEvent`s.
+
+| Concern | Behavior |
+| --- | --- |
+| History | `user_input` / `model_output` steps |
+| Multimodal | `image` / `audio` / `video` / `document` parts |
+| Structured | `responseFormat` JSON schema when enforced |
+| Output modes | Image / speech / structured are mutually exclusive |
+| Tools | Catalog `interactionsType` + plugins |
+| Grounding | Classic `grounding_metadata` **and** Interactions `google_search_result` / maps tool payloads (`search_suggestions` chips, annotations). Emits `grounding` (normalized) plus `evidence` with the raw tool payload so hosts can decide what to surface. |
+| Stop | `turnStopFromInteractionStatus` on terminal status |
+
+## Local provider
+
+`createLocalProvider` / `DEFAULT_LOCAL_BASE_URL` (`http://127.0.0.1:11434`). Hosts
+resolve `OLLAMA_HOST` (or similar) themselves and pass `baseUrl` here — THEORUM
+does not read environment variables for local endpoints (see module header in
+`local.ts`, not `docs/SECRETS.md`).
+
+```ts
+local: {
+  baseUrl: "http://127.0.0.1:11434", // no trailing slash
+  fetch: customFetch,
+}
+```
+
+- Raw `fetch` + `sse.ts` — no SDK.
+- Accumulates streaming tool calls; maps `finish_reason` through
+  `turnStopFromOpenRouter`.
+- Supports multimodal user content when the server accepts OpenAI-style parts.
+
+## Speech roles
+
+When `profile.outputs.speech` is defined and protocol/provider is OpenRouter
+OpenAI, `createProvider` returns `createSpeechProvider`:
+
+| Transport | Path | Notes |
+| --- | --- | --- |
+| OpenAI | `/audio/speech` | `mp3` allowed via `response_format` |
+| Interactions | audio `responseFormat` | PCM → WAV; `mp3` rejected at resolve |
+
+Fallback `openRouter.voice` when `outputs.speech.voice` omitted.
+
+## Gemini transport
+
+```ts
+createProvider(profile, {
+  gemini: { vault: { freeA, freeB, freeC, paid } },
+})
+```
+
+| Piece | Role |
+| --- | --- |
+| `GeminiTransport` | Vault + optional `fetch` |
+| Buckets | `freeA`, `freeB`, `freeC`, `paid` |
+| Selection | `model.key` / `ModelSpec.key` / `keyBuiltins` |
+
+Overflow to `paid` is host policy, not inferred here.
+
+## Exported API
+
+From `src/providers/mod.ts` only:
+
+| Export | Kind |
+| --- | --- |
+| `createProvider` | function |
+| `CreateProviderOptions` | type |
+| `GeminiTransport`, `GeminiVault` | types |
+| `createLocalProvider` | function |
+| `LocalProviderConfig` | type |
+| `DEFAULT_LOCAL_BASE_URL` | const |
+
+```theorum-evidence
+{
+  "sections": {
+    "Export": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/mod.ts" },
+        { "kind": "config", "path": "package.json" }
+      ]
+    },
+    "Ownership": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/mod.ts" },
+        { "kind": "graph", "path": "docs/_map.mjs" }
+      ]
+    },
+    "Package boundary": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/create-provider.ts" },
+        { "kind": "contract_test", "path": "tests/providers/create-provider.test.ts" }
+      ]
+    },
+    "createProvider": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/create-provider.ts" },
+        { "kind": "contract_test", "path": "tests/providers/create-provider.test.ts" }
+      ]
+    },
+    "Google Interactions": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/provider.ts" },
+        { "kind": "source", "path": "src/providers/interactions.ts" },
+        { "kind": "contract_test", "path": "tests/providers/interactions.test.ts" }
+      ]
+    },
+    "Local provider": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/local.ts" },
+        { "kind": "contract_test", "path": "tests/providers/local.test.ts" }
+      ]
+    },
+    "Speech roles": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/speech.ts" },
+        { "kind": "contract_test", "path": "tests/providers/speech.test.ts" }
+      ]
+    },
+    "Gemini transport": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/keys.ts" },
+        { "kind": "contract_test", "path": "tests/providers/keys.test.ts" }
+      ]
+    },
+    "Exported API": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/mod.ts" },
+        { "kind": "contract_test", "path": "tests/providers/create-provider.test.ts" }
+      ]
+    }
+  }
+}
+```

package/docs/streaming.md

@@ -0,0 +1,96 @@
+# Streaming (`theorum/streaming`)
+
+Structured-output streaming helpers and turn-stop classification re-exports for
+hosts that want a narrow import without taking the full kernel barrel.
+
+## Export
+
+| Field | Value |
+| --- | --- |
+| Import | `theorum/streaming` / `jsr:@theorum/core/streaming` |
+| Module | `src/streaming/mod.ts` |
+
+## Ownership
+
+| Path | Role |
+| --- | --- |
+| `src/streaming/readStreamingJsonStringField.ts` | Incomplete JSON string preview |
+| `src/streaming/mod.ts` | Barrel + stop re-exports |
+
+Stop source of truth: [`../kernel/CONTRACT.md`](../kernel/CONTRACT.md)
+(`src/kernel/stop.ts`).
+
+## Streaming JSON preview
+
+`readStreamingJsonStringField(jsonText, key)` reads one string field from
+**incomplete** JSON while structured output streams as text deltas.
+
+```ts
+const preview = readStreamingJsonStringField(buffer, "mermaid");
+// returns decoded prefix even before closing quote
+```
+
+| Behavior | Detail |
+| --- | --- |
+| Locator | `"key": "` pattern |
+| Escapes | `\n`, `\t`, `\uXXXX`, … |
+| Incomplete buffer | Returns prefix for live UI preview |
+| Missing key | `null` |
+
+Does not validate full JSON documents.
+
+## Stop re-exports
+
+| Category | Exports |
+| --- | --- |
+| Types | `TurnStop`, `TurnStopKind`, `TurnContinueFrom`, `ProfileResumeSpec` |
+| Constants | `CONTINUE_INSTRUCTION`, `DEFAULT_AUTO_CONTINUE`, `AUTO_CONTINUE_DELAY_MS` |
+| Helpers | `isResumeableStop`, `shouldAutoContinue`, `isUserCancelledStop`, mappers |
+| Errors | `GenerationStopError`, `isGenerationStopError` |
+
+Behavioral contract: kernel **Stop and resume** section.
+
+## Exported API
+
+| Group | Symbols |
+| --- | --- |
+| Streaming JSON | `readStreamingJsonStringField` |
+| Stop / resume (re-export from `kernel/stop.ts`) | `ProfileResumeSpec`, `TurnContinueFrom`, `TurnStop`, `TurnStopKind`, `AUTO_CONTINUE_DELAY_MS`, `CONTINUE_INSTRUCTION`, `DEFAULT_AUTO_CONTINUE`, `GenerationStopError`, `isGenerationStopError`, `isResumeableStop`, `isUserCancelledStop`, `shouldAutoContinue`, `turnStopFromClientStreamEnd`, `turnStopFromInteractionStatus`, `turnStopFromOpenRouter` |
+
+```theorum-evidence
+{
+  "sections": {
+    "Export": {
+      "supports": [
+        { "kind": "source", "path": "src/streaming/mod.ts" },
+        { "kind": "config", "path": "package.json" }
+      ]
+    },
+    "Ownership": {
+      "supports": [
+        { "kind": "source", "path": "src/streaming/mod.ts" },
+        { "kind": "graph", "path": "docs/_map.mjs" }
+      ]
+    },
+    "Streaming JSON preview": {
+      "supports": [
+        { "kind": "source", "path": "src/streaming/readStreamingJsonStringField.ts" },
+        { "kind": "contract_test", "path": "tests/streaming/readStreamingJsonStringField.test.ts" }
+      ]
+    },
+    "Stop re-exports": {
+      "supports": [
+        { "kind": "source", "path": "src/streaming/mod.ts" },
+        { "kind": "source", "path": "src/kernel/stop.ts" },
+        { "kind": "contract_test", "path": "tests/streaming/turnStop.test.ts" }
+      ]
+    },
+    "Exported API": {
+      "supports": [
+        { "kind": "source", "path": "src/streaming/mod.ts" },
+        { "kind": "contract_test", "path": "tests/streaming/readStreamingJsonStringField.test.ts" }
+      ]
+    }
+  }
+}
+```

package/esm/mod.d.ts

@@ -44,7 +44,7 @@ export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, }
 export type { CompactionSplit, CompactionTokens } from './src/kernel/engine/compaction.js';
 export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './src/kernel/engine/compaction.js';
 export { runTurn } from './src/kernel/engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
 export type { ProfileDefinition } from './src/kernel/registry/profiles.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
 export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';

package/esm/mod.js

@@ -42,7 +42,7 @@ export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, }
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
 export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './src/kernel/engine/compaction.js';
 export { runTurn } from './src/kernel/engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
 export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';
 export { getStructured, registerStructured } from './src/kernel/registry/schemas.js';

package/esm/src/kernel/engine/delta.js

@@ -168,6 +168,96 @@ function searchHtml(metadata) {
     }
     return undefined;
 }
+function nonEmptyString(value) {
+    if (typeof value === 'string' && value.trim()) {
+        return value;
+    }
+    return undefined;
+}
+function searchSuggestionsFromRecord(record) {
+    return nonEmptyString(record.search_suggestions ?? record.searchSuggestions);
+}
+function firstSearchSuggestions(items) {
+    if (!Array.isArray(items)) {
+        return undefined;
+    }
+    for (const item of items) {
+        const record = asRecord(item);
+        if (!record) {
+            continue;
+        }
+        const html = searchSuggestionsFromRecord(record);
+        if (html) {
+            return html;
+        }
+    }
+    return undefined;
+}
+/** Interactions streams search chips as `search_suggestions` HTML, not classic entry points. */
+function searchSuggestionsHtml(step) {
+    return (searchSuggestionsFromRecord(step) ??
+        firstSearchSuggestions(step.result) ??
+        firstSearchSuggestions(step.content));
+}
+function sourceFromAnnotation(ann) {
+    const record = asRecord(ann);
+    if (!record) {
+        return undefined;
+    }
+    const uri = nonEmptyString(record.url ?? record.uri);
+    if (!uri) {
+        return undefined;
+    }
+    const kind = String(record.type ?? '');
+    const title = nonEmptyString(record.title ?? record.name) ?? uri;
+    if (kind === 'place_citation') {
+        return { type: 'maps', uri, title };
+    }
+    if (kind === 'url_citation' || kind === 'citation' || !kind) {
+        return { type: 'web', uri, title };
+    }
+    return undefined;
+}
+function appendAnnotationSources(into, annotations) {
+    for (const source of sourcesFromAnnotations(annotations)) {
+        pushUniqueSource(into, source);
+    }
+}
+function sourcesFromAnnotations(annotations) {
+    if (!Array.isArray(annotations)) {
+        return [];
+    }
+    const sources = [];
+    for (const ann of annotations) {
+        pushUniqueSource(sources, sourceFromAnnotation(ann));
+    }
+    return sources;
+}
+/**
+ * Wrap Interactions tool-result steps (google_search_result, maps, etc.) into grounding.
+ * Preserves the raw step on `metadata` so hosts can inspect everything Gemini returned.
+ */
+function groundingFromInteractionsTool(step) {
+    const sources = [];
+    appendAnnotationSources(sources, step.annotations);
+    if (Array.isArray(step.content)) {
+        for (const block of step.content) {
+            const record = asRecord(block);
+            if (record) {
+                appendAnnotationSources(sources, record.annotations);
+            }
+        }
+    }
+    const html = searchSuggestionsHtml(step);
+    if (!html && sources.length === 0) {
+        return undefined;
+    }
+    return {
+        metadata: step,
+        ...(html ? { searchHtml: html } : {}),
+        sources,
+    };
+}
 function sourcesFromChunks(chunks) {
     const sources = [];
     for (const chunk of chunks) {
@@ -238,6 +328,8 @@ function groundingFromStep(stepValue) {
             grounding = mergeGrounding(grounding, groundingFromMetadata(groundingMetadataFromRecord(asRecord(block) ?? {})));
         }
     }
+    // Interactions search/maps tool results: chips + citations live on the step/delta itself.
+    grounding = mergeGrounding(grounding, groundingFromInteractionsTool(step));
     return grounding;
 }
 function groundingFromEvent(event) {

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

@@ -11,7 +11,7 @@ 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, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.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 { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
 export { projectProfile, resolveTurn } from './registry/resolve.js';

package/esm/src/kernel/mod.js

@@ -10,7 +10,7 @@
 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, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
 export { projectProfile, resolveTurn } from './registry/resolve.js';
 export { getStructured, registerStructured } from './registry/schemas.js';

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

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import type { BuiltinToolId, Catalog, GeminiInputKind, ModelId, ModelSpec, Profile, ThinkingLevel, ToolCatalogEntry, ToolId } from '../types.js';
+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). */
@@ -19,7 +19,7 @@ declare function listBuiltinIds(): BuiltinToolId[];
 declare function resetTools(): void;
 declare function mimeEssence(mime: string): string;
 declare function mimeAllowed(accept: string[], mime: string): boolean;
-declare function geminiKindForMime(mime: string): GeminiInputKind | undefined;
+declare function mediaKindForMime(mime: string): MediaInputKind | undefined;
 /** Require a host-declared model spec for an allowed profile model id. */
 declare function requireModelSpec(profile: Profile, modelId: ModelId): ModelSpec;
 /** Clamp a requested thinking level to what the model spec accepts. */
@@ -28,4 +28,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, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };