theorum 1.0.0 → 1.1.3

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

@@ -4,6 +4,7 @@
  * @module
  */
 import { z } from 'zod';
+import { AWAITING_USER_INPUT_STATUS } from '../schema.js';
 import { registerTool } from './registry.js';
 const AskInputSchema = z.object({
     kind: z.enum(['confirm', 'choice', 'text']),
@@ -11,14 +12,17 @@ const AskInputSchema = z.object({
     options: z.array(z.string()).optional(),
 });
 const AskOutputSchema = z.object({
-    answer: z.unknown(),
+    status: z.literal(AWAITING_USER_INPUT_STATUS),
+    kind: z.enum(['confirm', 'choice', 'text']),
+    prompt: z.string().trim().min(1),
+    options: z.array(z.string()).optional(),
 });
 /** Register harness tools shipped with THEORUM. */
 function registerHarnessTools() {
     registerTool({
         type: 'function',
         name: 'ask_user',
-        description: 'Ask the user a question and wait for a response',
+        description: 'Ask the user a question (completes with awaiting_user_input)', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         category: 'conversation',
         access: 'read-only',
         paths: ['*'],
@@ -26,19 +30,17 @@ function registerHarnessTools() {
         permission: 'auto',
         input: AskInputSchema,
         output: AskOutputSchema,
-        interactive: {
-            render: (input) => {
-                const ask = input;
-                return {
-                    kind: ask.kind,
-                    prompt: ask.prompt,
-                    options: ask.options,
-                };
-            },
+        handler: (input) => {
+            const out = {
+                status: AWAITING_USER_INPUT_STATUS,
+                kind: input.kind,
+                prompt: input.prompt,
+            };
+            if (input.kind === 'choice' && input.options?.length) {
+                out.options = input.options;
+            }
+            return out;
         },
-        handler: (_input, ctx) => ({
-            answer: ctx.resume?.value ?? ctx.resume?.granted,
-        }),
     });
 }
 export { registerHarnessTools };

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

@@ -14,12 +14,14 @@ function turnRequestFromInvoke(request) {
         path: request.path,
         sessionPermissions: request.sessionPermissions,
         input: request.turnInput,
-        select: request.select,
+        model: request.model,
+        host: request.host,
     };
 }
 async function prepareInvokeSnapshot(request, profile) {
     const req = turnRequestFromInvoke(request);
-    const model = pickModel(profile, request.select);
+    // 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. */
@@ -41,13 +43,14 @@ async function* invokeTool(request) {
                     failure,
                 },
             };
-            yield { type: 'done', stop: { kind: 'tool' } };
+            yield { type: 'done', stop: { kind: 'completed' } };
             return;
         }
     }
-    let sawPause = false;
+    let sawGate = false;
     let sawError = false;
     try {
+        const handlers = request.onStage ? [request.onStage] : [];
         for await (const event of executeRegisteredTool({
             profile,
             name: request.name,
@@ -55,18 +58,29 @@ async function* invokeTool(request) {
             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 === 'pause') {
-                sawPause = true;
+            if (event.tool?.phase === 'gate') {
+                sawGate = true;
             }
             if (event.tool?.phase === 'error') {
                 sawError = true;
@@ -77,7 +91,11 @@ async function* invokeTool(request) {
         yield toErrorEvent(err);
         sawError = true;
     }
-    const stopKind = sawError || sawPause ? 'tool' : 'completed';
-    yield { type: 'done', stop: { kind: stopKind } };
+    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

@@ -3,9 +3,11 @@
  *
  * @module
  */
-export { formatToolResult } from './execute.js';
+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

@@ -3,8 +3,9 @@
  *
  * @module
  */
-export { formatToolResult } from './execute.js';
+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.js

@@ -13,9 +13,11 @@ function projectTool(name) {
 }
 function builtInToolIds(profile) {
     const seen = new Set();
-    for (const modelId of profile.model.allow) {
-        const spec = profile.model.config[modelId];
-        for (const id of spec?.builtInTools ?? []) {
+    if (profile.type === 'host') {
+        return [];
+    }
+    for (const binding of Object.values(profile.models)) {
+        for (const id of binding.builtInTools ?? []) {
             seen.add(id);
         }
     }

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

@@ -11,22 +11,32 @@
 import { TheorumError } from '../../guardrails/error.js';
 import { jsonSchemaFromZod, validateToolInputSchema, validateToolOutputSchema } from './schema.js';
 const tools = new Map();
-function normalizeFunction(def) {
-    const inputSchema = jsonSchemaFromZod(def.input, 'input');
+function schemasFromZod(input, output) {
+    const inputSchema = jsonSchemaFromZod(input, 'input');
     validateToolInputSchema(inputSchema);
-    const outputSchema = jsonSchemaFromZod(def.output, 'output');
+    const outputSchema = jsonSchemaFromZod(output, 'output');
     validateToolOutputSchema(outputSchema);
-    return {
-        ...def,
-        type: 'function',
-        inputSchema,
-        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. */
@@ -45,7 +55,7 @@ function getTool(name) {
 function requireTool(name) {
     const tool = getTool(name);
     if (!tool) {
-        throw new TheorumError(`Tool '${name}' is not registered`);
+        throw new TheorumError(`Tool '${name}' is not registered`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return tool;
 }

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>;