theorum 0.1.7 → 0.1.10

package/esm/src/providers/keys.js

@@ -7,6 +7,7 @@
  * @module
  */
 import { isAbortError, TheorumError, UPSTREAM_FAILED } from '../guardrails/error.js';
+import { exposeForTests } from './expose-for-tests.js';
 const ATTEMPTS = 3;
 const LAST_ATTEMPT = ATTEMPTS - 1;
 const BACKOFF_FIRST_MS = 1000;
@@ -137,3 +138,13 @@ async function fetchGemini(url, init, bucket, transport) {
     return last;
 }
 export { fetchGemini, withGeminiKey };
+exposeForTests('keys', {
+    waitDefault,
+    isQuota,
+    isTransientHttp,
+    isTransientThrown,
+    requireKey,
+    backoffMs,
+    canOverflow,
+    withApiKey,
+});

package/esm/src/providers/openrouter-payload.d.ts

@@ -28,5 +28,12 @@ interface OpenRouterWireIds {
 declare function resolveOpenRouterModel(modelId: ModelId | string, customMap?: Record<string, string>, wire?: OpenRouterWireIds): string;
 /** Convert a provider-neutral request into an OpenRouter chat completion payload. */
 declare function toOpenRouterPayload(req: ProviderCompleteRequest, config: OpenRouterConfig): Record<string, unknown>;
-export type { OpenRouterConfig, OpenRouterWireIds };
-export { resolveOpenRouterModel, toOpenRouterPayload };
+interface ResolvedPlugins {
+    plugins: Array<{
+        id: string;
+    }>;
+    webSearch: boolean;
+}
+declare function resolveOpenRouterPlugins(builtins: readonly string[]): ResolvedPlugins;
+export type { OpenRouterConfig, OpenRouterWireIds, ResolvedPlugins };
+export { resolveOpenRouterModel, resolveOpenRouterPlugins, toOpenRouterPayload };

package/esm/src/providers/openrouter-payload.js

@@ -167,13 +167,29 @@ function toOpenRouterPayload(req, config) {
     if (tools.length > 0) {
         payload.tools = tools;
     }
-    const plugins = req.builtins
-        .map((id) => getTool(id)?.openRouterPlugin)
-        .filter((id) => Boolean(id))
-        .map((id) => ({ id }));
-    if (plugins.length > 0) {
-        payload.plugins = plugins;
+    const resolved = resolveOpenRouterPlugins(req.builtins);
+    if (resolved.webSearch) {
+        payload.web_search_options = {};
+    }
+    if (resolved.plugins.length > 0) {
+        payload.plugins = resolved.plugins;
     }
     return payload;
 }
-export { resolveOpenRouterModel, toOpenRouterPayload };
+function resolveOpenRouterPlugins(builtins) {
+    let webSearch = false;
+    const plugins = [];
+    for (const id of builtins) {
+        const pluginId = getTool(id)?.openRouterPlugin;
+        if (!pluginId)
+            continue;
+        if (pluginId === 'web') {
+            webSearch = true;
+        }
+        else {
+            plugins.push({ id: pluginId });
+        }
+    }
+    return { plugins, webSearch };
+}
+export { resolveOpenRouterModel, resolveOpenRouterPlugins, toOpenRouterPayload };

package/esm/src/providers/openrouter.js

@@ -11,9 +11,9 @@ import { createOpenRouter } from '@openrouter/ai-sdk-provider';
 import { jsonSchema, streamText, tool, } from 'ai';
 import { isAbortError, toErrorEvent } from '../guardrails/error.js';
 import { tryStructured } from '../kernel/engine/delta.js';
-import { getTool } from '../kernel/registry/catalog.js';
-import { resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter-payload.js';
-import { takeSsePayloads } from './sse.js';
+import { getStructured } from '../kernel/registry/schemas.js';
+import { resolveOpenRouterModel, resolveOpenRouterPlugins, toOpenRouterPayload, } from './openrouter-payload.js';
+import { exposeForTests } from './expose-for-tests.js';
 function trimApiKey(explicitKey) {
     if (explicitKey?.trim()) {
         return explicitKey.trim();
@@ -26,7 +26,6 @@ function createAccumulator() {
         evidenceSeen: false,
         emittedTokens: false,
         errored: false,
-        toolInputs: new Map(),
     };
 }
 function mediaPart(part) {
@@ -61,9 +60,6 @@ function parseToolInput(raw) {
 function stringDefault(value, fallback) {
     return value === undefined ? fallback : value;
 }
-function optionalSingle(value) {
-    return value === undefined ? undefined : [value];
-}
 function fallbackToolCallId(name) {
     return `call_${stringDefault(name, 'tool')}`;
 }
@@ -111,34 +107,21 @@ function contentHistoryMessage(msg) {
     const content = contentFromOptionalParts(msg.parts, msg.content);
     return { role: msg.role, content };
 }
-function sourceValue(part, key) {
-    const source = part;
-    const value = source[key];
-    return typeof value === 'string' ? value : undefined;
-}
-function sourceUrl(part) {
-    return sourceValue(part, 'url');
-}
-function sourceTitle(part) {
-    return sourceValue(part, 'title') ?? sourceUrl(part);
-}
-function sourceList(title, url) {
-    if (title === undefined || url === undefined) {
-        return undefined;
-    }
-    return [{ title, uri: url, type: 'web' }];
-}
 function sourceEvent(part) {
-    const raw = part;
-    const url = sourceUrl(part);
-    const title = sourceTitle(part);
+    if (part.sourceType !== 'url') {
+        return {
+            type: 'evidence',
+            evidence: { provider: 'openrouter', raw: part },
+        };
+    }
+    const title = part.title ?? part.url;
     return {
         type: 'evidence',
         evidence: {
             provider: 'openrouter',
-            raw,
-            citations: optionalSingle(url),
-            sources: sourceList(title, url),
+            raw: part,
+            citations: [part.url],
+            sources: [{ title, uri: part.url, type: 'web' }],
         },
     };
 }
@@ -171,19 +154,17 @@ function buildTools(dynamicTools) {
     }
     return tools;
 }
-function openRouterPlugins(req) {
-    const plugins = req.builtins
-        .map((id) => getTool(id)?.openRouterPlugin)
-        .filter((id) => Boolean(id))
-        .map((id) => ({ id }));
-    return plugins.length > 0 ? plugins : undefined;
-}
 function openRouterSettings(req) {
-    const plugins = openRouterPlugins(req);
-    if (!plugins) {
+    const { plugins, webSearch } = resolveOpenRouterPlugins(req.builtins);
+    if (plugins.length === 0 && !webSearch) {
         return undefined;
     }
-    return { plugins };
+    const settings = {};
+    if (plugins.length > 0)
+        settings.plugins = plugins;
+    if (webSearch)
+        settings.web_search_options = {};
+    return settings;
 }
 function tokensFromUsage(usage) {
     const input = usage.inputTokens ?? 0;
@@ -269,17 +250,6 @@ function toolArguments(input) {
     }
     return { value: input };
 }
-function isEmptyRecord(input) {
-    return Boolean(input) && Object.keys(input ?? {}).length === 0;
-}
-function toolCallArguments(part, acc) {
-    const fromInput = toolArguments(part.input);
-    const rawInput = acc.toolInputs.get(part.toolCallId);
-    if ((!fromInput || isEmptyRecord(fromInput)) && rawInput) {
-        return toolArguments(parseToolInput(rawInput));
-    }
-    return fromInput;
-}
 function toolResultData(output) {
     return rawRecord(output);
 }
@@ -333,45 +303,12 @@ function rawEvents(raw, acc) {
     }
     return events;
 }
-async function collectRawEvents(res) {
-    if (!res.body) {
-        return [];
-    }
-    const reader = res.body.getReader();
-    const decoder = new TextDecoder();
-    const events = [];
-    const acc = createAccumulator();
-    let buffer = '';
-    let pendingEvent = '';
-    while (true) {
-        const { done, value } = await reader.read();
-        if (done) {
-            break;
-        }
-        buffer += decoder.decode(value, { stream: true });
-        const taken = takeSsePayloads(buffer, pendingEvent);
-        buffer = taken.rest;
-        pendingEvent = taken.pendingEvent;
-        for (const payload of taken.payloads) {
-            events.push(...rawEvents(payload, acc));
-        }
-    }
-    return events;
-}
-function captureFetch(config, setCapture) {
-    const fetchFn = config.fetch ?? fetch;
-    return async (input, init) => {
-        const res = await fetchFn(input, init);
-        setCapture(collectRawEvents(res.clone()).catch(() => []));
-        return res;
-    };
-}
-function toolCallEvent(part, acc) {
+function toolCallEvent(part) {
     return {
         type: 'tool',
         tool: {
             name: part.toolName,
-            arguments: toolCallArguments(part, acc),
+            arguments: toolArguments(part.input),
             id: part.toolCallId,
         },
     };
@@ -401,22 +338,7 @@ function providerMetadataEvent(part, acc) {
     }
     return evidenceFromMetadata(part.providerMetadata, acc);
 }
-function appendToolInput(part, acc) {
-    if (part.type === 'tool-input-start') {
-        acc.toolInputs.set(part.id, '');
-        return true;
-    }
-    if (part.type === 'tool-input-delta') {
-        const current = acc.toolInputs.get(part.id) ?? '';
-        acc.toolInputs.set(part.id, current + part.delta);
-        return true;
-    }
-    return false;
-}
 function eventFromPart(part, acc) {
-    if (appendToolInput(part, acc)) {
-        return [];
-    }
     const mapped = primaryEventFromPart(part, acc);
     if (mapped) {
         return [mapped];
@@ -432,11 +354,15 @@ function primaryEventFromPart(part, acc) {
         case 'reasoning-delta':
             return { type: 'thought', text: part.text };
         case 'tool-call':
-            return toolCallEvent(part, acc);
+            return toolCallEvent(part);
         case 'tool-result':
             return toolResultEvent(part);
-        case 'source':
+        case 'source': {
+            if (acc.evidenceSeen)
+                return undefined;
+            acc.evidenceSeen = true;
             return sourceEvent(part);
+        }
         case 'finish':
             return finishEvent(part, acc);
         case 'error':
@@ -456,27 +382,12 @@ function finishEvent(part, acc) {
     }
     return event;
 }
-function emitRawEvents(rawCapture, acc) {
-    return (rawCapture ?? Promise.resolve([])).then((events) => events.filter((event) => {
-        if (event.type !== 'evidence') {
-            return true;
-        }
-        if (acc.evidenceSeen) {
-            return false;
-        }
-        acc.evidenceSeen = true;
-        return true;
-    }));
-}
 function createStreamContext(req, config, apiKey) {
-    let rawCapture;
     const openrouter = createOpenRouter({
         apiKey,
         baseURL: config.baseUrl,
         headers: openRouterHeaders(config),
-        fetch: captureFetch(config, (capture) => {
-            rawCapture = capture;
-        }),
+        fetch: config.fetch,
         compatibility: 'strict',
     });
     return {
@@ -485,27 +396,26 @@ function createStreamContext(req, config, apiKey) {
             apiId: req.apiId,
             openRouterId: req.openRouterId,
         }),
-        rawCapture: () => rawCapture,
     };
 }
 function streamTextOptions(req, context) {
     return {
         model: context.openrouter.chat(context.modelName, openRouterSettings(req)),
-        system: req.system,
+        instructions: req.system,
         messages: buildMessages(req),
         allowSystemInMessages: true,
         temperature: req.temperature,
         maxOutputTokens: req.maxOutputTokens,
         tools: buildTools(req.dynamicTools),
         providerOptions: providerOptionsFor(req),
-        includeRawChunks: true,
+        include: { rawChunks: true },
         abortSignal: req.signal,
         onError: () => undefined,
     };
 }
 async function* yieldAiSdkStream(req, acc, context) {
     const result = streamText(streamTextOptions(req, context));
-    for await (const part of result.fullStream) {
+    for await (const part of result.stream) {
         if (part.type === 'raw') {
             req.tapGemini?.(rawRecord(part.rawValue) ?? { rawValue: part.rawValue });
             for (const event of rawEvents(part.rawValue, acc)) {
@@ -518,16 +428,6 @@ async function* yieldAiSdkStream(req, acc, context) {
         }
     }
 }
-async function* yieldCapturedRawEvents(context, acc) {
-    for (const event of await emitRawEvents(context.rawCapture(), acc)) {
-        yield event;
-    }
-}
-async function* yieldCapturedRawEventsUnchecked(context) {
-    for (const event of await (context.rawCapture() ?? Promise.resolve([]))) {
-        yield event;
-    }
-}
 function missingOpenRouterKey() {
     return toErrorEvent('missing OpenRouter API key');
 }
@@ -541,14 +441,12 @@ async function* streamOpenRouter(req, config) {
     const context = createStreamContext(req, config, apiKey);
     try {
         yield* yieldAiSdkStream(req, acc, context);
-        yield* yieldCapturedRawEvents(context, acc);
         yield* finalEvents(req, acc);
     }
     catch (err) {
         if (isAbortError(err)) {
             throw err;
         }
-        yield* yieldCapturedRawEventsUnchecked(context);
         yield toErrorEvent(err);
     }
 }
@@ -564,16 +462,34 @@ function* finalEvents(req, acc) {
     }
     yield { type: 'done' };
 }
-function providerOptionsFor(req) {
-    if (req.thinking === 'none') {
+function responseFormatFor(req) {
+    if (!req.structured)
+        return undefined;
+    const spec = getStructured(req.structured);
+    if (!spec.jsonSchema)
         return undefined;
-    }
     return {
-        openrouter: {
-            reasoning: { effort: req.thinking },
+        type: 'json_schema',
+        json_schema: {
+            name: String(req.structured),
+            strict: true,
+            schema: spec.jsonSchema,
         },
     };
 }
+function providerOptionsFor(req) {
+    const openrouter = {};
+    if (req.thinking !== 'none') {
+        openrouter.reasoning = { effort: req.thinking };
+    }
+    const responseFormat = responseFormatFor(req);
+    if (responseFormat) {
+        openrouter.response_format = responseFormat;
+    }
+    if (Object.keys(openrouter).length === 0)
+        return undefined;
+    return { openrouter };
+}
 function openRouterHeaders(config) {
     const headers = {};
     if (config.siteUrl) {
@@ -591,3 +507,48 @@ function createOpenRouterProvider(config = {}) {
     };
 }
 export { createOpenRouterProvider, resolveOpenRouterModel, toOpenRouterPayload };
+exposeForTests('openrouter', {
+    trimApiKey,
+    createAccumulator,
+    mediaPart,
+    contentFromParts,
+    parseToolInput,
+    stringDefault,
+    fallbackToolCallId,
+    toolResultContent,
+    assistantToolCallContent,
+    historyMessage,
+    contentFromOptionalParts,
+    contentHistoryMessage,
+    buildMessages,
+    schemaForTool,
+    buildTools,
+    openRouterSettings,
+    tokensFromUsage,
+    rawRecord,
+    stringArray,
+    metadataRecord,
+    citationCandidates,
+    nestedCitations,
+    metadataAnnotations,
+    evidenceFromMetadata,
+    toolArguments,
+    toolResultData,
+    rawThoughtEvent,
+    rawChoiceMessageEvidence,
+    rawEvents,
+    toolCallEvent,
+    toolResultEvent,
+    tokenEvent,
+    providerMetadataEvent,
+    eventFromPart,
+    primaryEventFromPart,
+    finishEvent,
+    sourceEvent,
+    finalEvents,
+    responseFormatFor,
+    providerOptionsFor,
+    openRouterHeaders,
+    missingOpenRouterKey,
+    streamTextOptions,
+});

package/esm/src/providers/pcm.js

@@ -3,6 +3,7 @@
  *
  * @module
  */
+import { exposeForTests } from './expose-for-tests.js';
 const SAMPLE_RATE = 24000;
 function writeAscii(view, offset, str) {
     for (let i = 0; i < str.length; i++)
@@ -33,3 +34,4 @@ export function wrapPcmAsWav(pcm, sampleRate = SAMPLE_RATE) {
     new Uint8Array(buf, 44).set(pcm);
     return new Uint8Array(buf);
 }
+exposeForTests('pcm', { writeAscii, wrapPcmAsWav });

package/esm/src/providers/provider.js

@@ -15,6 +15,7 @@ import { toInteractionsBody } from './interactions.js';
 import { fetchGemini } from './keys.js';
 import { wrapPcmAsWav } from './pcm.js';
 import { INTERACTIONS_URL, takeSsePayloads } from './sse.js';
+import { exposeForTests } from './expose-for-tests.js';
 const HTTP_OK = 200;
 function base64ToBytes(data) {
     const bin = atob(data);
@@ -161,3 +162,15 @@ function createInteractionsProvider(transport) {
     };
 }
 export { createInteractionsProvider };
+exposeForTests('provider', {
+    base64ToBytes,
+    bytesToBase64,
+    isRawPcmMime,
+    normalizeSpeechMedia,
+    eventType,
+    isDeltaEvent,
+    isCompleteEvent,
+    foldDeltaPayload,
+    foldPayload,
+    withTap,
+});

package/esm/src/providers/speech.js

@@ -8,6 +8,7 @@
  */
 import { toErrorEvent } from '../guardrails/error.js';
 import { wrapPcmAsWav } from './pcm.js';
+import { exposeForTests } from './expose-for-tests.js';
 const HTTP_OK = 200;
 function bytesToBase64(bytes) {
     let bin = '';
@@ -124,3 +125,12 @@ function createSpeechProvider(config = {}) {
     };
 }
 export { createSpeechProvider, streamSpeech };
+exposeForTests('speech', {
+    bytesToBase64,
+    extractInputText,
+    resolveSpeechWireModel,
+    buildHeaders,
+    buildPayload,
+    requestSpeech,
+    yieldSpeechSuccess,
+});

package/esm/src/providers/sse.js

@@ -1,3 +1,4 @@
+import { exposeForTests } from './expose-for-tests.js';
 const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse';
 const DATA_PREFIX = 'data: ';
 const EVENT_PREFIX = 'event: ';
@@ -51,3 +52,4 @@ function takeSsePayloads(buffer, pendingEvent = '') {
     return { rest, payloads, pendingEvent: sseEvent };
 }
 export { INTERACTIONS_URL, takeSsePayloads };
+exposeForTests('sse', { asObject, dataRecord, takeSsePayloads });

package/esm/src/streaming/mod.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Structured-output streaming helpers (incomplete JSON text buffers).
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { readStreamingJsonStringField } from './readStreamingJsonStringField.js';

package/esm/src/streaming/mod.js

@@ -0,0 +1,7 @@
+/**
+ * Structured-output streaming helpers (incomplete JSON text buffers).
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { readStreamingJsonStringField } from './readStreamingJsonStringField.js';

package/esm/src/streaming/readStreamingJsonStringField.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Read one string field from incomplete JSON while structured output streams as text deltas.
+ *
+ * The buffer may lack a closing quote; any decoded prefix is returned for live preview.
+ */
+export declare function readStreamingJsonStringField(jsonText: string, key: string): string | null;

package/esm/src/streaming/readStreamingJsonStringField.js

@@ -0,0 +1,55 @@
+const JSON_ESCAPES = {
+    n: '\n',
+    t: '\t',
+    r: '\r',
+    '"': '"',
+    '\\': '\\',
+    '/': '/',
+};
+function decodeEscapedChar(ch, jsonText, index) {
+    if (ch === 'u' && index + 4 < jsonText.length) {
+        const hex = jsonText.slice(index + 1, index + 5);
+        if (/^[0-9a-fA-F]{4}$/.test(hex)) {
+            return { text: String.fromCharCode(Number.parseInt(hex, 16)), next: index + 4 };
+        }
+    }
+    const mapped = JSON_ESCAPES[ch];
+    return { text: mapped ?? ch, next: index };
+}
+/**
+ * Read one string field from incomplete JSON while structured output streams as text deltas.
+ *
+ * The buffer may lack a closing quote; any decoded prefix is returned for live preview.
+ */
+export function readStreamingJsonStringField(jsonText, key) {
+    const keyPattern = new RegExp(`"${key}"\\s*:\\s*"`);
+    const match = keyPattern.exec(jsonText);
+    if (!match || match.index === undefined) {
+        return null;
+    }
+    let i = match.index + match[0].length;
+    let result = '';
+    let escaped = false;
+    while (i < jsonText.length) {
+        const ch = jsonText[i];
+        if (escaped) {
+            const decoded = decodeEscapedChar(ch, jsonText, i);
+            result += decoded.text;
+            i = decoded.next;
+            escaped = false;
+            i += 1;
+            continue;
+        }
+        if (ch === '\\') {
+            escaped = true;
+        }
+        else if (ch === '"') {
+            return result;
+        }
+        else {
+            result += ch;
+        }
+        i += 1;
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theorum",
-  "version": "0.1.7",
+  "version": "0.1.10",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",
@@ -45,6 +45,9 @@
     },
     "./presets/google": {
       "import": "./esm/src/presets/google.js"
+    },
+    "./streaming": {
+      "import": "./esm/src/streaming/mod.js"
     }
   },
   "scripts": {},
@@ -54,8 +57,8 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@openrouter/ai-sdk-provider": "1.5.4",
-    "ai": "5.0.244",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
+    "ai": "^7.0.0",
     "@deno/shim-deno": "~0.18.0"
   },
   "devDependencies": {