theorum 0.1.15 → 1.1.3

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

@@ -0,0 +1,101 @@
+/**
+ * Host-initiated tool execution entrypoint.
+ *
+ * @module
+ */
+import { toErrorEvent } from '../../guardrails/error.js';
+import { getProfile } from '../registry/profiles.js';
+import { pickModel } from '../registry/resolve.js';
+import { executeRegisteredTool, newCallId } from './execute.js';
+import { cloneTurnToolSnapshot, prepareTurnToolSnapshot, promoteLoadedTools } from './resolve.js';
+function turnRequestFromInvoke(request) {
+    return {
+        profile: request.profile,
+        path: request.path,
+        sessionPermissions: request.sessionPermissions,
+        input: request.turnInput,
+        model: request.model,
+        host: request.host,
+    };
+}
+async function prepareInvokeSnapshot(request, profile) {
+    const req = turnRequestFromInvoke(request);
+    // Host profiles bind no model — the allow list is the whole snapshot.
+    const model = profile.type === 'host' ? undefined : pickModel(profile, request.model);
+    return await prepareTurnToolSnapshot(profile, req, model);
+}
+/** Execute a registered tool without calling a model provider. */
+async function* invokeTool(request) {
+    const profile = getProfile(request.profile);
+    const callId = newCallId(request.name);
+    const snapshot = request.snapshot
+        ? cloneTurnToolSnapshot(request.snapshot)
+        : await prepareInvokeSnapshot(request, profile);
+    if (request.promoted?.length) {
+        const { failure } = promoteLoadedTools(snapshot, request.promoted, profile);
+        if (failure) {
+            yield {
+                type: 'tool',
+                tool: {
+                    name: request.name,
+                    callId,
+                    phase: 'error',
+                    failure,
+                },
+            };
+            yield { type: 'done', stop: { kind: 'completed' } };
+            return;
+        }
+    }
+    let sawGate = false;
+    let sawError = false;
+    try {
+        const handlers = request.onStage ? [request.onStage] : [];
+        for await (const event of executeRegisteredTool({
+            profile,
+            name: request.name,
+            input: request.input,
+            callId,
+            ctx: {
+                sessionPermissions: request.sessionPermissions,
+                credentials: request.credentials,
+                path: request.path,
+                signal: request.signal,
+                resume: request.resume,
+                host: request.host,
+            },
+            snapshot,
+            stages: {
+                handlers,
+                profile,
+                step: 1,
+                history: () => [],
+                injectAllowed: false,
+                host: request.host,
+                signal: request.signal,
+            },
+        })) {
+            yield event;
+            if (event.type !== 'tool') {
+                continue;
+            }
+            if (event.tool?.phase === 'gate') {
+                sawGate = true;
+            }
+            if (event.tool?.phase === 'error') {
+                sawError = true;
+            }
+        }
+    }
+    catch (err) {
+        yield toErrorEvent(err);
+        sawError = true;
+    }
+    const stopKind = sawGate ? 'gate' : sawError ? 'completed' : 'completed';
+    yield {
+        type: 'done',
+        stop: { kind: stopKind },
+        ...(sawGate ? { tools: snapshot } : {}),
+    };
+}
+export { invokeTool };

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

@@ -0,0 +1,13 @@
+/**
+ * THEORUM tool registry and execution.
+ *
+ * @module
+ */
+export { coerceToolResultParts, executeRegisteredTool, formatToolResult, leanToolResultData, projectForModel, } from './execute.js';
+export { registerHarnessTools } from './harness.js';
+export { invokeTool } from './invoke.js';
+export { getTool, hasTool, listBuiltinIds, listFunctionIds, listTools, registerTool, registerTools, requireTool, resetTools, } from './registry.js';
+export type { McpProtocolVersion, McpRpcResponse } from './remote.js';
+export { buildHttpToolTarget, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, resolveToolAuth, } from './remote.js';
+export { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';
+export type * from './types.js';

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

@@ -0,0 +1,11 @@
+/**
+ * THEORUM tool registry and execution.
+ *
+ * @module
+ */
+export { coerceToolResultParts, executeRegisteredTool, formatToolResult, leanToolResultData, projectForModel, } from './execute.js';
+export { registerHarnessTools } from './harness.js';
+export { invokeTool } from './invoke.js';
+export { getTool, hasTool, listBuiltinIds, listFunctionIds, listTools, registerTool, registerTools, requireTool, resetTools, } from './registry.js';
+export { buildHttpToolTarget, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, resolveToolAuth, } from './remote.js';
+export { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';

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

@@ -0,0 +1,15 @@
+/**
+ * Declarative catalog permission + gate-resume helpers.
+ *
+ * Shared by function and HTTP/MCP execute paths (no circular import with remote).
+ *
+ * @module
+ */
+import type { InvokeToolResume, ToolGate, ToolPermission } from './types.js';
+export declare function isResumeContinuation(resume?: InvokeToolResume): boolean;
+/** Gate resume — only `granted: true` skips confirm/permission/`preTool` re-ask. */
+export declare function isGateResumeGranted(resume?: InvokeToolResume): boolean;
+/** Host denied after a gate — settle without running the body. */
+export declare function isGateResumeDenied(resume?: InvokeToolResume): boolean;
+export declare function permissionGranted(toolName: string, sessionPermissions?: string[]): boolean;
+export declare function checkPermission(toolName: string, permission: ToolPermission, sessionPermissions?: string[], resume?: InvokeToolResume): ToolGate | null;

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

@@ -0,0 +1,47 @@
+/**
+ * Declarative catalog permission + gate-resume helpers.
+ *
+ * Shared by function and HTTP/MCP execute paths (no circular import with remote).
+ *
+ * @module
+ */
+export function isResumeContinuation(resume) {
+    return resume?.value !== undefined || typeof resume?.granted === 'boolean';
+}
+/** Gate resume — only `granted: true` skips confirm/permission/`preTool` re-ask. */
+export function isGateResumeGranted(resume) {
+    return resume?.granted === true;
+}
+/** Host denied after a gate — settle without running the body. */
+export function isGateResumeDenied(resume) {
+    return resume?.granted === false;
+}
+export function permissionGranted(toolName, sessionPermissions) {
+    if (!sessionPermissions) {
+        return false;
+    }
+    return sessionPermissions.includes('*') || sessionPermissions.includes(toolName);
+}
+export function checkPermission(toolName, permission, sessionPermissions, resume) {
+    if (permission === 'auto') {
+        return null;
+    }
+    if (permission === 'always_confirm') {
+        if (resume?.granted === true) {
+            return null;
+        }
+        return {
+            kind: 'permission',
+            tool: toolName,
+            permission,
+        };
+    }
+    if (permissionGranted(toolName, sessionPermissions)) {
+        return null;
+    }
+    return {
+        kind: 'permission',
+        tool: toolName,
+        permission,
+    };
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Tool projection for host/UI inspection.
+ *
+ * @module
+ */
+import type { Profile, ToolId } from '../types.js';
+import type { RegisteredTool } from './types.js';
+declare function projectTools(profile: Profile): Array<RegisteredTool | {
+    name: ToolId;
+    missing: true;
+}>;
+export { projectTools };

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

@@ -0,0 +1,36 @@
+/**
+ * Tool projection for host/UI inspection.
+ *
+ * @module
+ */
+import { getTool } from './registry.js';
+function projectTool(name) {
+    const tool = getTool(name);
+    if (!tool) {
+        return { name, missing: true };
+    }
+    return tool;
+}
+function builtInToolIds(profile) {
+    const seen = new Set();
+    if (profile.type === 'host') {
+        return [];
+    }
+    for (const binding of Object.values(profile.models)) {
+        for (const id of binding.builtInTools ?? []) {
+            seen.add(id);
+        }
+    }
+    return [...seen];
+}
+function profileAllow(profile) {
+    if (profile.type === 'speech') {
+        return [];
+    }
+    return profile.tools.allow;
+}
+function projectTools(profile) {
+    const ids = [...profileAllow(profile), ...builtInToolIds(profile)];
+    return ids.map((name) => projectTool(name));
+}
+export { projectTools };

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

@@ -0,0 +1,23 @@
+/**
+ * Process-local tool registry.
+ *
+ * Registration is not synchronized — hosts must register tools at startup before
+ * concurrent turns or invokeTool calls. Reads during execution are safe under Deno's
+ * single-threaded event loop; concurrent mutation of a shared TurnToolSnapshot is
+ * avoided by cloneTurnToolSnapshot on invokeTool entry.
+ *
+ * @module
+ */
+import type { RegisteredTool, ToolDefinitionInput } from './types.js';
+/** Register or replace a tool definition. */
+declare function registerTool<TIn, TOut>(def: ToolDefinitionInput<TIn, TOut>): RegisteredTool<TIn, TOut>;
+/** Register several tools in order. */
+declare function registerTools(defs: ToolDefinitionInput[]): RegisteredTool[];
+declare function getTool(name: string): RegisteredTool | undefined;
+declare function requireTool(name: string): RegisteredTool;
+declare function hasTool(name: string): boolean;
+declare function listTools(): RegisteredTool[];
+declare function listBuiltinIds(): string[];
+declare function listFunctionIds(): string[];
+declare function resetTools(): void;
+export { getTool, hasTool, listBuiltinIds, listFunctionIds, listTools, registerTool, registerTools, requireTool, resetTools, };

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

@@ -0,0 +1,81 @@
+/**
+ * Process-local tool registry.
+ *
+ * Registration is not synchronized — hosts must register tools at startup before
+ * concurrent turns or invokeTool calls. Reads during execution are safe under Deno's
+ * single-threaded event loop; concurrent mutation of a shared TurnToolSnapshot is
+ * avoided by cloneTurnToolSnapshot on invokeTool entry.
+ *
+ * @module
+ */
+import { TheorumError } from '../../guardrails/error.js';
+import { jsonSchemaFromZod, validateToolInputSchema, validateToolOutputSchema } from './schema.js';
+const tools = new Map();
+function schemasFromZod(input, output) {
+    const inputSchema = jsonSchemaFromZod(input, 'input');
+    validateToolInputSchema(inputSchema);
+    const outputSchema = jsonSchemaFromZod(output, 'output');
+    validateToolOutputSchema(outputSchema);
+    return { inputSchema, outputSchema };
+}
+function normalizeHttp(def) {
+    return { ...def, type: 'http', ...schemasFromZod(def.input, def.output) };
+}
+function normalizeMcp(def) {
+    return { ...def, type: 'mcp', ...schemasFromZod(def.input, def.output) };
+}
+function normalizeFunction(def) {
+    return { ...def, type: 'function', ...schemasFromZod(def.input, def.output) };
+}
+function normalizeToolDefinition(def) {
+    if (def.type === 'builtin') {
+        return def;
+    }
+    if (def.type === 'http') {
+        return normalizeHttp(def);
+    }
+    if (def.type === 'mcp') {
+        return normalizeMcp(def);
+    }
+    return normalizeFunction(def);
+}
+/** Register or replace a tool definition. */
+function registerTool(def) {
+    const normalized = normalizeToolDefinition(def);
+    tools.set(normalized.name, normalized);
+    return normalized;
+}
+/** Register several tools in order. */
+function registerTools(defs) {
+    return defs.map((def) => registerTool(def));
+}
+function getTool(name) {
+    return tools.get(name);
+}
+function requireTool(name) {
+    const tool = getTool(name);
+    if (!tool) {
+        throw new TheorumError(`Tool '${name}' is not registered`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return tool;
+}
+function hasTool(name) {
+    return tools.has(name);
+}
+function listTools() {
+    return [...tools.values()];
+}
+function listBuiltinIds() {
+    return listTools()
+        .filter((t) => t.type === 'builtin')
+        .map((t) => t.name);
+}
+function listFunctionIds() {
+    return listTools()
+        .filter((t) => t.type === 'function')
+        .map((t) => t.name);
+}
+function resetTools() {
+    tools.clear();
+}
+export { getTool, hasTool, listBuiltinIds, listFunctionIds, listTools, registerTool, registerTools, requireTool, resetTools, };

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

@@ -0,0 +1,94 @@
+/**
+ * Execution runners for Declarative HTTP and Remote MCP tools.
+ *
+ * Implements:
+ * - URL parameter substitution and query/body mapping
+ * - Network SSRF guardrail enforcement via `assertSafeUrl`
+ * - Credential resolution (bearer, api_key, oauth2)
+ * - Proactive OAuth token refresh with progress event emission
+ * - ToolGate { kind: 'auth' } emission or model error reporting
+ * - Streamable HTTP MCP JSON-RPC protocol (`tools/call`) per 2026-07-28 spec
+ *
+ * @module
+ */
+import type { TurnEvent } from '../types.js';
+import { type ToolCallBase } from './events.js';
+import { type ToolStageSupport } from './stage-run.js';
+import type { HttpToolAuthConfig, HttpToolDef, McpToolDef, ModelToolResult, ToolBodyOutcome, ToolContext, ToolGate } from './types.js';
+export type AuthResolveResult = {
+    headers: Record<string, string>;
+    unauthenticated?: boolean;
+    modelMessage?: string;
+    gate?: ToolGate;
+};
+/**
+ * Resolves credentials and handles missing/expired tokens.
+ * Yields TurnEvents for auth pauses or progress (e.g. refreshed tokens).
+ */
+export declare function resolveToolAuth(toolName: string, authConfig: HttpToolAuthConfig | undefined, ctx: ToolContext, base: ToolCallBase): AsyncGenerator<TurnEvent, AuthResolveResult>;
+export type HttpToolMapping = NonNullable<HttpToolDef['mapping']>;
+export type HttpToolTarget = {
+    url: string;
+    body?: string;
+};
+/**
+ * Build the request URL (and optional JSON body) for a declarative HTTP tool
+ * from endpoint template, mapping, and validated input.
+ */
+export declare function buildHttpToolTarget(endpoint: string, method: HttpToolDef['method'], input: Record<string, unknown>, mapping?: HttpToolMapping): HttpToolTarget;
+export declare function parseToolOutput<T>(schema: {
+    safeParse: (data: unknown) => {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            flatten: () => unknown;
+        };
+    };
+}, responseData: unknown): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: {
+        flatten: () => unknown;
+    };
+};
+export declare function modelResultFromOutput(data: unknown): ModelToolResult;
+/**
+ * Executes a Declarative HTTP tool.
+ * Order: schema → permission → auth → preTool/host stages → body.
+ */
+export declare function executeHttpTool(tool: HttpToolDef, rawInput: unknown, ctx: ToolContext, base: ToolCallBase, stages?: ToolStageSupport): AsyncGenerator<TurnEvent, ToolBodyOutcome>;
+/** Preferred-first Streamable HTTP protocol revisions the kernel will negotiate. */
+export declare const MCP_PROTOCOL_VERSIONS: readonly ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26"];
+export type McpProtocolVersion = (typeof MCP_PROTOCOL_VERSIONS)[number];
+export type McpRpcResponse = {
+    jsonrpc?: string;
+    id?: unknown;
+    result?: {
+        content?: Array<{
+            type: string;
+            text?: string;
+            [key: string]: unknown;
+        }>;
+        isError?: boolean;
+        [key: string]: unknown;
+    };
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    method?: string;
+};
+/** Parse MCP JSON or SSE (`event: message` / `data:`) bodies into a JSON-RPC object. */
+export declare function parseMcpRpcResponse(text: string): McpRpcResponse;
+/** True when a JSON-RPC error indicates the server rejected our protocol revision. */
+export declare function isUnsupportedMcpProtocolError(error: McpRpcResponse['error']): boolean;
+/**
+ * Executes a Remote MCP tool over Streamable HTTP (spec revision 2026-07-28).
+ * Order: schema → permission → auth → preTool/host stages → body.
+ */
+export declare function executeMcpTool(tool: McpToolDef, rawInput: unknown, ctx: ToolContext, base: ToolCallBase, stages?: ToolStageSupport): AsyncGenerator<TurnEvent, ToolBodyOutcome>;