theorum 0.1.7 → 0.1.9

package/esm/src/providers/create-provider.d.ts

@@ -22,8 +22,15 @@ export interface CreateProviderOptions {
         voice?: string;
     };
 }
+declare function isSpeechRole(profile: Profile): boolean;
 /**
  * Create a `ModelProvider` for a profile.
  * One call: protocol/provider (and speech role) pick the transport.
  */
 export declare function createProvider(profile: Profile, options?: CreateProviderOptions): ModelProvider;
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    isSpeechRole: typeof isSpeechRole;
+    createProvider: typeof createProvider;
+};
+export {};

package/esm/src/providers/create-provider.js

@@ -36,3 +36,5 @@ export function createProvider(profile, options = {}) {
     }
     throw new TheorumError(`createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
 }
+/** @internal Exported for direct unit testing only. */
+export const _internals = { isSpeechRole, createProvider };

package/esm/src/providers/gemini-tape.d.ts

@@ -1,2 +1,16 @@
+declare function isImageBlob(rec: Record<string, unknown>): boolean;
+declare function scrubEntry(rec: Record<string, unknown>, key: string, nested: unknown): Promise<[string, unknown]>;
+declare function scrubRecord(rec: Record<string, unknown>): Promise<Record<string, unknown>>;
+declare function scrubGemini(value: unknown): Promise<unknown>;
+declare function redactCanaryInTree(value: unknown, canary: string): unknown;
 declare function tapeGemini(value: unknown, canary: string): Promise<unknown>;
 export { tapeGemini };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    isImageBlob: typeof isImageBlob;
+    scrubEntry: typeof scrubEntry;
+    scrubRecord: typeof scrubRecord;
+    scrubGemini: typeof scrubGemini;
+    redactCanaryInTree: typeof redactCanaryInTree;
+    tapeGemini: typeof tapeGemini;
+};

package/esm/src/providers/gemini-tape.js

@@ -44,3 +44,12 @@ async function tapeGemini(value, canary) {
     return redactCanaryInTree(await scrubGemini(value), canary);
 }
 export { tapeGemini };
+/** @internal Exported for direct unit testing only. */
+export const _internals = {
+    isImageBlob,
+    scrubEntry,
+    scrubRecord,
+    scrubGemini,
+    redactCanaryInTree,
+    tapeGemini,
+};

package/esm/src/providers/google-tap.d.ts

@@ -1,3 +1,13 @@
 import type { ProviderCompleteRequest } from '../kernel/types.js';
+declare function tapeHeaderValue(key: string, value: string): string;
+declare function tapeHeaders(headers?: HeadersInit): Record<string, string>;
+declare function throwRow(err: unknown): Record<string, unknown>;
 declare function tapFetch(tap: ProviderCompleteRequest['tapGemini'], send?: typeof fetch): typeof fetch;
 export { tapFetch };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    tapeHeaderValue: typeof tapeHeaderValue;
+    tapeHeaders: typeof tapeHeaders;
+    throwRow: typeof throwRow;
+    tapFetch: typeof tapFetch;
+};

package/esm/src/providers/google-tap.js

@@ -46,3 +46,5 @@ function tapFetch(tap, send = fetch) {
     };
 }
 export { tapFetch };
+/** @internal Exported for direct unit testing only. */
+export const _internals = { tapeHeaderValue, tapeHeaders, throwRow, tapFetch };

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

@@ -1,5 +1,41 @@
-import type { ProviderCompleteRequest } from '../kernel/types.js';
+import type { InteractionPart, ProviderCompleteRequest } from '../kernel/types.js';
 declare function camelToSnake(key: string): string;
+declare function toGoogleValue(value: unknown): unknown;
+declare function wirePart(part: InteractionPart): Record<string, string>;
+declare function userInputStep(parts: InteractionPart[]): {
+    type: string;
+    content: Record<string, string>[];
+};
+declare function historyStep(msg: import('../kernel/types.js').TurnHistoryMessage): {
+    type: string;
+    content: Record<string, string>[];
+};
+declare function systemHoldsUserInput(system: string, parts: InteractionPart[]): boolean;
+declare function jsonResponseFormat(schema: Record<string, unknown>): unknown[];
+declare function attachResponseFormat(req: ProviderCompleteRequest, camel: Record<string, unknown>): void;
+declare function attachSpeechConfig(req: ProviderCompleteRequest, generationConfig: Record<string, unknown>): void;
+declare function inputStepsFromRequest(req: ProviderCompleteRequest): {
+    type: string;
+    content: Record<string, string>[];
+}[];
+declare function applyOptionalRequestFields(req: ProviderCompleteRequest, camel: Record<string, unknown>): void;
+declare function baseInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;
 /** Interactions REST body for one complete() call (Google snake_case keys). */
 declare function toInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;
 export { camelToSnake, toInteractionsBody };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    camelToSnake: typeof camelToSnake;
+    toGoogleValue: typeof toGoogleValue;
+    wirePart: typeof wirePart;
+    userInputStep: typeof userInputStep;
+    historyStep: typeof historyStep;
+    systemHoldsUserInput: typeof systemHoldsUserInput;
+    jsonResponseFormat: typeof jsonResponseFormat;
+    attachResponseFormat: typeof attachResponseFormat;
+    attachSpeechConfig: typeof attachSpeechConfig;
+    inputStepsFromRequest: typeof inputStepsFromRequest;
+    applyOptionalRequestFields: typeof applyOptionalRequestFields;
+    baseInteractionsBody: typeof baseInteractionsBody;
+    toInteractionsBody: typeof toInteractionsBody;
+};

package/esm/src/providers/interactions.js

@@ -151,3 +151,19 @@ function toInteractionsBody(req) {
     return toGoogleValue(camel);
 }
 export { camelToSnake, toInteractionsBody };
+/** @internal Exported for direct unit testing only. */
+export const _internals = {
+    camelToSnake,
+    toGoogleValue,
+    wirePart,
+    userInputStep,
+    historyStep,
+    systemHoldsUserInput,
+    jsonResponseFormat,
+    attachResponseFormat,
+    attachSpeechConfig,
+    inputStepsFromRequest,
+    applyOptionalRequestFields,
+    baseInteractionsBody,
+    toInteractionsBody,
+};

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

@@ -13,7 +13,26 @@ interface GeminiTransport {
     wait?: (ms: number) => Promise<void>;
     fetch?: typeof fetch;
 }
+declare function waitDefault(ms: number): Promise<void>;
+declare function isQuota(err: unknown): boolean;
+declare function isTransientHttp(status: number): boolean;
+declare function isTransientThrown(err: unknown): boolean;
+declare function requireKey(vault: GeminiVault, bucket: GeminiBucket): string;
+declare function backoffMs(attempt: number): number;
+declare function canOverflow(bucket: GeminiBucket, vault: GeminiVault, primary: string): string | undefined;
 declare function withGeminiKey<T>(bucket: GeminiBucket, run: (apiKey: string) => Promise<T>, transport: GeminiTransport): Promise<T>;
+declare function withApiKey(init: RequestInit, apiKey: string): RequestInit;
 declare function fetchGemini(url: string, init: RequestInit, bucket: GeminiBucket, transport: GeminiTransport): Promise<Response>;
 export type { GeminiTransport, GeminiVault };
 export { fetchGemini, withGeminiKey };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    waitDefault: typeof waitDefault;
+    isQuota: typeof isQuota;
+    isTransientHttp: typeof isTransientHttp;
+    isTransientThrown: typeof isTransientThrown;
+    requireKey: typeof requireKey;
+    backoffMs: typeof backoffMs;
+    canOverflow: typeof canOverflow;
+    withApiKey: typeof withApiKey;
+};

package/esm/src/providers/keys.js

@@ -137,3 +137,14 @@ async function fetchGemini(url, init, bucket, transport) {
     return last;
 }
 export { fetchGemini, withGeminiKey };
+/** @internal Exported for direct unit testing only. */
+export const _internals = {
+    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.d.ts

@@ -7,9 +7,126 @@
  *
  * @module
  */
-import type { ModelProvider } from '../kernel/types.js';
+import { createOpenRouter, type OpenRouterChatSettings } from '@openrouter/ai-sdk-provider';
+import { type LanguageModelUsage, type ModelMessage, streamText, type TextStreamPart, type ToolSet } from 'ai';
+import type { DynamicToolDeclaration, InteractionPart, ModelProvider, ProviderCompleteRequest, TurnEvent, TurnHistoryMessage, TurnTokens } from '../kernel/types.js';
 import { type OpenRouterConfig, resolveOpenRouterModel, toOpenRouterPayload } from './openrouter-payload.js';
+interface StreamAccumulator {
+    text: string;
+    evidenceSeen: boolean;
+    emittedTokens: boolean;
+    errored: boolean;
+}
+interface OpenRouterStreamContext {
+    openrouter: ReturnType<typeof createOpenRouter>;
+    modelName: string;
+}
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type ProviderOptions = Record<string, {
+    [key: string]: JsonValue;
+}>;
+declare function trimApiKey(explicitKey?: string): string | undefined;
+declare function createAccumulator(): StreamAccumulator;
+declare function mediaPart(part: InteractionPart): Record<string, unknown>;
+declare function contentFromParts(parts: InteractionPart[]): string | Array<Record<string, unknown>>;
+declare function parseToolInput(raw: string): unknown;
+declare function stringDefault(value: string | undefined, fallback: string): string;
+declare function fallbackToolCallId(name?: string): string;
+declare function toolResultContent(msg: TurnHistoryMessage): ModelMessage;
+declare function assistantToolCallContent(msg: TurnHistoryMessage): ModelMessage | null;
+declare function historyMessage(msg: TurnHistoryMessage): ModelMessage | null;
+declare function contentFromOptionalParts(parts: InteractionPart[] | undefined, text: string | undefined): string | Array<Record<string, unknown>>;
+declare function contentHistoryMessage(msg: TurnHistoryMessage): ModelMessage;
+declare function sourceEvent(part: Extract<TextStreamPart<ToolSet>, {
+    type: 'source';
+}>): TurnEvent;
+declare function buildMessages(req: ProviderCompleteRequest): ModelMessage[];
+declare function schemaForTool(decl: DynamicToolDeclaration): Record<string, unknown>;
+declare function buildTools(dynamicTools?: DynamicToolDeclaration[]): ToolSet | undefined;
+declare function openRouterSettings(req: ProviderCompleteRequest): OpenRouterChatSettings | undefined;
+declare function tokensFromUsage(usage: LanguageModelUsage): TurnTokens | undefined;
+declare function rawRecord(value: unknown): Record<string, unknown> | undefined;
+declare function stringArray(value: unknown): string[] | undefined;
+declare function metadataRecord(raw: Record<string, unknown>, key: string): Record<string, unknown> | undefined;
+declare function citationCandidates(raw: Record<string, unknown>): unknown[];
+declare function nestedCitations(raw: Record<string, unknown>): string[] | undefined;
+declare function metadataAnnotations(raw: Record<string, unknown>): unknown[] | undefined;
+declare function evidenceFromMetadata(metadata: unknown, acc: StreamAccumulator): TurnEvent | undefined;
+declare function toolArguments(input: unknown): Record<string, unknown> | undefined;
+declare function toolResultData(output: unknown): Record<string, unknown> | undefined;
+declare function rawThoughtEvent(raw: Record<string, unknown>): TurnEvent | undefined;
+declare function rawChoiceMessageEvidence(raw: Record<string, unknown>, acc: StreamAccumulator): TurnEvent | undefined;
+declare function rawEvents(raw: unknown, acc: StreamAccumulator): TurnEvent[];
+declare function toolCallEvent(part: Extract<TextStreamPart<ToolSet>, {
+    type: 'tool-call';
+}>): TurnEvent;
+declare function toolResultEvent(part: Extract<TextStreamPart<ToolSet>, {
+    type: 'tool-result';
+}>): TurnEvent;
+declare function tokenEvent(part: Extract<TextStreamPart<ToolSet>, {
+    type: 'finish';
+}>): TurnEvent | undefined;
+declare function providerMetadataEvent(part: TextStreamPart<ToolSet>, acc: StreamAccumulator): TurnEvent | undefined;
+declare function eventFromPart(part: TextStreamPart<ToolSet>, acc: StreamAccumulator): TurnEvent[];
+declare function primaryEventFromPart(part: TextStreamPart<ToolSet>, acc: StreamAccumulator): TurnEvent | undefined;
+declare function finishEvent(part: Extract<TextStreamPart<ToolSet>, {
+    type: 'finish';
+}>, acc: StreamAccumulator): TurnEvent | undefined;
+declare function streamTextOptions(req: ProviderCompleteRequest, context: OpenRouterStreamContext): Parameters<typeof streamText>[0];
+declare function missingOpenRouterKey(): TurnEvent;
+declare function finalEvents(req: ProviderCompleteRequest, acc: StreamAccumulator): Generator<TurnEvent>;
+declare function responseFormatFor(req: ProviderCompleteRequest): Record<string, JsonValue> | undefined;
+declare function providerOptionsFor(req: ProviderCompleteRequest): ProviderOptions | undefined;
+declare function openRouterHeaders(config: OpenRouterConfig): Record<string, string> | undefined;
 /** Create a `ModelProvider` backed by OpenRouter through AI SDK Core. */
 declare function createOpenRouterProvider(config?: OpenRouterConfig): ModelProvider;
 export type { OpenRouterConfig };
 export { createOpenRouterProvider, resolveOpenRouterModel, toOpenRouterPayload };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    trimApiKey: typeof trimApiKey;
+    createAccumulator: typeof createAccumulator;
+    mediaPart: typeof mediaPart;
+    contentFromParts: typeof contentFromParts;
+    parseToolInput: typeof parseToolInput;
+    stringDefault: typeof stringDefault;
+    fallbackToolCallId: typeof fallbackToolCallId;
+    toolResultContent: typeof toolResultContent;
+    assistantToolCallContent: typeof assistantToolCallContent;
+    historyMessage: typeof historyMessage;
+    contentFromOptionalParts: typeof contentFromOptionalParts;
+    contentHistoryMessage: typeof contentHistoryMessage;
+    buildMessages: typeof buildMessages;
+    schemaForTool: typeof schemaForTool;
+    buildTools: typeof buildTools;
+    openRouterSettings: typeof openRouterSettings;
+    tokensFromUsage: typeof tokensFromUsage;
+    rawRecord: typeof rawRecord;
+    stringArray: typeof stringArray;
+    metadataRecord: typeof metadataRecord;
+    citationCandidates: typeof citationCandidates;
+    nestedCitations: typeof nestedCitations;
+    metadataAnnotations: typeof metadataAnnotations;
+    evidenceFromMetadata: typeof evidenceFromMetadata;
+    toolArguments: typeof toolArguments;
+    toolResultData: typeof toolResultData;
+    rawThoughtEvent: typeof rawThoughtEvent;
+    rawChoiceMessageEvidence: typeof rawChoiceMessageEvidence;
+    rawEvents: typeof rawEvents;
+    toolCallEvent: typeof toolCallEvent;
+    toolResultEvent: typeof toolResultEvent;
+    tokenEvent: typeof tokenEvent;
+    providerMetadataEvent: typeof providerMetadataEvent;
+    eventFromPart: typeof eventFromPart;
+    primaryEventFromPart: typeof primaryEventFromPart;
+    finishEvent: typeof finishEvent;
+    sourceEvent: typeof sourceEvent;
+    finalEvents: typeof finalEvents;
+    responseFormatFor: typeof responseFormatFor;
+    providerOptionsFor: typeof providerOptionsFor;
+    openRouterHeaders: typeof openRouterHeaders;
+    missingOpenRouterKey: typeof missingOpenRouterKey;
+    streamTextOptions: typeof streamTextOptions;
+};

package/esm/src/providers/openrouter.js

@@ -11,9 +11,8 @@ 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';
 function trimApiKey(explicitKey) {
     if (explicitKey?.trim()) {
         return explicitKey.trim();
@@ -26,7 +25,6 @@ function createAccumulator() {
         evidenceSeen: false,
         emittedTokens: false,
         errored: false,
-        toolInputs: new Map(),
     };
 }
 function mediaPart(part) {
@@ -61,9 +59,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 +106,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 +153,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 +249,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 +302,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 +337,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 +353,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 +381,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 +395,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 +427,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 +440,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 +461,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 +506,49 @@ function createOpenRouterProvider(config = {}) {
     };
 }
 export { createOpenRouterProvider, resolveOpenRouterModel, toOpenRouterPayload };
+/** @internal Exported for direct unit testing only. */
+export const _internals = {
+    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.d.ts

@@ -3,5 +3,12 @@
  *
  * @module
  */
+declare function writeAscii(view: DataView, offset: number, str: string): void;
 /** Wrap raw PCM bytes in a RIFF/WAVE container. */
 export declare function wrapPcmAsWav(pcm: Uint8Array, sampleRate?: number): Uint8Array;
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    writeAscii: typeof writeAscii;
+    wrapPcmAsWav: typeof wrapPcmAsWav;
+};
+export {};

package/esm/src/providers/pcm.js

@@ -33,3 +33,5 @@ export function wrapPcmAsWav(pcm, sampleRate = SAMPLE_RATE) {
     new Uint8Array(buf, 44).set(pcm);
     return new Uint8Array(buf);
 }
+/** @internal Exported for direct unit testing only. */
+export const _internals = { writeAscii, wrapPcmAsWav };

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

@@ -8,8 +8,36 @@
  *
  * @module
  */
-import type { ModelProvider } from '../kernel/types.js';
+import type { ModelProvider, ProviderCompleteRequest, TurnEvent } from '../kernel/types.js';
 import { type GeminiTransport } from './keys.js';
+declare function base64ToBytes(data: string): Uint8Array;
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function isRawPcmMime(mime: string): boolean;
+/** Google TTS returns raw PCM; wrap as WAV for hosts (matches OpenRouter pcm path). */
+declare function normalizeSpeechMedia(event: TurnEvent, speech: boolean): TurnEvent;
+declare function eventType(event: Record<string, unknown>): string;
+declare function isDeltaEvent(kind: string): boolean;
+declare function isCompleteEvent(kind: string): boolean;
+declare function foldDeltaPayload(event: Record<string, unknown>, acc: {
+    text: string;
+}): TurnEvent[];
+declare function foldPayload(event: Record<string, unknown>, acc: {
+    text: string;
+}): TurnEvent[];
+declare function withTap(req: ProviderCompleteRequest, transport: GeminiTransport): GeminiTransport;
 /** Create a `ModelProvider` backed by Google Interactions streaming. */
 declare function createInteractionsProvider(transport: GeminiTransport): ModelProvider;
 export { createInteractionsProvider };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    base64ToBytes: typeof base64ToBytes;
+    bytesToBase64: typeof bytesToBase64;
+    isRawPcmMime: typeof isRawPcmMime;
+    normalizeSpeechMedia: typeof normalizeSpeechMedia;
+    eventType: typeof eventType;
+    isDeltaEvent: typeof isDeltaEvent;
+    isCompleteEvent: typeof isCompleteEvent;
+    foldDeltaPayload: typeof foldDeltaPayload;
+    foldPayload: typeof foldPayload;
+    withTap: typeof withTap;
+};

package/esm/src/providers/provider.js

@@ -161,3 +161,16 @@ function createInteractionsProvider(transport) {
     };
 }
 export { createInteractionsProvider };
+/** @internal Exported for direct unit testing only. */
+export const _internals = {
+    base64ToBytes,
+    bytesToBase64,
+    isRawPcmMime,
+    normalizeSpeechMedia,
+    eventType,
+    isDeltaEvent,
+    isCompleteEvent,
+    foldDeltaPayload,
+    foldPayload,
+    withTap,
+};

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

@@ -6,7 +6,8 @@
  *
  * @module
  */
-import type { ModelProvider, ProviderCompleteRequest, TurnEvent } from '../kernel/types.js';
+import type { InteractionPart, ModelProvider, ProfileSpeechSpec, ProviderCompleteRequest, SpeechAudioFormat, TurnEvent } from '../kernel/types.js';
+declare function bytesToBase64(bytes: Uint8Array): string;
 /** Credentials for the openAi speech path (same shape as OpenRouter chat config + voice). */
 export interface SpeechProviderConfig {
     apiKey?: string;
@@ -17,7 +18,23 @@ export interface SpeechProviderConfig {
     siteName?: string;
     fetch?: typeof fetch;
 }
+declare function extractInputText(input: InteractionPart[]): string;
+declare function resolveSpeechWireModel(req: ProviderCompleteRequest): string;
+declare function buildHeaders(apiKey: string, config: SpeechProviderConfig): Record<string, string>;
+declare function buildPayload(req: ProviderCompleteRequest, text: string, speech: ProfileSpeechSpec | undefined, configVoice?: string): Record<string, unknown>;
+declare function requestSpeech(apiKey: string, text: string, req: ProviderCompleteRequest, config: SpeechProviderConfig): Promise<Response>;
+declare function yieldSpeechSuccess(rawBytes: Uint8Array, text: string, format: SpeechAudioFormat): Generator<TurnEvent>;
 declare function streamSpeech(req: ProviderCompleteRequest, config?: SpeechProviderConfig): AsyncGenerator<TurnEvent>;
 /** Internal ModelProvider for openAi speech roles. */
 declare function createSpeechProvider(config?: SpeechProviderConfig): ModelProvider;
 export { createSpeechProvider, streamSpeech };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    bytesToBase64: typeof bytesToBase64;
+    extractInputText: typeof extractInputText;
+    resolveSpeechWireModel: typeof resolveSpeechWireModel;
+    buildHeaders: typeof buildHeaders;
+    buildPayload: typeof buildPayload;
+    requestSpeech: typeof requestSpeech;
+    yieldSpeechSuccess: typeof yieldSpeechSuccess;
+};

package/esm/src/providers/speech.js

@@ -124,3 +124,13 @@ function createSpeechProvider(config = {}) {
     };
 }
 export { createSpeechProvider, streamSpeech };
+/** @internal Exported for direct unit testing only. */
+export const _internals = {
+    bytesToBase64,
+    extractInputText,
+    resolveSpeechWireModel,
+    buildHeaders,
+    buildPayload,
+    requestSpeech,
+    yieldSpeechSuccess,
+};

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

@@ -1,7 +1,15 @@
 declare const INTERACTIONS_URL = "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse";
+declare function asObject(parsed: unknown): Record<string, unknown> | undefined;
+declare function dataRecord(raw: string, sseEvent: string): Record<string, unknown>;
 declare function takeSsePayloads(buffer: string, pendingEvent?: string): {
     rest: string;
     payloads: Record<string, unknown>[];
     pendingEvent: string;
 };
 export { INTERACTIONS_URL, takeSsePayloads };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    asObject: typeof asObject;
+    dataRecord: typeof dataRecord;
+    takeSsePayloads: typeof takeSsePayloads;
+};

package/esm/src/providers/sse.js

@@ -51,3 +51,5 @@ function takeSsePayloads(buffer, pendingEvent = '') {
     return { rest, payloads, pendingEvent: sseEvent };
 }
 export { INTERACTIONS_URL, takeSsePayloads };
+/** @internal Exported for direct unit testing only. */
+export const _internals = { 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.9",
   "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": {