theorum 0.1.14 → 1.0.0

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

@@ -0,0 +1,363 @@
+/**
+ * Shared tool execution core for model-initiated and host-initiated calls.
+ *
+ * @module
+ */
+import { throwIfAborted } from '../../guardrails/error.js';
+import { sanitizeText } from '../../guardrails/sanitize.js';
+import { getTool } from './registry.js';
+import { promoteLoadedTools } from './resolve.js';
+function isStreamHandler(handler) {
+    return (typeof handler === 'function' &&
+        Object.prototype.toString.call(handler) === '[object AsyncGeneratorFunction]');
+}
+export function isResumeContinuation(resume) {
+    return resume?.value !== undefined || resume?.granted === true;
+}
+export function isToolPause(value) {
+    return ('kind' in value &&
+        (value.kind === 'interactive' || value.kind === 'confirmation' || value.kind === 'permission'));
+}
+export function* yieldHandlerSideEvent(base, event) {
+    if (event.kind === 'progress') {
+        yield toolEvent(base, { phase: 'progress', data: event.data });
+    }
+    else if (event.kind === 'trace') {
+        yield toolEvent(base, { phase: 'trace', step: event.step });
+    }
+    else if (event.kind === 'artifact') {
+        yield toolEvent(base, { phase: 'artifact', artifact: event.artifact });
+    }
+    else if (event.kind === 'warning') {
+        yield toolEvent(base, { phase: 'warning', warning: event.warning });
+    }
+}
+/** Run the handler, yielding stream side-events live; returns terminal output. */
+async function* runHandler(handler, input, ctx, base) {
+    if (isStreamHandler(handler)) {
+        let output;
+        const gen = handler(input, ctx);
+        for await (const event of gen) {
+            throwIfAborted(ctx.signal);
+            if (event.kind === 'complete') {
+                output = event.output;
+                continue;
+            }
+            yield* yieldHandlerSideEvent(base, event);
+        }
+        return output;
+    }
+    const output = await handler(input, ctx);
+    return output;
+}
+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,
+            input: {},
+        };
+    }
+    if (permissionGranted(toolName, sessionPermissions)) {
+        return null;
+    }
+    return {
+        kind: 'permission',
+        tool: toolName,
+        permission,
+        input: {},
+    };
+}
+function toolEvent(base, patch) {
+    return {
+        type: 'tool',
+        tool: { ...base, ...patch },
+    };
+}
+function failureEvent(base, failure) {
+    return toolEvent(base, { phase: 'error', failure });
+}
+export function projectForModel(tool, output) {
+    if (tool.exposeToModel === false) {
+        return { finding: 'Completed.' };
+    }
+    const finding = typeof output === 'object' && output !== null && 'finding' in output
+        ? String(output.finding)
+        : JSON.stringify(output);
+    return {
+        finding: sanitizeText(finding),
+        data: output,
+    };
+}
+/** Format model-facing tool output for provider history continuation. */
+export function formatToolResult(result) {
+    if (result.data !== undefined) {
+        return sanitizeText(`${result.finding}\n${JSON.stringify(result.data)}`);
+    }
+    return sanitizeText(result.finding);
+}
+/** Format a tool failure for provider history — structured so the model (or host) sees the code. */
+export function formatToolFailureForModel(failure) {
+    return {
+        finding: `Tool error (${failure.code}): ${failure.message}`,
+        data: {
+            ok: false,
+            code: failure.code,
+            message: failure.message,
+            ...(failure.details !== undefined ? { details: failure.details } : {}),
+        },
+    };
+}
+export function* startToolExecution(tool, rawInput, ctx, base) {
+    yield toolEvent(base, { phase: 'running' });
+    throwIfAborted(ctx.signal);
+    const parsed = tool.input.safeParse(rawInput);
+    if (!parsed.success) {
+        yield failureEvent(base, {
+            code: 'invalid_input',
+            message: 'Tool input validation failed',
+            details: parsed.error.flatten(),
+        });
+        return { ok: false };
+    }
+    return { ok: true, data: parsed.data };
+}
+export async function* executeFunction(tool, rawInput, ctx, base, snapshot) {
+    const parsed = yield* startToolExecution(tool, rawInput, ctx, base);
+    if (!parsed.ok)
+        return undefined;
+    const input = parsed.data;
+    const permissionPause = checkPermission(tool.name, tool.permission, ctx.sessionPermissions, ctx.resume);
+    if (permissionPause) {
+        permissionPause.input = input;
+        yield toolEvent(base, { phase: 'pause', pause: permissionPause });
+        return undefined;
+    }
+    throwIfAborted(ctx.signal);
+    if (tool.canExecute) {
+        try {
+            const allowed = await tool.canExecute(input, ctx);
+            if (!allowed) {
+                yield failureEvent(base, {
+                    code: 'not_authorized',
+                    message: 'Tool execution not authorized',
+                });
+                return undefined;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            yield failureEvent(base, {
+                code: 'not_authorized',
+                message: `Authorization failed for '${tool.name}': ${msg}`,
+            });
+            return undefined;
+        }
+    }
+    if (tool.preflight) {
+        const pre = await tool.preflight(input, ctx);
+        if (pre) {
+            if (isToolPause(pre)) {
+                const pausePayload = { ...pre, input: pre.input ?? input };
+                yield toolEvent(base, { phase: 'pause', pause: pausePayload });
+                return undefined;
+            }
+            yield failureEvent(base, pre);
+            return undefined;
+        }
+    }
+    if (tool.interactive && ctx.resume?.value === undefined) {
+        const render = tool.interactive.render(input);
+        const interactivePause = {
+            kind: 'interactive',
+            tool: tool.name,
+            render,
+            input,
+        };
+        yield toolEvent(base, { phase: 'pause', pause: interactivePause });
+        return undefined;
+    }
+    throwIfAborted(ctx.signal);
+    try {
+        const output = yield* runHandler(tool.handler, input, ctx, base);
+        if (output === undefined) {
+            yield failureEvent(base, { code: 'invalid_output', message: 'Handler returned no output' });
+            return undefined;
+        }
+        const checked = tool.output.safeParse(output);
+        if (!checked.success) {
+            yield failureEvent(base, {
+                code: 'invalid_output',
+                message: 'Tool output validation failed',
+                details: checked.error.flatten(),
+            });
+            return undefined;
+        }
+        let finalOutput = checked.data;
+        if (ctx.profile.type !== 'speech' && ctx.profile.tools.t2Loader === tool.name) {
+            if (!snapshot) {
+                yield failureEvent(base, {
+                    code: 'invalid_output',
+                    message: `tools.t2Loader '${tool.name}' requires a turn tool snapshot`,
+                });
+                return undefined;
+            }
+            const loaded = extractLoadedIds(checked.data);
+            if (!loaded) {
+                yield failureEvent(base, {
+                    code: 'invalid_output',
+                    message: `T2 loader '${tool.name}' must return { loaded: string[] }`,
+                });
+                return undefined;
+            }
+            const { promoted, failure: promoteFailure } = promoteLoadedTools(snapshot, loaded, ctx.profile);
+            if (promoteFailure) {
+                yield failureEvent(base, promoteFailure);
+                return undefined;
+            }
+            finalOutput = { ...checked.data, loaded: promoted };
+            const rechecked = tool.output.safeParse(finalOutput);
+            if (!rechecked.success) {
+                yield failureEvent(base, {
+                    code: 'invalid_output',
+                    message: 'T2 loader output validation failed after promotion',
+                    details: rechecked.error.flatten(),
+                });
+                return undefined;
+            }
+            finalOutput = rechecked.data;
+        }
+        const modelResult = projectForModel(tool, finalOutput);
+        yield toolEvent(base, { phase: 'complete', output: finalOutput });
+        return modelResult;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        yield failureEvent(base, { code: 'handler_error', message: msg });
+        return undefined;
+    }
+}
+export function notLoadedMessage(tool) {
+    if (tool.loadTier === 'T1') {
+        return `Tool '${tool.name}' is not wired — profile.tools.t1Policy must select it`;
+    }
+    if (tool.loadTier === 'T2') {
+        return `Tool '${tool.name}' is not loaded — run profile.tools.t2Loader first`;
+    }
+    return `Tool '${tool.name}' is not visible this turn`;
+}
+export function extractLoadedIds(output) {
+    if (!output || typeof output !== 'object' || Array.isArray(output)) {
+        return undefined;
+    }
+    const loaded = output.loaded;
+    if (!Array.isArray(loaded) || !loaded.every((id) => typeof id === 'string')) {
+        return undefined;
+    }
+    return loaded;
+}
+/** Strip prototype-pollution keys from provider/host tool args before validation. */
+export function plainToolInput(input) {
+    if (input === null || typeof input !== 'object') {
+        return input;
+    }
+    if (Array.isArray(input)) {
+        return input.map(plainToolInput);
+    }
+    const out = {};
+    for (const key of Object.keys(input)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+            continue;
+        }
+        out[key] = plainToolInput(input[key]);
+    }
+    return out;
+}
+export async function* executeBuiltin(tool, ctx, base, snapshot) {
+    yield toolEvent(base, { phase: 'running' });
+    throwIfAborted(ctx.signal);
+    if (!snapshot.builtins.includes(tool.name)) {
+        yield failureEvent(base, {
+            code: 'not_loaded',
+            message: `Builtin '${tool.name}' is not enabled this turn`,
+        });
+        return undefined;
+    }
+    yield failureEvent(base, {
+        code: 'provider_native',
+        message: `Tool '${tool.name}' is a provider builtin — execution is handled by the model provider, not the kernel`,
+    });
+    return undefined;
+}
+export async function* executeRegisteredTool(args) {
+    const { profile, name, input, callId, ctx, snapshot } = args;
+    const tool = getTool(name);
+    const safeInput = plainToolInput(input);
+    const base = {
+        name,
+        callId,
+        arguments: typeof safeInput === 'object' && safeInput !== null && !Array.isArray(safeInput)
+            ? safeInput
+            : { value: safeInput },
+    };
+    if (!tool) {
+        yield failureEvent(base, { code: 'unknown_tool', message: `Tool '${name}' is not registered` });
+        return undefined;
+    }
+    if (tool.type === 'builtin') {
+        if (!snapshot) {
+            yield failureEvent(base, {
+                code: 'provider_native',
+                message: `Tool '${name}' is a provider builtin and requires a turn tool snapshot`,
+            });
+            return undefined;
+        }
+        const fullCtx = { ...ctx, callId, profile };
+        return yield* executeBuiltin(tool, fullCtx, base, snapshot);
+    }
+    if (profile.type === 'speech' || !profile.tools.allow.includes(name)) {
+        yield failureEvent(base, {
+            code: 'not_allowed',
+            message: `Tool '${name}' is not allowed on ${profile.id}`,
+        });
+        return undefined;
+    }
+    if (snapshot) {
+        const continuing = isResumeContinuation(ctx.resume);
+        if (!continuing && !snapshot.gated.includes(name)) {
+            yield failureEvent(base, {
+                code: 'not_gated',
+                message: `Tool '${name}' is not eligible on this turn (allow/path)`,
+            });
+            return undefined;
+        }
+        if (!snapshot.visible.includes(name)) {
+            const skipLoadCheck = continuing && tool.loadTier === 'T0';
+            if (!skipLoadCheck) {
+                yield failureEvent(base, {
+                    code: 'not_loaded',
+                    message: notLoadedMessage(tool),
+                });
+                return undefined;
+            }
+        }
+    }
+    const fullCtx = { ...ctx, callId, profile };
+    return yield* executeFunction(tool, safeInput, fullCtx, base, snapshot);
+}
+export function newCallId(name) {
+    return `call_${name}_${Date.now()}`;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Built-in harness tools registered with THEORUM.
+ *
+ * @module
+ */
+/** Register harness tools shipped with THEORUM. */
+declare function registerHarnessTools(): void;
+export { registerHarnessTools };

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

@@ -0,0 +1,44 @@
+/**
+ * Built-in harness tools registered with THEORUM.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { registerTool } from './registry.js';
+const AskInputSchema = z.object({
+    kind: z.enum(['confirm', 'choice', 'text']),
+    prompt: z.string().trim().min(1),
+    options: z.array(z.string()).optional(),
+});
+const AskOutputSchema = z.object({
+    answer: z.unknown(),
+});
+/** 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',
+        category: 'conversation',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        input: AskInputSchema,
+        output: AskOutputSchema,
+        interactive: {
+            render: (input) => {
+                const ask = input;
+                return {
+                    kind: ask.kind,
+                    prompt: ask.prompt,
+                    options: ask.options,
+                };
+            },
+        },
+        handler: (_input, ctx) => ({
+            answer: ctx.resume?.value ?? ctx.resume?.granted,
+        }),
+    });
+}
+export { registerHarnessTools };

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

@@ -0,0 +1,10 @@
+/**
+ * Host-initiated tool execution entrypoint.
+ *
+ * @module
+ */
+import type { TurnEvent } from '../types.js';
+import type { InvokeToolRequest } from './types.js';
+/** Execute a registered tool without calling a model provider. */
+declare function invokeTool(request: InvokeToolRequest): AsyncGenerator<TurnEvent>;
+export { invokeTool };

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

@@ -0,0 +1,83 @@
+/**
+ * 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,
+        select: request.select,
+    };
+}
+async function prepareInvokeSnapshot(request, profile) {
+    const req = turnRequestFromInvoke(request);
+    const model = pickModel(profile, request.select);
+    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: 'tool' } };
+            return;
+        }
+    }
+    let sawPause = false;
+    let sawError = false;
+    try {
+        for await (const event of executeRegisteredTool({
+            profile,
+            name: request.name,
+            input: request.input,
+            callId,
+            ctx: {
+                sessionPermissions: request.sessionPermissions,
+                path: request.path,
+                signal: request.signal,
+                resume: request.resume,
+            },
+            snapshot,
+        })) {
+            yield event;
+            if (event.type !== 'tool') {
+                continue;
+            }
+            if (event.tool?.phase === 'pause') {
+                sawPause = true;
+            }
+            if (event.tool?.phase === 'error') {
+                sawError = true;
+            }
+        }
+    }
+    catch (err) {
+        yield toErrorEvent(err);
+        sawError = true;
+    }
+    const stopKind = sawError || sawPause ? 'tool' : 'completed';
+    yield { type: 'done', stop: { kind: stopKind } };
+}
+export { invokeTool };

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

@@ -0,0 +1,11 @@
+/**
+ * THEORUM tool registry and execution.
+ *
+ * @module
+ */
+export { formatToolResult } 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 { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';
+export type * from './types.js';

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

@@ -0,0 +1,10 @@
+/**
+ * THEORUM tool registry and execution.
+ *
+ * @module
+ */
+export { formatToolResult } 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 { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';

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,34 @@
+/**
+ * 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();
+    for (const modelId of profile.model.allow) {
+        const spec = profile.model.config[modelId];
+        for (const id of spec?.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,71 @@
+/**
+ * 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 normalizeFunction(def) {
+    const inputSchema = jsonSchemaFromZod(def.input, 'input');
+    validateToolInputSchema(inputSchema);
+    const outputSchema = jsonSchemaFromZod(def.output, 'output');
+    validateToolOutputSchema(outputSchema);
+    return {
+        ...def,
+        type: 'function',
+        inputSchema,
+        outputSchema,
+    };
+}
+function normalizeToolDefinition(def) {
+    if (def.type === 'builtin') {
+        return 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`);
+    }
+    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, };