@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,263 @@
+import { TheoremError } from '../../../guardrails/error.js';
+import { historyMessageParts, wireInteractionPart } from '../../../kernel/interaction-parts.js';
+import { GOOGLE_SPEECH_FORMATS } from '../../../presets/google-limits.js';
+import { builtinWire } from '../../shared/builtin-wire.js';
+import { historyToolArguments, historyToolIdentity } from '../../shared/tool-args.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)) {
+            // Schema property names stay as authored; snake-casing them breaks Gemini validation.
+            if (key === 'schema' || key === 'parameters') {
+                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: '' }];
+}
+function functionResultStep(msg) {
+    const result = historyContent(msg);
+    return {
+        type: 'function_result',
+        ...historyToolIdentity({ name: msg.name, call_id: msg.tool_call_id }),
+        result,
+    };
+}
+/**
+ * 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) {
+    const step = {
+        type: 'function_call',
+        id: call.id,
+        name: call.function.name,
+        arguments: historyToolArguments(call.function.arguments),
+    };
+    return call.thoughtSignature
+        ? [{ type: 'thought', signature: call.thoughtSignature }, step]
+        : [step];
+}
+function textOrPartsStep(role, msg) {
+    // 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`. */
+export function historySteps(msg) {
+    if (msg.role === 'tool') {
+        return [functionResultStep(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 call of msg.tool_calls) {
+            steps.push(...functionCallSteps(call));
+        }
+        return steps;
+    }
+    if (msg.role === 'assistant') {
+        return [textOrPartsStep('assistant', msg)];
+    }
+    return [textOrPartsStep('user', 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' };
+        camel.responseModalities = ['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`);
+            }
+        }
+        // An object asks for image only; an array for text + image.
+        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 = req.speech.voice;
+    if (!voice) {
+        return;
+    }
+    generationConfig.speechConfig = [{ voice }];
+}
+function wireInteractionsFunctionTool(decl) {
+    return {
+        type: 'function',
+        name: decl.name,
+        description: decl.description,
+        parameters: decl.parameters,
+    };
+}
+function wireGoogleMapsTool(req) {
+    const loc = req.googleMapsLocation;
+    if (loc && Number.isFinite(loc.latitude) && Number.isFinite(loc.longitude)) {
+        return {
+            type: 'google_maps',
+            latitude: loc.latitude,
+            longitude: loc.longitude,
+        };
+    }
+    return { type: 'google_maps' };
+}
+function wireInteractionsTools(req) {
+    const tools = [];
+    for (const builtin of req.builtins) {
+        const type = builtinWire(builtin, 'interactions');
+        if (type === 'google_maps') {
+            tools.push(wireGoogleMapsTool(req));
+            continue;
+        }
+        tools.push({ type });
+    }
+    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 withToolNames(req.continuation).flatMap((msg) => historySteps(msg));
+    }
+    const inputSteps = [];
+    for (const h of withToolNames(req.history ?? [])) {
+        inputSteps.push(...historySteps(h));
+    }
+    if (req.input.length > 0 || inputSteps.length === 0) {
+        inputSteps.push(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) {
+        // 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/mod.d.ts

@@ -0,0 +1,2 @@
+export { camelToSnake, toInteractionsBody } from './framing.js';
+export { createInteractionsProvider } from './stream.js';

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

@@ -0,0 +1,2 @@
+export { camelToSnake, toInteractionsBody } from './framing.js';
+export { createInteractionsProvider } from './stream.js';

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

@@ -0,0 +1,12 @@
+import type { ProviderEvent, 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): ProviderEvent[];
+declare function eventsFromThoughtStep(step: Record<string, unknown>): ProviderEvent[];
+declare function eventsFromModelOutputStep(step: Record<string, unknown>): ProviderEvent[];
+declare function extractTokenEvent(interaction: Record<string, unknown>): TurnEventOf<'tokens'> | undefined;
+declare function eventsFromInteractionEnd(interaction: Record<string, unknown>): ProviderEvent[];
+declare function interactionResponse(interaction: Record<string, unknown>): TurnResponse | undefined;
+export { codeExecutionEvidence, eventsFromDelta, eventsFromInteractionEnd, eventsFromModelOutputStep, eventsFromThoughtStep, extractTokenEvent, interactionResponse, isCodeExecutionType, isGoogleBuiltinStepType, rawStepEvidence, };

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

@@ -0,0 +1,200 @@
+import { asRecord, nonEmptyString } from '../../../kernel/engine/record.js';
+import { reportedTokens, usageCount } from '../../../kernel/engine/usage.js';
+import { turnStopFromInteractionStatus } from '../../../kernel/stop.js';
+import { groundingFromSteps } from '../grounding.js';
+import { byModality, groundingCounts, modalityCounts } from '../usage.js';
+/*
+ * Interactions steps and deltas read only the shapes recorded from the wire
+ * (probes 23/09/2026, gemini-3.8-flash, gemini-3.1-pro-preview, image and TTS
+ * models, streamed and buffered):
+ *
+ * - `text` deltas carry `text`; `thought_summary` deltas carry
+ *   `content: { type: 'text', text }`; buffered `thought` steps carry
+ *   `summary[]` of the same text blocks.
+ * - `image` / `audio` deltas and `model_output` content blocks carry
+ *   `mime_type` + `data`. Audio also reports `sample_rate` / `channels`; the
+ *   buffered mime already states them (`audio/l16; rate=24000; channels=1`),
+ *   the streamed one does not (`audio/l16`), so they are folded into the mime.
+ * - `code_execution_call` carries `id` and `arguments: { language, code }`;
+ *   `code_execution_result` carries `call_id`, `result` and `is_error`. Each
+ *   arrives whole, in one delta (5 577 characters of code in one probe).
+ */
+function thoughtText(content) {
+    const block = asRecord(content);
+    return block?.type === 'text' && typeof block.text === 'string' ? block.text : '';
+}
+function interactionsMime(rec) {
+    const mime = rec.mime_type;
+    if (typeof mime !== 'string' || !mime) {
+        return undefined;
+    }
+    const params = mime.toLowerCase();
+    const extra = [];
+    if (typeof rec.sample_rate === 'number' && !/;\s*rate=/.test(params)) {
+        extra.push(`rate=${String(rec.sample_rate)}`);
+    }
+    if (typeof rec.channels === 'number' && !/;\s*channels=/.test(params)) {
+        extra.push(`channels=${String(rec.channels)}`);
+    }
+    return extra.length > 0 ? `${mime}; ${extra.join('; ')}` : mime;
+}
+function interactionsMedia(rec) {
+    const mimeType = interactionsMime(rec);
+    const { data } = rec;
+    if (!mimeType || typeof data !== 'string' || !data) {
+        return [];
+    }
+    return [{ type: 'media', media: { mimeType, data } }];
+}
+function textEvent(type, text) {
+    return text ? [{ type, text }] : [];
+}
+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 rawStepEvidence(raw) {
+    return {
+        type: 'evidence',
+        evidence: { provider: 'google', kind: 'provider_step', step: String(raw.type ?? ''), raw },
+    };
+}
+function codeExecutionEvidence(raw) {
+    if (raw.type === 'code_execution_result') {
+        const callId = nonEmptyString(raw.call_id);
+        return {
+            type: 'evidence',
+            evidence: {
+                provider: 'google',
+                kind: 'code_execution_result',
+                raw,
+                ...(typeof raw.result === 'string' ? { result: raw.result } : {}),
+                ...(typeof raw.is_error === 'boolean' ? { isError: raw.is_error } : {}),
+                ...(callId ? { callId } : {}),
+            },
+        };
+    }
+    const args = asRecord(raw.arguments);
+    const id = nonEmptyString(raw.id);
+    if (raw.type !== 'code_execution_call' || !id || typeof args?.code !== 'string') {
+        return rawStepEvidence(raw);
+    }
+    return {
+        type: 'evidence',
+        evidence: {
+            provider: 'google',
+            kind: 'code_execution_call',
+            raw,
+            code: args.code,
+            ...(typeof args.language === 'string' ? { language: args.language } : {}),
+            id,
+        },
+    };
+}
+function eventsFromDelta(deltaValue) {
+    const delta = asRecord(deltaValue);
+    if (!delta) {
+        return [];
+    }
+    switch (delta.type) {
+        case 'thought_summary':
+            return textEvent('thought', thoughtText(delta.content));
+        case 'text':
+            return textEvent('text', typeof delta.text === 'string' ? delta.text : '');
+        case 'image':
+        case 'audio':
+            return interactionsMedia(delta);
+        default:
+            return [];
+    }
+}
+function eventsFromThoughtStep(step) {
+    const summary = Array.isArray(step.summary) ? step.summary : [];
+    return summary.flatMap((block) => textEvent('thought', thoughtText(block)));
+}
+function eventsFromModelOutputStep(step) {
+    const content = Array.isArray(step.content) ? step.content : [];
+    return content.flatMap((block) => {
+        const rec = asRecord(block);
+        if (rec?.type === 'text') {
+            return textEvent('text', typeof rec.text === 'string' ? rec.text : '');
+        }
+        if (rec?.type === 'image' || rec?.type === 'audio') {
+            return interactionsMedia(rec);
+        }
+        return [];
+    });
+}
+/**
+ * Google reports thought and tool-use tokens beside input and output; the
+ * OpenTelemetry meanings fold them in. Probes (gemini-3.8-flash, 22/09/2026):
+ * `total_tokens` = input + output + thought + tool use, and cached sits inside input.
+ * For inputs Google converts first (Markdown, Python, mono `audio/L16`, …) input
+ * comes back 0 while `total_tokens` holds the full sum, so input is derived from it.
+ */
+function interactionsUsageTokens(raw) {
+    const usage = asRecord(raw);
+    if (!usage)
+        return undefined;
+    const output = usageCount(usage.total_output_tokens);
+    const thought = usageCount(usage.total_thought_tokens) ?? 0;
+    const toolUse = usageCount(usage.total_tool_use_tokens) ?? 0;
+    const total = usageCount(usage.total_tokens);
+    const derived = total === undefined ? undefined : total - (output ?? 0) - thought - toolUse;
+    const read = usageCount(usage.total_input_tokens) || (derived && derived > 0 ? derived : 0);
+    return reportedTokens({
+        input: read ? read + toolUse : undefined,
+        output: output === undefined ? undefined : output + thought,
+        thinking: thought,
+        toolUse,
+        cached: usageCount(usage.total_cached_tokens),
+        byModality: byModality(modalityCounts(usage.input_tokens_by_modality, 'tokens'), modalityCounts(usage.output_tokens_by_modality, 'tokens')),
+        grounding: groundingCounts(usage.grounding_tool_count),
+    });
+}
+function extractTokenEvent(interaction) {
+    const usage = interactionsUsageTokens(interaction.usage);
+    if (!usage) {
+        return undefined;
+    }
+    const interactionId = typeof interaction.id === 'string' ? interaction.id : undefined;
+    return {
+        type: 'tokens',
+        tokens: usage,
+        ...(interactionId ? { interactionId } : {}),
+    };
+}
+function eventsFromInteractionEnd(interaction) {
+    const events = [];
+    const tokenEvent = extractTokenEvent(interaction);
+    if (tokenEvent)
+        events.push(tokenEvent);
+    // Only a buffered body carries `steps[]`; streamed grounding arrives on deltas.
+    const { steps } = interaction;
+    if (Array.isArray(steps))
+        events.push(...groundingFromSteps(steps));
+    const done = doneFromInteractionStatus(interaction);
+    if (done)
+        events.push(done);
+    return events;
+}
+function interactionResponse(interaction) {
+    const id = nonEmptyString(interaction.id);
+    const model = nonEmptyString(interaction.model);
+    if (!id && !model)
+        return undefined;
+    return { ...(id ? { id } : {}), ...(model ? { model } : {}) };
+}
+function doneFromInteractionStatus(interaction) {
+    const { status } = interaction;
+    if (typeof status !== 'string')
+        return undefined;
+    return {
+        type: 'done',
+        stop: turnStopFromInteractionStatus(status),
+        ...(typeof interaction.id === 'string' ? { interactionId: interaction.id } : {}),
+    };
+}
+export { codeExecutionEvidence, eventsFromDelta, eventsFromInteractionEnd, eventsFromModelOutputStep, eventsFromThoughtStep, extractTokenEvent, interactionResponse, isCodeExecutionType, isGoogleBuiltinStepType, rawStepEvidence, };

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

@@ -0,0 +1,24 @@
+import type { ModelProvider, ProviderCompleteRequest, ProviderEvent, TurnResponse } from '../../../kernel/types.js';
+import { type GeminiTransport } from '../keys.js';
+export interface StreamFold {
+    text: string;
+    /** Open `function_call`, `code_execution_*` and builtin steps by `index`. */
+    steps: Map<number, Record<string, unknown>>;
+    sawMedia: boolean;
+    /** A `done` came out: the interaction reported a status. */
+    sawDone: boolean;
+    /** Identity named so far: `interaction.created` names it before any output, so a cut call still has it. */
+    response?: TurnResponse;
+    /** The signature of the last thought, until the `function_call` that follows it takes it. */
+    thoughtSignature?: string;
+}
+export declare function newStreamFold(): StreamFold;
+export declare function eventsFromStep(step: Record<string, unknown>, fold: StreamFold): ProviderEvent[];
+export declare function openStepEvents(fold: StreamFold): ProviderEvent[];
+export declare function foldPayload(payload: Record<string, unknown>, fold: StreamFold): ProviderEvent[];
+export declare function foldBody(body: Record<string, unknown>, fold: StreamFold): ProviderEvent[];
+export declare function finalizeStructured(req: ProviderCompleteRequest, fold: StreamFold): Generator<ProviderEvent>;
+export declare function isVoiceProfile(req: ProviderCompleteRequest): boolean;
+/** What the profile asked for and the model did not return; even an empty turn fails. */
+export declare function missingMediaError(req: ProviderCompleteRequest, fold: StreamFold): ProviderEvent | undefined;
+export declare function createInteractionsProvider(transport: GeminiTransport): ModelProvider;