theorum 0.1.14 → 1.0.0

package/esm/src/kernel/engine/runner/tools.js

@@ -1,198 +0,0 @@
-import { toErrorEvent } from '../../../guardrails/error.js';
-import { sanitizeDynamicTools, sanitizeText } from '../../../guardrails/sanitize.js';
-import { CATALOG } from '../../registry/catalog.js';
-import { executeTool } from '../../registry/tools.js';
-function formatToolFinding(res) {
-    let raw;
-    if (res.finding) {
-        raw = res.finding;
-    }
-    else if (res.data) {
-        raw = JSON.stringify(res.data);
-    }
-    else {
-        return 'ok';
-    }
-    return sanitizeText(raw);
-}
-function* invokeFromUi(profile, req) {
-    const invoke = req.toolInvoke;
-    if (!invoke) {
-        return;
-    }
-    try {
-        const result = executeTool(profile, invoke.name, invoke.arguments);
-        yield {
-            type: 'tool',
-            tool: { name: invoke.name, arguments: invoke.arguments, result },
-        };
-        if (result.status === 'error') {
-            yield toErrorEvent(formatToolFinding(result));
-            return;
-        }
-        yield { type: 'done' };
-    }
-    catch (err) {
-        yield toErrorEvent(err);
-        yield { type: 'done' };
-    }
-}
-function executeCustomModelTool(profile, name, args) {
-    try {
-        const result = executeTool(profile, name, args);
-        const events = [
-            {
-                type: 'tool',
-                tool: { name, arguments: args, result },
-            },
-        ];
-        if (result.status === 'error') {
-            events.push(toErrorEvent(formatToolFinding(result)));
-        }
-        return events;
-    }
-    catch (err) {
-        return [toErrorEvent(err)];
-    }
-}
-function dispatchModelTool(profile, event, gated) {
-    const { tool } = event;
-    if (!tool) {
-        return [];
-    }
-    const name = tool.name;
-    if (CATALOG.tools[name]?.kind === 'builtin') {
-        return [event];
-    }
-    if (!gated.includes(name)) {
-        return [toErrorEvent(`Tool '${name}' is not gated on this turn`)];
-    }
-    const args = tool.arguments ?? {};
-    return executeCustomModelTool(profile, name, args);
-}
-function findDynamicDeclaration(tools, name) {
-    return tools?.find((t) => t.name === name);
-}
-async function checkDynamicAuthorization(decl, args, profile, sessionPermissions) {
-    if (!decl.canExecute) {
-        return null;
-    }
-    try {
-        const decision = await decl.canExecute({
-            args,
-            profile,
-            sessionPermissions,
-        });
-        if (typeof decision === 'boolean' && !decision) {
-            return {
-                status: 'error',
-                finding: `Tool '${decl.name}' execution not authorized.`,
-            };
-        }
-        if (typeof decision === 'object' && decision !== null) {
-            return decision;
-        }
-        return null;
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-            status: 'error',
-            finding: `Authorization error for '${decl.name}': ${msg}`,
-        };
-    }
-}
-function checkDynamicPermissionTier(decl, args, sessionPermissions) {
-    if (decl.permissionTier === 'session_consent' || decl.permissionTier === 'always_confirm') {
-        const isGranted = sessionPermissions?.includes(decl.name) || sessionPermissions?.includes('*');
-        if (!isGranted) {
-            return {
-                status: 'pause',
-                finding: `Tool '${decl.name}' requires ${decl.permissionTier} authorization.`,
-                data: { tool: decl.name, permissionTier: decl.permissionTier, args },
-            };
-        }
-    }
-    return null;
-}
-async function runDynamicHandler(decl, args) {
-    if (!decl.handler) {
-        return {
-            status: 'ok',
-            finding: `${decl.name} accepted (no handler)`,
-            data: args,
-        };
-    }
-    try {
-        return await decl.handler(args);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { status: 'error', finding: msg };
-    }
-}
-async function executeDynamicTool(decl, args, profile, sessionPermissions) {
-    const authEnvelope = await checkDynamicAuthorization(decl, args, profile, sessionPermissions);
-    if (authEnvelope) {
-        return authEnvelope;
-    }
-    const permissionEnvelope = checkDynamicPermissionTier(decl, args, sessionPermissions);
-    if (permissionEnvelope) {
-        return permissionEnvelope;
-    }
-    return runDynamicHandler(decl, args);
-}
-function mergeDynamicTools(current, loaded) {
-    const merged = [...(current ?? [])];
-    for (const tool of loaded) {
-        const existing = merged.findIndex((item) => item.name === tool.name);
-        if (existing >= 0) {
-            merged[existing] = tool;
-        }
-        else {
-            merged.push(tool);
-        }
-    }
-    return merged;
-}
-async function executeDynamicToolLoader(args) {
-    const { decl, toolArgs, profile, generation } = args;
-    const loader = generation.dynamicToolLoader;
-    if (!loader) {
-        return {
-            status: 'error',
-            finding: `Tool '${decl.name}' is marked as a loader but no loader is configured.`,
-        };
-    }
-    const rawLoaded = await loader({
-        name: decl.name,
-        args: toolArgs,
-        profile,
-        currentTools: generation.dynamicTools ?? [],
-        sessionPermissions: generation.sessionPermissions,
-    });
-    const loaded = sanitizeDynamicTools(rawLoaded) ?? [];
-    generation.dynamicTools = mergeDynamicTools(generation.dynamicTools, loaded);
-    return {
-        status: 'ok',
-        finding: `Loaded ${String(loaded.length)} dynamic tool schema(s).`,
-        data: { loadedTools: loaded.map((tool) => tool.name) },
-    };
-}
-function isActionableDynamicDeclaration(decl) {
-    return Boolean(decl?.handler || decl?.canExecute || decl?.permissionTier || decl?.loadsDynamicTools);
-}
-async function executeDynamicDeclaration(args) {
-    const { decl, toolArgs, profile, generation } = args;
-    const res = await executeDynamicTool(decl, toolArgs, profile, generation.sessionPermissions);
-    if (res.status === 'ok' && decl.loadsDynamicTools) {
-        return await executeDynamicToolLoader({
-            decl,
-            toolArgs,
-            profile,
-            generation,
-        });
-    }
-    return res;
-}
-export { dispatchModelTool, executeDynamicDeclaration, findDynamicDeclaration, formatToolFinding, invokeFromUi, isActionableDynamicDeclaration, };

package/esm/src/kernel/registry/tools.d.ts

@@ -1,12 +0,0 @@
-/**
- * Generic built-in custom tool executor.
- *
- * Static custom tools are intentionally minimal. Application-specific tools
- * should be supplied as dynamic declarations with host-owned handlers.
- *
- * @module
- */
-import type { CustomToolId, Profile, ToolEnvelope } from '../types.js';
-/** Execute a static tool after enforcing the profile allowlist. */
-declare function executeTool(profile: Profile, name: CustomToolId, args: Record<string, unknown>): ToolEnvelope;
-export { executeTool };

package/esm/src/kernel/registry/tools.js

@@ -1,36 +0,0 @@
-/**
- * Generic built-in custom tool executor.
- *
- * Static custom tools are intentionally minimal. Application-specific tools
- * should be supplied as dynamic declarations with host-owned handlers.
- *
- * @module
- */
-import { getTool } from './catalog.js';
-import { assertToolAllowed } from './resolve.js';
-function executeAskUser(args) {
-    const { kind, prompt } = args;
-    if (kind !== 'confirm' && kind !== 'choice' && kind !== 'text') {
-        return { status: 'error', finding: 'askUser.kind must be confirm, choice, or text' };
-    }
-    if (typeof prompt !== 'string' || !prompt.trim()) {
-        return { status: 'error', finding: 'askUser.prompt is required' };
-    }
-    return {
-        status: 'pause',
-        finding: prompt,
-        data: { ...args, schema: getTool('askUser')?.schema },
-    };
-}
-/** Execute a static tool after enforcing the profile allowlist. */
-function executeTool(profile, name, args) {
-    assertToolAllowed(profile, name);
-    if (name === 'askUser') {
-        return executeAskUser(args);
-    }
-    return {
-        status: 'error',
-        finding: `Tool '${name}' has no kernel executor; pass a dynamic tool handler instead.`,
-    };
-}
-export { executeTool };

package/esm/src/providers/expose-for-tests.d.ts

@@ -1 +0,0 @@
-export declare function exposeForTests(bucket: string, api: Record<string, unknown>): void;

package/esm/src/providers/expose-for-tests.js

@@ -1,25 +0,0 @@
-/**
- * Side-channel for repo unit/mutation tests. Not part of the public package API
- * (not listed in package exports). Enabled only when THEORUM_TEST_INTERNALS=1.
- *
- * @module
- */
-import * as dntShim from "../../_dnt.shims.js";
-export function exposeForTests(bucket, api) {
-    let enabled = false;
-    try {
-        enabled = typeof dntShim.Deno !== 'undefined' && dntShim.Deno.env.get('THEORUM_TEST_INTERNALS') === '1';
-    }
-    catch {
-        // Missing --allow-env, or non-Deno runtime: never expose.
-    }
-    if (!enabled)
-        return;
-    const g = dntShim.dntGlobalThis;
-    let root = g.__theorumTestInternals;
-    if (!root) {
-        root = {};
-        g.__theorumTestInternals = root;
-    }
-    root[bucket] = api;
-}

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

@@ -1,2 +0,0 @@
-declare function tapeGemini(value: unknown, canary: string): Promise<unknown>;
-export { tapeGemini };

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

@@ -1,3 +0,0 @@
-import type { ProviderCompleteRequest } from '../kernel/types.js';
-declare function tapFetch(tap: ProviderCompleteRequest['tapGemini'], send?: typeof fetch): typeof fetch;
-export { tapFetch };

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

@@ -1,5 +0,0 @@
-import type { ProviderCompleteRequest } from '../kernel/types.js';
-declare function camelToSnake(key: string): string;
-/** Interactions REST body for one complete() call (Google snake_case keys). */
-declare function toInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;
-export { camelToSnake, toInteractionsBody };

package/esm/src/providers/interactions.js

@@ -1,169 +0,0 @@
-import { TheorumError } from '../guardrails/error.js';
-import { getTool } from '../kernel/registry/catalog.js';
-import { getStructured } from '../kernel/registry/schemas.js';
-import { exposeForTests } from './expose-for-tests.js';
-function camelToSnake(key) {
-    return key.replaceAll(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
-}
-function toGoogleValue(value) {
-    if (Array.isArray(value)) {
-        return value.map(toGoogleValue);
-    }
-    if (value && typeof value === 'object') {
-        const out = {};
-        for (const [key, nested] of Object.entries(value)) {
-            // JSON Schema property names must stay as authored (e.g. correctAnswer in
-            // both properties and required). Snake-casing breaks Gemini validation.
-            if (key === 'schema') {
-                out[camelToSnake(key)] = nested;
-                continue;
-            }
-            out[camelToSnake(key)] = toGoogleValue(nested);
-        }
-        return out;
-    }
-    return value;
-}
-function wirePart(part) {
-    if (part.type === 'text') {
-        return { type: 'text', text: part.text };
-    }
-    return { type: part.type, mimeType: part.mimeType, data: part.data };
-}
-const USER_INPUT = 'user_input';
-function userInputStep(parts) {
-    return { type: USER_INPUT, content: parts.map(wirePart) };
-}
-function historyStep(msg) {
-    const isAssistant = msg.role === 'assistant';
-    // Google Interactions input steps: assistant history is `model_output` (not `model_turn`).
-    const type = isAssistant ? 'model_output' : 'user_input';
-    if (msg.parts && msg.parts.length > 0) {
-        return { type, content: msg.parts.map(wirePart) };
-    }
-    return { type, content: [{ type: 'text', text: msg.content ?? '' }] };
-}
-function systemHoldsUserInput(system, parts) {
-    for (const part of parts) {
-        if (part.type === 'text' && part.text && system.includes(part.text)) {
-            return true;
-        }
-    }
-    return false;
-}
-function jsonResponseFormat(schema) {
-    return [{ type: 'text', mimeType: 'application/json', schema }];
-}
-function attachResponseFormat(req, camel) {
-    if (req.speech) {
-        if (req.image) {
-            throw new TheorumError('cannot mix speech and image response formats');
-        }
-        if (req.structured) {
-            throw new TheorumError('cannot mix speech and structured response formats');
-        }
-        camel.responseFormat = { type: 'audio' };
-        return;
-    }
-    if (req.image) {
-        camel.responseFormat = {
-            type: 'image',
-            mimeType: req.image.mimeType,
-            aspectRatio: req.image.aspectRatio,
-            imageSize: req.image.size,
-        };
-        return;
-    }
-    if (!req.structured) {
-        return;
-    }
-    const spec = getStructured(req.structured);
-    if (spec.enforced !== 'responseFormat' || !spec.jsonSchema) {
-        return;
-    }
-    camel.responseFormat = jsonResponseFormat(spec.jsonSchema);
-}
-function attachSpeechConfig(req, generationConfig) {
-    if (!req.speech) {
-        return;
-    }
-    if (req.speech.voice) {
-        generationConfig.speechConfig = [{ voice: req.speech.voice }];
-    }
-}
-function inputStepsFromRequest(req) {
-    const inputSteps = [];
-    for (const h of req.history ?? []) {
-        inputSteps.push(historyStep(h));
-    }
-    if (req.input.length > 0 || inputSteps.length === 0) {
-        inputSteps.push(userInputStep(req.input));
-    }
-    return inputSteps;
-}
-function applyOptionalRequestFields(req, camel) {
-    if (req.store !== undefined) {
-        camel.store = req.store;
-    }
-    if (req.previousInteractionId) {
-        camel.previousInteractionId = req.previousInteractionId;
-    }
-    if (req.system) {
-        camel.systemInstruction = req.system;
-    }
-    if (req.builtins.length > 0) {
-        camel.tools = req.builtins.map((id) => {
-            const type = getTool(id)?.interactionsType;
-            if (!type) {
-                throw new TheorumError(`Builtin '${id}' has no Interactions wire type`);
-            }
-            return { type };
-        });
-    }
-}
-function baseInteractionsBody(req) {
-    const generationConfig = {
-        temperature: req.temperature,
-        maxOutputTokens: req.maxOutputTokens,
-    };
-    if (req.speech) {
-        // TTS models reject chat thinking knobs; voice lives under speech_config.
-        attachSpeechConfig(req, generationConfig);
-    }
-    else {
-        generationConfig.thinkingLevel = req.thinking;
-        generationConfig.thinkingSummaries = req.summaries;
-    }
-    return {
-        model: req.apiId,
-        stream: true,
-        input: inputStepsFromRequest(req),
-        generationConfig,
-    };
-}
-/** Interactions REST body for one complete() call (Google snake_case keys). */
-function toInteractionsBody(req) {
-    if (systemHoldsUserInput(req.system, req.input)) {
-        throw new TheorumError('user input cannot be placed in the system block');
-    }
-    const camel = baseInteractionsBody(req);
-    applyOptionalRequestFields(req, camel);
-    attachResponseFormat(req, camel);
-    return toGoogleValue(camel);
-}
-export { camelToSnake, toInteractionsBody };
-exposeForTests('interactions', {
-    camelToSnake,
-    toGoogleValue,
-    wirePart,
-    userInputStep,
-    historyStep,
-    systemHoldsUserInput,
-    jsonResponseFormat,
-    attachResponseFormat,
-    attachSpeechConfig,
-    inputStepsFromRequest,
-    applyOptionalRequestFields,
-    baseInteractionsBody,
-    toInteractionsBody,
-});

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

@@ -1,19 +0,0 @@
-/**
- * Gemini key vault selection, quota overflow, and fetch retries.
- *
- * Host applications supply vault credentials through `GeminiTransport`.
- * THEORUM does not read environment variables for these keys.
- *
- * @module
- */
-import type { GeminiBucket } from '../kernel/types.js';
-type GeminiVault = Record<GeminiBucket, string | undefined>;
-interface GeminiTransport {
-    vault: GeminiVault;
-    wait?: (ms: number) => Promise<void>;
-    fetch?: typeof fetch;
-}
-declare function withGeminiKey<T>(bucket: GeminiBucket, run: (apiKey: string) => Promise<T>, transport: GeminiTransport): Promise<T>;
-declare function fetchGemini(url: string, init: RequestInit, bucket: GeminiBucket, transport: GeminiTransport): Promise<Response>;
-export type { GeminiTransport, GeminiVault };
-export { fetchGemini, withGeminiKey };

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

@@ -1,29 +0,0 @@
-/**
- * Local provider adapter for OpenAI-compatible endpoints (Ollama, llama.cpp,
- * vLLM, LM Studio, etc.).
- *
- * Streams SSE from `/v1/chat/completions`, accumulates tool calls, and yields
- * normalized `TurnEvent` objects. No external SDK dependency — raw fetch + SSE.
- *
- * Hosts pass `baseUrl` explicitly. THEORUM does not read `OLLAMA_HOST` or other
- * environment variables (see src/providers/CONTRACT.md).
- *
- * @module
- */
-import type { ModelProvider } from '../kernel/types.js';
-/** Default OpenAI-compat base when the host omits `baseUrl` (Ollama's default port). */
-export declare const DEFAULT_LOCAL_BASE_URL = "http://127.0.0.1:11434";
-/** Host-supplied config for the local provider. */
-export interface LocalProviderConfig {
-    /**
-     * Base URL of the OpenAI-compat server (no trailing slash).
-     * Defaults to `http://127.0.0.1:11434`. Hosts that honor `OLLAMA_HOST` should
-     * resolve it themselves and pass the result here.
-     */
-    baseUrl?: string;
-    /** Custom fetch implementation for testing or proxying. */
-    fetch?: typeof globalThis.fetch;
-}
-/** Create a `ModelProvider` for a local OpenAI-compatible server (Ollama, llama.cpp, vLLM, LM Studio). */
-declare function createLocalProvider(config?: LocalProviderConfig): ModelProvider;
-export { createLocalProvider };

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

@@ -1,13 +0,0 @@
-/**
- * OpenRouter provider adapter and payload helpers.
- *
- * Prefer `createProvider(profile, { openRouter })` from `theorum` / `theorum/providers`
- * for turn execution. This entrypoint is for hosts that build OpenRouter payloads
- * outside the runner.
- *
- * @module
- */
-import "../../_dnt.polyfills.js";
-export { createOpenRouterProvider } from './openrouter.js';
-export type { OpenRouterConfig } from './openrouter-payload.js';
-export { resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter-payload.js';

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

@@ -1,12 +0,0 @@
-/**
- * OpenRouter provider adapter and payload helpers.
- *
- * Prefer `createProvider(profile, { openRouter })` from `theorum` / `theorum/providers`
- * for turn execution. This entrypoint is for hosts that build OpenRouter payloads
- * outside the runner.
- *
- * @module
- */
-import "../../_dnt.polyfills.js";
-export { createOpenRouterProvider } from './openrouter.js';
-export { resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter-payload.js';

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

@@ -1,39 +0,0 @@
-/**
- * OpenRouter payload builder.
- *
- * Converts THEORUM provider requests into OpenAI-compatible chat completion
- * payloads for OpenRouter and compatible gateways.
- *
- * @module
- */
-import type { ModelId, ProviderCompleteRequest } from '../kernel/types.js';
-/** Configuration supplied by the host app when creating OpenRouter providers. */
-interface OpenRouterConfig {
-    apiKey?: string;
-    baseUrl?: string;
-    siteUrl?: string;
-    siteName?: string;
-    fetch?: typeof fetch;
-    modelMap?: Record<string, string>;
-}
-/** Host-owned wire ids used when resolving an OpenRouter model string. */
-interface OpenRouterWireIds {
-    apiId?: string;
-    openRouterId?: string;
-}
-/**
- * Resolve a THEORUM model id to an OpenRouter model string.
- * Prefer `openRouterId` / `apiId` from the profile model spec on the request.
- */
-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>;
-interface ResolvedPlugins {
-    plugins: Array<{
-        id: string;
-    }>;
-    webSearch: boolean;
-}
-declare function resolveOpenRouterPlugins(builtins: readonly string[]): ResolvedPlugins;
-export type { OpenRouterConfig, OpenRouterWireIds, ResolvedPlugins };
-export { resolveOpenRouterModel, resolveOpenRouterPlugins, toOpenRouterPayload };