@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/providers/google/grounding.js

@@ -0,0 +1,226 @@
+import { asRecord, nonEmptyString } from '../../kernel/engine/record.js';
+function groundedEvents(grounded) {
+    if (!grounded)
+        return [];
+    const { grounding, sources } = grounded;
+    return [
+        { type: 'grounding', grounding },
+        ...(sources.length > 0 ? [{ type: 'citation', sources }] : []),
+    ];
+}
+function sourceFromPlace(place) {
+    const uri = nonEmptyString(place.url);
+    if (!uri) {
+        return undefined;
+    }
+    const placeId = nonEmptyString(place.place_id);
+    return {
+        type: 'maps',
+        uri,
+        title: nonEmptyString(place.name) ?? uri,
+        ...(placeId ? { placeId } : {}),
+    };
+}
+function chunkFromMapsSource(source) {
+    return {
+        maps: {
+            title: source.title,
+            uri: source.uri,
+            ...(source.placeId ? { placeId: source.placeId } : {}),
+        },
+    };
+}
+function sourceFromWeb(web) {
+    const uri = nonEmptyString(web.uri);
+    if (!uri) {
+        return undefined;
+    }
+    return { type: 'web', uri, title: nonEmptyString(web.title) ?? uri };
+}
+function pushUniqueSource(sources, source) {
+    if (!source) {
+        return;
+    }
+    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 pushUniqueChunk(chunks, chunk) {
+    const maps = asRecord(asRecord(chunk)?.maps);
+    if (!maps) {
+        chunks.push(chunk);
+        return;
+    }
+    const placeId = nonEmptyString(maps.placeId);
+    const uri = nonEmptyString(maps.uri);
+    if (chunks.some((existing) => {
+        const existingMaps = asRecord(asRecord(existing)?.maps);
+        if (!existingMaps) {
+            return false;
+        }
+        const existingId = nonEmptyString(existingMaps.placeId);
+        if (placeId && existingId && placeId === existingId) {
+            return true;
+        }
+        return Boolean(uri && nonEmptyString(existingMaps.uri) === uri);
+    })) {
+        return;
+    }
+    chunks.push(chunk);
+}
+function searchSuggestionsHtml(result) {
+    if (!Array.isArray(result)) {
+        return undefined;
+    }
+    for (const entry of result) {
+        const html = nonEmptyString(asRecord(entry)?.search_suggestions);
+        if (html) {
+            return html;
+        }
+    }
+    return undefined;
+}
+function sourceFromAnnotation(ann) {
+    const record = asRecord(ann);
+    const uri = nonEmptyString(record?.url);
+    if (!record || !uri) {
+        return undefined;
+    }
+    if (record.type === 'place_citation') {
+        const title = nonEmptyString(record.name) ?? uri;
+        const placeId = nonEmptyString(record.place_id);
+        return { type: 'maps', uri, title, ...(placeId ? { placeId } : {}) };
+    }
+    if (record.type === 'url_citation') {
+        return { type: 'web', uri, title: nonEmptyString(record.title) ?? uri };
+    }
+    return undefined;
+}
+function appendAnnotationSources(into, annotations) {
+    if (!Array.isArray(annotations)) {
+        return;
+    }
+    for (const ann of annotations) {
+        pushUniqueSource(into, sourceFromAnnotation(ann));
+    }
+}
+function appendPlaceSources(into, result) {
+    if (!Array.isArray(result)) {
+        return;
+    }
+    for (const entry of result) {
+        const places = asRecord(entry)?.places;
+        if (!Array.isArray(places)) {
+            continue;
+        }
+        for (const placeValue of places) {
+            const place = asRecord(placeValue);
+            const source = place ? sourceFromPlace(place) : undefined;
+            if (source) {
+                pushUniqueSource(into, source);
+            }
+        }
+    }
+}
+/** Maps sources also emit normalized `chunks[].maps` so hosts share one parse shape with Live. */
+function groundingFromInteractionsStep(step) {
+    const sources = [];
+    appendAnnotationSources(sources, step.annotations);
+    if (Array.isArray(step.content)) {
+        for (const block of step.content) {
+            appendAnnotationSources(sources, asRecord(block)?.annotations);
+        }
+    }
+    appendPlaceSources(sources, step.result);
+    const chunks = [];
+    for (const source of sources) {
+        if (source.type === 'maps') {
+            pushUniqueChunk(chunks, chunkFromMapsSource(source));
+        }
+    }
+    const html = searchSuggestionsHtml(step.result);
+    if (!html && sources.length === 0) {
+        return undefined;
+    }
+    return {
+        grounding: {
+            metadata: step,
+            ...(chunks.length > 0 ? { chunks } : {}),
+            ...(html ? { searchHtml: html } : {}),
+        },
+        sources,
+    };
+}
+function mergeGrounding(a, b) {
+    if (!a) {
+        return b;
+    }
+    if (!b) {
+        return a;
+    }
+    const chunks = [];
+    for (const chunk of [...(a.grounding.chunks ?? []), ...(b.grounding.chunks ?? [])]) {
+        pushUniqueChunk(chunks, chunk);
+    }
+    const sources = [...a.sources];
+    for (const source of b.sources) {
+        pushUniqueSource(sources, source);
+    }
+    const searchHtml = b.grounding.searchHtml ?? a.grounding.searchHtml;
+    const metadata = b.grounding.metadata ?? a.grounding.metadata;
+    return {
+        grounding: {
+            ...(metadata ? { metadata } : {}),
+            ...(chunks.length > 0 ? { chunks } : {}),
+            ...(searchHtml ? { searchHtml } : {}),
+        },
+        sources,
+    };
+}
+function groundingFromDelta(event) {
+    const delta = asRecord(event.delta);
+    return groundedEvents(delta ? groundingFromInteractionsStep(delta) : undefined);
+}
+function groundingFromSteps(steps) {
+    let grounded;
+    for (const stepValue of steps) {
+        const step = asRecord(stepValue);
+        if (step) {
+            grounded = mergeGrounding(grounded, groundingFromInteractionsStep(step));
+        }
+    }
+    return groundedEvents(grounded);
+}
+function groundingFromLiveMetadata(value) {
+    const metadata = asRecord(value);
+    if (!metadata) {
+        return [];
+    }
+    const chunks = Array.isArray(metadata.groundingChunks) ? metadata.groundingChunks : [];
+    const sources = [];
+    for (const chunk of chunks) {
+        const web = asRecord(asRecord(chunk)?.web);
+        if (web) {
+            pushUniqueSource(sources, sourceFromWeb(web));
+        }
+    }
+    const html = nonEmptyString(asRecord(metadata.searchEntryPoint)?.renderedContent);
+    return groundedEvents({
+        grounding: {
+            metadata,
+            ...(chunks.length > 0 ? { chunks } : {}),
+            ...(html ? { searchHtml: html } : {}),
+        },
+        sources,
+    });
+}
+export { groundingFromDelta, groundingFromLiveMetadata, groundingFromSteps };

package/esm/src/providers/google/interactions/framing.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { InteractionPart, ModelRequest, TurnHistoryMessage } from '../../../kernel/types.js';
+/** A turn as Interactions frames it: the request, plus whether Google keeps it and what it continues. */
+export type InteractionsRequest = ModelRequest & {
+    store?: boolean;
+    previousInteractionId?: string;
+    /** What came after the stored interaction, sent in place of the whole history. */
+    continuation?: TurnHistoryMessage[];
+};
+export declare function camelToSnake(key: string): string;
+export declare function toGoogleValue(value: unknown): unknown;
+export declare function wirePart(part: InteractionPart): Record<string, string>;
+export declare function userInputStep(parts: InteractionPart[]): Record<string, unknown>;
+/** A thought's signature, for the tool call at `call` in the same assistant message. */
+export declare const thoughtSignature: z.ZodType<{
+    call: number;
+    signature: string;
+}>;
+export declare function historySteps(msg: TurnHistoryMessage): Record<string, unknown>[];
+export declare function historyStep(msg: TurnHistoryMessage): Record<string, unknown>;
+export declare function jsonResponseFormat(schema: Record<string, unknown>): unknown[];
+export declare function attachResponseFormat(req: InteractionsRequest, camel: Record<string, unknown>): void;
+export declare function attachSpeechConfig(req: InteractionsRequest, generationConfig: Record<string, unknown>): void;
+export declare function inputStepsFromRequest(req: InteractionsRequest): Record<string, unknown>[];
+export declare function applyOptionalRequestFields(req: InteractionsRequest, camel: Record<string, unknown>): void;
+export declare function baseInteractionsBody(req: InteractionsRequest): Record<string, unknown>;
+export declare function toInteractionsBody(req: InteractionsRequest): Record<string, unknown>;

package/esm/src/providers/google/interactions/framing.js

@@ -0,0 +1,304 @@
+import { z } from 'zod';
+import { TheoremError } from '../../../guardrails/error.js';
+import { historyMessageParts, wireInteractionPart } from '../../../kernel/interaction-parts.js';
+import { GOOGLE_SPEECH_FORMATS } from '../../../presets/google-limits.js';
+import { withCarriedToolFiles } from '../../shared/carried-tool-files.js';
+import { historyToolArguments, historyToolIdentity } from '../../shared/tool-args.js';
+import { interactionsBuiltinTool } from '../builtins.js';
+import { assertGoogleThinkingLevel } from '../thinking.js';
+export function camelToSnake(key) {
+    return key.replaceAll(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+export function toGoogleValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(toGoogleValue);
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            // why: A schema's property names and a call's argument names are the builder's own; snake-casing them breaks Gemini validation and shows the model a call it did not make.
+            if (key === 'schema' || key === 'parameters' || key === 'arguments') {
+                out[camelToSnake(key)] = nested;
+                continue;
+            }
+            out[camelToSnake(key)] = toGoogleValue(nested);
+        }
+        return out;
+    }
+    return value;
+}
+export function wirePart(part) {
+    return wireInteractionPart(part);
+}
+const USER_INPUT = 'user_input';
+export function userInputStep(parts) {
+    return { type: USER_INPUT, content: parts.map(wirePart) };
+}
+function historyContent(msg) {
+    const parts = historyMessageParts(msg);
+    return parts.length > 0 ? parts.map(wirePart) : [{ type: 'text', text: '' }];
+}
+// why: Google refuses any other part inside a `function_result`: "The value 'document' is not supported for 'type' at 'input[8].result[2]'. Supported values: 'function', 'image', 'text', 'video'." (live, 13/10/2026, gemini-3.5-flash-lite).
+const FUNCTION_RESULT_PART_TYPES = new Set([
+    'text',
+    'image',
+    'video',
+]);
+function functionResultStep(msg) {
+    const parts = historyMessageParts(msg);
+    return {
+        type: 'function_result',
+        ...historyToolIdentity({ name: msg.name, call_id: msg.tool_call_id }),
+        result: parts.length > 0 ? parts.map(wirePart) : [{ type: 'text', text: '' }],
+    };
+}
+/**
+ * A history call as input steps: the thought that led to it when it carries
+ * that thought's signature, then the call. Google rejects a current-turn call
+ * replayed without its signature, and rejects a `thought_signature` field on
+ * the call; a `thought` step with the signature ahead of it is accepted (probe
+ * 25/09/2026, gemini-3.1-flash-lite, `store: false`).
+ */
+function functionCallSteps(call, signature) {
+    const step = {
+        type: 'function_call',
+        id: call.id,
+        name: call.function.name,
+        arguments: historyToolArguments(call.function.arguments),
+    };
+    return signature ? [{ type: 'thought', signature }, step] : [step];
+}
+/** A thought's signature, for the tool call at `call` in the same assistant message. */
+export const thoughtSignature = z.strictObject({
+    call: z.number().int().min(0),
+    signature: z.string().min(1),
+});
+/** The signature written with the message's call at `index`, if its reasoning holds one. */
+function signatureAt(msg, index) {
+    for (const part of msg.reasoning ?? []) {
+        const parsed = thoughtSignature.safeParse(part.data);
+        if (parsed.success && parsed.data.call === index)
+            return parsed.data.signature;
+    }
+    return undefined;
+}
+function textOrPartsStep(role, msg) {
+    // why: Assistant history is `model_output`, not `model_turn`.
+    const type = role === 'assistant' ? 'model_output' : 'user_input';
+    return { type, content: historyContent(msg) };
+}
+/** Assistant `tool_calls` (often with no `content`) become `function_call` steps, never empty `model_output`. */
+function nonToolSteps(msg) {
+    if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
+        const steps = [];
+        if (historyMessageParts(msg).length > 0) {
+            steps.push(textOrPartsStep('assistant', msg));
+        }
+        for (const [index, call] of msg.tool_calls.entries()) {
+            steps.push(...functionCallSteps(call, signatureAt(msg, index)));
+        }
+        return steps;
+    }
+    if (msg.role === 'assistant') {
+        return [textOrPartsStep('assistant', msg)];
+    }
+    return [textOrPartsStep('user', msg)];
+}
+/**
+ * History as input steps. A file a `function_result` cannot hold follows its run
+ * of tool results in a `user_input` step (`withCarriedToolFiles`).
+ */
+function historyStepsOf(messages) {
+    return withCarriedToolFiles(messages, FUNCTION_RESULT_PART_TYPES).flatMap((msg) => msg.role === 'tool' ? [functionResultStep(msg)] : nonToolSteps(msg));
+}
+export function historySteps(msg) {
+    return historyStepsOf([msg]);
+}
+export function historyStep(msg) {
+    const steps = historySteps(msg);
+    return steps[0] ?? { type: 'user_input', content: [{ type: 'text', text: '' }] };
+}
+export function jsonResponseFormat(schema) {
+    return [{ type: 'text', mimeType: 'application/json', schema }];
+}
+export function attachResponseFormat(req, camel) {
+    if (req.speech) {
+        if (req.image) {
+            throw new TheoremError('config', 'cannot mix speech and image response formats');
+        }
+        if (req.structured) {
+            throw new TheoremError('config', 'cannot mix speech and structured response formats');
+        }
+        const format = req.speech.format;
+        if (format && !GOOGLE_SPEECH_FORMATS.includes(format)) {
+            throw new TheoremError('unsupported', `Gemini speech returns ${GOOGLE_SPEECH_FORMATS.join(', ')}, not '${format}'`);
+        }
+        camel.responseFormat = { type: 'audio' };
+        return;
+    }
+    if (req.image) {
+        const imageEntry = {
+            type: 'image',
+            mimeType: req.image.mimeType,
+        };
+        if (req.image.aspectRatio) {
+            imageEntry.aspectRatio = req.image.aspectRatio;
+        }
+        if (req.image.resolution) {
+            imageEntry.imageSize = req.image.resolution;
+        }
+        for (const [name, value] of [
+            ['quality', req.image.quality],
+            ['background', req.image.background],
+            ['n', req.image.n],
+            ['outputCompression', req.image.outputCompression],
+        ]) {
+            if (value !== undefined) {
+                throw new TheoremError('unsupported', `image.${name} is not supported on Google image models`);
+            }
+        }
+        camel.responseFormat = req.image.includeText ? [{ type: 'text' }, imageEntry] : imageEntry;
+        return;
+    }
+    if (!req.structured) {
+        return;
+    }
+    camel.responseFormat = jsonResponseFormat(req.structured.jsonSchema);
+}
+export function attachSpeechConfig(req, generationConfig) {
+    if (!req.speech) {
+        return;
+    }
+    const { voice, speed } = req.speech;
+    if (speed !== undefined) {
+        // why: Interactions has no rate field, and a speed dropped here would be a setting the host believes it made.
+        throw new TheoremError('config', 'Gemini Interactions speech has no speed field: set the pace in speech.style');
+    }
+    if (!voice) {
+        // why: Interactions has no default voice and refuses the request without one (live, 17/10/2026).
+        throw new TheoremError('config', 'Gemini speech needs a voice: set speech.voice');
+    }
+    generationConfig.speechConfig = [{ voice }];
+}
+/**
+ * The speech models that read a delivery note as a `speech_metadata` annotation. The others refuse
+ * it ("Speech metadata is not supported for this model", gemini-3.1-flash-tts-preview, live
+ * 17/10/2026) and take the note as a direction ahead of the script, as Google's guide shows.
+ */
+const SPEECH_METADATA_MODELS = new Set([
+    'gemini-3.8-flash-tts',
+    'gemini-3.8-flash-lite-tts',
+]);
+/** The script with its delivery note, in the form the model reads it. */
+function speechInputStep(parts, style, apiId) {
+    if (!SPEECH_METADATA_MODELS.has(apiId)) {
+        return {
+            type: USER_INPUT,
+            content: [
+                { type: 'text', text: `Read the following aloud. ${style.trim()}\n` },
+                ...parts.map(wirePart),
+            ],
+        };
+    }
+    // why: Gemini reads `text` aloud and `speech_metadata` as direction.
+    const annotations = [{ type: 'speech_metadata', style }];
+    return {
+        type: USER_INPUT,
+        content: parts
+            .map(wirePart)
+            .map((part) => (part.type === 'text' ? { ...part, annotations } : part)),
+    };
+}
+function wireInteractionsFunctionTool(decl) {
+    return {
+        type: 'function',
+        name: decl.name,
+        description: decl.description,
+        parameters: decl.parameters,
+    };
+}
+function wireInteractionsTools(req) {
+    const tools = [];
+    for (const builtin of req.builtins) {
+        tools.push(interactionsBuiltinTool(builtin));
+    }
+    for (const decl of req.wireTools ?? []) {
+        tools.push(wireInteractionsFunctionTool(decl));
+    }
+    return tools;
+}
+/**
+ * A `tool` message without `name` takes its call's name: Google rejects a
+ * `function_result` without one as "Invalid input received" (live, 29/09/2026).
+ */
+function withToolNames(messages) {
+    const names = new Map();
+    return messages.map((msg) => {
+        for (const call of msg.tool_calls ?? [])
+            names.set(call.id, call.function.name);
+        if (msg.role !== 'tool' || msg.name || !msg.tool_call_id)
+            return msg;
+        const name = names.get(msg.tool_call_id);
+        return name ? { ...msg, name } : msg;
+    });
+}
+export function inputStepsFromRequest(req) {
+    if (req.continuation && req.continuation.length > 0) {
+        return historyStepsOf(withToolNames(req.continuation));
+    }
+    const inputSteps = historyStepsOf(withToolNames(req.history ?? []));
+    if (req.input.length > 0 || inputSteps.length === 0) {
+        const style = req.speech?.style;
+        inputSteps.push(style ? speechInputStep(req.input, style, req.apiId) : userInputStep(req.input));
+    }
+    return inputSteps;
+}
+export function applyOptionalRequestFields(req, camel) {
+    if (req.store !== undefined) {
+        camel.store = req.store;
+    }
+    if (req.previousInteractionId) {
+        camel.previousInteractionId = req.previousInteractionId;
+    }
+    if (req.system) {
+        camel.systemInstruction = req.system;
+    }
+    const tools = wireInteractionsTools(req);
+    if (tools.length > 0) {
+        camel.tools = tools;
+    }
+}
+export function baseInteractionsBody(req) {
+    const generationConfig = {
+        temperature: req.temperature,
+        maxOutputTokens: req.maxOutputTokens,
+    };
+    if (req.speech) {
+        // why: TTS models reject chat thinking knobs; voice lives under speech_config.
+        attachSpeechConfig(req, generationConfig);
+    }
+    else {
+        assertGoogleThinkingLevel(req.thinking);
+        if (req.thinking) {
+            generationConfig.thinkingLevel = req.thinking;
+        }
+        if (req.summaries) {
+            generationConfig.thinkingSummaries = req.summaries;
+        }
+        if (req.image?.seed !== undefined) {
+            generationConfig.seed = req.image.seed;
+        }
+    }
+    return {
+        model: req.apiId,
+        stream: req.stream ?? true,
+        input: inputStepsFromRequest(req),
+        generationConfig,
+    };
+}
+export function toInteractionsBody(req) {
+    const body = baseInteractionsBody(req);
+    attachResponseFormat(req, body);
+    applyOptionalRequestFields(req, body);
+    return toGoogleValue(body);
+}

package/esm/src/providers/google/interactions/steps.d.ts

@@ -0,0 +1,12 @@
+import type { ModelEvent, TurnEventOf, TurnResponse } from '../../../kernel/types.js';
+declare function isCodeExecutionType(type: string): boolean;
+declare function isGoogleBuiltinStepType(type: string): boolean;
+declare function rawStepEvidence(raw: Record<string, unknown>): TurnEventOf<'evidence'>;
+declare function codeExecutionEvidence(raw: Record<string, unknown>): TurnEventOf<'evidence'>;
+declare function eventsFromDelta(deltaValue: unknown): ModelEvent[];
+declare function eventsFromThoughtStep(step: Record<string, unknown>): ModelEvent[];
+declare function eventsFromModelOutputStep(step: Record<string, unknown>): ModelEvent[];
+declare function extractTokenEvent(interaction: Record<string, unknown>): TurnEventOf<'tokens'> | undefined;
+declare function eventsFromInteractionEnd(interaction: Record<string, unknown>): ModelEvent[];
+declare function interactionResponse(interaction: Record<string, unknown>): TurnResponse | undefined;
+export { codeExecutionEvidence, eventsFromDelta, eventsFromInteractionEnd, eventsFromModelOutputStep, eventsFromThoughtStep, extractTokenEvent, interactionResponse, isCodeExecutionType, isGoogleBuiltinStepType, rawStepEvidence, };