theorum 0.1.15 → 1.1.3

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

@@ -48,12 +48,173 @@ function eventsFromAudio(delta) {
     }
     return [];
 }
+function nonEmptyString(value) {
+    if (typeof value === 'string' && value.trim()) {
+        return value;
+    }
+    return undefined;
+}
+function isCodeExecutionType(type) {
+    return type === 'code_execution_call' || type === 'code_execution_result';
+}
+function isGoogleBuiltinStepType(type) {
+    return type.startsWith('google_') || type === 'url_context_call' || type === 'url_context_result';
+}
+function googleBuiltinEvidence(raw) {
+    const type = String(raw.type ?? '');
+    return {
+        type: 'evidence',
+        evidence: {
+            provider: 'google',
+            raw,
+            ...(type ? { kind: type } : {}),
+        },
+    };
+}
+function mergeSandboxString(prev, next) {
+    if (typeof next !== 'string') {
+        return typeof prev === 'string' ? prev : undefined;
+    }
+    if (typeof prev !== 'string' || !prev) {
+        return next;
+    }
+    if (next.startsWith(prev) || prev.endsWith(next)) {
+        return next.length >= prev.length ? next : prev;
+    }
+    return prev + next;
+}
+function argumentsField(record) {
+    if (!record) {
+        return undefined;
+    }
+    return record.arguments;
+}
+function mergedArgObject(prevArgs, incomingArgs) {
+    const language = incomingArgs?.language;
+    return {
+        ...prevArgs,
+        ...incomingArgs,
+        code: mergeSandboxString(prevArgs?.code, incomingArgs?.code),
+        language: language === undefined ? prevArgs?.language : language,
+    };
+}
+function mergeStringArguments(prev, next) {
+    if (typeof next === 'string') {
+        return mergeSandboxString(prev, next);
+    }
+    if (typeof prev === 'string') {
+        return mergeSandboxString(prev, next);
+    }
+    if (next !== undefined) {
+        return next;
+    }
+    return prev;
+}
+function mergeCodeExecutionArguments(existing, incoming) {
+    const prevArgs = asRecord(argumentsField(existing));
+    const incomingArgs = asRecord(incoming.arguments);
+    if (prevArgs) {
+        return mergedArgObject(prevArgs, incomingArgs);
+    }
+    if (incomingArgs) {
+        return mergedArgObject(prevArgs, incomingArgs);
+    }
+    return mergeStringArguments(argumentsField(existing), incoming.arguments);
+}
+/** Merge a later code-exec delta/step onto an earlier snapshot (partial code/stdout). */
+function mergeCodeExecutionPayload(existing, incoming) {
+    const next = { ...existing, ...incoming };
+    const argumentsValue = mergeCodeExecutionArguments(existing, incoming);
+    if (argumentsValue !== undefined) {
+        next.arguments = argumentsValue;
+    }
+    const result = mergeSandboxString(existing?.result, incoming.result);
+    if (result !== undefined) {
+        next.result = result;
+    }
+    return next;
+}
+function codeFromArguments(args) {
+    if (typeof args === 'string') {
+        return { code: args };
+    }
+    const rec = asRecord(args);
+    if (!rec) {
+        return {};
+    }
+    return {
+        ...(typeof rec.code === 'string' ? { code: rec.code } : {}),
+        ...(typeof rec.language === 'string' ? { language: rec.language } : {}),
+    };
+}
+function sandboxReportedError(raw) {
+    if (raw.is_error === undefined && raw.isError === undefined) {
+        return undefined;
+    }
+    return raw.is_error === true || raw.isError === true;
+}
+function applyCodeExecutionFields(evidence, raw) {
+    const type = String(raw.type ?? '');
+    if (isCodeExecutionType(type)) {
+        evidence.kind = type;
+    }
+    const fromArgs = codeFromArguments(raw.arguments);
+    if (fromArgs.code) {
+        evidence.code = fromArgs.code;
+    }
+    if (fromArgs.language) {
+        evidence.language = fromArgs.language;
+    }
+    if (typeof raw.result === 'string') {
+        evidence.result = raw.result;
+    }
+    const isError = sandboxReportedError(raw);
+    if (isError !== undefined) {
+        evidence.isError = isError;
+    }
+    const id = nonEmptyString(raw.id);
+    if (id) {
+        evidence.id = id;
+    }
+    const callId = nonEmptyString(raw.call_id ?? raw.callId);
+    if (callId) {
+        evidence.callId = callId;
+    }
+}
+/** Normalize a Google `code_execution_*` step/delta into an `evidence` event. */
+function codeExecutionEvidence(raw) {
+    const evidence = { provider: 'google', raw };
+    applyCodeExecutionFields(evidence, raw);
+    return { type: 'evidence', evidence };
+}
+/** Stable key so streamed deltas and batched `steps[]` do not double-emit. */
+function codeExecutionStepKey(raw, index) {
+    const type = String(raw.type ?? 'code_execution');
+    const id = nonEmptyString(raw.id) ?? nonEmptyString(raw.call_id ?? raw.callId);
+    if (id) {
+        return `${type}:${id}`;
+    }
+    const fromArgs = codeFromArguments(raw.arguments);
+    if (fromArgs.code) {
+        return `${type}:code:${fromArgs.code}`;
+    }
+    if (typeof raw.result === 'string') {
+        return `${type}:result:${raw.result}`;
+    }
+    if (raw.result !== undefined) {
+        return `${type}:result:${JSON.stringify(raw.result)}`;
+    }
+    return `${type}:idx:${String(index ?? '')}`;
+}
 function eventsFromDelta(deltaValue) {
     const delta = asRecord(deltaValue);
     if (!delta) {
         return [];
     }
     const deltaType = String(delta.type ?? '');
+    if (isCodeExecutionType(deltaType)) {
+        return [codeExecutionEvidence(delta)];
+    }
     if (deltaType === 'thought_summary' || deltaType === 'thought') {
         return eventIfText('thought', delta);
     }
@@ -86,51 +247,166 @@ function mediaFromOutputItem(item) {
     }
     return mediaFromRecord(rec);
 }
-function mediaFromOutputs(outputs) {
+function mediaEventsFromOutputs(outputs) {
     if (!Array.isArray(outputs)) {
-        return undefined;
+        return [];
     }
+    const events = [];
     for (const item of outputs) {
         const media = mediaFromOutputItem(item);
         if (media) {
-            return media;
+            events.push(media);
         }
     }
-    return undefined;
+    return events;
 }
-function mediaFromComplete(event) {
+function mediaEventsFromComplete(event) {
     const interaction = asRecord(event.interaction) ?? event;
+    const events = [];
     const directImage = asRecord(interaction.output_image);
     if (directImage) {
         const media = mediaFromRecord(directImage);
         if (media) {
-            return media;
+            events.push(media);
         }
     }
     const directAudio = asRecord(interaction.output_audio);
     if (directAudio) {
         const media = mediaFromRecord(directAudio);
         if (media) {
-            return media;
+            events.push(media);
         }
-        // Google TTS convenience field: base64 PCM without mime.
-        const { data } = directAudio;
-        if (typeof data === 'string' && data) {
-            return { type: 'media', media: { mimeType: 'audio/pcm', data } };
+        else {
+            const { data } = directAudio;
+            if (typeof data === 'string' && data) {
+                events.push({ type: 'media', media: { mimeType: 'audio/pcm', data } });
+            }
         }
     }
-    return mediaFromOutputs(interaction.outputs);
+    if (events.length === 0) {
+        events.push(...mediaEventsFromOutputs(interaction.outputs));
+    }
+    return events;
+}
+function eventsFromModelOutputContent(step, alreadyText) {
+    const events = [];
+    const content = step.content;
+    if (!Array.isArray(content)) {
+        return events;
+    }
+    for (const block of content) {
+        const rec = asRecord(block);
+        if (!rec) {
+            continue;
+        }
+        const type = String(rec.type ?? '');
+        if (type === 'text' && !alreadyText) {
+            events.push(...eventIfText('text', rec));
+        }
+        if (type === 'image' || type === 'media') {
+            events.push(...eventsFromImage(rec));
+        }
+        if (type === 'audio' || type === 'output_audio') {
+            events.push(...eventsFromAudio(rec));
+        }
+    }
+    return events;
+}
+function eventsFromInteractionStep(step, sawText) {
+    const type = String(step.type ?? '');
+    if (isCodeExecutionType(type)) {
+        return { events: [codeExecutionEvidence(step)], sawText };
+    }
+    if (isGoogleBuiltinStepType(type)) {
+        return { events: [googleBuiltinEvidence(step)], sawText };
+    }
+    if (type !== 'model_output') {
+        return { events: [], sawText };
+    }
+    const fromOutput = eventsFromModelOutputContent(step, sawText);
+    return {
+        events: fromOutput,
+        sawText: sawText || fromOutput.some((item) => item.type === 'text'),
+    };
+}
+/**
+ * Replay a completed Interactions `steps[]` array (non-SSE or stream tail).
+ * Emits typed code-execution evidence plus model_output text/media.
+ */
+function eventsFromInteractionSteps(steps, alreadyText) {
+    const events = [];
+    let sawText = alreadyText;
+    for (const stepValue of steps) {
+        const step = asRecord(stepValue);
+        if (!step) {
+            continue;
+        }
+        const next = eventsFromInteractionStep(step, sawText);
+        events.push(...next.events);
+        sawText = next.sawText;
+    }
+    return events;
+}
+function cleanMapsTitle(title) {
+    const suffix = 'google maps';
+    const trimmed = title.trimEnd();
+    if (trimmed.length < suffix.length) {
+        return title.trim();
+    }
+    if (trimmed.slice(-suffix.length).toLowerCase() !== suffix) {
+        return title.trim();
+    }
+    let end = trimmed.length - suffix.length;
+    while (end > 0 && /\s/.test(trimmed[end - 1])) {
+        end--;
+    }
+    if (end > 0 && trimmed[end - 1] === '-') {
+        end--;
+        while (end > 0 && /\s/.test(trimmed[end - 1])) {
+            end--;
+        }
+    }
+    return trimmed.slice(0, end).trimEnd();
+}
+function isPrimaryMapsPlace(name, uri) {
+    if (/^Review of\b/i.test(name)) {
+        return false;
+    }
+    if (/\/maps\/reviews\//i.test(uri)) {
+        return false;
+    }
+    return true;
+}
+function placeIdFromRecord(record) {
+    return nonEmptyString(record.placeId ?? record.place_id);
 }
 function sourceFromMaps(maps) {
-    const uri = maps.uri ?? maps.googleMapsUri ?? maps.google_maps_uri;
+    const uri = maps.uri ?? maps.googleMapsUri ?? maps.google_maps_uri ?? maps.url;
     if (typeof uri !== 'string' || !uri) {
         return undefined;
     }
-    const title = maps.title ?? maps.name;
+    const rawTitle = maps.title ?? maps.name;
+    const title = typeof rawTitle === 'string' && rawTitle ? cleanMapsTitle(rawTitle) : uri;
+    const placeId = placeIdFromRecord(maps);
     return {
         type: 'maps',
         uri,
-        title: typeof title === 'string' && title ? title : uri,
+        title,
+        ...(placeId ? { placeId } : {}),
+    };
+}
+/** Classic grounding chunk shape hosts already parse (`chunks[].maps`). */
+function chunkFromMapsPlace(place) {
+    const source = sourceFromMaps(place);
+    if (!source || !isPrimaryMapsPlace(source.title, source.uri)) {
+        return undefined;
+    }
+    return {
+        maps: {
+            title: source.title,
+            uri: source.uri,
+            ...(source.placeId ? { placeId: source.placeId } : {}),
+        },
     };
 }
 function sourceFromWeb(web) {
@@ -149,9 +425,18 @@ function pushUniqueSource(sources, source) {
     if (!source) {
         return;
     }
-    if (!sources.some((item) => item.uri === source.uri && item.type === source.type)) {
-        sources.push(source);
+    if (sources.some((item) => {
+        if (item.type !== source.type) {
+            return false;
+        }
+        if (source.placeId && item.placeId && source.placeId === item.placeId) {
+            return true;
+        }
+        return item.uri === source.uri;
+    })) {
+        return;
     }
+    sources.push(source);
 }
 function groundingChunks(metadata) {
     const chunks = metadata.groundingChunks ?? metadata.grounding_chunks;
@@ -168,12 +453,6 @@ 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);
 }
@@ -209,15 +488,79 @@ function sourceFromAnnotation(ann) {
         return undefined;
     }
     const kind = String(record.type ?? '');
-    const title = nonEmptyString(record.title ?? record.name) ?? uri;
+    const rawTitle = nonEmptyString(record.title ?? record.name) ?? uri;
     if (kind === 'place_citation') {
-        return { type: 'maps', uri, title };
+        const title = cleanMapsTitle(rawTitle);
+        if (!isPrimaryMapsPlace(title, uri)) {
+            return undefined;
+        }
+        const placeId = placeIdFromRecord(record);
+        return {
+            type: 'maps',
+            uri,
+            title,
+            ...(placeId ? { placeId } : {}),
+        };
     }
     if (kind === 'url_citation' || kind === 'citation' || !kind) {
-        return { type: 'web', uri, title };
+        return { type: 'web', uri, title: rawTitle };
     }
     return undefined;
 }
+function pushUniqueChunk(chunks, chunk) {
+    const maps = asRecord(asRecord(chunk)?.maps);
+    if (!maps) {
+        chunks.push(chunk);
+        return;
+    }
+    const placeId = placeIdFromRecord(maps);
+    const uri = nonEmptyString(maps.uri ?? maps.url);
+    if (chunks.some((existing) => {
+        const existingMaps = asRecord(asRecord(existing)?.maps);
+        if (!existingMaps) {
+            return false;
+        }
+        const existingId = placeIdFromRecord(existingMaps);
+        if (placeId && existingId && placeId === existingId) {
+            return true;
+        }
+        return Boolean(uri && nonEmptyString(existingMaps.uri ?? existingMaps.url) === uri);
+    })) {
+        return;
+    }
+    chunks.push(chunk);
+}
+/** Interactions `google_maps_result.result[].places[]` — not classic groundingChunks. */
+function chunksAndSourcesFromMapsResult(result) {
+    const chunks = [];
+    const sources = [];
+    if (!Array.isArray(result)) {
+        return { chunks, sources };
+    }
+    for (const entry of result) {
+        const record = asRecord(entry);
+        if (!record) {
+            continue;
+        }
+        const places = record.places;
+        if (!Array.isArray(places)) {
+            continue;
+        }
+        for (const placeValue of places) {
+            const place = asRecord(placeValue);
+            if (!place) {
+                continue;
+            }
+            const chunk = chunkFromMapsPlace(place);
+            if (!chunk) {
+                continue;
+            }
+            pushUniqueChunk(chunks, chunk);
+            pushUniqueSource(sources, sourceFromMaps(place));
+        }
+    }
+    return { chunks, sources };
+}
 function appendAnnotationSources(into, annotations) {
     for (const source of sourcesFromAnnotations(annotations)) {
         pushUniqueSource(into, source);
@@ -236,9 +579,15 @@ function sourcesFromAnnotations(annotations) {
 /**
  * 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.
+ *
+ * Maps places arrive as `google_maps_result.result[].places[]` and as
+ * `place_citation` annotations on model_output content — not classic
+ * `grounding_metadata.groundingChunks`. Emit both `sources` and `chunks`
+ * (`chunks[].maps`) so hosts share one parse shape.
  */
 function groundingFromInteractionsTool(step) {
     const sources = [];
+    const chunks = [];
     appendAnnotationSources(sources, step.annotations);
     if (Array.isArray(step.content)) {
         for (const block of step.content) {
@@ -248,12 +597,32 @@ function groundingFromInteractionsTool(step) {
             }
         }
     }
+    for (const source of sources) {
+        if (source.type !== 'maps') {
+            continue;
+        }
+        pushUniqueChunk(chunks, {
+            maps: {
+                title: source.title,
+                uri: source.uri,
+                ...(source.placeId ? { placeId: source.placeId } : {}),
+            },
+        });
+    }
+    const fromMapsResult = chunksAndSourcesFromMapsResult(step.result);
+    for (const chunk of fromMapsResult.chunks) {
+        pushUniqueChunk(chunks, chunk);
+    }
+    for (const source of fromMapsResult.sources) {
+        pushUniqueSource(sources, source);
+    }
     const html = searchSuggestionsHtml(step);
-    if (!html && sources.length === 0) {
+    if (!html && sources.length === 0 && chunks.length === 0) {
         return undefined;
     }
     return {
         metadata: step,
+        ...(chunks.length > 0 ? { chunks } : {}),
         ...(html ? { searchHtml: html } : {}),
         sources,
     };
@@ -283,7 +652,10 @@ function mergeGrounding(a, b) {
     if (!b) {
         return a;
     }
-    const chunks = [...(a.chunks ?? []), ...(b.chunks ?? [])];
+    const chunks = [];
+    for (const chunk of [...(a.chunks ?? []), ...(b.chunks ?? [])]) {
+        pushUniqueChunk(chunks, chunk);
+    }
     const sources = [...a.sources];
     for (const source of b.sources) {
         pushUniqueSource(sources, source);
@@ -391,6 +763,27 @@ const TOOL_KEYS = [
     'toolTokens',
     'toolUse',
 ];
+const INTERMEDIATE_KEYS = [
+    'total_intermediate_tokens',
+    'totalIntermediateTokens',
+    'intermediate_tokens',
+    'intermediateTokens',
+    'intermediate',
+];
+const CACHED_KEYS = [
+    'total_cached_tokens',
+    'totalCachedTokens',
+    'cached_tokens',
+    'cachedTokens',
+    'cached',
+];
+const CACHE_WRITE_KEYS = [
+    'cache_write_tokens',
+    'cacheWriteTokens',
+    'cache_creation_input_tokens',
+    'cacheCreationInputTokens',
+    'cacheWrite',
+];
 const TOTAL_KEYS = [
     'total_tokens',
     'totalTokens',
@@ -410,18 +803,53 @@ function pickNumericField(record, keys) {
     }
     return 0;
 }
+function detailsRecord(raw) {
+    for (const key of [
+        'prompt_tokens_details',
+        'promptTokensDetails',
+        'input_tokens_details',
+        'inputTokensDetails',
+    ]) {
+        const value = raw[key];
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
 function extractUsageTokens(raw) {
     if (!raw || typeof raw !== 'object') {
         return undefined;
     }
     const r = raw;
+    const details = detailsRecord(r);
     const input = pickNumericField(r, INPUT_KEYS);
     const output = pickNumericField(r, OUTPUT_KEYS);
     const thinking = pickNumericField(r, THINKING_KEYS);
     const toolUse = pickNumericField(r, TOOL_KEYS);
-    const total = pickNumericField(r, TOTAL_KEYS) || input + output + thinking + toolUse;
-    if (input > 0 || output > 0 || thinking > 0 || toolUse > 0 || total > 0) {
-        return { input, output, thinking, toolUse, total };
+    const intermediate = pickNumericField(r, INTERMEDIATE_KEYS);
+    const cached = pickNumericField(r, CACHED_KEYS) || (details ? pickNumericField(details, CACHED_KEYS) : 0);
+    const cacheWrite = pickNumericField(r, CACHE_WRITE_KEYS) ||
+        (details ? pickNumericField(details, CACHE_WRITE_KEYS) : 0);
+    const total = pickNumericField(r, TOTAL_KEYS) || input + output + thinking + toolUse + intermediate;
+    if (input > 0 ||
+        output > 0 ||
+        thinking > 0 ||
+        toolUse > 0 ||
+        intermediate > 0 ||
+        cached > 0 ||
+        cacheWrite > 0 ||
+        total > 0) {
+        return {
+            input,
+            output,
+            thinking,
+            toolUse,
+            total,
+            ...(intermediate > 0 ? { intermediate } : {}),
+            ...(cached > 0 ? { cached } : {}),
+            ...(cacheWrite > 0 ? { cacheWrite } : {}),
+        };
     }
     return undefined;
 }
@@ -453,13 +881,23 @@ function extractTokenEvent(event, interaction) {
 function eventsFromComplete(event, alreadyText) {
     const interaction = asRecord(event.interaction) ?? event;
     const events = [];
+    let sawText = alreadyText;
+    const steps = interaction.steps;
+    if (Array.isArray(steps)) {
+        const fromSteps = eventsFromInteractionSteps(steps, sawText);
+        events.push(...fromSteps);
+        if (fromSteps.some((item) => item.type === 'text')) {
+            sawText = true;
+        }
+    }
     const outputText = interaction.output_text;
-    if (!alreadyText && typeof outputText === 'string' && outputText) {
+    if (!sawText && typeof outputText === 'string' && outputText) {
         events.push({ type: 'text', text: outputText });
+        sawText = true;
+    }
+    if (!events.some((item) => item.type === 'media')) {
+        events.push(...mediaEventsFromComplete(event));
     }
-    const media = mediaFromComplete(event);
-    if (media)
-        events.push(media);
     const tokenEvent = extractTokenEvent(event, interaction);
     if (tokenEvent)
         events.push(tokenEvent);
@@ -493,12 +931,13 @@ function doneFromInteractionStatus(interaction, event) {
         ...(typeof interaction.id === 'string' ? { interactionId: interaction.id } : {}),
     };
 }
-function tryStructured(text) {
+/** Parse model text as structured JSON. Invalid JSON is a hard failure — never silent skip. */
+function parseStructuredOutput(text) {
     try {
-        return { type: 'structured', structured: JSON.parse(text) };
+        return { ok: true, structured: JSON.parse(text) };
     }
     catch {
-        return undefined;
+        return { ok: false, error: 'structured output was not valid JSON' }; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
 }
-export { eventsFromComplete, eventsFromDelta, extractTokenEvent, extractUsageTokens, groundingFromEvent, tryStructured, };
+export { codeExecutionEvidence, codeExecutionStepKey, eventsFromComplete, eventsFromDelta, eventsFromInteractionSteps, extractTokenEvent, extractUsageTokens, googleBuiltinEvidence, groundingFromEvent, isCodeExecutionType, isGoogleBuiltinStepType, mergeCodeExecutionPayload, parseStructuredOutput, };

package/esm/src/kernel/engine/live-inbound.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Live realtime inbound text — same sanitize + user_data fence as runTurn ingress.
+ *
+ * @module
+ */
+import type { Profile, TurnEvent } from '../types.js';
+export interface LiveInboundPrepareResult {
+    text: string;
+    /** Present when inbound sanitize redacted spans. */
+    guardrail?: TurnEvent;
+}
+/**
+ * Sanitize profile-controlled inbound text and wrap with user_data fencing.
+ *
+ * Resolves through the shared policy so Live ingress and the turn engine cannot
+ * drift apart on what an unset switch means. Returns an optional guardrail event
+ * for the session stream when redaction ran. Match previews follow
+ * `observability.include.guardrailMatchPreview`.
+ */
+declare function prepareLiveInboundText(profile: Profile, text: string): LiveInboundPrepareResult;
+export { prepareLiveInboundText };