theorum 0.1.14 → 0.1.15

package/README.md

@@ -10,6 +10,8 @@
 
 # THEORUM: The Flat Agent Kernel
 
+**Current release: `0.1.15`** (`jsr:@theorum/core` / npm `theorum`).
+
 > **"Profiles describe the contract. Providers move bytes. The runner enforces the turn."**
 
 THEORUM is a compact TypeScript agent kernel for apps that need deterministic agent execution without embedding product logic inside the runtime. It gives a host application one runner, typed profiles, multimodal input normalization, dynamic tool dispatch, provider adapters, trace sinks, and guardrail hooks.

package/docs/kernel.md

@@ -102,7 +102,7 @@ different transport than the primary turn.
 | `tool` | Tool call envelope (`ok` / `error` / `pause`) |
 | `structured` | Parsed JSON object when schema enforced |
 | `media` | Generated image/audio bytes + mime |
-| `grounding` | Search/maps grounding metadata |
+| `grounding` | Search/maps grounding metadata (classic `grounding_metadata` and Interactions tool results such as `google_search_result.search_suggestions`) |
 | `evidence` | Provider-native evidence attachments |
 | `tokens` | `input` / `output` / `total` usage (billing; may gate `meter: 'input'`) |
 | `done` | Terminal: `stop`, `tokens`, `compaction`, final text pointer |

package/docs/providers.md

@@ -76,6 +76,7 @@ OpenRouter Vercel AI SDK loads **only** on first `complete` for `openAi` +
 | 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

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/providers/provider.js

@@ -10,6 +10,7 @@
  */
 import { isAbortError, TheorumError, toErrorEvent } from '../guardrails/error.js';
 import { eventsFromComplete, eventsFromDelta, extractTokenEvent, groundingFromEvent, tryStructured, } from '../kernel/engine/delta.js';
+import { asRecord } from '../kernel/engine/record.js';
 import { exposeForTests } from './expose-for-tests.js';
 import { tapFetch } from './google-tap.js';
 import { toInteractionsBody } from './interactions.js';
@@ -109,8 +110,32 @@ function foldPayload(event, acc) {
     if (groundingEvent && !events.some((e) => e.type === 'grounding')) {
         events.push(groundingEvent);
     }
+    const evidenceEvent = evidenceFromGooglePayload(event);
+    if (evidenceEvent && !events.some((e) => e.type === 'evidence')) {
+        events.push(evidenceEvent);
+    }
     return events;
 }
+/** Preserve raw Google Interactions tool payloads so hosts can inspect everything returned. */
+function evidenceFromGooglePayload(event) {
+    for (const key of ['delta', 'step']) {
+        const payload = asRecord(event[key]);
+        if (!payload) {
+            continue;
+        }
+        const type = String(payload.type ?? '');
+        if (type === 'google_search_result' ||
+            type === 'google_maps' ||
+            type === 'google_maps_result' ||
+            type.startsWith('google_')) {
+            return {
+                type: 'evidence',
+                evidence: { provider: 'google', raw: payload },
+            };
+        }
+    }
+    return undefined;
+}
 function withTap(req, transport) {
     return {
         ...transport,
@@ -172,5 +197,6 @@ exposeForTests('provider', {
     isCompleteEvent,
     foldDeltaPayload,
     foldPayload,
+    evidenceFromGooglePayload,
     withTap,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theorum",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",