theorum 0.1.14 → 1.0.0

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

@@ -0,0 +1,29 @@
+/**
+ * Turn tool visibility and wire snapshot resolution.
+ *
+ * @module
+ */
+import type { ModelId, Profile, ToolId, TurnRequest } from '../types.js';
+import type { PromoteLoadedResult, ToolFailure, TurnToolSnapshot, WireFunctionTool } from './types.js';
+export declare function pathMatches(catalogPaths?: string[], turnPath?: string): boolean;
+export declare function applyBuiltinMutualExclusions(requested: string[]): string[];
+export declare function resolveAllowedCustomToolIds(profile: Profile, req: TurnRequest): ToolId[];
+/** Provider builtins listed on the selected model — on for the turn (path-filtered). */
+export declare function resolveModelBuiltinIds(profile: Profile, req: TurnRequest, modelId: ModelId): ToolId[];
+export declare function wireForTool(name: string): WireFunctionTool | undefined;
+export declare function buildWire(visible: ToolId[]): WireFunctionTool[];
+export declare function promoteTool(state: TurnToolSnapshot, id: ToolId): void;
+export declare function promoteBuiltin(state: TurnToolSnapshot, id: ToolId): void;
+export declare function initialVisible(gated: ToolId[]): ToolId[];
+export declare function initialBuiltins(gated: ToolId[]): ToolId[];
+/** Build the initial tool snapshot for a turn (T0 wired; T1/T2 pending). */
+export declare function resolveTurnTools(profile: Profile, req: TurnRequest, modelId: ModelId): TurnToolSnapshot;
+/** Resolve T0 snapshot and expand T1 selections from `profile.tools.t1Policy`. */
+export declare function prepareTurnToolSnapshot(profile: Profile, req: TurnRequest, modelId: ModelId): Promise<TurnToolSnapshot>;
+/** Deep-clone a turn snapshot so host-side concurrent invokes do not share mutable state. */
+export declare function cloneTurnToolSnapshot(state: TurnToolSnapshot): TurnToolSnapshot;
+/** Wire T1 tools selected by `profile.tools.t1Policy`. */
+export declare function expandT1Policy(state: TurnToolSnapshot, profile: Profile, req: TurnRequest): Promise<void>;
+/** Promote T2 tools into the visible set after tools.t2Loader returns { loaded }. */
+export declare function promoteLoadedTools(state: TurnToolSnapshot, loaded: string[], profile: Profile): PromoteLoadedResult;
+export declare function promotionFailure(id: string, profile: Profile): ToolFailure | undefined;

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

@@ -0,0 +1,262 @@
+/**
+ * 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;
+        }
+        return 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];
+    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);
+}
+export function initialVisible(gated) {
+    return gated.filter((id) => getTool(id)?.loadTier === 'T0');
+}
+export function initialBuiltins(gated) {
+    return applyBuiltinMutualExclusions(gated.filter((id) => {
+        const tool = getTool(id);
+        return tool?.type === 'builtin' && tool.loadTier === 'T0';
+    }));
+}
+/** Build the initial tool snapshot for a turn (T0 wired; T1/T2 pending). */
+export function resolveTurnTools(profile, req, modelId) {
+    const customAllowed = resolveAllowedCustomToolIds(profile, req);
+    const modelBuiltins = resolveModelBuiltinIds(profile, req, modelId);
+    const gated = [...customAllowed, ...modelBuiltins];
+    const builtins = initialBuiltins(gated);
+    const visible = initialVisible(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') {
+        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,
+        });
+    }
+    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[]`);
+    }
+    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) {
+    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',
+                },
+            };
+        }
+        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`,
+                },
+            };
+        }
+        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`,
+        };
+    }
+    const tool = getTool(id);
+    if (!tool) {
+        return {
+            code: 'invalid_output',
+            message: `tools.t2Loader attempted to promote unknown tool '${id}'`,
+        };
+    }
+    if (tool.type === 'builtin') {
+        return {
+            code: 'invalid_output',
+            message: `tools.t2Loader attempted to promote builtin '${id}' — only custom tools may be promoted`,
+        };
+    }
+    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`,
+        };
+    }
+    return undefined;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * 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 };

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

@@ -0,0 +1,159 @@
+/**
+ * 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}'`);
+        }
+    }
+}
+function validateSchemaShape(schema, path, mode, errors) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        errors.push(`${path}: schema must be an object`);
+        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`);
+    }
+    if (mode === 'gemini') {
+        validateGeminiKeys(schema, path, errors);
+    }
+    if (schema.type === 'array' && schema.items === undefined) {
+        errors.push(`${path}: array schema must define items`);
+    }
+    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`);
+        }
+    }
+    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('; ')}`);
+    }
+}
+/** 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 };

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

@@ -0,0 +1,216 @@
+/**
+ * Tool registry types — single catalog, shared execution.
+ *
+ * Closed unions (`TOOL_*`) live in `../schema.ts`. This module owns the
+ * structural contracts built on those unions.
+ *
+ * @module
+ */
+import type { z } from 'zod';
+import type { ToolAccess, ToolLoadTier, ToolPermission } from '../schema.js';
+import type { Profile, ToolId, TurnInput } from '../types.js';
+export type { ToolAccess, ToolPermission };
+export interface ToolLabels {
+    activity?: string;
+    activityPast?: string;
+    hiddenFromSettings?: boolean;
+}
+export interface ToolBase {
+    name: string;
+    description: string;
+    category: string;
+    access: ToolAccess;
+    paths: string[];
+    loadTier: ToolLoadTier;
+    permission: ToolPermission;
+    labels?: ToolLabels;
+}
+export interface BuiltinWire {
+    interactions?: string;
+    openRouter?: string;
+    live?: string;
+}
+export interface BuiltinToolDef extends ToolBase {
+    type: 'builtin';
+    wire: BuiltinWire;
+    conflictsWith?: string[];
+    /** When enabled, select the paid Vault key slot unless model.spec.key overrides. */
+    forcePaidKey?: boolean;
+}
+export interface InteractiveRender {
+    kind: string;
+    prompt: string;
+    options?: string[];
+    [key: string]: unknown;
+}
+export interface InteractiveConfig<TIn = unknown> {
+    render: (input: TIn) => InteractiveRender;
+}
+export interface InvokeToolResume {
+    value?: unknown;
+    granted?: boolean;
+}
+export interface ToolContext {
+    profile: Profile;
+    callId: string;
+    sessionPermissions?: string[];
+    path?: string;
+    signal?: AbortSignal;
+    turn?: {
+        step: number;
+    };
+    resume?: InvokeToolResume;
+}
+export interface ToolFailure {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface ToolPause {
+    kind: 'interactive' | 'confirmation' | 'permission';
+    tool: string;
+    render?: InteractiveRender;
+    summary?: string;
+    input: unknown;
+    permission?: ToolPermission;
+}
+export interface ToolWarning {
+    code: string;
+    message: string;
+    severity?: 'info' | 'warning' | 'error';
+}
+export interface ToolTraceStep {
+    name: string;
+    kind: string;
+    status: string;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+}
+export type ToolStreamEvent<TOut = unknown> = {
+    kind: 'progress';
+    data: unknown;
+} | {
+    kind: 'trace';
+    step: ToolTraceStep;
+} | {
+    kind: 'artifact';
+    artifact: unknown;
+} | {
+    kind: 'warning';
+    warning: ToolWarning;
+} | {
+    kind: 'complete';
+    output: TOut;
+};
+export type SyncToolHandler<TIn, TOut> = (input: TIn, ctx: ToolContext) => TOut | Promise<TOut>;
+export type StreamToolHandler<TIn, TOut> = (input: TIn, ctx: ToolContext) => AsyncGenerator<ToolStreamEvent<TOut>>;
+export type ToolHandler<TIn, TOut> = SyncToolHandler<TIn, TOut> | StreamToolHandler<TIn, TOut>;
+export interface FunctionToolDef<TIn = unknown, TOut = unknown> extends ToolBase {
+    type: 'function';
+    input: z.ZodType<TIn>;
+    output: z.ZodType<TOut>;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    handler: ToolHandler<TIn, TOut>;
+    interactive?: InteractiveConfig<TIn>;
+    canExecute?: (input: TIn, ctx: ToolContext) => boolean | Promise<boolean>;
+    preflight?: (input: TIn, ctx: ToolContext) => undefined | ToolFailure | ToolPause | Promise<undefined | ToolFailure | ToolPause>;
+    exposeToModel?: boolean;
+}
+export type RegisteredTool<TIn = unknown, TOut = unknown> = BuiltinToolDef | FunctionToolDef<TIn, TOut>;
+export type ToolDefinitionInput<TIn = unknown, TOut = unknown> = BuiltinToolDef | (Omit<FunctionToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
+    input: z.ZodType<TIn>;
+    output: z.ZodType<TOut>;
+});
+export interface WireFunctionTool {
+    type: 'function';
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export interface TurnToolSnapshot {
+    builtins: ToolId[];
+    /** Tool ids eligible this turn (custom: allow + path; builtin: model builtInTools + path). */
+    gated: ToolId[];
+    /** Schemas sent to the provider (respects loadTier + t2Loader promotion). */
+    visible: ToolId[];
+    /** Kernel-executable tools: eligible, visible, and loaded (excludes builtins). */
+    executable: ToolId[];
+    path?: string;
+    sessionPermissions?: string[];
+    wire: WireFunctionTool[];
+}
+export interface PromoteLoadedResult {
+    promoted: ToolId[];
+    failure?: ToolFailure;
+}
+/** Context for profile T1 tool selection via `profile.tools.t1Policy`. */
+export interface ToolLoadContext {
+    profile: Profile;
+    input?: TurnInput;
+    path?: string;
+    sessionPermissions?: string[];
+    /** Tool ids eligible this turn. */
+    gated: ToolId[];
+}
+/** Profile-owned T1 selection — which eligible T1 tools to wire at turn start. */
+export type ToolPolicy = (ctx: ToolLoadContext) => ToolId[] | Promise<ToolId[]>;
+export interface InvokeToolRequest {
+    profile: string;
+    name: string;
+    input: unknown;
+    /** Turn input context for `profile.tools.t1Policy` selection (same as `TurnRequest.input`). */
+    turnInput?: TurnInput;
+    /**
+     * T2 tools already promoted for this invoke (e.g. restored from pause metadata).
+     * Host must have run tools.t2Loader (or equivalent) before listing ids here.
+     */
+    promoted?: ToolId[];
+    /** Model select key — same as `TurnRequest.select` (builtins resolve from that model). */
+    select?: string;
+    /**
+     * Optional turn snapshot from a paused turn. Cloned before use so concurrent host
+     * invokes do not share mutable visibility state.
+     */
+    snapshot?: TurnToolSnapshot;
+    resume?: InvokeToolResume;
+    sessionPermissions?: string[];
+    path?: string;
+    signal?: AbortSignal;
+}
+export interface ProfileToolsSpec {
+    /** Custom function tools this profile may run. Builtins live on model specs. */
+    allow: ToolId[];
+    /**
+     * Optional T1 policy — returns which eligible T1 tools to wire at turn start.
+     * Tools must already be on `allow` (custom) or `builtInTools` (builtin) and `loadTier: 'T1'`.
+     */
+    t1Policy?: ToolPolicy;
+    /**
+     * Optional designated function tool id for T2 promotion.
+     * Must be in `allow`. When that tool completes with `{ loaded: string[] }`, those T2 ids are promoted.
+     */
+    t2Loader?: ToolId;
+}
+export interface ModelToolResult {
+    finding: string;
+    data?: unknown;
+}
+export type ToolCallPhase = 'running' | 'progress' | 'trace' | 'artifact' | 'warning' | 'complete' | 'pause' | 'error'
+/** Provider cancelled an in-flight tool call (e.g. live barge-in). */
+ | 'cancel';
+export interface ToolCallEvent {
+    name: string;
+    /** Provider-native id or kernel-assigned call id. */
+    callId?: string;
+    arguments?: Record<string, unknown>;
+    /** Absent on raw provider tool-call events; set by kernel execution. */
+    phase?: ToolCallPhase;
+    data?: unknown;
+    step?: ToolTraceStep;
+    artifact?: unknown;
+    warning?: ToolWarning;
+    output?: unknown;
+    pause?: ToolPause;
+    failure?: ToolFailure;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Tool registry types — single catalog, shared execution.
+ *
+ * Closed unions (`TOOL_*`) live in `../schema.ts`. This module owns the
+ * structural contracts built on those unions.
+ *
+ * @module
+ */
+export {};