theorum 0.1.15 → 1.1.3

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

@@ -0,0 +1,283 @@
+/**
+ * Turn tool visibility and wire snapshot resolution.
+ *
+ * @module
+ */
+import { TheorumError } from '../../guardrails/error.js';
+import { getTool } from './registry.js';
+export function pathMatches(catalogPaths, turnPath) {
+    if (!catalogPaths || catalogPaths.includes('*')) {
+        return true;
+    }
+    if (!turnPath) {
+        return false;
+    }
+    return catalogPaths.includes(turnPath);
+}
+export function applyBuiltinMutualExclusions(requested) {
+    return requested.filter((id) => {
+        const tool = getTool(id);
+        if (tool?.type !== 'builtin') {
+            return true;
+        }
+        const conflicts = tool.conflictsWith ?? [];
+        return !conflicts.some((other) => requested.includes(other));
+    });
+}
+export function resolveAllowedCustomToolIds(profile, req) {
+    if (profile.type === 'speech') {
+        return [];
+    }
+    return profile.tools.allow.filter((id) => {
+        const tool = getTool(id);
+        if (!tool || tool.type === 'builtin') {
+            return false;
+        }
+        // Host profiles execute every allowed tool — path gating does not apply.
+        return profile.type === 'host' || pathMatches(tool.paths, req.path);
+    });
+}
+/** Provider builtins listed on the selected model — on for the turn (path-filtered). */
+export function resolveModelBuiltinIds(profile, req, modelId) {
+    const spec = profile.models[modelId];
+    if (!spec) {
+        return [];
+    }
+    return (spec.builtInTools ?? []).filter((id) => {
+        const tool = getTool(id);
+        if (tool?.type !== 'builtin') {
+            return false;
+        }
+        return pathMatches(tool.paths, req.path);
+    });
+}
+export function wireForTool(name) {
+    const tool = getTool(name);
+    if (!tool || tool.type === 'builtin') {
+        return undefined;
+    }
+    return {
+        type: 'function',
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.inputSchema,
+    };
+}
+export function buildWire(visible) {
+    const out = [];
+    for (const id of visible) {
+        const wire = wireForTool(id);
+        if (wire) {
+            out.push(wire);
+        }
+    }
+    return out;
+}
+export function promoteTool(state, id) {
+    if (state.visible.includes(id)) {
+        return;
+    }
+    state.visible.push(id);
+    const wire = wireForTool(id);
+    if (wire && !state.wire.some((w) => w.name === id)) {
+        state.wire.push(wire);
+    }
+}
+export function promoteBuiltin(state, id) {
+    if (state.builtins.includes(id)) {
+        return;
+    }
+    const tool = getTool(id);
+    if (tool?.type !== 'builtin') {
+        return;
+    }
+    const conflicts = tool.conflictsWith ?? [];
+    state.builtins = state.builtins.filter((existing) => {
+        if (conflicts.includes(existing)) {
+            return false;
+        }
+        const existingTool = getTool(existing);
+        return !(existingTool?.type === 'builtin' && existingTool.conflictsWith?.includes(id));
+    });
+    state.builtins.push(id);
+}
+/**
+ * Custom tools wired at turn start. Text/image: T0 only (T1/T2 pending).
+ * Live: every gated tool — declarations are fixed at session setup, so every
+ * allowed tool is effectively T0. Host: every gated tool — no tiers at all.
+ */
+export function initialVisible(profile, gated) {
+    if (profile.type === 'live' || profile.type === 'host') {
+        return [...gated];
+    }
+    return gated.filter((id) => getTool(id)?.loadTier === 'T0');
+}
+/** Builtins on at turn start — every gated builtin on live, T0 elsewhere (mutual exclusions applied). */
+export function initialBuiltins(profile, gated) {
+    return applyBuiltinMutualExclusions(gated.filter((id) => {
+        const tool = getTool(id);
+        return tool?.type === 'builtin' && (profile.type === 'live' || tool.loadTier === 'T0');
+    }));
+}
+/**
+ * Build the initial tool snapshot for a turn.
+ * Text/image: T0 wired, T1/T2 pending. Live: the whole allow list and every
+ * model builtin. Host: the whole allow list, no builtins, no path gating.
+ */
+export function resolveTurnTools(profile, req, modelId) {
+    const customAllowed = resolveAllowedCustomToolIds(profile, req);
+    const modelBuiltins = profile.type === 'host' || modelId === undefined
+        ? []
+        : resolveModelBuiltinIds(profile, req, modelId);
+    const gated = [...customAllowed, ...modelBuiltins];
+    const builtins = initialBuiltins(profile, gated);
+    const visible = initialVisible(profile, gated);
+    const executable = visible.filter((id) => getTool(id)?.type !== 'builtin');
+    return {
+        builtins,
+        gated,
+        visible,
+        executable,
+        path: req.path,
+        sessionPermissions: req.sessionPermissions,
+        wire: buildWire(visible),
+    };
+}
+/** Resolve T0 snapshot and expand T1 selections from `profile.tools.t1Policy`. */
+export async function prepareTurnToolSnapshot(profile, req, modelId) {
+    const snapshot = resolveTurnTools(profile, req, modelId);
+    await expandT1Policy(snapshot, profile, req);
+    return snapshot;
+}
+/** Deep-clone a turn snapshot so host-side concurrent invokes do not share mutable state. */
+export function cloneTurnToolSnapshot(state) {
+    return {
+        builtins: [...state.builtins],
+        gated: [...state.gated],
+        visible: [...state.visible],
+        executable: [...state.executable],
+        path: state.path,
+        sessionPermissions: state.sessionPermissions ? [...state.sessionPermissions] : undefined,
+        wire: state.wire.map((w) => ({ ...w, parameters: structuredClone(w.parameters) })),
+    };
+}
+/** Wire T1 tools selected by `profile.tools.t1Policy`. */
+export async function expandT1Policy(state, profile, req) {
+    if (profile.type === 'speech' || profile.type === 'live' || profile.type === 'host') {
+        return;
+    }
+    const t1Policy = profile.tools.t1Policy;
+    if (!t1Policy) {
+        return;
+    }
+    let selected;
+    try {
+        selected = await t1Policy({
+            profile,
+            input: req.input,
+            path: req.path,
+            sessionPermissions: req.sessionPermissions,
+            gated: state.gated,
+            host: req.host,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new TheorumError(`Profile '${profile.id}' tools.t1Policy rejected: ${msg}`, {
+            cause: err,
+        });
+    }
+    if (!Array.isArray(selected)) {
+        throw new TheorumError(`Profile '${profile.id}' tools.t1Policy must return ToolId[]`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    for (const id of selected) {
+        if (!state.gated.includes(id)) {
+            continue;
+        }
+        const tool = getTool(id);
+        // T0 tools are already visible; t1Policy may promote T1/T2 gated tools at turn start.
+        if (!tool || tool.loadTier === 'T0') {
+            continue;
+        }
+        if (tool.type === 'builtin') {
+            promoteBuiltin(state, id);
+        }
+        else {
+            promoteTool(state, id);
+        }
+    }
+    state.executable = state.visible.filter((id) => getTool(id)?.type !== 'builtin');
+}
+const LOADED_ID_BLOCKLIST = new Set(['__proto__', 'constructor', 'prototype']);
+/** Promote T2 tools into the visible set after tools.t2Loader returns { loaded }. */
+export function promoteLoadedTools(state, loaded, profile) {
+    if (profile.type === 'live' || profile.type === 'host') {
+        // Every allowed tool is already visible — there is nothing to promote.
+        return { promoted: [] };
+    }
+    const toPromote = [];
+    for (const id of loaded) {
+        if (typeof id !== 'string' || LOADED_ID_BLOCKLIST.has(id)) {
+            return {
+                promoted: [],
+                failure: {
+                    code: 'invalid_output',
+                    message: 'tools.t2Loader loaded ids must be plain strings', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                },
+            };
+        }
+        const failure = promotionFailure(id, profile);
+        if (failure) {
+            return { promoted: [], failure };
+        }
+        const tool = getTool(id);
+        if (!tool) {
+            return {
+                promoted: [],
+                failure: {
+                    code: 'invalid_output',
+                    message: `Tool '${id}' is not registered`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                },
+            };
+        }
+        if (!pathMatches(tool.paths, state.path) || !state.gated.includes(id)) {
+            continue;
+        }
+        toPromote.push(id);
+    }
+    const promoted = [];
+    for (const id of toPromote) {
+        promoteTool(state, id);
+        promoted.push(id);
+    }
+    state.executable = state.visible.filter((tid) => getTool(tid)?.type !== 'builtin');
+    return { promoted };
+}
+export function promotionFailure(id, profile) {
+    if (profile.type === 'speech' || !profile.tools.allow.includes(id)) {
+        return {
+            code: 'invalid_output',
+            message: `tools.t2Loader attempted to promote tool '${id}' outside profile allow`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        };
+    }
+    const tool = getTool(id);
+    if (!tool) {
+        return {
+            code: 'invalid_output',
+            message: `tools.t2Loader attempted to promote unknown tool '${id}'`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        };
+    }
+    if (tool.type === 'builtin') {
+        return {
+            code: 'invalid_output',
+            message: `tools.t2Loader attempted to promote builtin '${id}' — only custom tools may be promoted`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        };
+    }
+    if (tool.loadTier !== 'T2') {
+        return {
+            code: 'invalid_output',
+            message: `tools.t2Loader attempted to promote tool '${id}' with loadTier '${tool.loadTier}' — only T2 tools may be promoted`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        };
+    }
+    return undefined;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Tool JSON Schema validation and Zod → wire schema conversion.
+ *
+ * @module
+ */
+import { type ZodType } from 'zod';
+export type JsonSchema = Record<string, unknown>;
+/** Validate a tool parameter schema for provider compatibility. */
+declare function validateToolInputSchema(schema: JsonSchema, mode?: 'gemini' | 'structural'): void;
+/** Validate a tool result schema at registration. */
+declare function validateToolOutputSchema(schema: JsonSchema, mode?: 'gemini' | 'structural'): void;
+declare function jsonSchemaFromZod(schema: ZodType, io?: 'input' | 'output'): JsonSchema;
+export { jsonSchemaFromZod, validateToolInputSchema, validateToolOutputSchema };
+/** Strip prototype-pollution keys from provider/host tool args or host-mutated values before validation. */
+export declare function plainToolInput(input: unknown): unknown;

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

@@ -0,0 +1,176 @@
+/**
+ * Tool JSON Schema validation and Zod → wire schema conversion.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { TheorumError } from '../../guardrails/error.js';
+const GEMINI_SUPPORTED_SCHEMA_KEYS = [
+    'type',
+    'format',
+    'title',
+    'description',
+    'nullable',
+    'enum',
+    'default',
+    'example',
+    'items',
+    'minItems',
+    'maxItems',
+    'properties',
+    'required',
+    'propertyOrdering',
+    'minProperties',
+    'maxProperties',
+    'minimum',
+    'maximum',
+    'pattern',
+    'minLength',
+    'maxLength',
+    'anyOf',
+    'oneOf',
+];
+function validateGeminiKeys(schema, path, errors) {
+    for (const key of Object.keys(schema)) {
+        if (!GEMINI_SUPPORTED_SCHEMA_KEYS.includes(key)) {
+            errors.push(`${path}: unsupported Gemini schema key '${key}'`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+}
+function validateSchemaShape(schema, path, mode, errors) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        errors.push(`${path}: schema must be an object`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return false;
+    }
+    const hasType = typeof schema.type === 'string' || Array.isArray(schema.type);
+    const hasCombinator = schema.anyOf !== undefined || schema.oneOf !== undefined;
+    if (!hasType && !hasCombinator) {
+        if (mode === 'structural' && path !== '$') {
+            return true;
+        }
+        errors.push(`${path}: missing type or combinator`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (mode === 'gemini') {
+        validateGeminiKeys(schema, path, errors);
+    }
+    if (schema.type === 'array' && schema.items === undefined) {
+        errors.push(`${path}: array schema must define items`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return true;
+}
+function walkSchemaProperties(props, required, path, mode, errors) {
+    const reqList = Array.isArray(required) ? required : [];
+    for (const req of reqList) {
+        if (typeof req === 'string' && !(req in props)) {
+            errors.push(`${path}: required key '${req}' missing from properties`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+    for (const [key, child] of Object.entries(props)) {
+        if (child && typeof child === 'object') {
+            walkSchema(child, `${path}.properties.${key}`, mode, errors);
+        }
+    }
+}
+function walkSchema(schema, path, mode, errors) {
+    if (!validateSchemaShape(schema, path, mode, errors))
+        return;
+    const props = schema.properties;
+    if (props && typeof props === 'object' && !Array.isArray(props)) {
+        walkSchemaProperties(props, schema.required, path, mode, errors);
+    }
+    if (schema.items && typeof schema.items === 'object' && !Array.isArray(schema.items)) {
+        walkSchema(schema.items, `${path}.items`, mode, errors);
+    }
+    for (const combinator of ['anyOf', 'oneOf']) {
+        const branch = schema[combinator];
+        if (Array.isArray(branch)) {
+            branch.forEach((entry, index) => {
+                if (entry && typeof entry === 'object') {
+                    walkSchema(entry, `${path}.${combinator}[${index}]`, mode, errors);
+                }
+            });
+        }
+    }
+}
+/** Validate a tool wire schema for provider compatibility. */
+function validateToolWireSchema(schema, mode = 'gemini', label = 'input') {
+    const errors = [];
+    walkSchema(schema, '$', mode, errors);
+    if (errors.length > 0) {
+        throw new TheorumError(`Invalid tool ${label} schema: ${errors.join('; ')}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+/** Validate a tool parameter schema for provider compatibility. */
+function validateToolInputSchema(schema, mode = 'gemini') {
+    validateToolWireSchema(schema, mode, 'input');
+}
+/** Validate a tool result schema at registration. */
+function validateToolOutputSchema(schema, mode = 'structural') {
+    validateToolWireSchema(schema, mode, 'output');
+}
+function stripProperties(value) {
+    const props = {};
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        for (const [propKey, propValue] of Object.entries(value)) {
+            if (propValue && typeof propValue === 'object') {
+                props[propKey] = stripUnsupportedGeminiKeys(propValue);
+            }
+        }
+    }
+    return props;
+}
+function stripBranches(branches) {
+    return branches.map((entry) => entry && typeof entry === 'object' ? stripUnsupportedGeminiKeys(entry) : entry);
+}
+/** Derive provider wire JSON Schema from a Zod type. */
+function stripUnsupportedGeminiKeys(schema) {
+    const out = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (!GEMINI_SUPPORTED_SCHEMA_KEYS.includes(key)) {
+            continue;
+        }
+        if (key === 'properties') {
+            out.properties = stripProperties(value);
+            continue;
+        }
+        if (key === 'items' && value && typeof value === 'object' && !Array.isArray(value)) {
+            out.items = stripUnsupportedGeminiKeys(value);
+            continue;
+        }
+        if ((key === 'anyOf' || key === 'oneOf') && Array.isArray(value)) {
+            out[key] = stripBranches(value);
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function jsonSchemaFromZod(schema, io = 'output') {
+    const json = z.toJSONSchema(schema, {
+        target: 'openApi3',
+        io,
+    });
+    delete json.$schema;
+    if (!json.type) {
+        json.type = 'object';
+    }
+    return stripUnsupportedGeminiKeys(json);
+}
+export { jsonSchemaFromZod, validateToolInputSchema, validateToolOutputSchema };
+/** Strip prototype-pollution keys from provider/host tool args or host-mutated values 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;
+}

package/esm/src/kernel/tools/stage-run.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Tool execute wiring around the stage spine: `pre_tool` outcomes (deny, gate,
+ * mutate, abort) and `post_tool` inject hand-off.
+ *
+ * Contract: `docs/contracts/stages.md` (tool execute pipeline).
+ *
+ * @module
+ */
+import type { z } from 'zod';
+import { type StageHandler, type StageResult } from '../stages.js';
+import type { Profile, TurnEvent, TurnHistoryMessage } from '../types.js';
+import type { ToolCallBase } from './events.js';
+import type { ModelToolResult, ToolContext, ToolFailure, ToolGate } from './types.js';
+/** Stage wiring passed into `executeRegisteredTool`. */
+export interface ToolStageSupport {
+    /** Ordered host handlers: request `onStage`, then turn/session ambient. */
+    handlers: StageHandler[];
+    /** Profile whose guardrails sanitize injects and whose inject gate applies. */
+    profile: Profile;
+    step: number;
+    history: () => readonly TurnHistoryMessage[];
+    injectAllowed: boolean;
+    injectWouldExceedMaxSteps?: boolean;
+    /** Apply sanitized inject messages immediately instead of handing them back. */
+    applyInject?: (messages: TurnHistoryMessage[]) => void;
+    host?: unknown;
+    signal?: AbortSignal;
+}
+/**
+ * Everything before a tool body runs, after schema + permission: tool `preTool`,
+ * host `pre_tool`, and the mutate re-parse. Each execute path maps the terminal
+ * shapes onto its own settlement; the pipeline itself lives here once.
+ */
+export type PreBodyOutcome = {
+    ok: true;
+    input: unknown;
+} | {
+    ok: false;
+    kind: 'aborted';
+    aborted: true | {
+        reason?: string;
+    };
+} | {
+    ok: false;
+    kind: 'gated';
+    gate: ToolGate;
+} | {
+    ok: false;
+    kind: 'failed';
+    failure: ToolFailure;
+};
+export type PostToolStageOutcome = {
+    abort?: boolean | {
+        reason?: string;
+    };
+    /** Sanitized inject messages for the caller to apply after recording the tool result. */
+    inject?: TurnHistoryMessage[];
+    /** Host refused the result: the model gets this failure instead. */
+    deny?: {
+        code: string;
+        message: string;
+    };
+    /** Host replaced the raw output; the caller re-validates and re-projects it. */
+    mutate?: {
+        output: unknown;
+    };
+};
+/**
+ * Tool-local `preTool` (skipped when resume.granted) → host `pre_tool` →
+ * mutate re-parse. Emits the gate wire for a host confirm.
+ */
+export declare function runPreToolPipeline(args: {
+    tool: {
+        name: string;
+        input: {
+            safeParse: (value: unknown) => z.ZodSafeParseResult<unknown>;
+        };
+        preTool?: (input: never, ctx: ToolContext) => StageResult | undefined | Promise<StageResult | undefined>;
+    };
+    input: unknown;
+    ctx: ToolContext;
+    base: ToolCallBase;
+    stages?: ToolStageSupport;
+}): AsyncGenerator<TurnEvent, PreBodyOutcome>;
+/** Emit `post_tool`, run host handlers, hand back inject/abort. */
+export declare function runPostToolStages(args: {
+    stages: ToolStageSupport;
+    toolName: string;
+    callId: string;
+    input?: unknown;
+    callNotStarted?: boolean;
+    outputRaw?: unknown;
+    outputModel?: ModelToolResult;
+    failure?: ToolFailure;
+    awaiting?: boolean;
+    /** False when there is no completed output for `mutate` to replace. */
+    mutable: boolean;
+}): AsyncGenerator<TurnEvent, PostToolStageOutcome>;
+/** Emit observe `pre_tool` (callNotStarted) then the tool `gate` wire. */
+export declare function emitGateSettlement(args: {
+    base: ToolCallBase;
+    gate: ToolGate;
+    callId: string;
+    toolName: string;
+}): AsyncGenerator<TurnEvent, void>;