theorum 0.1.15 → 1.1.3

package/esm/src/providers/{keys.js → google/keys.js}

@@ -1,13 +1,12 @@
 /**
- * Gemini key vault selection, quota overflow, and fetch retries.
+ * Google transport credentials, quota overflow, and fetch retries.
  *
- * Host applications supply vault credentials through `GeminiTransport`.
+ * Hosts supply a provider-neutral `KeyVault` via `GeminiTransport`.
  * THEORUM does not read environment variables for these keys.
  *
  * @module
  */
-import { isAbortError, TheorumError, UPSTREAM_FAILED } from '../guardrails/error.js';
-import { exposeForTests } from './expose-for-tests.js';
+import { isAbortError, TheorumError, UPSTREAM_FAILED } from '../../guardrails/error.js';
 const ATTEMPTS = 3;
 const LAST_ATTEMPT = ATTEMPTS - 1;
 const BACKOFF_FIRST_MS = 1000;
@@ -22,16 +21,16 @@ const HTTP_UNAVAILABLE = 503;
 const HTTP_GATEWAY_TIMEOUT = 504;
 const QUOTA_RE = /quota/i;
 const TRANSIENT_THROWN_RE = /name resolution|dns|econnreset|econnrefused|etimedout|network|fetch failed|temporarily unavailable|socket|503|502|504/i;
-function waitDefault(ms) {
+export function waitDefault(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
     });
 }
-function isQuota(err) {
+export function isQuota(err) {
     const s = String(err);
     return s.includes(String(HTTP_QUOTA)) || s.includes('RESOURCE_EXHAUSTED') || QUOTA_RE.test(s);
 }
-function isTransientHttp(status) {
+export function isTransientHttp(status) {
     return (status === HTTP_TIMEOUT ||
         status === HTTP_QUOTA ||
         status === HTTP_SERVER ||
@@ -39,20 +38,20 @@ function isTransientHttp(status) {
         status === HTTP_UNAVAILABLE ||
         status === HTTP_GATEWAY_TIMEOUT);
 }
-function isTransientThrown(err) {
+export function isTransientThrown(err) {
     if (isAbortError(err)) {
         return false;
     }
     return TRANSIENT_THROWN_RE.test(String(err));
 }
-function requireKey(vault, bucket) {
-    const key = vault[bucket];
+export function requireKey(vault, slot) {
+    const key = vault[slot];
     if (!key) {
         throw new TheorumError(UPSTREAM_FAILED);
     }
     return key;
 }
-function backoffMs(attempt) {
+export function backoffMs(attempt) {
     return BACKOFF_MS[attempt] ?? BACKOFF_SECOND_MS;
 }
 async function runWithBackoff(apiKey, run, wait, attempt) {
@@ -69,8 +68,8 @@ async function runWithBackoff(apiKey, run, wait, attempt) {
         return runWithBackoff(apiKey, run, wait, attempt + 1);
     }
 }
-function canOverflow(bucket, vault, primary) {
-    if (bucket === 'paid') {
+export function canOverflow(slot, vault, primary) {
+    if (slot === 'paid') {
         return undefined;
     }
     const { paid } = vault;
@@ -79,21 +78,21 @@ function canOverflow(bucket, vault, primary) {
     }
     return paid;
 }
-async function withGeminiKey(bucket, run, transport) {
+export async function withGeminiKey(slot, run, transport) {
     const wait = transport.wait ?? waitDefault;
-    const primary = requireKey(transport.vault, bucket);
+    const primary = requireKey(transport.vault, slot);
     try {
         return await runWithBackoff(primary, run, wait, 0);
     }
     catch (err) {
-        const paid = canOverflow(bucket, transport.vault, primary);
+        const paid = canOverflow(slot, transport.vault, primary);
         if (!(isQuota(err) && paid)) {
             throw err;
         }
         return await runWithBackoff(paid, run, wait, 0);
     }
 }
-function withApiKey(init, apiKey) {
+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') {
@@ -125,26 +124,15 @@ async function fetchWithBackoff(args) {
         return fetchWithBackoff({ ...args, attempt: args.attempt + 1 });
     }
 }
-async function fetchGemini(url, init, bucket, transport) {
+export async function fetchGemini(url, init, slot, transport) {
     const parsed = new URL(url);
     parsed.searchParams.delete('key');
     const href = parsed.toString();
-    const primary = requireKey(transport.vault, bucket);
+    const primary = requireKey(transport.vault, slot);
     let last = await fetchWithBackoff({ href, init, apiKey: primary, transport, attempt: 0 });
-    const paid = canOverflow(bucket, transport.vault, primary);
+    const paid = canOverflow(slot, transport.vault, primary);
     if (last.status === HTTP_QUOTA && paid) {
         last = await fetchWithBackoff({ href, init, apiKey: paid, transport, attempt: 0 });
     }
     return last;
 }
-export { fetchGemini, withGeminiKey };
-exposeForTests('keys', {
-    waitDefault,
-    isQuota,
-    isTransientHttp,
-    isTransientThrown,
-    requireKey,
-    backoffMs,
-    canOverflow,
-    withApiKey,
-});

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

@@ -0,0 +1,49 @@
+/**
+ * Pure protocol framing & serialization for Google Gemini Live WebSocket API (`BidiGenerateContent`).
+ *
+ * All functions are pure data transformations with no network I/O.
+ *
+ * @module
+ */
+import type { InteractionPart, ProviderCompleteRequest, TurnEvent, TurnHistoryMessage, TurnTokens, WireFunctionTool } from '../../../kernel/types.js';
+import { parseToolArgumentsObject } from '../../shared/tool-args.js';
+/** Construct authenticated WebSocket URL for Gemini Live API. */
+export declare function buildGeminiLiveWebSocketUrl(apiKey: string): string;
+export declare function wireFunctionDeclaration(decl: WireFunctionTool): Record<string, unknown>;
+export declare function wireLiveTools(req: ProviderCompleteRequest): Array<Record<string, unknown>>;
+/** Build the initial `setup` message sent once immediately after WebSocket open. */
+export declare function buildGeminiLiveSetupMessage(req: ProviderCompleteRequest): Record<string, unknown>;
+/** Build the `clientContent` message used for seeding conversation history before realtime streaming. */
+export declare function buildGeminiLiveClientContent(history: TurnHistoryMessage[]): Record<string, unknown> | null;
+/** Build a `realtimeInput` message for streaming audio, video, or text chunks. */
+export declare function buildGeminiLiveRealtimeInput(input: InteractionPart): Record<string, unknown>;
+/** Build a `realtimeInput` message with text. */
+export declare function buildGeminiLiveRealtimeText(text: string): Record<string, unknown>;
+/** Build a `toolResponse` message returning the execution result of a tool call. */
+export declare function buildGeminiLiveToolResponse(id: string, name: string, output: unknown): Record<string, unknown>;
+/** Build a batched `toolResponse` for one or more function results. */
+export declare function buildGeminiLiveToolResponses(responses: Array<{
+    id: string;
+    name: string;
+    output: unknown;
+}>): Record<string, unknown>;
+/** Parse raw WebSocket message text / buffer into a JSON record. */
+export type ParsedLiveMessage = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    reason: 'empty' | 'malformed';
+};
+export declare function parseGeminiLiveMessage(raw: unknown): ParsedLiveMessage;
+export declare function parseFunctionArguments(raw: unknown): ReturnType<typeof parseToolArgumentsObject>;
+export declare function extractLiveUsageTokens(metadata: Record<string, unknown>): TurnTokens | undefined;
+/** Parse Gemini goAway.timeLeft (seconds number, "10s", duration string) → ms when known. */
+export declare function parseGoAwayTimeLeftMs(timeLeft: unknown): number | undefined;
+export type LiveInteractionStatus = 'IN_PROGRESS' | 'IDLE';
+/** Read the server-side `interactionStatus` when the message carries one. */
+export declare function readLiveInteractionStatus(message: Record<string, unknown>): LiveInteractionStatus | undefined;
+/**
+ * Fold a raw `BidiGenerateContentServerMessage` into normalized `TurnEvent` items.
+ */
+export declare function foldGeminiLiveServerMessage(message: Record<string, unknown> | null | undefined): TurnEvent[];