theorum 0.1.4 → 0.1.5

package/esm/src/providers/provider.js

@@ -0,0 +1,160 @@
+/**
+ * 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 { TheorumError, toErrorEvent } from '../guardrails/error.js';
+import { eventsFromComplete, eventsFromDelta, extractTokenEvent, groundingFromEvent, tryStructured, } from '../kernel/engine/delta.js';
+import { tapFetch } from './google-tap.js';
+import { toInteractionsBody } from './interactions.js';
+import { fetchGemini } from './keys.js';
+import { wrapPcmAsWav } from './pcm.js';
+import { INTERACTIONS_URL, takeSsePayloads } from './sse.js';
+const HTTP_OK = 200;
+function base64ToBytes(data) {
+    const bin = atob(data);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function bytesToBase64(bytes) {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+function isRawPcmMime(mime) {
+    const lower = mime.toLowerCase();
+    return lower === 'audio/pcm' || lower === 'audio/l16' || lower === 'audio/raw';
+}
+/** Google TTS returns raw PCM; wrap as WAV for hosts (matches OpenRouter pcm path). */
+function normalizeSpeechMedia(event, speech) {
+    if (!(speech && event.type === 'media' && event.media)) {
+        return event;
+    }
+    const { mimeType, data } = event.media;
+    if (!isRawPcmMime(mimeType)) {
+        return event;
+    }
+    const wav = wrapPcmAsWav(base64ToBytes(data));
+    return {
+        type: 'media',
+        media: { mimeType: 'audio/wav', data: bytesToBase64(wav) },
+    };
+}
+async function* readSseRecords(res) {
+    if (!res.body) {
+        throw new TheorumError('empty Gemini stream');
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    yield* pumpSse(reader, decoder, '', '');
+}
+async function* pumpSse(reader, decoder, buffer, pendingEvent) {
+    const { done, value } = await reader.read();
+    if (done) {
+        return;
+    }
+    const next = buffer + decoder.decode(value, { stream: true });
+    const taken = takeSsePayloads(next, pendingEvent);
+    for (const payload of taken.payloads) {
+        yield payload;
+    }
+    yield* pumpSse(reader, decoder, taken.rest, taken.pendingEvent);
+}
+function eventType(event) {
+    return String(event.event_type ?? event.type ?? '');
+}
+function isDeltaEvent(kind) {
+    return kind === 'content.delta' || kind === 'step.delta';
+}
+function isCompleteEvent(kind) {
+    return (kind === 'interaction.complete' ||
+        kind === 'interaction.completed' ||
+        kind.startsWith('interaction.'));
+}
+function foldDeltaPayload(event, acc) {
+    const deltaEvents = eventsFromDelta(event.delta);
+    for (const item of deltaEvents) {
+        if (item.type === 'text' && item.text) {
+            acc.text += item.text;
+        }
+    }
+    return deltaEvents;
+}
+function foldPayload(event, acc) {
+    const kind = eventType(event);
+    const events = [];
+    if (isDeltaEvent(kind)) {
+        events.push(...foldDeltaPayload(event, acc));
+    }
+    else if (isCompleteEvent(kind)) {
+        events.push(...eventsFromComplete(event, acc.text.length > 0));
+    }
+    // Also check if usage was included on the event directly
+    if (!events.some((e) => e.type === 'tokens')) {
+        const tokenEvent = extractTokenEvent(event);
+        if (tokenEvent) {
+            events.push(tokenEvent);
+        }
+    }
+    const groundingEvent = groundingFromEvent(event);
+    if (groundingEvent && !events.some((e) => e.type === 'grounding')) {
+        events.push(groundingEvent);
+    }
+    return events;
+}
+function withTap(req, transport) {
+    return {
+        ...transport,
+        fetch: tapFetch(req.tapGemini, transport.fetch),
+    };
+}
+async function* streamComplete(req, transport) {
+    if (!req.geminiBucket) {
+        yield toErrorEvent('missing Gemini vault bucket for Interactions');
+        return;
+    }
+    const res = await fetchGemini(INTERACTIONS_URL, { method: 'POST', body: JSON.stringify(toInteractionsBody(req)) }, req.geminiBucket, withTap(req, transport));
+    if (res.status !== HTTP_OK) {
+        const errorBody = await res.text().catch(() => '');
+        yield toErrorEvent(`Gemini HTTP ${String(res.status)}: ${errorBody}`);
+        return;
+    }
+    const acc = { text: '' };
+    const speech = Boolean(req.speech);
+    for await (const payload of readSseRecords(res)) {
+        req.tapGemini?.(payload);
+        const events = foldPayload(payload, acc);
+        for (const event of events) {
+            yield normalizeSpeechMedia(event, speech);
+        }
+    }
+    if (req.structured && acc.text) {
+        const structured = tryStructured(acc.text);
+        if (structured) {
+            yield structured;
+        }
+    }
+}
+async function* streamGuarded(req, transport) {
+    try {
+        yield* streamComplete(req, transport);
+    }
+    catch (err) {
+        yield toErrorEvent(err);
+    }
+}
+/** Create a `ModelProvider` backed by Google Interactions streaming. */
+function createInteractionsProvider(transport) {
+    return {
+        complete: (req) => streamGuarded(req, transport),
+    };
+}
+export { createInteractionsProvider };

package/esm/src/providers/speech.d.ts

@@ -0,0 +1,23 @@
+/**
+ * OpenAI-compatible `/audio/speech` transport (internal).
+ *
+ * Hosts use `createProvider(profile, { openRouter })` — this module is selected
+ * when the profile is an openAi speech role. Not a separate public door.
+ *
+ * @module
+ */
+import type { ModelProvider, ProviderCompleteRequest, TurnEvent } from '../kernel/types.js';
+/** Credentials for the openAi speech path (same shape as OpenRouter chat config + voice). */
+export interface SpeechProviderConfig {
+    apiKey?: string;
+    /** Fallback TTS voice when the profile does not pin `outputs.speech.voice`. */
+    voice?: string;
+    baseUrl?: string;
+    siteUrl?: string;
+    siteName?: string;
+    fetch?: typeof fetch;
+}
+declare function streamSpeech(req: ProviderCompleteRequest, config?: SpeechProviderConfig): AsyncGenerator<TurnEvent>;
+/** Internal ModelProvider for openAi speech roles. */
+declare function createSpeechProvider(config?: SpeechProviderConfig): ModelProvider;
+export { createSpeechProvider, streamSpeech };

package/esm/src/providers/speech.js

@@ -0,0 +1,125 @@
+/**
+ * OpenAI-compatible `/audio/speech` transport (internal).
+ *
+ * Hosts use `createProvider(profile, { openRouter })` — this module is selected
+ * when the profile is an openAi speech role. Not a separate public door.
+ *
+ * @module
+ */
+import { toErrorEvent } from '../guardrails/error.js';
+import { wrapPcmAsWav } from './pcm.js';
+const HTTP_OK = 200;
+function bytesToBase64(bytes) {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+function extractInputText(input) {
+    return input
+        .filter((p) => p.type === 'text')
+        .map((p) => (p.type === 'text' ? p.text : ''))
+        .join(' ')
+        .trim();
+}
+function resolveSpeechWireModel(req) {
+    if (req.openRouterId) {
+        return req.openRouterId;
+    }
+    if (req.apiId.includes('/')) {
+        return req.apiId;
+    }
+    if (req.apiId) {
+        return `google/${req.apiId}`;
+    }
+    return String(req.model);
+}
+function buildHeaders(apiKey, config) {
+    const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+    };
+    if (config.siteUrl) {
+        headers['HTTP-Referer'] = config.siteUrl;
+    }
+    if (config.siteName) {
+        headers['X-Title'] = config.siteName;
+    }
+    return headers;
+}
+function buildPayload(req, text, speech, configVoice) {
+    const voice = speech?.voice ?? configVoice;
+    const format = speech?.format ?? 'pcm';
+    const payload = {
+        model: resolveSpeechWireModel(req),
+        input: text,
+        response_format: format,
+    };
+    if (voice) {
+        payload.voice = voice;
+    }
+    return payload;
+}
+async function requestSpeech(apiKey, text, req, config) {
+    const fetchFn = config.fetch ?? fetch;
+    const baseUrl = config.baseUrl?.replace(/\/+$/, '') ?? 'https://openrouter.ai/api/v1';
+    const url = `${baseUrl}/audio/speech`;
+    return await fetchFn(url, {
+        method: 'POST',
+        headers: buildHeaders(apiKey, config),
+        body: JSON.stringify(buildPayload(req, text, req.speech, config.voice)),
+    });
+}
+function* yieldSpeechSuccess(rawBytes, text, format) {
+    let mediaMime = 'audio/mpeg';
+    let mediaBytes = rawBytes;
+    if (format === 'pcm') {
+        mediaMime = 'audio/wav';
+        mediaBytes = wrapPcmAsWav(rawBytes);
+    }
+    yield {
+        type: 'media',
+        media: { mimeType: mediaMime, data: bytesToBase64(mediaBytes) },
+    };
+    const inputTokens = Math.max(1, Math.round(text.length / 4));
+    const outputTokens = Math.max(1, Math.round(rawBytes.length / 100));
+    yield {
+        type: 'tokens',
+        tokens: { input: inputTokens, output: outputTokens, total: inputTokens + outputTokens },
+    };
+    yield { type: 'done' };
+}
+async function* streamSpeech(req, config = {}) {
+    const apiKey = config.apiKey?.trim() || undefined;
+    if (!apiKey) {
+        yield toErrorEvent('missing API key for speech');
+        return;
+    }
+    const text = extractInputText(req.input);
+    if (!text) {
+        yield toErrorEvent('empty text for speech');
+        return;
+    }
+    const res = await requestSpeech(apiKey, text, req, config);
+    if (res.status !== HTTP_OK) {
+        yield toErrorEvent(`Speech HTTP ${String(res.status)}`);
+        return;
+    }
+    const arrayBuffer = await res.arrayBuffer();
+    const rawBytes = new Uint8Array(arrayBuffer);
+    if (rawBytes.length === 0) {
+        yield toErrorEvent('no audio returned from speech');
+        return;
+    }
+    const format = req.speech?.format ?? 'pcm';
+    for (const ev of yieldSpeechSuccess(rawBytes, text, format)) {
+        yield ev;
+    }
+}
+/** Internal ModelProvider for openAi speech roles. */
+function createSpeechProvider(config = {}) {
+    return {
+        complete: (req) => streamSpeech(req, config),
+    };
+}
+export { createSpeechProvider, streamSpeech };

package/esm/src/providers/sse.d.ts

@@ -0,0 +1,7 @@
+declare const INTERACTIONS_URL = "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse";
+declare function takeSsePayloads(buffer: string, pendingEvent?: string): {
+    rest: string;
+    payloads: Record<string, unknown>[];
+    pendingEvent: string;
+};
+export { INTERACTIONS_URL, takeSsePayloads };

package/esm/src/providers/sse.js

@@ -0,0 +1,53 @@
+const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse';
+const DATA_PREFIX = 'data: ';
+const EVENT_PREFIX = 'event: ';
+const DONE = '[DONE]';
+function asObject(parsed) {
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return undefined;
+}
+function dataRecord(raw, sseEvent) {
+    const data = raw.slice(DATA_PREFIX.length).trim();
+    const row = {};
+    if (sseEvent) {
+        row.sseEvent = sseEvent;
+    }
+    if (!data || data === DONE) {
+        row.eventType = 'sse_done';
+        return row;
+    }
+    try {
+        const parsed = JSON.parse(data);
+        const obj = asObject(parsed);
+        if (obj) {
+            return { ...obj, ...row };
+        }
+        row.eventType = 'sse_unparsed';
+        row.data = parsed;
+        return row;
+    }
+    catch {
+        row.eventType = 'sse_unparsed';
+        row.data = data;
+        return row;
+    }
+}
+function takeSsePayloads(buffer, pendingEvent = '') {
+    const payloads = [];
+    const chunks = buffer.split('\n');
+    const rest = chunks.pop() ?? '';
+    let sseEvent = pendingEvent;
+    for (const line of chunks) {
+        if (line.startsWith(EVENT_PREFIX)) {
+            sseEvent = line.slice(EVENT_PREFIX.length).trim();
+        }
+        else if (line.startsWith(DATA_PREFIX)) {
+            payloads.push(dataRecord(line, sseEvent));
+            sseEvent = '';
+        }
+    }
+    return { rest, payloads, pendingEvent: sseEvent };
+}
+export { INTERACTIONS_URL, takeSsePayloads };

package/package.json

@@ -1,9 +1,7 @@
 {
   "name": "theorum",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
-  "license": "MIT",
-  "type": "module",
   "keywords": [
     "agent",
     "ai",
@@ -15,42 +13,53 @@
     "openrouter",
     "gemini"
   ],
+  "license": "MIT",
+  "module": "./esm/mod.js",
   "exports": {
-    ".": "./mod.ts",
-    "./kernel": "./src/kernel/mod.ts",
-    "./providers": "./src/providers/mod.ts",
-    "./openrouter": "./src/providers/openrouter-mod.ts",
-    "./guardrails": "./src/guardrails/mod.ts",
-    "./observability": "./src/observability/mod.ts",
-    "./host": "./src/host/mod.ts",
-    "./cli": "./src/cli/index.ts",
-    "./presets": "./src/presets/mod.ts",
-    "./presets/google": "./src/presets/google.ts"
+    ".": {
+      "import": "./esm/mod.js"
+    },
+    "./kernel": {
+      "import": "./esm/src/kernel/mod.js"
+    },
+    "./providers": {
+      "import": "./esm/src/providers/mod.js"
+    },
+    "./openrouter": {
+      "import": "./esm/src/providers/openrouter-mod.js"
+    },
+    "./guardrails": {
+      "import": "./esm/src/guardrails/mod.js"
+    },
+    "./observability": {
+      "import": "./esm/src/observability/mod.js"
+    },
+    "./host": {
+      "import": "./esm/src/host/mod.js"
+    },
+    "./cli": {
+      "import": "./esm/src/cli/index.js"
+    },
+    "./presets": {
+      "import": "./esm/src/presets/mod.js"
+    },
+    "./presets/google": {
+      "import": "./esm/src/presets/google.js"
+    }
   },
-  "files": [
-    "README.md",
-    "deno.json",
-    "deno.lock",
-    "docs/",
-    "mod.ts",
-    "src/"
-  ],
+  "scripts": {},
+  "bin": {
+    "theorum": "./esm/src/cli/index.js"
+  },
+  "type": "module",
+  "sideEffects": false,
   "dependencies": {
     "@openrouter/ai-sdk-provider": "1.5.4",
-    "ai": "5.0.244"
-  },
-  "scripts": {
-    "build:npm": "deno run --allow-read --allow-write --allow-env --allow-net --allow-run=npm scripts/build-npm.ts",
-    "test": "deno test --allow-read --allow-write --allow-net",
-    "coverage": "rm -rf coverage && deno test --allow-read --allow-write --allow-net --coverage=coverage tests/ && deno coverage coverage --lcov --output=coverage/lcov.info && node scripts/lcov-to-istanbul.mjs",
-    "lint:biome": "biome check .",
-    "lint:ast-grep": "ast-grep scan",
-    "lint:fallow": "npm run coverage && fallow audit && fallow health && fallow dupes && fallow dead-code",
-    "lint": "npm run lint:biome && npm run lint:ast-grep && npm run lint:fallow"
+    "ai": "5.0.244",
+    "@deno/shim-deno": "~0.18.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.8",
-    "@ast-grep/cli": "^0.41.0",
-    "fallow": "3.17.0"
-  }
-}
+    "@types/node": "^20.9.0"
+  },
+  "_generatedBy": "dnt@0.43.2"
+}

package/deno.json

@@ -1,57 +0,0 @@
-{
-  "name": "@theorum/core",
-  "version": "0.1.4",
-  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
-  "license": "MIT",
-  "keywords": [
-    "agent",
-    "ai",
-    "kernel",
-    "llm",
-    "typescript",
-    "deno",
-    "node",
-    "openrouter",
-    "gemini"
-  ],
-  "exports": {
-    ".": "./mod.ts",
-    "./kernel": "./src/kernel/mod.ts",
-    "./providers": "./src/providers/mod.ts",
-    "./openrouter": "./src/providers/openrouter-mod.ts",
-    "./guardrails": "./src/guardrails/mod.ts",
-    "./observability": "./src/observability/mod.ts",
-    "./host": "./src/host/mod.ts",
-    "./cli": "./src/cli/index.ts",
-    "./presets": "./src/presets/mod.ts",
-    "./presets/google": "./src/presets/google.ts"
-  },
-  "publish": {
-    "exclude": [
-      ".fallow/",
-      ".fallowrc.jsonc",
-      ".github/",
-      "ast-grep-rules/",
-      "biome.json",
-      "coverage/",
-      "node_modules/",
-      "npm/",
-      "package-lock.json",
-      "scripts/",
-      "sgconfig.yml",
-      "tests/"
-    ]
-  },
-  "imports": {
-    "@openrouter/ai-sdk-provider": "npm:@openrouter/ai-sdk-provider@1.5.4",
-    "ai": "npm:ai@5.0.244",
-    "@std/assert": "jsr:@std/assert@^1.0.0"
-  },
-  "tasks": {
-    "theorum": "deno run --allow-read --allow-write --allow-net src/cli/index.ts",
-    "test": "deno test --allow-read --allow-write --allow-net tests/",
-    "check": "deno check mod.ts",
-    "lint": "npm run lint",
-    "verify:live": "deno run --allow-net scripts/verify-live.ts"
-  }
-}