@jini-ai/core 0.4.7 → 0.4.9

package/dist/text/sanitize-untrusted-text.js

@@ -1,4 +1,4 @@
-import { LABELED_SECRET_RE, OPAQUE_TOKEN_RE, NON_SECRET_TOKEN_RE } from "../redact.js";
+import { redactSecrets, LABELED_SECRET_RE, OPAQUE_TOKEN_RE, NON_SECRET_TOKEN_RE } from "../redact.js";
 /**
  * @module redact
  *
@@ -39,6 +39,38 @@ function isOtherControlCode(code) {
         return true; // C1 controls
     return false;
 }
+/** True when position `j` starts an OSC terminator: BEL, or ST (`ESC \\`). */
+function isOscTerminatorAt(text, j) {
+    const code = text.charCodeAt(j);
+    return code === BEL || (code === ESC && text.charCodeAt(j + 1) === BACKSLASH);
+}
+/** Index of a CSI's final byte at or after `from`, or `text.length` when the CSI is truncated. */
+function csiEnd(text, from) {
+    let j = from;
+    while (j < text.length && !isCsiFinalByte(text.charCodeAt(j)))
+        j++;
+    return j;
+}
+/** Index of the last code unit of an OSC body starting at `from`: the BEL, the `\\` of ST, or the
+ * final code unit when the OSC is never terminated. */
+function oscEnd(text, from) {
+    let j = from;
+    while (j < text.length && !isOscTerminatorAt(text, j))
+        j++;
+    // charCodeAt past the end is NaN, so a truncated OSC never matches BEL here.
+    if (text.charCodeAt(j) === BEL)
+        return j;
+    return Math.min(j + 1, text.length - 1);
+}
+/** Index of the last code unit consumed by the escape sequence whose ESC sits at `start`. */
+function escapeSequenceEnd(text, start) {
+    const next = text.charCodeAt(start + 1);
+    if (next === CSI_OPEN)
+        return csiEnd(text, start + 2);
+    if (next === OSC_OPEN)
+        return oscEnd(text, start + 2);
+    return start; // bare ESC (or an unrecognized ESC-prefixed byte): drop just the ESC byte
+}
 /**
  * Strip ANSI/terminal escape sequences (CSI `ESC [ ... final-byte`, OSC `ESC ] ... BEL-or-ST`,
  * and bare ESC-prefixed bytes) plus other C0/C1 control characters from `text`. Written as an
@@ -50,53 +82,41 @@ export function stripControlSequences({ text }) {
     for (let i = 0; i < text.length; i++) {
         const code = text.charCodeAt(i);
         if (code === ESC) {
-            const next = text.charCodeAt(i + 1);
-            if (next === CSI_OPEN) {
-                let j = i + 2;
-                while (j < text.length && !isCsiFinalByte(text.charCodeAt(j)))
-                    j++;
-                i = j; // land on the final byte; the outer loop's i++ steps past it
-                continue;
-            }
-            if (next === OSC_OPEN) {
-                let j = i + 2;
-                while (j < text.length &&
-                    text.charCodeAt(j) !== BEL &&
-                    !(text.charCodeAt(j) === ESC && text.charCodeAt(j + 1) === BACKSLASH)) {
-                    j++;
-                }
-                if (j < text.length && text.charCodeAt(j) === BEL)
-                    i = j;
-                else
-                    i = Math.min(j + 1, text.length - 1);
-                continue;
-            }
-            continue; // bare ESC (or an unrecognized ESC-prefixed byte): drop just the ESC byte
-        }
-        if (isOtherControlCode(code))
+            i = escapeSequenceEnd(text, i); // land on the last consumed byte; the loop's i++ steps past it
             continue;
-        out += text[i];
+        }
+        if (!isOtherControlCode(code))
+            out += text[i];
     }
     return out;
 }
-// A labeled credential (`Authorization: ...`, `api-key=...`) has everything after the label
-// redacted. A bare run of 20+ base64url/hex-alphabet characters is treated as a possible
-// opaque token/secret and redacted outright, even with no label.
-/** Redact labeled credentials and long opaque-token-looking substrings from `text`. */
-function redactSecretLike({ text }) {
-    return text
-        .replace(LABELED_SECRET_RE, (match) => match.replace(/\S+$/, '[redacted]'))
-        .replace(OPAQUE_TOKEN_RE, (match) => (NON_SECRET_TOKEN_RE.test(match) ? match : '[redacted]'));
+/** Exact diagnostic vocabulary only: unknown spellings and glued suffixes remain opaque. */
+const DIAGNOSTIC_TOKENS = new Set([
+    'additionalProperties', 'additionalItems', 'unevaluatedProperties', 'unevaluatedItems',
+    'dependentRequired', 'dependentSchemas', 'exclusiveMinimum', 'exclusiveMaximum',
+    'minContains', 'maxContains', 'patternProperties', 'propertyNames', 'prefixItems',
+    'contentEncoding', 'contentMediaType', 'contentSchema',
+]);
+/** Mask credentials before preserving complete trusted IDs and UPPER_SNAKE diagnostics; redact opaque spans elsewhere. */
+function redactSecretLike({ text, diagnosticToolIds }) {
+    return redactSecrets({ input: text }, { redactPii: false })
+        .replace(LABELED_SECRET_RE, match => match.replace(/([:=]\s*)\S+$/, '$1[redacted]'))
+        .replace(/\[REDACTED:[^\]\r\n]+\]/g, '[redacted]')
+        // Trust whole dotted IDs so their components cannot become a general redaction bypass.
+        .replace(/[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*/g, token => diagnosticToolIds.has(token) ? token
+        : token.replace(OPAQUE_TOKEN_RE, match => NON_SECRET_TOKEN_RE.test(match) || DIAGNOSTIC_TOKENS.has(match) ? match : '[redacted]'));
 }
 /**
  * Strip terminal control sequences, redact anything that looks like a secret, and cap the
  * length of `text` — the one function every boundary that surfaces daemon/network-derived text
  * to stderr/stdout should route through first.
+ * Trusted diagnosticToolIds exempt complete IDs (including dots) only, after credential masking.
+ * @complexity O(n + t) local time/space for n text bytes and t trusted ID bytes.
  */
 export function sanitizeUntrustedText({ text }, options = {}) {
     const requestedLength = options.maxLength ?? DEFAULT_MAX_EXCERPT_LENGTH;
     const maxLength = Number.isFinite(requestedLength) ? Math.max(0, Math.floor(requestedLength)) : DEFAULT_MAX_EXCERPT_LENGTH;
-    const sanitized = redactSecretLike({ text: stripControlSequences({ text }) });
+    const sanitized = redactSecretLike({ text: stripControlSequences({ text }), diagnosticToolIds: new Set(options.diagnosticToolIds) });
     if (sanitized.length <= maxLength)
         return sanitized;
     // The marker is part of the output budget, including when the budget cannot fit the full marker.

package/dist/tool-exposure.d.ts

@@ -0,0 +1,79 @@
+/** Descriptor-only projections. Execution and current authorization remain with ToolExecutor. */
+import type { ToolDescriptor, ToolRegistry } from './tool-registry.js';
+export interface ToolNameMap {
+    wireNameFor(required: {
+        toolId: string;
+    }, optional?: Record<string, never>): string | undefined;
+    toolIdFor(required: {
+        wireName: string;
+    }, optional?: Record<string, never>): string | undefined;
+}
+/**
+ * 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 declare function createToolNameMap({ toolIds }: {
+    toolIds: readonly string[];
+}, { reservedNames }?: {
+    reservedNames?: readonly string[];
+}): ToolNameMap;
+export interface ExposedToolDescriptor {
+    readonly wireName: string;
+    readonly descriptor: ToolDescriptor;
+}
+export interface ToolExposureSnapshot {
+    readonly revision: number;
+    readonly tools: readonly ExposedToolDescriptor[];
+    /** UTF-8 bytes of JSON-serialized input schemas, excluding absent schemas. */
+    readonly schemaBytes: number;
+}
+export interface ToolExposureSkipped {
+    readonly toolId: string;
+    readonly reason: 'not-found' | 'tool-limit' | 'schema-byte-limit';
+}
+export interface ToolExposurePromotion {
+    readonly snapshot: ToolExposureSnapshot;
+    readonly added: readonly string[];
+    readonly skipped: readonly ToolExposureSkipped[];
+}
+export interface ToolExposure {
+    /** Synchronous and idempotent; successful promotions are never evicted within this scope. */
+    promote(required: {
+        toolIds: readonly string[];
+    }, optional?: Record<string, never>): ToolExposurePromotion;
+    getSnapshot(required: Record<string, never>, optional?: Record<string, never>): ToolExposureSnapshot;
+    /** Resolves published names only. Callers must still invoke the authoritative executor. */
+    resolveToolId(required: {
+        wireName: string;
+    }, optional?: Record<string, never>): string | undefined;
+}
+export declare class ToolExposureError extends Error {
+    readonly code: 'invalid-limit' | 'invalid-descriptor';
+    constructor({ code }: {
+        code: 'invalid-limit' | 'invalid-descriptor';
+    }, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare function createToolExposure({ registry }: {
+    registry: Pick<ToolRegistry, 'list'>;
+}, { maxTools, maxSchemaBytes, reservedNames }?: {
+    maxTools?: number;
+    maxSchemaBytes?: number;
+    reservedNames?: readonly string[];
+}): ToolExposure;
+//# sourceMappingURL=tool-exposure.d.ts.map

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