@jini-ai/core 0.4.8 → 0.6.10

package/dist/tool-exposure.js

@@ -0,0 +1,163 @@
+const SAFE_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const MAX_NAME_LENGTH = 64;
+/** A stable, non-security hash keeps transformed names independent of discovery order.
+ * Collisions are still checked against the entire namespace, never trusted as unique. */
+function nameHash(id) {
+    let hash = 2166136261;
+    for (let i = 0; i < id.length; i++)
+        hash = Math.imul(hash ^ id.charCodeAt(i), 16777619);
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+function nameBase(id) {
+    if (SAFE_NAME.test(id))
+        return id;
+    const readable = id.replace(/[^A-Za-z0-9_]/g, '_');
+    return `tool_${readable.slice(0, 49)}_${nameHash(id)}`;
+}
+/** O(c) collision probes for c occupied alternatives; suffix space stays inside the wire limit. */
+function assignName(index, id) {
+    if (index.forward.has(id))
+        return;
+    const base = nameBase(id);
+    let candidate = base;
+    let counter = 1;
+    while (index.occupied.has(candidate)) {
+        const suffix = `_${counter++}`;
+        candidate = `${base.slice(0, MAX_NAME_LENGTH - suffix.length)}${suffix}`;
+    }
+    index.forward.set(id, candidate);
+    index.reverse.set(candidate, id);
+    index.occupied.add(candidate);
+}
+/** Reserve native spellings first so a transformed ID cannot steal an existing safe name. */
+function indexNames(index, toolIds) {
+    const sorted = [...new Set(toolIds)].sort();
+    for (const id of sorted)
+        if (SAFE_NAME.test(id))
+            assignName(index, id);
+    for (const id of sorted)
+        if (!SAFE_NAME.test(id))
+            assignName(index, id);
+}
+/**
+ * Build a deterministic, collision-checked mapping to conservative 64-character wire names.
+ * @param required - Registry IDs; duplicates share one mapping.
+ * @param optional - Names already occupied by transport-owned tools.
+ * @returns Read-only forward/reverse lookups, with no descriptors or execution authority.
+ * @complexity O(n log n + l + c) time, O(n + l) space for n IDs, l characters and c collision probes.
+ */
+export function createToolNameMap({ toolIds }, { reservedNames = [] } = {}) {
+    const index = { forward: new Map(), reverse: new Map(), occupied: new Set(reservedNames) };
+    indexNames(index, toolIds);
+    return Object.freeze({
+        wireNameFor: ({ toolId }, _optional = {}) => index.forward.get(toolId),
+        toolIdFor: ({ wireName }, _optional = {}) => index.reverse.get(wireName),
+    });
+}
+export class ToolExposureError extends Error {
+    code;
+    constructor({ code }, options = {}) {
+        super(`ToolExposure: ${code}`, options);
+        this.name = 'ToolExposureError';
+        this.code = code;
+    }
+}
+function assertLimit(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new ToolExposureError({ code: 'invalid-limit' });
+}
+/** Freeze detached data only; registry-owned descriptors are never frozen or mutated. */
+function freezeData(value, seen = new Set()) {
+    if (value === null || typeof value !== 'object' || Object.isFrozen(value) || seen.has(value))
+        return;
+    seen.add(value);
+    for (const child of Object.values(value))
+        freezeData(child, seen);
+    Object.freeze(value);
+}
+/** Clone and measure before publication. Invalid data cannot partially change exposure state. */
+function pinDescriptor(descriptor) {
+    try {
+        const pinned = structuredClone(descriptor);
+        const json = JSON.stringify(pinned.inputSchema);
+        const bytes = json === undefined ? 0 : new TextEncoder().encode(json).byteLength;
+        freezeData(pinned);
+        return { descriptor: pinned, bytes };
+    }
+    catch (cause) {
+        throw new ToolExposureError({ code: 'invalid-descriptor' }, { cause });
+    }
+}
+/** Count and byte caps reject new entries without evicting any previously callable definition. */
+function limitReason(snapshot, bytes, limits) {
+    if (snapshot.tools.length >= limits.maxTools)
+        return 'tool-limit';
+    if (snapshot.schemaBytes + bytes > limits.maxSchemaBytes)
+        return 'schema-byte-limit';
+    return undefined;
+}
+/** Stage all changes locally so malformed descriptors leave the last published revision intact. */
+function promoteDescriptors(snapshot, toolIds, descriptors, names, limits) {
+    const available = new Map(descriptors.map(descriptor => [descriptor.id, descriptor]));
+    const published = new Set(snapshot.tools.map(tool => tool.descriptor.id));
+    const tools = [...snapshot.tools];
+    const added = [];
+    const skipped = [];
+    let schemaBytes = snapshot.schemaBytes;
+    for (const toolId of new Set(toolIds)) {
+        if (published.has(toolId))
+            continue;
+        const descriptor = available.get(toolId);
+        if (!descriptor) {
+            skipped.push({ toolId, reason: 'not-found' });
+            continue;
+        }
+        const pinned = pinDescriptor(descriptor);
+        const reason = limitReason({ tools, schemaBytes, revision: snapshot.revision }, pinned.bytes, limits);
+        if (reason) {
+            skipped.push({ toolId, reason });
+            continue;
+        }
+        assignName(names, toolId);
+        tools.push({ wireName: names.forward.get(toolId), descriptor: pinned.descriptor });
+        schemaBytes += pinned.bytes;
+        added.push(toolId);
+    }
+    let next = snapshot;
+    if (added.length > 0)
+        next = { revision: snapshot.revision + 1, tools, schemaBytes };
+    const result = { snapshot: next, added, skipped };
+    freezeData(result);
+    return result;
+}
+/**
+ * Create one run's bounded, append-only descriptor exposure over the existing registry.
+ * @param required - Descriptor source; a filtered registry view may enforce host visibility.
+ * @param optional - Count/schema-byte budgets and transport-owned reserved wire names.
+ * @returns Immutable snapshots and promotion deltas; no handlers, policies or execution path.
+ * @throws ToolExposureError for invalid limits or non-cloneable/non-serializable descriptors.
+ * @complexity Promotion O(r log r + s + b + c) time and O(r + s + b) space for r registry IDs,
+ * s exposed entries, b promoted descriptor bytes and c name collision probes. No I/O.
+ * @remarks Scope mutation is synchronous, so concurrent promise continuations cannot lose updates.
+ * Definitions stay pinned until this object is released; execution must recheck current registry policy.
+ */
+export function createToolExposure({ registry }, { maxTools = 64, maxSchemaBytes = 262_144, reservedNames = [] } = {}) {
+    assertLimit(maxTools);
+    assertLimit(maxSchemaBytes);
+    const names = { forward: new Map(), reverse: new Map(), occupied: new Set(reservedNames) };
+    let snapshot = Object.freeze({ revision: 0, tools: Object.freeze([]), schemaBytes: 0 });
+    return Object.freeze({
+        promote({ toolIds }, _optional = {}) {
+            const descriptors = registry.list({});
+            indexNames(names, descriptors.map(descriptor => descriptor.id));
+            const result = promoteDescriptors(snapshot, toolIds, descriptors, names, { maxTools, maxSchemaBytes });
+            snapshot = result.snapshot;
+            return result;
+        },
+        getSnapshot(_required, _optional = {}) { return snapshot; },
+        resolveToolId({ wireName }, _optional = {}) {
+            return snapshot.tools.find(tool => tool.wireName === wireName)?.descriptor.id;
+        },
+    });
+}
+//# sourceMappingURL=tool-exposure.js.map

package/dist/tool-input-errors.d.ts

@@ -0,0 +1,23 @@
+/** @file Dependency-free tool input errors shared by registration and normalization. */
+/**
+ * Thrown by a `ToolHandler` (or a validator it calls, e.g. the kernel's `registration-kit.ts`
+ * `requireString`/`requireInputRecord`/etc.) to mean "the caller's input was malformed or missing a
+ * required field" — a fact about the CALL, not the server. `@jini-ai/daemon`'s `ToolExecutor.execute`
+ * tags a handler rejection's `ToolExecutionResult.errorKind` as `'validation'` when the thrown error
+ * is `instanceof ToolInputError`, and every HTTP-facing mapping of a `'failed'` execution (today:
+ * `@jini-ai/http-kit`'s `delegated-tools.ts`) uses that tag to answer with a 4xx instead of folding
+ * it into the same redacted 500 an actual internal/infrastructure failure gets.
+ *
+ * Deliberately a plain marker with no extra fields: the message itself is already caller-actionable
+ * (`withSchemaOnRejection` appends the tool's own input schema to it), so nothing beyond "this IS one
+ * of these" needs to survive the `instanceof` check.
+ */
+export declare class ToolInputError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optional?: ErrorOptions);
+}
+/** Keeps caller shape failures distinct from infrastructure/policy failures in the gate. */
+export declare class ToolInputNormalizationError extends ToolInputError {
+}
+//# sourceMappingURL=tool-input-errors.d.ts.map

package/dist/tool-input-errors.js

@@ -0,0 +1,24 @@
+/** @file Dependency-free tool input errors shared by registration and normalization. */
+/**
+ * Thrown by a `ToolHandler` (or a validator it calls, e.g. the kernel's `registration-kit.ts`
+ * `requireString`/`requireInputRecord`/etc.) to mean "the caller's input was malformed or missing a
+ * required field" — a fact about the CALL, not the server. `@jini-ai/daemon`'s `ToolExecutor.execute`
+ * tags a handler rejection's `ToolExecutionResult.errorKind` as `'validation'` when the thrown error
+ * is `instanceof ToolInputError`, and every HTTP-facing mapping of a `'failed'` execution (today:
+ * `@jini-ai/http-kit`'s `delegated-tools.ts`) uses that tag to answer with a 4xx instead of folding
+ * it into the same redacted 500 an actual internal/infrastructure failure gets.
+ *
+ * Deliberately a plain marker with no extra fields: the message itself is already caller-actionable
+ * (`withSchemaOnRejection` appends the tool's own input schema to it), so nothing beyond "this IS one
+ * of these" needs to survive the `instanceof` check.
+ */
+export class ToolInputError extends Error {
+    constructor({ message }, optional = {}) {
+        super(message, optional);
+        this.name = 'ToolInputError';
+    }
+}
+/** Keeps caller shape failures distinct from infrastructure/policy failures in the gate. */
+export class ToolInputNormalizationError extends ToolInputError {
+}
+//# sourceMappingURL=tool-input-errors.js.map

package/dist/tool-input-normalization.d.ts

@@ -0,0 +1,37 @@
+import type { ToolRegistration } from './tool-registry.js';
+export { ToolInputNormalizationError } from './tool-input-errors.js';
+/** A value-free account of canonicalization; domain hooks use the same contract as the gate. */
+export interface NormalizedToolInput {
+    readonly input: unknown;
+    readonly notes: readonly string[];
+}
+export type ToolInputNormalizer = (required: {
+    input: Readonly<Record<string, unknown>>;
+}, optional?: Record<string, never>) => NormalizedToolInput | Promise<NormalizedToolInput>;
+/** Canonicalize one batch layer before merging; preserve values and domain aliases for the
+ * final normalization. Throws ToolInputError for collisions within this layer, never across
+ * layers. Uses the same bounded schema walk as normalizeToolInput.
+ * @example canonicalizeToolInputKeys({ input: { max_chars: '1000' }, schema });
+ */
+export declare function canonicalizeToolInputKeys({ input, schema }: {
+    input: Readonly<Record<string, unknown>>;
+    schema: unknown;
+}, _options?: Record<string, never>): {
+    input: Record<string, unknown>;
+    notes: readonly string[];
+};
+/** Normalize before policy, confirmation and handler validation. Domain hooks own semantic aliases.
+ * Never changes the caller's object or includes values in notes. Invalid/ambiguous input remains
+ * a ToolInputError; ordinary domain/schema validation still belongs to the registered handler.
+ * @complexity Two bounded schema walks plus the optional domain hook's cost.
+ */
+export declare function normalizeToolInput({ input, registration }: {
+    input: unknown;
+    registration: Pick<ToolRegistration, 'descriptor' | 'normalizeInput' | 'invocationSchema'>;
+}, _options?: Record<string, never>): Promise<NormalizedToolInput>;
+/** Keep result shapes intact and make rewrite notes visible in plain and MCP tool results. */
+export declare function withNormalizationNotes({ output, notes }: {
+    output: unknown;
+    notes: readonly string[];
+}, _options?: Record<string, never>): unknown;
+//# sourceMappingURL=tool-input-normalization.d.ts.map

package/dist/tool-input-normalization.js

@@ -0,0 +1,188 @@
+import { isNonArrayRecord } from './records.js';
+import { ToolInputError, ToolInputNormalizationError } from './tool-input-errors.js';
+export { ToolInputNormalizationError } from './tool-input-errors.js';
+const object = (value) => isNonArrayRecord({ value });
+const keyShape = (key) => key.replace(/[_-]/g, '').toLowerCase();
+/** Length of the shared prefix of two strings. */
+function commonPrefixLength({ left, right }) {
+    let index = 0;
+    while (index < left.length && left[index] === right[index])
+        index++;
+    return index;
+}
+/** Same-length strings that differ by one substitution or one adjacent transposition at `index`. */
+function sameLengthNearMiss({ left, right, index }) {
+    return left.slice(index + 1) === right.slice(index + 1)
+        || (left[index] === right[index + 1] && left[index + 1] === right[index] && left.slice(index + 2) === right.slice(index + 2));
+}
+/** Whether either key is the generic id shorthand for the other's id suffix; hints only. */
+function isIdShorthand({ left, right }, _options = {}) {
+    return (left === 'id' && right.endsWith('id')) || (right === 'id' && left.endsWith('id'));
+}
+/** Detect id shorthand or one insertion, deletion, substitution or transposition, for hints only. */
+function nearMiss({ left, right }, _options = {}) {
+    if (left.length > 128 || right.length > 128)
+        return false;
+    if (isIdShorthand({ left, right }))
+        return true;
+    if (Math.abs(left.length - right.length) > 1)
+        return false;
+    const index = commonPrefixLength({ left, right });
+    if (left.length === right.length)
+        return sameLengthNearMiss({ left, right, index });
+    return left.length > right.length ? left.slice(index + 1) === right.slice(index) : left.slice(index) === right.slice(index + 1);
+}
+const NUMBER_PATTERN = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+/** Number/integer coercion; returns `value` itself when the string is not a representable number. */
+function coerceNumber({ value, types, path, notes }) {
+    const numeric = types.includes('number');
+    const integer = types.includes('integer');
+    if (!(numeric || integer) || !NUMBER_PATTERN.test(value.trim()))
+        return value;
+    const number = Number(value);
+    if (!Number.isFinite(number) || (integer && !numeric && !Number.isSafeInteger(number)))
+        return value;
+    notes.push(`${path}: string→${numeric ? 'number' : 'integer'}`);
+    return number;
+}
+/** Boolean words first, then numbers; any other string is left for the handler's validator. */
+function coerceString({ value, types, path, notes }) {
+    if (types.includes('boolean') && /^(true|false)$/i.test(value.trim())) {
+        notes.push(`${path}: string→boolean`);
+        return value.trim().toLowerCase() === 'true';
+    }
+    return coerceNumber({ value, types, path, notes });
+}
+function normalizeArray({ value, schema, step }) {
+    const { path, depth, walk } = step;
+    let list = value;
+    // The single-object shorthand applies to items batching, never arbitrary domain arrays.
+    if (!walk.keysOnly && object(value) && path.split('.').at(-1) === 'items') {
+        walk.notes.push(`${path}: object→one-item array`);
+        list = [value];
+    }
+    if (!Array.isArray(list))
+        return list;
+    return list.map((item, index) => normalizeValue({ value: item, schema: schema.items, step: { path: `${path}[${index}]`, depth: depth + 1, walk } }));
+}
+/** The declared property a supplied key names, or undefined; refuses a key that names two. */
+function canonicalKey({ key, location, shape }) {
+    const candidates = Object.hasOwn(shape.properties, key) ? [key] : shape.names.filter(name => keyShape(name) === keyShape(key));
+    if (candidates.length > 1)
+        throw new ToolInputError({ message: `Ambiguous input '${location}': matches ${candidates.join(', ')}. Use exactly one canonical property name.` });
+    return candidates[0];
+}
+/** Describe the local schema and likely names without choosing a name or exposing input values.
+ * Target and permission fields must be declared in the tool schema before callers can use them.
+ * @complexity O(p) time and space for p declared properties; name comparisons are length-bounded.
+ */
+function unknownKeyError({ key, location, shape }, _options = {}) {
+    const required = new Set(shape.required);
+    const names = [...shape.names.filter(name => required.has(name)), ...shape.names.filter(name => !required.has(name))];
+    const declared = names.map(name => `${name} (${required.has(name) ? 'required' : 'optional'})`).join(', ') || 'none';
+    const hints = names.filter(name => nearMiss({ left: keyShape(key), right: keyShape(name) }));
+    const suggestion = hints.length ? ` Did you mean ${hints.map(name => `'${name}'`).join(', ')}?` : '';
+    return new ToolInputError({ message: `Unknown input '${location}'. Declared inputs: ${declared}.${suggestion} Resend with the declared name.` });
+}
+/** One key of an object: canonical rename + recursion, closed-schema refusal, or open pass-through. */
+function normalizeEntry({ key, raw, shape, sources, step }) {
+    const { path, depth, walk } = step;
+    const location = path ? `${path}.${key}` : key;
+    const target = canonicalKey({ key, location, shape });
+    if (target === undefined) {
+        if (walk.validateClosed && shape.schema.additionalProperties === false)
+            throw unknownKeyError({ key, location, shape });
+        const childSchema = object(shape.schema.additionalProperties) ? shape.schema.additionalProperties : undefined;
+        return [key, normalizeValue({ value: raw, schema: childSchema, step: { path: location, depth: depth + 1, walk } })];
+    }
+    const previous = sources.get(target);
+    if (previous !== undefined)
+        throw new ToolInputError({ message: `Conflicting inputs '${previous}' and '${key}' both name '${target}'. Send only '${target}'.` });
+    sources.set(target, key);
+    if (target !== key)
+        walk.notes.push(`${location}→${target}`);
+    return [target, normalizeValue({ value: raw, schema: shape.properties[target], step: { path: `${path ? `${path}.` : ''}${target}`, depth: depth + 1, walk } })];
+}
+function normalizeObject({ value, schema, step }) {
+    const properties = object(schema.properties) ? schema.properties : {};
+    const required = Array.isArray(schema.required) ? schema.required.filter((key) => typeof key === 'string') : [];
+    const shape = { schema, properties, names: Object.keys(properties), required };
+    const sources = new Map();
+    return Object.fromEntries(Object.entries(value).map(([key, raw]) => normalizeEntry({ key, raw, shape, sources, step })));
+}
+/** Schema-guided copies only: unconstrained data and unsupported schema dialects stay untouched.
+ * Cost is O(k*p) per object with k supplied keys and p schema properties; recursion is bounded
+ * to 64 levels so a hostile input/schema cannot exhaust the execution gate's stack.
+ */
+function normalizeValue({ value, schema, step }) {
+    if (!object(schema))
+        return value;
+    if (step.depth > 64)
+        throw new ToolInputError({ message: 'Tool input exceeds the 64-level normalization limit. Send a shallower object.' });
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    // A string is never an array or object, so it is either coerced here or returned as-is.
+    if (typeof value === 'string') {
+        return step.walk.keysOnly || types.includes('string') ? value : coerceString({ value, types, path: step.path, notes: step.walk.notes });
+    }
+    if (types.includes('array'))
+        return normalizeArray({ value, schema, step });
+    return object(value) ? normalizeObject({ value, schema, step }) : value;
+}
+/** A walk from the root of one input. */
+function walkRoot({ input, schema, notes, validateClosed, keysOnly }) {
+    return normalizeValue({ value: input, schema, step: { path: '', depth: 0, walk: { notes, validateClosed, keysOnly } } });
+}
+/** Canonicalize one batch layer before merging; preserve values and domain aliases for the
+ * final normalization. Throws ToolInputError for collisions within this layer, never across
+ * layers. Uses the same bounded schema walk as normalizeToolInput.
+ * @example canonicalizeToolInputKeys({ input: { max_chars: '1000' }, schema });
+ */
+export function canonicalizeToolInputKeys({ input, schema }, _options = {}) {
+    const notes = [];
+    return { input: walkRoot({ input, schema, notes, validateClosed: false, keysOnly: true }), notes };
+}
+/** Normalize before policy, confirmation and handler validation. Domain hooks own semantic aliases.
+ * Never changes the caller's object or includes values in notes. Invalid/ambiguous input remains
+ * a ToolInputError; ordinary domain/schema validation still belongs to the registered handler.
+ * @complexity Two bounded schema walks plus the optional domain hook's cost.
+ */
+export async function normalizeToolInput({ input, registration }, _options = {}) {
+    try {
+        return await normalizeWithinGate({ input, registration });
+    }
+    catch (error) {
+        if (error instanceof ToolInputError)
+            throw new ToolInputNormalizationError({ message: error.message });
+        throw error;
+    }
+}
+const isObjectTool = (schema) => object(schema) && schema.type === 'object';
+/** First pass (open), the optional domain hook, then the final closed-schema pass. */
+async function normalizeWithinGate({ input, registration }) {
+    const schema = registration.invocationSchema ?? registration.descriptor.inputSchema;
+    if (isObjectTool(schema) && !object(input))
+        throw new ToolInputError({ message: `${registration.descriptor.id}: send one input object containing the tool's fields.` });
+    const notes = [];
+    let normalized = walkRoot({ input, schema, notes, validateClosed: false, keysOnly: false });
+    if (registration.normalizeInput && object(normalized)) {
+        const result = await registration.normalizeInput({ input: normalized });
+        normalized = result.input;
+        notes.push(...result.notes);
+    }
+    if (isObjectTool(schema) && !object(normalized))
+        throw new ToolInputError({ message: `${registration.descriptor.id}: normalization must produce one input object.` });
+    return { input: walkRoot({ input: normalized, schema, notes, validateClosed: true, keysOnly: false }), notes };
+}
+/** Keep result shapes intact and make rewrite notes visible in plain and MCP tool results. */
+export function withNormalizationNotes({ output, notes }, _options = {}) {
+    if (!notes.length)
+        return output;
+    const text = `normalized: ${notes.join('; ')}`;
+    if (typeof output === 'string')
+        return `${output}\n${text}`;
+    if (object(output))
+        return { ...output, normalizationNotes: notes,
+            ...(Array.isArray(output.content) ? { content: [...output.content, { type: 'text', text }] } : {}) };
+    return { result: output, normalizationNotes: notes };
+}
+//# sourceMappingURL=tool-input-normalization.js.map

package/dist/tool-metadata-types.d.ts

@@ -0,0 +1,26 @@
+/** Domain registrations own these declarations; projections never infer risk or authorization. */
+export interface ToolApprovalMetadata {
+    readonly class: 'read' | 'edit' | 'trash' | 'delete' | 'restore-over-existing' | 'publish' | 'replace-secret' | 'escalation';
+    readonly confirmation: 'direct' | 'policy' | 'plan';
+    readonly input?: 'human-form';
+    /** Host-owned input classification rule, separate from the declared side effects. */
+    readonly rule?: string;
+}
+export interface ToolMetadata<A extends ToolApprovalMetadata = ToolApprovalMetadata> {
+    /** Installed guidance capabilities needed by a writer; independent of permission and risk. */
+    readonly guidanceCapabilities?: readonly string[];
+    readonly search?: {
+        readonly keywords?: string;
+        readonly queries?: readonly string[];
+    };
+    readonly approval?: A;
+    readonly mcpUi?: {
+        readonly redeemable?: boolean;
+        readonly exchangeOnly?: boolean;
+        readonly secretField?: {
+            readonly secret: true;
+        };
+    };
+}
+export type ToolMetadataById<A extends ToolApprovalMetadata = ToolApprovalMetadata> = Readonly<Record<string, ToolMetadata<A>>>;
+//# sourceMappingURL=tool-metadata-types.d.ts.map

package/dist/tool-metadata-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-metadata-types.js.map

package/dist/tool-metadata.d.ts

@@ -1,26 +1,5 @@
-/** Domain registrations own these declarations; projections never infer risk or authorization. */
-export interface ToolApprovalMetadata {
-    readonly class: 'read' | 'edit' | 'trash' | 'delete' | 'restore-over-existing' | 'publish' | 'replace-secret' | 'escalation';
-    readonly confirmation: 'direct' | 'policy' | 'plan';
-    readonly input?: 'human-form';
-    /** Host-owned input classification rule, separate from the declared side effects. */
-    readonly rule?: string;
-}
-export interface ToolMetadata<A extends ToolApprovalMetadata = ToolApprovalMetadata> {
-    readonly search?: {
-        readonly keywords?: string;
-        readonly queries?: readonly string[];
-    };
-    readonly approval?: A;
-    readonly mcpUi?: {
-        readonly redeemable?: boolean;
-        readonly exchangeOnly?: boolean;
-        readonly secretField?: {
-            readonly secret: true;
-        };
-    };
-}
-export type ToolMetadataById<A extends ToolApprovalMetadata = ToolApprovalMetadata> = Readonly<Record<string, ToolMetadata<A>>>;
+import type { ToolApprovalMetadata, ToolMetadata, ToolMetadataById } from './tool-metadata-types.js';
+export type { ToolApprovalMetadata, ToolMetadata, ToolMetadataById } from './tool-metadata-types.js';
 /** Own-property lookup: inherited object keys can never declare a tool's approval or callback access. */
 export declare function toolMetadataFor({ toolId, metadata }: {
     toolId: string;

package/dist/tool-registry.d.ts

@@ -26,7 +26,9 @@
  * `archived provenance ledger` for the 2026-07-29 hardening note.
  */
 import type { Principal } from './principal.js';
-import type { ToolMetadata } from './tool-metadata.js';
+import type { AgentToolSideEffect } from './agent-tools.js';
+import type { ToolMetadata } from './tool-metadata-types.js';
+import { type ToolInputNormalizer } from './tool-input-normalization.js';
 /** A structural run reference — anything with a stable `id` satisfies this (e.g. `@jini-ai/protocol`'s `RunStatus`). No import needed to satisfy it; see the module doc. */
 export interface RunRef {
     readonly id: string;
@@ -42,8 +44,8 @@ export interface ToolDescriptor {
     readonly description?: string;
     /**
      * JSON-Schema-shaped description of this tool's accepted input, carried as `unknown` because the
-     * kernel neither parses nor validates it — a schema dialect is a consumer concern, and taking a
-     * validator dependency here would put one in every package that touches a registry.
+     * gate reads common property/type fields for input normalization but leaves validation and
+     * schema dialects to the handler; no validator dependency belongs in every registry consumer.
      *
      * It exists because *every* discovery mechanism needs it and nothing else in the kernel can
      * supply it: a caller that can enumerate `ToolRegistry.list({})` still cannot tell an agent what
@@ -74,6 +76,8 @@ export interface ToolDescriptor {
      * would admit every unclassified write, which is the exact failure the flag exists to prevent.
      */
     readonly readOnly?: boolean;
+    /** Independently checked domain risk, retained for discovery; never grants permission. */
+    readonly sideEffects?: AgentToolSideEffect;
 }
 /**
  * The single read-only determination: may this tool run through a surface that has promised its
@@ -90,6 +94,17 @@ export interface ToolDescriptor {
 export declare function isReadOnlyTool({ descriptor }: {
     descriptor: ToolDescriptor | undefined;
 }): boolean;
+/** Project registration risk for discovery using the same read-only decision as execution.
+ * Missing classification stays unknown; discovery never grants execution authority.
+ * @returns Explicit readOnly and sideEffects fields for a registry descriptor.
+ * @complexity O(1); no effects.
+ */
+export declare function toolDiscoveryMetadata({ descriptor }: {
+    descriptor: Pick<ToolDescriptor, 'id' | 'readOnly' | 'sideEffects'> | undefined;
+}, _options?: {}): {
+    readOnly: boolean;
+    sideEffects: AgentToolSideEffect | 'unknown';
+};
 /**
  * One human-facing message a handler pushes out mid-call.
  *
@@ -145,27 +160,21 @@ export interface ToolExecutionContext {
 /** Optional handler ports supplied by the invoking transport. */
 export interface ToolExecutionOptions {
     readonly emitSurface?: SurfaceEmitter;
+    /** Invoke through the same executor, retaining this call's principal, run, cancellation and
+     * transport gates. Rejects on denial, failed confirmation, validation or execution failure.
+     * A composition-owned registry may retain a source registration behind a derived catalog card.
+     * Batch wrappers use this port for each final merged input; every supplied registry is gated.
+     */
+    readonly invokeTool?: (required: {
+        toolId: string;
+        input: unknown;
+    }, optional?: {
+        registry?: ToolRegistry;
+    }) => Promise<unknown>;
 }
 /** Runs the tool's actual side effect. Only ever invoked by `ToolExecutor`, never called directly by a route/agent holding the registry. */
 export type ToolHandler = (required: ToolExecutionContext, optional?: ToolExecutionOptions) => Promise<unknown>;
-/**
- * Thrown by a `ToolHandler` (or a validator it calls, e.g. the kernel's `registration-kit.ts`
- * `requireString`/`requireInputRecord`/etc.) to mean "the caller's input was malformed or missing a
- * required field" — a fact about the CALL, not the server. `@jini-ai/daemon`'s `ToolExecutor.execute`
- * tags a handler rejection's `ToolExecutionResult.errorKind` as `'validation'` when the thrown error
- * is `instanceof ToolInputError`, and every HTTP-facing mapping of a `'failed'` execution (today:
- * `@jini-ai/http-kit`'s `delegated-tools.ts`) uses that tag to answer with a 4xx instead of folding
- * it into the same redacted 500 an actual internal/infrastructure failure gets.
- *
- * Deliberately a plain marker with no extra fields: the message itself is already caller-actionable
- * (`withSchemaOnRejection` appends the tool's own input schema to it), so nothing beyond "this IS one
- * of these" needs to survive the `instanceof` check.
- */
-export declare class ToolInputError extends Error {
-    constructor({ message }: {
-        message: string;
-    }, optional?: ErrorOptions);
-}
+export { ToolInputError } from './tool-input-errors.js';
 export type AuthorizationDecision = 'allow' | 'deny';
 export interface ToolAuthorizationContext {
     readonly principal: Principal;
@@ -185,13 +194,18 @@ export interface ToolPolicy {
     authorize(ctx: ToolAuthorizationContext): AuthorizationDecision | Promise<AuthorizationDecision>;
 }
 export interface ToolRegistration {
+    /** Optional execution-only schema, e.g. authenticated form callbacks. Never published by discovery;
+     * the handler must retain callback authentication and authorization. Defaults to descriptor.inputSchema. */
+    readonly invocationSchema?: unknown;
+    /** Domain-owned aliases, read by the single execution gate before validation/authorization. */
+    readonly normalizeInput?: ToolInputNormalizer;
     readonly descriptor: ToolDescriptor;
     readonly handler: ToolHandler;
     readonly policy: ToolPolicy;
 }
 /** The public registration/enumeration surface. See the module doc for why `handler`/`policy` never appear here. */
 export interface ToolRegistry {
-    /** @throws If `registration.descriptor.id` is already registered — re-registration must be explicit (unregister is not exposed; this registry is append-only by design, matching the kernel's "tools are registered once at composition time" model). */
+    /** @throws If the policy has no callable `authorize` or `registration.descriptor.id` is already registered — re-registration must be explicit (unregister is not exposed; this registry is append-only by design, matching the kernel's "tools are registered once at composition time" model). */
     register(registration: ToolRegistration): void;
     has(required: {
         toolId: string;
@@ -242,6 +256,8 @@ export type ToolInvocationAuthorization = {
     readonly descriptor: ToolDescriptor;
     readonly decision: 'allow';
     readonly handler: ToolHandler;
+    readonly input: unknown;
+    readonly normalizationNotes: readonly string[];
 } | {
     readonly descriptor: ToolDescriptor;
     readonly decision: 'deny';