theorum 1.0.0 → 1.1.3

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

@@ -33,12 +33,13 @@ export function resolveAllowedCustomToolIds(profile, req) {
         if (!tool || tool.type === 'builtin') {
             return false;
         }
-        return pathMatches(tool.paths, req.path);
+        // 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.model.config[modelId];
+    const spec = profile.models[modelId];
     if (!spec) {
         return [];
     }
@@ -100,22 +101,37 @@ export function promoteBuiltin(state, id) {
     });
     state.builtins.push(id);
 }
-export function initialVisible(gated) {
+/**
+ * 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');
 }
-export function initialBuiltins(gated) {
+/** 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' && tool.loadTier === 'T0';
+        return tool?.type === 'builtin' && (profile.type === 'live' || tool.loadTier === 'T0');
     }));
 }
-/** Build the initial tool snapshot for a turn (T0 wired; T1/T2 pending). */
+/**
+ * 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 = resolveModelBuiltinIds(profile, req, modelId);
+    const modelBuiltins = profile.type === 'host' || modelId === undefined
+        ? []
+        : resolveModelBuiltinIds(profile, req, modelId);
     const gated = [...customAllowed, ...modelBuiltins];
-    const builtins = initialBuiltins(gated);
-    const visible = initialVisible(gated);
+    const builtins = initialBuiltins(profile, gated);
+    const visible = initialVisible(profile, gated);
     const executable = visible.filter((id) => getTool(id)?.type !== 'builtin');
     return {
         builtins,
@@ -147,7 +163,7 @@ export function cloneTurnToolSnapshot(state) {
 }
 /** Wire T1 tools selected by `profile.tools.t1Policy`. */
 export async function expandT1Policy(state, profile, req) {
-    if (profile.type === 'speech') {
+    if (profile.type === 'speech' || profile.type === 'live' || profile.type === 'host') {
         return;
     }
     const t1Policy = profile.tools.t1Policy;
@@ -162,6 +178,7 @@ export async function expandT1Policy(state, profile, req) {
             path: req.path,
             sessionPermissions: req.sessionPermissions,
             gated: state.gated,
+            host: req.host,
         });
     }
     catch (err) {
@@ -171,7 +188,7 @@ export async function expandT1Policy(state, profile, req) {
         });
     }
     if (!Array.isArray(selected)) {
-        throw new TheorumError(`Profile '${profile.id}' tools.t1Policy must return ToolId[]`);
+        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)) {
@@ -194,6 +211,10 @@ export async function expandT1Policy(state, profile, req) {
 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)) {
@@ -201,7 +222,7 @@ export function promoteLoadedTools(state, loaded, profile) {
                 promoted: [],
                 failure: {
                     code: 'invalid_output',
-                    message: 'tools.t2Loader loaded ids must be plain strings',
+                    message: 'tools.t2Loader loaded ids must be plain strings', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                 },
             };
         }
@@ -215,7 +236,7 @@ export function promoteLoadedTools(state, loaded, profile) {
                 promoted: [],
                 failure: {
                     code: 'invalid_output',
-                    message: `Tool '${id}' is not registered`,
+                    message: `Tool '${id}' is not registered`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                 },
             };
         }
@@ -236,26 +257,26 @@ 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`,
+            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}'`,
+            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`,
+            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`,
+            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

@@ -11,3 +11,5 @@ declare function validateToolInputSchema(schema: JsonSchema, mode?: 'gemini' | '
 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

@@ -33,13 +33,13 @@ const GEMINI_SUPPORTED_SCHEMA_KEYS = [
 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}'`);
+            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`);
+        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);
@@ -48,13 +48,13 @@ function validateSchemaShape(schema, path, mode, errors) {
         if (mode === 'structural' && path !== '$') {
             return true;
         }
-        errors.push(`${path}: missing type or combinator`);
+        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`);
+        errors.push(`${path}: array schema must define items`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return true;
 }
@@ -62,7 +62,7 @@ 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`);
+            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)) {
@@ -97,7 +97,7 @@ 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('; ')}`);
+        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. */
@@ -157,3 +157,20 @@ function jsonSchemaFromZod(schema, io = 'output') {
     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>;

package/esm/src/kernel/tools/stage-run.js

@@ -0,0 +1,155 @@
+/**
+ * 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 { lexiconText } from '../../guardrails/lexicon.js';
+import { runStage, stageEventFields } from '../stages.js';
+import { isGateResumeGranted } from './permission.js';
+import { plainToolInput } from './schema.js';
+/** Stage support when only a tool-local `preTool` is present. */
+function defaultToolStageSupport(ctx) {
+    return {
+        handlers: [],
+        profile: ctx.profile,
+        step: ctx.turn?.step ?? 1,
+        history: () => [],
+        injectAllowed: false,
+        host: ctx.host,
+        signal: ctx.signal,
+    };
+}
+/**
+ * Tool-local `preTool` (skipped when resume.granted) → host `pre_tool` →
+ * mutate re-parse. Emits the gate wire for a host confirm.
+ */
+export async function* runPreToolPipeline(args) {
+    const { tool, ctx, base, stages } = args;
+    let toolPreTool;
+    if (tool.preTool && !isGateResumeGranted(ctx.resume)) {
+        toolPreTool = (await tool.preTool(args.input, ctx)) ?? undefined;
+    }
+    if (!stages && toolPreTool === undefined) {
+        return { ok: true, input: args.input };
+    }
+    const pre = yield* runPreToolStages({
+        stages: stages ?? defaultToolStageSupport(ctx),
+        toolName: tool.name,
+        callId: base.callId ?? '',
+        input: args.input,
+        toolPreTool,
+    });
+    if (!pre.ok) {
+        if (pre.kind === 'gated')
+            yield gateEvent(base, pre.gate);
+        return pre;
+    }
+    if (!pre.mutated)
+        return { ok: true, input: pre.input };
+    const reparsed = tool.input.safeParse(plainToolInput(pre.input));
+    if (!reparsed.success) {
+        return {
+            ok: false,
+            kind: 'failed',
+            failure: {
+                code: 'invalid_input',
+                message: lexiconText('tool.input_invalid_after_mutate'),
+                details: reparsed.error.flatten(),
+            },
+        };
+    }
+    return { ok: true, input: reparsed.data };
+}
+/** Emit `pre_tool`, run tool `preTool` then host handlers, map affordances to an outcome. */
+async function* runPreToolStages(args) {
+    const { stages, toolName, callId, input, toolPreTool } = args;
+    const applied = yield* runStage({
+        stage: 'pre_tool',
+        step: stages.step,
+        history: stages.history(),
+        handlers: [...(toolPreTool !== undefined ? [() => toolPreTool] : []), ...stages.handlers],
+        guardrails: stages.profile.guardrails,
+        injectAllowed: false,
+        host: stages.host,
+        signal: stages.signal,
+        callId,
+        tool: toolName,
+        input,
+    });
+    if (applied.abort) {
+        return { ok: false, kind: 'aborted', aborted: applied.abort };
+    }
+    if (applied.deny) {
+        return { ok: false, kind: 'failed', failure: applied.deny };
+    }
+    if (applied.confirm) {
+        const gate = {
+            kind: 'confirmation',
+            tool: toolName,
+            ...(applied.confirm.summary ? { summary: applied.confirm.summary } : {}),
+        };
+        yield stageEventFields('pre_tool', { callId, toolName, callNotStarted: true, gate });
+        return { ok: false, kind: 'gated', gate };
+    }
+    if (applied.mutate && 'input' in applied.mutate) {
+        return { ok: true, input: applied.mutate.input, mutated: true };
+    }
+    return { ok: true, input, mutated: false };
+}
+/** Emit `post_tool`, run host handlers, hand back inject/abort. */
+export async function* runPostToolStages(args) {
+    const { stages, toolName, callId, mutable, ...call } = args;
+    const applied = yield* runStage({
+        ...call,
+        stage: 'post_tool',
+        step: stages.step,
+        history: stages.history(),
+        handlers: stages.handlers,
+        guardrails: stages.profile.guardrails,
+        injectAllowed: stages.injectAllowed,
+        injectWouldExceedMaxSteps: stages.injectWouldExceedMaxSteps,
+        mutable,
+        host: stages.host,
+        signal: stages.signal,
+        callId,
+        tool: toolName,
+    });
+    const terminal = {
+        ...(applied.abort !== undefined ? { abort: applied.abort } : {}),
+        ...(applied.deny ? { deny: applied.deny } : {}),
+        ...(applied.mutate && 'output' in applied.mutate ? { mutate: applied.mutate } : {}),
+    };
+    if (applied.inject.length === 0)
+        return terminal;
+    // Prefer returning inject for the runner to apply after recording the provider
+    // tool result (Interactions continuation must exist first). When applyInject is
+    // set the caller wants immediate apply (e.g. invokeTool).
+    if (stages.applyInject) {
+        stages.applyInject(applied.inject);
+        return terminal;
+    }
+    return { ...terminal, inject: applied.inject };
+}
+function gateEvent(base, gate) {
+    return {
+        type: 'tool',
+        tool: {
+            ...base,
+            phase: 'gate',
+            gate,
+        },
+    };
+}
+/** Emit observe `pre_tool` (callNotStarted) then the tool `gate` wire. */
+export async function* emitGateSettlement(args) {
+    yield stageEventFields('pre_tool', {
+        callId: args.callId,
+        toolName: args.toolName,
+        callNotStarted: true,
+        gate: args.gate,
+    });
+    yield gateEvent(args.base, args.gate);
+}