@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/providers/openrouter/chat.js

@@ -1,490 +0,0 @@
-import { createOpenRouter } from '@openrouter/ai-sdk-provider';
-import { AISDKError, APICallError, generateText, jsonSchema, RetryError, StreamProviderError, streamText, tool, } from 'ai';
-import { isAbortError, kindOfHttpStatus, TheoremError, toErrorEvent, } from '../../guardrails/error.js';
-import { asRecord } from '../../kernel/engine/record.js';
-import { reportedTokens, usageCount } from '../../kernel/engine/usage.js';
-import { turnStopFromOpenAiFinishReason } from '../../kernel/stop.js';
-import { builtinWire } from '../shared/builtin-wire.js';
-import { foldResponse } from '../shared/response-identity.js';
-import { structuredEvent } from '../shared/structured-output.js';
-import { malformedToolCall, toolCallEvents } from '../shared/tool-args.js';
-import { networkError } from '../shared/upstream-tap.js';
-import { bearerFetch } from '../shared/vault.js';
-import { cacheControlJson } from './cache-control.js';
-import { openAiGatewayHeaders, resolveResponseFormat } from './openai/compat.js';
-import { buildAiSdkMessages } from './openai/sdk-messages.js';
-import { openAiResponse, openAiUsageTokens } from './openai/usage.js';
-import { resolveOpenAiGatewayApiKey } from './resolve-api-key.js';
-export function trimApiKey(explicitKey) {
-    if (explicitKey?.trim()) {
-        return explicitKey.trim();
-    }
-    return undefined;
-}
-export function createAccumulator() {
-    return {
-        text: '',
-        citedUris: new Set(),
-        reportedAnnotations: new Set(),
-        emittedTokens: false,
-        errored: false,
-    };
-}
-function webSource(uri, title) {
-    return { title: title || uri, uri, type: 'web' };
-}
-function citationEvent(sources, acc) {
-    const fresh = [];
-    for (const source of sources) {
-        if (acc.citedUris.has(source.uri))
-            continue;
-        acc.citedUris.add(source.uri);
-        fresh.push(source);
-    }
-    return fresh.length > 0 ? { type: 'citation', sources: fresh } : undefined;
-}
-export function sourceEvent(part, acc) {
-    if (part.sourceType === 'url') {
-        return citationEvent([webSource(part.url, part.title)], acc);
-    }
-    return {
-        type: 'evidence',
-        evidence: { provider: 'openrouter', kind: 'provider_step', step: 'source', raw: { ...part } },
-    };
-}
-export function schemaForTool(decl) {
-    return decl.parameters ?? { type: 'object', properties: {}, additionalProperties: true };
-}
-export function buildTools(wireTools) {
-    if (!wireTools || wireTools.length === 0) {
-        return undefined;
-    }
-    const tools = {};
-    for (const decl of wireTools) {
-        tools[decl.name] = tool({
-            description: decl.description,
-            inputSchema: jsonSchema(schemaForTool(decl)),
-        });
-    }
-    return tools;
-}
-/** `web` wires as `web_search_options`; every other builtin is a plugin. */
-function openRouterSettings(req) {
-    let webSearch = false;
-    const plugins = [];
-    for (const builtin of req.builtins) {
-        const pluginId = builtinWire(builtin, 'openRouter');
-        if (pluginId === 'web')
-            webSearch = true;
-        else
-            plugins.push({ id: pluginId });
-    }
-    if (plugins.length === 0 && !webSearch) {
-        return undefined;
-    }
-    const settings = {};
-    if (plugins.length > 0) {
-        settings.plugins = plugins;
-    }
-    if (webSearch)
-        settings.web_search_options = {};
-    return settings;
-}
-/** Only when the raw stream carried no `usage` row; `rawEvents` reads that one first, with cost. */
-export function tokensFromUsage(usage) {
-    return reportedTokens({
-        input: usageCount(usage.inputTokens),
-        output: usageCount(usage.outputTokens),
-        thinking: usageCount(usage.outputTokenDetails?.reasoningTokens),
-        cached: usageCount(usage.inputTokenDetails?.cacheReadTokens),
-        cacheWrite: usageCount(usage.inputTokenDetails?.cacheWriteTokens),
-    });
-}
-export function stringArray(value) {
-    if (!Array.isArray(value)) {
-        return undefined;
-    }
-    const out = value.filter((item) => typeof item === 'string');
-    return out.length > 0 ? out : undefined;
-}
-export function metadataRecord(raw, key) {
-    return asRecord(raw[key]);
-}
-export function citationCandidates(raw) {
-    const openrouter = metadataRecord(raw, 'openrouter') ?? {};
-    return [
-        raw.citations,
-        metadataRecord(raw, 'providerMetadata')?.citations,
-        metadataRecord(raw, 'provider_metadata')?.citations,
-        openrouter.citations,
-        metadataRecord(openrouter, 'providerMetadata')?.citations,
-        metadataRecord(openrouter, 'provider_metadata')?.citations,
-    ];
-}
-export function nestedCitations(raw) {
-    for (const candidate of citationCandidates(raw)) {
-        const citations = stringArray(candidate);
-        if (citations) {
-            return citations;
-        }
-    }
-    return undefined;
-}
-export function metadataAnnotations(raw) {
-    const openrouter = metadataRecord(raw, 'openrouter');
-    if (Array.isArray(raw.annotations)) {
-        return raw.annotations;
-    }
-    if (Array.isArray(openrouter?.annotations)) {
-        return openrouter.annotations;
-    }
-    return undefined;
-}
-function annotationSource(annotation) {
-    const record = asRecord(annotation);
-    const cited = asRecord(record?.url_citation);
-    if (record?.type !== 'url_citation' || typeof cited?.url !== 'string') {
-        return undefined;
-    }
-    return webSource(cited.url, typeof cited.title === 'string' ? cited.title : undefined);
-}
-/** Each citation or annotation reports once per call, however many rows repeat it. */
-export function eventsFromMetadata(metadata, acc) {
-    const raw = asRecord(metadata);
-    if (!raw) {
-        return [];
-    }
-    const annotations = metadataAnnotations(raw) ?? [];
-    const sources = (nestedCitations(raw) ?? []).map((uri) => webSource(uri));
-    const other = [];
-    for (const annotation of annotations) {
-        const source = annotationSource(annotation);
-        if (source) {
-            sources.push(source);
-            continue;
-        }
-        const key = String(JSON.stringify(annotation));
-        if (acc.reportedAnnotations.has(key))
-            continue;
-        acc.reportedAnnotations.add(key);
-        other.push(annotation);
-    }
-    const events = [];
-    const citation = citationEvent(sources, acc);
-    if (citation) {
-        events.push(citation);
-    }
-    if (other.length > 0) {
-        events.push({
-            type: 'evidence',
-            evidence: {
-                provider: 'openrouter',
-                kind: 'provider_step',
-                step: 'annotations',
-                raw: { annotations: other },
-            },
-        });
-    }
-    return events;
-}
-export function rawThoughtEvent(raw) {
-    const choices = raw.choices;
-    if (!Array.isArray(choices)) {
-        return undefined;
-    }
-    for (const choice of choices) {
-        const delta = asRecord(asRecord(choice)?.delta);
-        if (typeof delta?.thinking === 'string') {
-            return { type: 'thought', text: delta.thinking };
-        }
-    }
-    return undefined;
-}
-export function rawChoiceMessageEvents(raw, acc) {
-    const choices = Array.isArray(raw.choices) ? raw.choices : [];
-    return choices.flatMap((choice) => eventsFromMetadata(asRecord(choice)?.message, acc));
-}
-export function rawEvents(raw, acc) {
-    const record = asRecord(raw);
-    if (!record) {
-        return [];
-    }
-    const identity = foldResponse(acc.response, openAiResponse(record));
-    acc.response = identity.known;
-    const events = identity.event ? [identity.event] : [];
-    const thought = rawThoughtEvent(record);
-    if (thought) {
-        events.push(thought);
-    }
-    events.push(...eventsFromMetadata(record, acc), ...rawChoiceMessageEvents(record, acc));
-    if (!acc.emittedTokens) {
-        const usage = openAiUsageTokens(record.usage);
-        if (usage) {
-            acc.emittedTokens = true;
-            events.push({ type: 'tokens', tokens: usage });
-        }
-    }
-    const choices = Array.isArray(record.choices) ? record.choices : [];
-    for (const choice of choices) {
-        const row = asRecord(choice);
-        if (!row)
-            continue;
-        if (typeof row.finish_reason === 'string' || row.finish_reason === null) {
-            acc.finishReason = row.finish_reason;
-        }
-        if (typeof row.native_finish_reason === 'string' || row.native_finish_reason === null) {
-            acc.nativeFinishReason = row.native_finish_reason;
-        }
-    }
-    return events;
-}
-/** A call the SDK could not parse or match is the call with no arguments, then its failure. */
-export function toolCallPartEvents(part) {
-    if (part.invalid) {
-        const message = part.error instanceof Error ? part.error.message : 'tool call was not valid';
-        return malformedToolCall({ name: part.toolName, callId: part.toolCallId }, message, part.input);
-    }
-    return toolCallEvents({ id: part.toolCallId, name: part.toolName }, part.input);
-}
-export function tokenEvent(part) {
-    const tokens = tokensFromUsage(part.totalUsage);
-    return tokens ? { type: 'tokens', tokens } : undefined;
-}
-export function providerMetadataEvents(part, acc) {
-    return 'providerMetadata' in part ? eventsFromMetadata(part.providerMetadata, acc) : [];
-}
-export function eventFromPart(part, acc) {
-    return [...primaryEventsFromPart(part, acc), ...providerMetadataEvents(part, acc)];
-}
-export function primaryEventsFromPart(part, acc) {
-    switch (part.type) {
-        case 'text-delta':
-            acc.text += part.text;
-            return [{ type: 'text', text: part.text }];
-        case 'reasoning-delta':
-            return [{ type: 'thought', text: part.text }];
-        case 'tool-call':
-            return toolCallPartEvents(part);
-        case 'source': {
-            const event = sourceEvent(part, acc);
-            return event ? [event] : [];
-        }
-        case 'finish': {
-            const event = finishEvent(part, acc);
-            return event ? [event] : [];
-        }
-        case 'error':
-            acc.errored = true;
-            return [toErrorEvent(streamPartError(part.error))];
-        default:
-            return [];
-    }
-}
-export function finishEvent(part, acc) {
-    if (part.finishReason != null) {
-        acc.finishReason = String(part.finishReason);
-    }
-    if (acc.emittedTokens) {
-        return undefined;
-    }
-    if (!part.totalUsage) {
-        return undefined;
-    }
-    const event = tokenEvent({ totalUsage: part.totalUsage });
-    if (event) {
-        acc.emittedTokens = true;
-    }
-    return event;
-}
-export function* finalEvents(req, acc) {
-    if (acc.errored) {
-        return;
-    }
-    if (req.structured && acc.text) {
-        const event = structuredEvent(acc.text);
-        yield event;
-        if (event.type === 'error')
-            return;
-    }
-    yield {
-        type: 'done',
-        stop: turnStopFromOpenAiFinishReason(acc.finishReason, acc.nativeFinishReason),
-    };
-}
-function createStreamContext(req, config, apiKey) {
-    const openrouter = createOpenRouter({
-        apiKey,
-        baseURL: config.baseUrl,
-        headers: openAiGatewayHeaders(config),
-        // The AI SDK retries internally; tapping its fetch tapes every try.
-        fetch: bearerFetch(req, config.fetch ?? fetch, config.vault, apiKey),
-        compatibility: 'strict',
-    });
-    return {
-        openrouter,
-        modelName: req.apiId,
-    };
-}
-/** System via instructions XOR a cache-marked system message — never both. */
-export function systemDelivery(req) {
-    if (!req.system) {
-        return {};
-    }
-    if (req.cache?.mode === 'system') {
-        return {
-            systemMessage: {
-                role: 'system',
-                content: req.system,
-                providerOptions: {
-                    openrouter: { cacheControl: cacheControlJson(req.cache) },
-                },
-            },
-        };
-    }
-    return { instructions: req.system };
-}
-function streamTextOptions(req, context) {
-    const delivery = systemDelivery(req);
-    const messages = buildAiSdkMessages(req);
-    if (delivery.systemMessage) {
-        messages.unshift(delivery.systemMessage);
-    }
-    return {
-        model: context.openrouter.chat(context.modelName, openRouterSettings(req)),
-        instructions: delivery.instructions,
-        messages,
-        allowSystemInMessages: true,
-        temperature: req.temperature,
-        maxOutputTokens: req.maxOutputTokens,
-        tools: buildTools(req.wireTools),
-        providerOptions: providerOptionsFor(req),
-        include: { rawChunks: true },
-        abortSignal: req.signal,
-        onError: () => undefined,
-    };
-}
-function shouldEmitProviderEvent(req, event) {
-    return event.type !== 'thought' || req.summaries !== 'none';
-}
-async function* yieldAiSdkStream(req, acc, context) {
-    const result = streamText(streamTextOptions(req, context));
-    for await (const part of result.stream) {
-        if (part.type === 'raw') {
-            req.tapUpstream?.(asRecord(part.rawValue) ?? { rawValue: part.rawValue });
-            for (const event of rawEvents(part.rawValue, acc)) {
-                if (shouldEmitProviderEvent(req, event)) {
-                    yield event;
-                }
-            }
-            continue;
-        }
-        for (const event of eventFromPart(part, acc)) {
-            if (shouldEmitProviderEvent(req, event)) {
-                yield event;
-            }
-        }
-    }
-}
-async function* yieldAiSdkBuffered(req, acc, context) {
-    const { include: _, onError: __, ...options } = streamTextOptions(req, context);
-    const result = await generateText({ ...options, include: { responseBody: true } });
-    const body = asRecord(result.response.body);
-    if (body) {
-        req.tapUpstream?.(body);
-        yield* rawEvents(body, acc).filter((event) => shouldEmitProviderEvent(req, event));
-    }
-    for (const part of result.content) {
-        const events = part.type === 'text'
-            ? [{ type: 'text', text: part.text }]
-            : part.type === 'reasoning'
-                ? [{ type: 'thought', text: part.text }]
-                : part.type === 'tool-call' || part.type === 'source'
-                    ? primaryEventsFromPart(part, acc)
-                    : [];
-        if (part.type === 'text')
-            acc.text += part.text;
-        yield* events.filter((event) => shouldEmitProviderEvent(req, event));
-    }
-    yield* eventsFromMetadata(result.providerMetadata, acc).filter((event) => shouldEmitProviderEvent(req, event));
-    const tokens = finishEvent(result, acc);
-    if (tokens)
-        yield tokens;
-}
-async function* streamOpenRouter(req, config) {
-    let apiKey;
-    try {
-        apiKey = resolveOpenAiGatewayApiKey(config, req.keySlot);
-    }
-    catch (err) {
-        yield toErrorEvent(err);
-        return;
-    }
-    const acc = createAccumulator();
-    const context = createStreamContext(req, config, apiKey);
-    try {
-        yield* req.stream === false
-            ? yieldAiSdkBuffered(req, acc, context)
-            : yieldAiSdkStream(req, acc, context);
-        yield* finalEvents(req, acc);
-    }
-    catch (err) {
-        if (isAbortError(err)) {
-            throw err;
-        }
-        yield toErrorEvent(sdkError(err));
-    }
-}
-/**
- * An HTTP status wins; a call with no response could not reach OpenRouter; a
- * mid-stream error without a status is OpenRouter's own; any other SDK error is
- * a reply the SDK could not read.
- */
-function sdkError(err) {
-    if (RetryError.isInstance(err)) {
-        return sdkError(err.lastError);
-    }
-    if (!AISDKError.isInstance(err)) {
-        return err;
-    }
-    const status = asRecord(err)?.statusCode;
-    const kind = typeof status === 'number'
-        ? kindOfHttpStatus(status)
-        : APICallError.isInstance(err)
-            ? 'network'
-            : StreamProviderError.isInstance(err)
-                ? 'unavailable'
-                : 'bad_response';
-    return new TheoremError(kind, err.message, { cause: err });
-}
-/** A body that breaks mid-read arrives as a plain error, not an SDK one. */
-function streamPartError(error) {
-    return AISDKError.isInstance(error) || RetryError.isInstance(error)
-        ? sdkError(error)
-        : networkError(error);
-}
-export function providerOptionsFor(req) {
-    const openrouter = {};
-    if (req.thinking) {
-        openrouter.reasoning = { effort: req.thinking };
-    }
-    const responseFormat = resolveResponseFormat(req.structured);
-    if (responseFormat) {
-        openrouter.response_format = responseFormat;
-        // Route only to endpoints that honour the schema; one that ignores it answers in prose.
-        openrouter.provider = { require_parameters: true };
-    }
-    if (req.cache?.mode === 'automatic') {
-        openrouter.cacheControl = cacheControlJson(req.cache);
-    }
-    if (req.sessionId) {
-        openrouter.session_id = req.sessionId;
-    }
-    if (Object.keys(openrouter).length === 0)
-        return undefined;
-    return { openrouter };
-}
-export function createOpenRouterProvider(config = {}) {
-    return {
-        complete: (req) => streamOpenRouter(req, config),
-    };
-}

package/esm/src/providers/openrouter/openai/sdk-messages.d.ts

@@ -1,10 +0,0 @@
-import type { ModelMessage } from 'ai';
-import type { InteractionPart, ProviderCompleteRequest, TurnHistoryMessage } from '../../../kernel/types.js';
-export declare function sdkPart(input: InteractionPart): Record<string, unknown>;
-export declare function sdkContentFromParts(parts: InteractionPart[]): string | Array<Record<string, unknown>>;
-export declare function toolResultMessage(msg: TurnHistoryMessage): ModelMessage;
-export declare function assistantToolCallMessage(msg: TurnHistoryMessage): ModelMessage | null;
-export declare function contentHistoryMessage(msg: TurnHistoryMessage): ModelMessage;
-export declare function historyToSdk(msg: TurnHistoryMessage): ModelMessage | null;
-/** Leaves `req.system` to the caller (`systemDelivery` in chat.ts). */
-export declare function buildAiSdkMessages(req: ProviderCompleteRequest): ModelMessage[];

package/esm/src/providers/openrouter/openai/sdk-messages.js

@@ -1,99 +0,0 @@
-import { TheoremError } from '../../../guardrails/error.js';
-import { historyMessageParts, isMediaRefPart } from '../../../kernel/interaction-parts.js';
-import { historyToolArguments, historyToolIdentity } from '../../shared/tool-args.js';
-function inlineMediaPart(part) {
-    if (isMediaRefPart(part)) {
-        throw new TheoremError('unsupported', 'media references are not supported on openAi');
-    }
-    return part;
-}
-export function sdkPart(input) {
-    if (input.type === 'text') {
-        return { type: 'text', text: input.text };
-    }
-    const part = inlineMediaPart(input);
-    return { type: 'file', mediaType: part.mimeType, data: part.data };
-}
-export function sdkContentFromParts(parts) {
-    if (parts.every((part) => part.type === 'text')) {
-        return parts
-            .map((part) => (part.type === 'text' ? part.text : ''))
-            .filter(Boolean)
-            .join('\n');
-    }
-    return parts.map(sdkPart);
-}
-export function toolResultMessage(msg) {
-    const parts = historyMessageParts(msg);
-    const content = sdkContentFromParts(parts);
-    const output = typeof content === 'string'
-        ? { type: 'text', value: content }
-        : {
-            type: 'content',
-            value: parts.map((input) => {
-                if (input.type === 'text') {
-                    return { type: 'text', text: input.text };
-                }
-                const part = inlineMediaPart(input);
-                return {
-                    type: 'file',
-                    mediaType: part.mimeType,
-                    data: { type: 'data', data: part.data },
-                };
-            }),
-        };
-    // AI SDK ToolModelMessage is a branded union; structural tool-result is correct at runtime.
-    return {
-        role: 'tool',
-        content: [
-            {
-                type: 'tool-result',
-                // The AI SDK rejects a missing id or name (`AI_InvalidPromptError`).
-                ...historyToolIdentity({ toolCallId: msg.tool_call_id, toolName: msg.name }),
-                output,
-            },
-        ],
-    };
-}
-export function assistantToolCallMessage(msg) {
-    if (!msg.tool_calls || msg.tool_calls.length === 0) {
-        return null;
-    }
-    const said = sdkContentFromParts(historyMessageParts(msg));
-    const lead = typeof said === 'string' ? (said ? [{ type: 'text', text: said }] : []) : said;
-    return {
-        role: 'assistant',
-        content: [
-            ...lead,
-            ...msg.tool_calls.map((call) => ({
-                type: 'tool-call',
-                toolCallId: call.id,
-                toolName: call.function.name,
-                input: historyToolArguments(call.function.arguments),
-            })),
-        ],
-    };
-}
-export function contentHistoryMessage(msg) {
-    return { role: msg.role, content: sdkContentFromParts(historyMessageParts(msg)) };
-}
-export function historyToSdk(msg) {
-    if (msg.role === 'tool') {
-        return toolResultMessage(msg);
-    }
-    return assistantToolCallMessage(msg) || contentHistoryMessage(msg);
-}
-/** Leaves `req.system` to the caller (`systemDelivery` in chat.ts). */
-export function buildAiSdkMessages(req) {
-    const messages = [];
-    for (const msg of req.history ?? []) {
-        const wired = historyToSdk(msg);
-        if (wired) {
-            messages.push(wired);
-        }
-    }
-    if (req.input.length > 0) {
-        messages.push({ role: 'user', content: sdkContentFromParts(req.input) });
-    }
-    return messages;
-}

package/esm/src/providers/openrouter/resolve-api-key.d.ts

@@ -1,3 +0,0 @@
-import type { KeySlot } from '../../kernel/types.js';
-import type { OpenAiGatewayTransport } from '../types.js';
-export declare function resolveOpenAiGatewayApiKey(config: OpenAiGatewayTransport, keySlot: KeySlot | undefined): string;

package/esm/src/providers/openrouter/resolve-api-key.js

@@ -1,8 +0,0 @@
-import { TheoremError } from '../../guardrails/error.js';
-import { requireKey } from '../shared/vault.js';
-export function resolveOpenAiGatewayApiKey(config, keySlot) {
-    if (keySlot === undefined) {
-        throw new TheoremError('auth', 'an OpenRouter model must name a vault slot');
-    }
-    return requireKey(config.vault, keySlot);
-}

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

@@ -1,18 +0,0 @@
-import type { InteractionPart, ModelProvider, ProfileSpeechSpec, ProviderCompleteRequest, ProviderEvent } from '../../kernel/types.js';
-import type { OpenAiGatewayTransport } from '../types.js';
-export type SpeechProviderConfig = OpenAiGatewayTransport & {
-    /** Fallback when the profile does not pin `speech.voice`. */
-    voice?: string;
-};
-export declare function extractInputText(input: InteractionPart[]): string;
-export declare function buildSpeechHeaders(apiKey: string, config: SpeechProviderConfig): Record<string, string>;
-export declare function buildPayload(req: ProviderCompleteRequest, text: string, speech: ProfileSpeechSpec | undefined, configVoice?: string): Record<string, unknown>;
-export declare function requestSpeech(apiKey: string, text: string, req: ProviderCompleteRequest, config: SpeechProviderConfig): Promise<Response>;
-/**
- * The response's `content-type` states the audio (probe 23/09/2026:
- * `audio/pcm;rate=24000;channels=1` for `pcm`). Raw PCM with a stated rate is
- * wrapped as WAV; anything else keeps its reported type.
- */
-export declare function yieldSpeechSuccess(rawBytes: Uint8Array, contentType: string | null): Generator<ProviderEvent>;
-export declare function streamSpeech(req: ProviderCompleteRequest, config?: SpeechProviderConfig): AsyncGenerator<ProviderEvent>;
-export declare function createSpeechProvider(config?: SpeechProviderConfig): ModelProvider;