@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,297 @@
+import { isAbortError, TheoremError, toErrorEvent } from '../../../guardrails/error.js';
+import { asRecord } from '../../../kernel/engine/record.js';
+import { pcmMediaAsWav } from '../../shared/pcm.js';
+import { foldResponse } from '../../shared/response-identity.js';
+import { readSseChunks } from '../../shared/sse.js';
+import { structuredEvent } from '../../shared/structured-output.js';
+import { toolCallEvents } from '../../shared/tool-args.js';
+import { readGeminiApiError, readNonOkError } from '../api-error.js';
+import { groundingFromDelta } from '../grounding.js';
+import { fetchGemini } from '../keys.js';
+import { INTERACTIONS_JSON_URL, INTERACTIONS_URL } from '../urls.js';
+import { toInteractionsBody } from './framing.js';
+import { codeExecutionEvidence, eventsFromDelta, eventsFromInteractionEnd, eventsFromModelOutputStep, eventsFromThoughtStep, interactionResponse, isCodeExecutionType, isGoogleBuiltinStepType, rawStepEvidence, } from './steps.js';
+const HTTP_OK = 200;
+export function newStreamFold() {
+    return { text: '', steps: new Map(), sawMedia: false, sawDone: false };
+}
+function isMergedStepType(type) {
+    return type === 'function_call' || isCodeExecutionType(type) || isGoogleBuiltinStepType(type);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * Hold a thought's signature for the call that follows it. The model thinks
+ * once before a step's calls, so the signature arrives on a `thought` step:
+ * whole when buffered, as a `thought_signature` delta when streamed (probe
+ * 25/09/2026, gemini-3.1-flash-lite). Calls carried an empty `signature`.
+ */
+function holdThoughtSignature(signature, fold) {
+    const held = nonEmptyString(signature);
+    if (held)
+        fold.thoughtSignature = held;
+}
+/**
+ * The signature a `function_call` replays with: its own when it carries a
+ * non-empty one, else the held thought's. The first call takes the held one;
+ * its siblings share that thought and carry none.
+ */
+function takeThoughtSignature(step, fold) {
+    const signature = nonEmptyString(step.signature) ?? fold.thoughtSignature;
+    fold.thoughtSignature = undefined;
+    return signature;
+}
+export function eventsFromStep(step, fold) {
+    const type = String(step.type ?? '');
+    if (type === 'function_call') {
+        const id = typeof step.id === 'string' ? step.id : undefined;
+        const name = typeof step.name === 'string' ? step.name : '';
+        const thoughtSignature = takeThoughtSignature(step, fold);
+        return toolCallEvents({ id, name, thoughtSignature }, step.arguments);
+    }
+    if (isCodeExecutionType(type)) {
+        return [codeExecutionEvidence(step)];
+    }
+    if (isGoogleBuiltinStepType(type)) {
+        return [rawStepEvidence(step)];
+    }
+    if (type === 'thought') {
+        holdThoughtSignature(step.signature, fold);
+        return eventsFromThoughtStep(step);
+    }
+    if (type === 'model_output') {
+        return eventsFromModelOutputStep(step);
+    }
+    return [];
+}
+function stepIndex(payload) {
+    return typeof payload.index === 'number' ? payload.index : 0;
+}
+function foldStepStart(payload, fold) {
+    const step = asRecord(payload.step);
+    if (!step)
+        return;
+    const type = String(step.type ?? '');
+    if (type === 'thought') {
+        holdThoughtSignature(step.signature, fold);
+    }
+    if (isMergedStepType(type)) {
+        fold.steps.set(stepIndex(payload), { ...step });
+    }
+}
+function foldStepDelta(payload, fold) {
+    const delta = asRecord(payload.delta);
+    if (!delta) {
+        return [];
+    }
+    const open = fold.steps.get(stepIndex(payload));
+    if (!open) {
+        if (delta.type === 'thought_signature') {
+            holdThoughtSignature(delta.signature, fold);
+        }
+        return eventsFromDelta(delta);
+    }
+    if (delta.type === 'arguments_delta') {
+        // Replaces the `arguments: {}` placeholder from `step.start` with the streamed JSON string.
+        const sofar = typeof open.arguments === 'string' ? open.arguments : '';
+        open.arguments = sofar + (typeof delta.arguments === 'string' ? delta.arguments : '');
+        return [];
+    }
+    Object.assign(open, delta);
+    return [];
+}
+function foldStepStop(payload, fold) {
+    const index = stepIndex(payload);
+    const step = fold.steps.get(index);
+    if (!step) {
+        return [];
+    }
+    fold.steps.delete(index);
+    return eventsFromStep(step, fold);
+}
+function partialStepEvidence(step) {
+    const event = isCodeExecutionType(String(step.type ?? ''))
+        ? codeExecutionEvidence(step)
+        : rawStepEvidence(step);
+    return { ...event, evidence: { ...event.evidence, partial: true } };
+}
+export function openStepEvents(fold) {
+    const events = [...fold.steps.values()].map(partialStepEvidence);
+    fold.steps.clear();
+    return events;
+}
+function delivered(events, fold) {
+    return events.map((ev) => {
+        if (ev.type === 'done') {
+            fold.sawDone = true;
+        }
+        if (ev.type === 'text' && ev.text) {
+            fold.text += ev.text;
+        }
+        if (ev.type !== 'media' || !ev.media) {
+            return ev;
+        }
+        fold.sawMedia = true;
+        return { ...ev, media: pcmMediaAsWav(ev.media) };
+    });
+}
+function eventsFromStreamRow(payload, fold) {
+    if (payload.eventType === 'sse_unparsed') {
+        // Every observed Interactions row is a JSON object; anything else is a wire change.
+        return [
+            toErrorEvent(new TheoremError('bad_response', 'Interactions stream row was not a JSON object')),
+        ];
+    }
+    const apiError = readGeminiApiError(payload);
+    if (apiError) {
+        return [toErrorEvent(apiError)];
+    }
+    const events = groundingFromDelta(payload);
+    switch (payload.event_type) {
+        case 'step.start':
+            foldStepStart(payload, fold);
+            break;
+        case 'step.delta':
+            events.push(...foldStepDelta(payload, fold));
+            break;
+        case 'step.stop':
+            events.push(...foldStepStop(payload, fold));
+            break;
+        case 'interaction.created': {
+            const interaction = asRecord(payload.interaction);
+            if (interaction)
+                events.push(...identityEvents(interaction, fold));
+            break;
+        }
+        case 'interaction.completed': {
+            const interaction = asRecord(payload.interaction);
+            if (interaction) {
+                events.push(...identityEvents(interaction, fold), ...eventsFromInteractionEnd(interaction));
+            }
+            break;
+        }
+    }
+    return events;
+}
+function identityEvents(interaction, fold) {
+    const identity = foldResponse(fold.response, interactionResponse(interaction));
+    fold.response = identity.known;
+    return identity.event ? [identity.event] : [];
+}
+export function foldPayload(payload, fold) {
+    return delivered(eventsFromStreamRow(payload, fold), fold);
+}
+export function foldBody(body, fold) {
+    const steps = Array.isArray(body.steps) ? body.steps : [];
+    const fromSteps = steps.flatMap((value) => {
+        const step = asRecord(value);
+        return step ? eventsFromStep(step, fold) : [];
+    });
+    return delivered([...identityEvents(body, fold), ...fromSteps, ...eventsFromInteractionEnd(body)], fold);
+}
+export function* finalizeStructured(req, fold) {
+    if (!req.structured || !fold.text) {
+        return;
+    }
+    yield structuredEvent(fold.text);
+}
+export function isVoiceProfile(req) {
+    return Boolean(req.speech?.voice);
+}
+/** What the profile asked for and the model did not return; even an empty turn fails. */
+export function missingMediaError(req, fold) {
+    if (fold.sawMedia)
+        return undefined;
+    if (isVoiceProfile(req)) {
+        return toErrorEvent(new TheoremError('bad_response', 'speech audio was not returned by the model'));
+    }
+    if (req.image) {
+        return toErrorEvent(new TheoremError('bad_response', 'no image returned from image generation'));
+    }
+    return undefined;
+}
+async function* parseInteractionsSse(response, req) {
+    if (!response.body) {
+        yield toErrorEvent(new TheoremError('bad_response', 'empty response body'));
+        return;
+    }
+    const fold = newStreamFold();
+    for await (const row of readSseChunks(response.body)) {
+        req.tapUpstream?.(row);
+        if (row.eventType === 'sse_done') {
+            break;
+        }
+        const events = foldPayload(row, fold);
+        yield* events;
+        if (events.some((ev) => ev.type === 'error')) {
+            yield* openStepEvents(fold);
+            return;
+        }
+    }
+    yield* openStepEvents(fold);
+    yield* finalizeStructured(req, fold);
+    const missing = missingMediaError(req, fold);
+    if (missing)
+        yield missing;
+    if (!fold.sawDone) {
+        // The stream ended before the interaction reported a status: it did not complete.
+        yield { type: 'done', stop: { kind: 'stream_incomplete' } };
+    }
+}
+async function postInteractions(url, req, transport) {
+    if (!req.keySlot) {
+        throw new TheoremError('config', 'Request requires keySlot');
+    }
+    const init = {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(toInteractionsBody(req)),
+        signal: req.signal,
+    };
+    const response = await fetchGemini(url, init, req.keySlot, transport, req.tapUpstream, req.fallbackKeySlot);
+    if (response.status !== HTTP_OK) {
+        throw await readNonOkError(response);
+    }
+    return response;
+}
+async function* fetchInteractionsOnce(req, transport) {
+    const response = await postInteractions(INTERACTIONS_JSON_URL, req, transport);
+    const text = await response.text();
+    const parsed = JSON.parse(text);
+    const apiError = readGeminiApiError(parsed);
+    if (apiError) {
+        throw apiError;
+    }
+    req.tapUpstream?.(parsed);
+    const fold = newStreamFold();
+    yield* foldBody(parsed, fold);
+    yield* finalizeStructured(req, fold);
+    const missing = missingMediaError(req, fold);
+    if (missing)
+        yield missing;
+}
+async function* streamInteractions(req, transport) {
+    const response = await postInteractions(INTERACTIONS_URL, req, transport);
+    yield* parseInteractionsSse(response, req);
+}
+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,20 @@
+import type { KeySlot, KeyVault, ProviderCompleteRequest } from '../../kernel/types.js';
+/** A host's Gemini settings; keys come from the one vault. */
+interface GeminiOptions {
+    wait?: (ms: number) => Promise<void>;
+    fetch?: typeof fetch;
+}
+interface GeminiTransport extends GeminiOptions {
+    vault: KeyVault;
+}
+export declare function waitDefault(ms: number): Promise<void>;
+export declare function isTransientHttp(status: number): boolean;
+export declare function isTransientThrown(err: unknown): boolean;
+export declare function backoffMs(attempt: number): number;
+export declare function withApiKey(init: RequestInit, apiKey: string): RequestInit;
+/**
+ * Backs off on transient failures. A quota refusal retries once on the profile's fallback slot,
+ * when it names one; each try's slot is on the tape, so the trace shows the switch.
+ */
+export declare function fetchGemini(url: string, init: RequestInit, slot: KeySlot, transport: GeminiTransport, tap?: ProviderCompleteRequest['tapUpstream'], fallbackSlot?: KeySlot): Promise<Response>;
+export type { GeminiOptions, GeminiTransport };

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

@@ -0,0 +1,87 @@
+import { isAbortError } from '../../guardrails/error.js';
+import { networkError, tapFetch } from '../shared/upstream-tap.js';
+import { fallbackKey, requireKey } from '../shared/vault.js';
+const ATTEMPTS = 3;
+const LAST_ATTEMPT = ATTEMPTS - 1;
+const BACKOFF_FIRST_MS = 1000;
+const BACKOFF_SECOND_MS = 2000;
+const BACKOFF_THIRD_MS = 4000;
+const BACKOFF_MS = [BACKOFF_FIRST_MS, BACKOFF_SECOND_MS, BACKOFF_THIRD_MS];
+const HTTP_TIMEOUT = 408;
+const HTTP_QUOTA = 429;
+const HTTP_SERVER = 500;
+const HTTP_BAD_GATEWAY = 502;
+const HTTP_UNAVAILABLE = 503;
+const HTTP_GATEWAY_TIMEOUT = 504;
+const TRANSIENT_THROWN_RE = /name resolution|dns|econnreset|econnrefused|etimedout|network|fetch failed|temporarily unavailable|socket|503|502|504/i;
+export function waitDefault(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export function isTransientHttp(status) {
+    return (status === HTTP_TIMEOUT ||
+        status === HTTP_QUOTA ||
+        status === HTTP_SERVER ||
+        status === HTTP_BAD_GATEWAY ||
+        status === HTTP_UNAVAILABLE ||
+        status === HTTP_GATEWAY_TIMEOUT);
+}
+export function isTransientThrown(err) {
+    if (isAbortError(err)) {
+        return false;
+    }
+    return TRANSIENT_THROWN_RE.test(String(err));
+}
+export function backoffMs(attempt) {
+    return BACKOFF_MS[attempt] ?? BACKOFF_SECOND_MS;
+}
+export function withApiKey(init, apiKey) {
+    const headers = new Headers(init.headers);
+    headers.set('x-goog-api-key', apiKey);
+    if (!headers.has('Content-Type') && (init.method || 'GET').toUpperCase() !== 'GET') {
+        headers.set('Content-Type', 'application/json');
+    }
+    return { ...init, headers };
+}
+async function fetchWithBackoff(args) {
+    const wait = args.transport.wait ?? waitDefault;
+    const send = tapFetch(args.tap, args.transport.fetch ?? fetch, args.slot);
+    try {
+        const last = await send(args.href, withApiKey(args.init, args.apiKey));
+        if (!isTransientHttp(last.status) || args.attempt === LAST_ATTEMPT) {
+            return last;
+        }
+        if (args.init.signal?.aborted) {
+            throw args.init.signal.reason instanceof Error
+                ? args.init.signal.reason
+                : new DOMException('The operation was aborted.', 'AbortError');
+        }
+        await wait(backoffMs(args.attempt));
+        return fetchWithBackoff({ ...args, attempt: args.attempt + 1 });
+    }
+    catch (err) {
+        if (isAbortError(err) || !isTransientThrown(err) || args.attempt === LAST_ATTEMPT) {
+            throw networkError(err);
+        }
+        await wait(backoffMs(args.attempt));
+        return fetchWithBackoff({ ...args, attempt: args.attempt + 1 });
+    }
+}
+/**
+ * Backs off on transient failures. A quota refusal retries once on the profile's fallback slot,
+ * when it names one; each try's slot is on the tape, so the trace shows the switch.
+ */
+export async function fetchGemini(url, init, slot, transport, tap, fallbackSlot) {
+    const parsed = new URL(url);
+    parsed.searchParams.delete('key');
+    const href = parsed.toString();
+    const primary = requireKey(transport.vault, slot);
+    const first = { href, init, transport, tap, attempt: 0 };
+    let last = await fetchWithBackoff({ ...first, apiKey: primary, slot });
+    const fallback = fallbackKey(fallbackSlot, transport.vault, primary);
+    if (last.status === HTTP_QUOTA && fallback) {
+        last = await fetchWithBackoff({ ...first, apiKey: fallback.key, slot: fallback.slot });
+    }
+    return last;
+}

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

@@ -0,0 +1,51 @@
+import type { InteractionPart, ProviderCompleteRequest, ProviderEvent, TurnHistoryMessage, TurnTokens, WireFunctionTool } from '../../../kernel/types.js';
+export declare function buildGeminiLiveWebSocketUrl(apiKey: string): string;
+export declare function wireFunctionDeclaration(decl: WireFunctionTool): Record<string, unknown>;
+export declare function buildGeminiLiveSetupMessage(req: ProviderCompleteRequest): Record<string, unknown>;
+export declare function buildGeminiLiveClientContent(history: TurnHistoryMessage[]): Record<string, unknown> | null;
+export declare function buildGeminiLiveContext(text: string): Record<string, unknown>;
+export declare function buildGeminiLiveRealtimeInput(input: InteractionPart): Record<string, unknown>;
+export declare function liveFunctionResponsePayload(output: unknown): Record<string, unknown>;
+export declare function buildGeminiLiveToolResponse(id: string, name: string, output: unknown): Record<string, unknown>;
+export declare function buildGeminiLiveToolResponses(responses: Array<{
+    id: string;
+    name: string;
+    output: unknown;
+}>): Record<string, unknown>;
+/** What one outbound frame gives the model to read; setup and control frames give none. */
+export declare function liveFrameInput(frame: Record<string, unknown>): TurnHistoryMessage[];
+export type ParsedLiveMessage = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    reason: 'empty' | 'malformed';
+};
+export declare function parseGeminiLiveMessage(raw: unknown): ParsedLiveMessage;
+/**
+ * Live sends one usage row per model response, at its `turnComplete`, covering that
+ * response alone; the prompt count grows because each response re-reads the session.
+ * Probe (gemini-3.1-flash-live-preview, 22/09/2026): `thoughtsTokenCount` sits outside
+ * `responseTokenCount` and `totalTokenCount`, so it is added to output.
+ * `toolUsePromptTokenCount` (not seen in that probe) is added to input, as on Interactions.
+ */
+export declare function extractLiveUsageTokens(metadata: Record<string, unknown>): TurnTokens | undefined;
+export interface LiveFold {
+    /** Tool call names by id, for the cancel that names only ids. */
+    calls: Map<string, string>;
+}
+export declare function newLiveFold(): LiveFold;
+/**
+ * `goAway.timeLeft` → milliseconds. It is a protobuf Duration, which JSON
+ * encodes as seconds with an `s` suffix (`"10s"`, `"1.5s"`).
+ */
+export declare function parseGoAwayTimeLeftMs(timeLeft: unknown): number | undefined;
+export type LiveInteractionStatus = 'IN_PROGRESS' | 'IDLE';
+/**
+ * `serverContent.interactionStatus`, sent beside `turnComplete` by models that
+ * keep working after a turn (gemini-3.8-live-extended-thinking, probe
+ * 23/09/2026: `IN_PROGRESS` on each intermediate `turnComplete` of a tool
+ * flow, `IDLE` on the last).
+ */
+export declare function readLiveInteractionStatus(message: Record<string, unknown>): LiveInteractionStatus | undefined;
+export declare function foldGeminiLiveServerMessage(message: Record<string, unknown> | null | undefined, fold: LiveFold): ProviderEvent[];