theorum 0.1.15 → 1.1.3

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

@@ -0,0 +1,588 @@
+/**
+ * Google Interactions provider adapter.
+ *
+ * This adapter converts THEORUM's provider-neutral request into the Google
+ * Interactions wire format and streams normalized `TurnEvent` objects.
+ * Speech-role turns use `response_format: audio` + `speech_config` (same
+ * transport as chat/image).
+ *
+ * @module
+ */
+import { isAbortError, TheorumError, toErrorEvent } from '../../../guardrails/error.js';
+import { codeExecutionEvidence, codeExecutionStepKey, eventsFromComplete, eventsFromDelta, extractTokenEvent, googleBuiltinEvidence, groundingFromEvent, isCodeExecutionType, isGoogleBuiltinStepType, mergeCodeExecutionPayload, parseStructuredOutput, } from '../../../kernel/engine/delta.js';
+import { asRecord } from '../../../kernel/engine/record.js';
+import { base64ToBytes, bytesToBase64, wrapPcmAsWav } from '../../shared/pcm.js';
+import { readSseChunks } from '../../shared/sse.js';
+import { parseToolArgumentsObject } from '../../shared/tool-args.js';
+import { tapFetch } from '../../shared/upstream-tap.js';
+import { fetchGemini } from '../keys.js';
+import { INTERACTIONS_JSON_URL, INTERACTIONS_URL } from '../urls.js';
+import { toInteractionsBody } from './framing.js';
+const HTTP_OK = 200;
+export function isRawPcmMime(mime) {
+    const lower = mime.toLowerCase();
+    return (lower.startsWith('audio/pcm') || lower.startsWith('audio/raw') || lower.startsWith('audio/l16'));
+}
+export function normalizeSpeechMedia(event, speech) {
+    if (!speech || event.type !== 'media' || !event.media) {
+        return event;
+    }
+    const { media } = event;
+    if (!isRawPcmMime(media.mimeType)) {
+        return event;
+    }
+    const pcm = base64ToBytes(media.data);
+    const wav = wrapPcmAsWav(pcm, 24000);
+    return {
+        type: 'media',
+        media: { mimeType: 'audio/wav', data: bytesToBase64(wav) },
+    };
+}
+export function newStreamFold() {
+    return {
+        text: '',
+        functionCalls: new Map(),
+        emittedToolKeys: new Set(),
+        emittedEvidenceKeys: new Set(),
+        codeSteps: new Map(),
+        sawStreamedMedia: false,
+    };
+}
+export function eventType(payload) {
+    return String(payload.event_type ?? payload.type ?? '');
+}
+export function isDeltaEvent(type) {
+    return type === 'content.delta' || type === 'step.delta';
+}
+export function isCompleteEvent(type) {
+    return type === 'interaction.complete' || type === 'interaction.completed';
+}
+export function* yieldGrounding(event) {
+    const g = groundingFromEvent(event);
+    if (g) {
+        yield g;
+    }
+}
+export function* yieldTokens(event) {
+    const tokens = extractTokenEvent(event);
+    if (tokens) {
+        yield tokens;
+    }
+}
+export function functionCallKey(tool) {
+    return `${tool.name ?? ''}:${tool.id ?? ''}:${JSON.stringify(tool.arguments ?? {})}`;
+}
+export function* yieldEvidenceStep(step, emittedKeys) {
+    const event = googleBuiltinEvidence(step);
+    const ev = event.evidence;
+    if (!ev)
+        return;
+    const kind = String(ev.kind ?? ev.raw?.type ?? '');
+    const id = (typeof ev.callId === 'string' && ev.callId) ||
+        (typeof ev.id === 'string' && ev.id) ||
+        (typeof ev.raw?.call_id === 'string' && ev.raw.call_id) ||
+        (typeof ev.raw?.id === 'string' && ev.raw.id) ||
+        '';
+    const hasResult = ev.raw?.result !== undefined;
+    // Stub maps/search starts often arrive before `result`; allow a second emit once result lands.
+    const key = `${kind}:${id}:${hasResult ? 'result' : 'stub'}:${ev.code ?? ''}`;
+    if (emittedKeys.has(key))
+        return;
+    // Prefer the result-bearing emit: drop the stub key so hosts don't keep an empty payload.
+    if (hasResult) {
+        emittedKeys.delete(`${kind}:${id}:stub:`);
+    }
+    emittedKeys.add(key);
+    yield event;
+}
+function recordCodeStep(index, delta, steps) {
+    const existing = steps.get(index);
+    if (!existing) {
+        steps.set(index, delta);
+        return;
+    }
+    mergeCodeExecutionPayload(existing, delta);
+}
+export function isCompleteCodeStep(step) {
+    return step.arguments !== undefined || step.result !== undefined;
+}
+function* flushCompletedCodeSteps(steps, emittedKeys) {
+    for (const [index, step] of steps) {
+        if (!isCompleteCodeStep(step)) {
+            continue;
+        }
+        const key = codeExecutionStepKey(step);
+        if (!key || emittedKeys.has(key)) {
+            continue;
+        }
+        const event = codeExecutionEvidence(step);
+        if (event) {
+            emittedKeys.add(key);
+            steps.delete(index);
+            yield event;
+        }
+    }
+}
+export function foldStepStart(payload, fold) {
+    const step = asRecord(payload.step);
+    if (!step)
+        return [];
+    const type = String(step.type ?? '');
+    const index = typeof payload.index === 'number' ? payload.index : 0;
+    if (type === 'function_call') {
+        // Always buffer until step.stop. Gemini often sends arguments: {} on start, then
+        // streams the real JSON via arguments_delta — early emit would run with empty args
+        // and leave a nameless pending for the deltas.
+        const existing = fold.functionCalls.get(index);
+        let argumentsStr = existing?.arguments ?? '';
+        if (typeof step.arguments === 'string') {
+            argumentsStr = step.arguments;
+        }
+        else if (step.arguments !== undefined && typeof step.arguments === 'object') {
+            argumentsStr = JSON.stringify(step.arguments);
+        }
+        fold.functionCalls.set(index, {
+            id: typeof step.id === 'string' ? step.id : existing?.id,
+            name: typeof step.name === 'string' ? step.name : existing?.name,
+            arguments: argumentsStr,
+        });
+        return [];
+    }
+    if (isCodeExecutionType(type)) {
+        recordCodeStep(index, step, fold.codeSteps);
+        return Array.from(flushCompletedCodeSteps(fold.codeSteps, fold.emittedEvidenceKeys));
+    }
+    if (isGoogleBuiltinStepType(type)) {
+        return Array.from(yieldEvidenceStep(step, fold.emittedEvidenceKeys));
+    }
+    return [];
+}
+export function parseArgumentsObject(raw) {
+    return parseToolArgumentsObject(raw);
+}
+export function emitUniqueToolEvent(tool, fold) {
+    const key = functionCallKey(tool);
+    if (fold.emittedToolKeys.has(key))
+        return [];
+    fold.emittedToolKeys.add(key);
+    return [{ type: 'tool', tool }];
+}
+/** Emit a tool call, or a structured tool failure when arguments cannot be parsed. */
+export function emitToolCallFromRawArguments(tool, rawArguments, fold) {
+    const name = tool.name.trim();
+    if (!name) {
+        return emitUniqueToolEvent({
+            id: tool.id,
+            name: '',
+            arguments: {},
+            phase: 'error',
+            failure: {
+                code: 'malformed_arguments',
+                message: 'function call is missing a name',
+                details: { rawArguments },
+            },
+        }, fold);
+    }
+    const parsed = parseArgumentsObject(rawArguments);
+    if (!parsed.ok) {
+        return emitUniqueToolEvent({
+            id: tool.id,
+            name,
+            arguments: {},
+            phase: 'error',
+            failure: {
+                code: 'malformed_arguments',
+                message: parsed.error,
+                details: { raw: parsed.raw },
+            },
+        }, fold);
+    }
+    return emitUniqueToolEvent({ id: tool.id, name, arguments: parsed.value }, fold);
+}
+export function foldArgumentsDelta(delta, index, fold) {
+    const existing = fold.functionCalls.get(index) ?? { arguments: '' };
+    const chunk = typeof delta.arguments === 'string' ? delta.arguments : '';
+    if (!chunk) {
+        fold.functionCalls.set(index, existing);
+        return;
+    }
+    // Replace empty / `{}` placeholder from step.start so streamed JSON is not concatenated onto it.
+    if (existing.arguments === '' || existing.arguments === '{}') {
+        existing.arguments = chunk;
+    }
+    else {
+        existing.arguments += chunk;
+    }
+    fold.functionCalls.set(index, existing);
+}
+export function foldFunctionCallDelta(delta, fold) {
+    const id = typeof delta.id === 'string' ? delta.id : undefined;
+    const name = typeof delta.name === 'string' ? delta.name : '';
+    return emitToolCallFromRawArguments({ id, name }, delta.arguments, fold);
+}
+export function foldDeltaPayload(payload, fold) {
+    const delta = asRecord(payload.delta);
+    if (!delta) {
+        return [];
+    }
+    const stepType = String(delta.type ?? '');
+    const index = typeof payload.index === 'number' ? payload.index : 0;
+    if (stepType === 'arguments_delta' || stepType === 'arguments') {
+        foldArgumentsDelta(delta, index, fold);
+        return [];
+    }
+    if (stepType === 'function_call') {
+        return foldFunctionCallDelta(delta, fold);
+    }
+    if (isCodeExecutionType(stepType)) {
+        recordCodeStep(index, delta, fold.codeSteps);
+        return Array.from(flushCompletedCodeSteps(fold.codeSteps, fold.emittedEvidenceKeys));
+    }
+    if (isGoogleBuiltinStepType(stepType)) {
+        return Array.from(yieldEvidenceStep(delta, fold.emittedEvidenceKeys));
+    }
+    const events = [];
+    for (const ev of eventsFromDelta(delta)) {
+        if (ev.type === 'text' && ev.text) {
+            fold.text += ev.text;
+        }
+        events.push(ev);
+    }
+    return events;
+}
+export function readData(part) {
+    const data = part.data;
+    if (typeof data === 'string' && data.length > 0)
+        return data;
+    return undefined;
+}
+export function readMime(part) {
+    const mime = part.mime_type ?? part.mimeType;
+    if (typeof mime === 'string' && mime.length > 0)
+        return mime;
+    return undefined;
+}
+export function* yieldMediaChunk(part) {
+    const data = readData(part);
+    if (!data)
+        return;
+    const mime = readMime(part) ?? 'application/octet-stream';
+    if (isRawPcmMime(mime)) {
+        const wav = wrapPcmAsWav(base64ToBytes(data), 24000);
+        yield {
+            type: 'media',
+            media: { mimeType: 'audio/wav', data: bytesToBase64(wav) },
+        };
+        return;
+    }
+    yield { type: 'media', media: { mimeType: mime, data } };
+}
+export function* scanMediaParts(content) {
+    if (!Array.isArray(content))
+        return;
+    for (const item of content) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const part = item;
+        const type = typeof part.type === 'string' ? part.type : '';
+        if (type === 'image' || type === 'audio' || type === 'media' || type === 'video') {
+            yield* yieldMediaChunk(part);
+        }
+    }
+}
+export function emitPendingFunctionCall(index, fold) {
+    const pending = fold.functionCalls.get(index);
+    if (!pending)
+        return [];
+    fold.functionCalls.delete(index);
+    return emitToolCallFromRawArguments({ id: pending.id, name: pending.name ?? '' }, pending.arguments || {}, fold);
+}
+export function foldStepStop(payload, fold) {
+    const index = typeof payload.index === 'number' ? payload.index : 0;
+    const fromFunctionCall = emitPendingFunctionCall(index, fold);
+    if (fromFunctionCall.length > 0) {
+        return fromFunctionCall;
+    }
+    const step = asRecord(payload.step);
+    if (!step)
+        return [];
+    const stepType = String(step.type ?? '');
+    if (isGoogleBuiltinStepType(stepType)) {
+        return Array.from(yieldEvidenceStep(step, fold.emittedEvidenceKeys));
+    }
+    if (isCodeExecutionType(stepType)) {
+        return [codeExecutionEvidence(step)];
+    }
+    return [];
+}
+export function foldInteractionSteps(interaction, fold) {
+    const events = [];
+    const steps = interaction.steps;
+    if (!Array.isArray(steps))
+        return events;
+    for (const s of steps) {
+        const step = asRecord(s);
+        if (!step)
+            continue;
+        const stepType = String(step.type ?? '');
+        if (stepType === 'function_call') {
+            const id = typeof step.id === 'string' ? step.id : undefined;
+            const name = typeof step.name === 'string' ? step.name : '';
+            events.push(...emitToolCallFromRawArguments({ id, name }, step.arguments, fold));
+        }
+    }
+    return events;
+}
+export function foldCompleteEvents(payload, fold) {
+    const events = [];
+    const fromComp = eventsFromComplete(payload, fold.text.length > 0);
+    for (const ev of fromComp) {
+        if (ev.type === 'evidence' && ev.evidence?.raw) {
+            const key = codeExecutionStepKey(ev.evidence.raw);
+            if (fold.emittedEvidenceKeys.has(key))
+                continue;
+            fold.emittedEvidenceKeys.add(key);
+        }
+        if (ev.type === 'media') {
+            fold.sawStreamedMedia = true;
+        }
+        events.push(ev);
+    }
+    return events;
+}
+export function foldPayload(payload, fold) {
+    const apiError = readApiErrorMessage(payload);
+    if (apiError) {
+        return [toErrorEvent(new TheorumError(apiError))];
+    }
+    const events = [];
+    for (const ev of yieldGrounding(payload))
+        events.push(ev);
+    const type = eventType(payload);
+    if (!isCompleteEvent(type)) {
+        for (const ev of yieldTokens(payload))
+            events.push(ev);
+    }
+    if (type === 'step.start') {
+        events.push(...foldStepStart(payload, fold));
+        return events;
+    }
+    if (type === 'step.stop') {
+        events.push(...foldStepStop(payload, fold));
+        return events;
+    }
+    if (isDeltaEvent(type)) {
+        events.push(...foldDeltaPayload(payload, fold));
+        return events;
+    }
+    if (type === 'interaction.status_update' || isCompleteEvent(type)) {
+        const interaction = asRecord(payload.interaction) ?? payload;
+        events.push(...foldInteractionSteps(interaction, fold));
+        if (isCompleteEvent(type)) {
+            events.push(...foldCompleteEvents(payload, fold));
+        }
+        return events;
+    }
+    return events;
+}
+export function* finalizeStructured(req, fold) {
+    if (!req.structured || !fold.text) {
+        return;
+    }
+    const parsed = parseStructuredOutput(fold.text);
+    if (!parsed.ok) {
+        yield toErrorEvent(new TheorumError(parsed.error));
+        return;
+    }
+    yield { type: 'structured', structured: parsed.structured };
+}
+export function* scanInteractionsMedia(json) {
+    const steps = json.steps;
+    if (!Array.isArray(steps)) {
+        return;
+    }
+    for (const step of steps) {
+        if (!step || typeof step !== 'object')
+            continue;
+        const content = step.content;
+        yield* scanMediaParts(content);
+    }
+}
+export function isVoiceProfile(req) {
+    return Boolean(req.speech?.voice);
+}
+export function shouldReportMissingSpeechAudio(req, fold) {
+    // Any speech-role completion without real audio is a failure — including
+    // empty turns (no text and no media). Never invent PCM from text.
+    return isVoiceProfile(req) && !fold.sawStreamedMedia;
+}
+/** Speech-role turns must receive real audio; never invent PCM from text bytes. */
+export function* missingSpeechAudioError() {
+    yield toErrorEvent(new TheorumError('speech audio was not returned by the model'));
+}
+async function* parseInteractionsSse(response, req) {
+    if (!response.body) {
+        yield toErrorEvent('empty response body');
+        return;
+    }
+    const fold = newStreamFold();
+    const speech = Boolean(req.speech);
+    let hasError = false;
+    for await (const row of readSseChunks(response.body)) {
+        req.tapUpstream?.(row);
+        if (row.eventType === 'sse_done') {
+            break;
+        }
+        const events = foldPayload(row, fold);
+        for (const ev of events) {
+            if (ev.type === 'media') {
+                fold.sawStreamedMedia = true;
+            }
+            if (ev.type === 'error') {
+                hasError = true;
+            }
+            yield normalizeSpeechMedia(ev, speech);
+        }
+        if (hasError) {
+            return;
+        }
+    }
+    if (hasError) {
+        return;
+    }
+    yield* flushCompletedCodeSteps(fold.codeSteps, fold.emittedEvidenceKeys);
+    yield* finalizeStructured(req, fold);
+    if (shouldReportMissingSpeechAudio(req, fold)) {
+        yield* missingSpeechAudioError();
+    }
+}
+export function readApiErrorMessage(record) {
+    const error = record.error;
+    if (!error) {
+        if (record.sseEvent === 'error' ||
+            record.eventType === 'error' ||
+            record.event_type === 'error' ||
+            record.type === 'error') {
+            const msg = typeof record.message === 'string' ? record.message : null;
+            return msg || 'Gemini returned an error.';
+        }
+        return null;
+    }
+    if (typeof error === 'string' && error.length > 0) {
+        return error;
+    }
+    if (typeof error !== 'object')
+        return null;
+    const errorRecord = error;
+    if (typeof errorRecord.message === 'string' && errorRecord.message.length > 0) {
+        const status = typeof errorRecord.status === 'string' ? errorRecord.status : null;
+        return status ? `${status}: ${errorRecord.message}` : errorRecord.message;
+    }
+    return 'Gemini returned an error.';
+}
+export async function readNonOkErrorMessage(response) {
+    try {
+        const text = await response.text();
+        if (!text.trim())
+            return `HTTP ${response.status}`;
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const msg = readApiErrorMessage(parsed);
+                if (msg)
+                    return msg;
+            }
+        }
+        catch {
+            // JSON parse failed; return raw body below.
+        }
+        return `Gemini HTTP ${response.status}: ${text}`;
+    }
+    catch {
+        return `HTTP ${response.status}`;
+    }
+}
+function prepareInteractionsFetch(req) {
+    if (!req.keySlot) {
+        throw new TheorumError('Request requires keySlot');
+    }
+    const body = JSON.stringify(toInteractionsBody(req));
+    return {
+        slot: req.keySlot,
+        init: {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body,
+            signal: req.signal,
+        },
+    };
+}
+async function* fetchInteractionsOnce(req, transport) {
+    const { slot, init } = prepareInteractionsFetch(req);
+    const response = await fetchGemini(INTERACTIONS_JSON_URL, init, slot, transport);
+    if (response.status !== HTTP_OK) {
+        const reason = await readNonOkErrorMessage(response);
+        throw new TheorumError(reason);
+    }
+    const text = await response.text();
+    const parsed = JSON.parse(text);
+    const apiError = readApiErrorMessage(parsed);
+    if (apiError) {
+        throw new TheorumError(apiError);
+    }
+    req.tapUpstream?.(parsed);
+    yield* yieldGrounding(parsed);
+    yield* yieldTokens(parsed);
+    const fold = newStreamFold();
+    for (const ev of scanInteractionsMedia(parsed)) {
+        fold.sawStreamedMedia = true;
+        yield ev;
+    }
+    for (const ev of eventsFromComplete(parsed, fold.text.length > 0)) {
+        if (ev.type === 'text' && ev.text)
+            fold.text += ev.text;
+        yield ev;
+    }
+    yield* finalizeStructured(req, fold);
+    if (shouldReportMissingSpeechAudio(req, fold)) {
+        yield* missingSpeechAudioError();
+    }
+}
+export function withTap(req, transport) {
+    if (!req.tapUpstream) {
+        return transport;
+    }
+    const fetchFn = tapFetch(req.tapUpstream, transport.fetch ?? fetch);
+    return { ...transport, fetch: fetchFn };
+}
+async function* streamInteractions(req, transport) {
+    const { slot, init } = prepareInteractionsFetch(req);
+    const customTransport = withTap(req, transport);
+    const response = await fetchGemini(INTERACTIONS_URL, init, slot, customTransport);
+    if (response.status !== HTTP_OK) {
+        const reason = await readNonOkErrorMessage(response);
+        throw new TheorumError(reason);
+    }
+    yield* parseInteractionsSse(response, req);
+}
+/** Create a `ModelProvider` backed by Google Interactions HTTP / SSE. */
+export function createInteractionsProvider(transport) {
+    return {
+        async *complete(req) {
+            try {
+                if (req.stream === false) {
+                    yield* fetchInteractionsOnce(req, transport);
+                }
+                else {
+                    yield* streamInteractions(req, transport);
+                }
+            }
+            catch (err) {
+                if (isAbortError(err)) {
+                    throw err;
+                }
+                yield toErrorEvent(err);
+            }
+        },
+    };
+}

package/esm/src/providers/google/keys.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Google transport credentials, quota overflow, and fetch retries.
+ *
+ * Hosts supply a provider-neutral `KeyVault` via `GeminiTransport`.
+ * THEORUM does not read environment variables for these keys.
+ *
+ * @module
+ */
+import type { KeySlot, KeyVault } from '../../kernel/types.js';
+/** Google Interactions / Live transport: shared `KeyVault` + optional fetch/wait. */
+interface GeminiTransport {
+    vault: KeyVault;
+    wait?: (ms: number) => Promise<void>;
+    fetch?: typeof fetch;
+}
+export declare function waitDefault(ms: number): Promise<void>;
+export declare function isQuota(err: unknown): boolean;
+export declare function isTransientHttp(status: number): boolean;
+export declare function isTransientThrown(err: unknown): boolean;
+export declare function requireKey(vault: KeyVault, slot: KeySlot): string;
+export declare function backoffMs(attempt: number): number;
+export declare function canOverflow(slot: KeySlot, vault: KeyVault, primary: string): string | undefined;
+export declare function withGeminiKey<T>(slot: KeySlot, run: (apiKey: string) => Promise<T>, transport: GeminiTransport): Promise<T>;
+export declare function withApiKey(init: RequestInit, apiKey: string): RequestInit;
+export declare function fetchGemini(url: string, init: RequestInit, slot: KeySlot, transport: GeminiTransport): Promise<Response>;
+export type { GeminiTransport };