@mxf-dev/core 1.0.0

package/dist/utils/MxpEncryption.js

@@ -0,0 +1,169 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * MXP Encryption Utilities
+ *
+ * Simple encryption/decryption using a shared key from environment variables.
+ * Uses AES-256-GCM for authenticated encryption.
+ */
+import * as crypto from 'crypto';
+import { requireEnv } from './env.js';
+import { MxpEncryptionAlgorithm } from '../schemas/MxpProtocolSchemas.js';
+import { Logger } from './Logger.js';
+const logger = new Logger('info', 'MxpEncryption', 'server');
+/**
+ * MXP Encryption configuration
+ */
+export class MxpEncryption {
+    static instance;
+    encryptionKey = null;
+    isEnabled = false;
+    constructor() {
+        this.initializeFromEnv();
+    }
+    static getInstance() {
+        if (!MxpEncryption.instance) {
+            MxpEncryption.instance = new MxpEncryption();
+        }
+        return MxpEncryption.instance;
+    }
+    /**
+     * Initialize encryption from environment variables
+     */
+    initializeFromEnv() {
+        const keyPhrase = process.env.MXP_ENCRYPTION_KEY;
+        const enableEncryption = process.env.MXP_ENCRYPTION_ENABLED !== 'false'; // Default to true
+        if (keyPhrase) {
+            // Derive a 256-bit key from the passphrase using PBKDF2. Opting
+            // into MXP encryption requires a unique salt — a hardcoded default
+            // would let attackers precompute the key derivation.
+            const salt = requireEnv('MXP_ENCRYPTION_SALT', 'MXP_ENCRYPTION_KEY is set, so a unique salt is required (generate one with `openssl rand -hex 16`).');
+            this.encryptionKey = crypto.pbkdf2Sync(keyPhrase, salt, 100000, 32, 'sha256');
+            this.isEnabled = enableEncryption;
+        }
+        else {
+            logger.warn('MXP_ENCRYPTION_KEY not set - encryption disabled');
+            this.isEnabled = false;
+        }
+    }
+    /**
+     * Check if encryption is enabled
+     */
+    isEncryptionEnabled() {
+        return this.isEnabled && this.encryptionKey !== null;
+    }
+    /**
+     * Encrypt an MXP payload
+     */
+    encrypt(payload) {
+        if (!this.isEncryptionEnabled()) {
+            return null;
+        }
+        try {
+            // Generate a random IV for each encryption
+            const iv = crypto.randomBytes(16);
+            // Create cipher
+            const cipher = crypto.createCipheriv('aes-256-gcm', this.encryptionKey, iv);
+            // Encrypt the payload
+            const payloadString = JSON.stringify(payload);
+            const encrypted = Buffer.concat([
+                cipher.update(payloadString, 'utf8'),
+                cipher.final()
+            ]);
+            // Get the authentication tag
+            const authTag = cipher.getAuthTag();
+            return {
+                algorithm: MxpEncryptionAlgorithm.AES_256_GCM,
+                data: encrypted.toString('base64'),
+                iv: iv.toString('base64'),
+                authTag: authTag.toString('base64')
+            };
+        }
+        catch (error) {
+            logger.error(`Encryption failed: ${error}`);
+            return null;
+        }
+    }
+    /**
+     * Decrypt an encrypted payload
+     */
+    decrypt(encryptedPayload) {
+        if (!this.isEncryptionEnabled()) {
+            logger.error('Cannot decrypt - encryption not configured');
+            return null;
+        }
+        if (encryptedPayload.algorithm !== MxpEncryptionAlgorithm.AES_256_GCM) {
+            logger.error(`Unsupported encryption algorithm: ${encryptedPayload.algorithm}`);
+            return null;
+        }
+        try {
+            // Decode from base64
+            const encrypted = Buffer.from(encryptedPayload.data, 'base64');
+            const iv = Buffer.from(encryptedPayload.iv, 'base64');
+            const authTag = Buffer.from(encryptedPayload.authTag, 'base64');
+            // Create decipher
+            const decipher = crypto.createDecipheriv('aes-256-gcm', this.encryptionKey, iv);
+            decipher.setAuthTag(authTag);
+            // Decrypt
+            const decrypted = Buffer.concat([
+                decipher.update(encrypted),
+                decipher.final()
+            ]);
+            // Parse the JSON payload
+            return JSON.parse(decrypted.toString('utf8'));
+        }
+        catch (error) {
+            logger.error(`Decryption failed: ${error}`);
+            return null;
+        }
+    }
+    /**
+     * Encrypt a full message payload (for convenience)
+     */
+    encryptMessage(payload) {
+        if (!this.isEncryptionEnabled()) {
+            return payload; // Return unencrypted if encryption is disabled
+        }
+        const encrypted = this.encrypt(payload);
+        return encrypted || payload; // Fallback to unencrypted on error
+    }
+    /**
+     * Decrypt a message payload (with type checking)
+     */
+    decryptMessage(payload) {
+        // Check if it's an encrypted payload
+        if ('algorithm' in payload && 'data' in payload && 'iv' in payload) {
+            return this.decrypt(payload);
+        }
+        // It's already decrypted
+        return payload;
+    }
+    /**
+     * Generate a secure random key (utility for initial setup)
+     */
+    static generateSecureKey() {
+        return crypto.randomBytes(32).toString('base64');
+    }
+}
+/**
+ * Singleton instance export
+ */
+export const mxpEncryption = MxpEncryption.getInstance();
+//# sourceMappingURL=MxpEncryption.js.map

package/dist/utils/MxpEncryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MxpEncryption.js","sourceRoot":"","sources":["../../src/utils/MxpEncryption.ts"],"names":[],"mappings":"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"}

package/dist/utils/ParameterNormalizer.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * Maximum number of items that can be collected into an array via _collectToArray
+ * Prevents unbounded memory growth from malicious or malformed LLM output
+ */
+export declare const MAX_COLLECTED_ITEMS = 50;
+/**
+ * Maximum number of properties to process from input
+ * Prevents DoS from extremely large objects
+ */
+export declare const MAX_INPUT_PROPERTIES = 100;
+/**
+ * Parameter name mappings for common LLM variations on ORPAR tools
+ * Maps incorrect/alternative names to the correct schema property names
+ *
+ * Special directives:
+ * - '_remove': Delete this property (not a valid schema field)
+ * - '_extractFirst:fieldName': Extract first element from array to target field
+ * - '_collectToArray:fieldName': Collect numbered properties into target array
+ * - '_stringToArray:fieldName': Convert string value to single-element array
+ */
+export declare const ORPAR_PARAMETER_MAPPINGS: Record<string, Record<string, string>>;
+/**
+ * Allowed properties for each ORPAR tool (from schema definitions)
+ * Unknown properties will be stripped to prevent additionalProperties errors
+ */
+export declare const ORPAR_ALLOWED_PROPERTIES: Record<string, string[]>;
+/**
+ * Coerce string arrays to actual arrays
+ * Handles cases where LLMs pass arrays as strings
+ */
+export declare function coerceToArray(value: any): string[] | undefined;
+/**
+ * Coerce input fields that should be arrays
+ */
+export declare function coerceArrayFields<T extends Record<string, any>>(input: T, arrayFields: string[]): T;
+/**
+ * Normalize parameter names for a specific tool
+ * Maps common LLM parameter variations to the correct schema names
+ *
+ * Handles special directives:
+ * - '_remove': Delete this property (not a valid schema field)
+ * - '_extractFirst:fieldName': Extract first element from array to target field
+ * - '_collectToArray:fieldName': Collect numbered properties into target array
+ * - '_stringToArray:fieldName': Convert string value to single-element array
+ *
+ * @param toolName - The name of the tool being processed
+ * @param input - The input parameters from LLM (may be null, undefined, or malformed)
+ * @returns Normalized parameters object, or empty object if input is invalid
+ */
+export declare function normalizeOrparParameters(toolName: string, input: Record<string, any>): Record<string, any>;
+/**
+ * Strip unknown parameters that are not in the tool's schema
+ * Prevents additionalProperties validation errors from LLM hallucinations
+ *
+ * @param toolName - The name of the tool being processed
+ * @param input - The input parameters (may be null, undefined, or malformed)
+ * @param allowedProperties - Optional list of allowed property names
+ * @returns Filtered object with only allowed properties, or empty object if input invalid
+ */
+export declare function stripUnknownParameters<T extends Record<string, any>>(toolName: string, input: T, allowedProperties?: string[]): T;
+/**
+ * Full normalization pipeline for ORPAR tool parameters
+ * Combines all normalization steps in the correct order
+ */
+export declare function normalizeOrparToolInput<T extends Record<string, any>>(toolName: string, input: T, arrayFields?: string[]): T;
+//# sourceMappingURL=ParameterNormalizer.d.ts.map

package/dist/utils/ParameterNormalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParameterNormalizer.d.ts","sourceRoot":"","sources":["../../src/utils/ParameterNormalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkBH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqE3E,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAM7D,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,EAAE,GAAG,SAAS,CAyC9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,CAanG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqJ1G;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAChE,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,CAAC,EACR,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAC7B,CAAC,CAwBH;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjE,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,CAAC,EACR,WAAW,CAAC,EAAE,MAAM,EAAE,GACvB,CAAC,CAaH"}

package/dist/utils/ParameterNormalizer.js

@@ -0,0 +1,409 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * Shared Parameter Normalizer for ORPAR Tools
+ *
+ * This utility normalizes LLM parameter outputs to match expected schema formats.
+ * LLMs (especially faster models like Haiku) often output parameters with:
+ * - Wrong names (reasoning vs analysis)
+ * - Wrong types (string vs array)
+ * - Extra fields not in schema
+ *
+ * This normalizer handles all these cases to improve tool execution reliability.
+ */
+import { Logger } from './Logger.js';
+const logger = new Logger('debug', 'ParameterNormalizer', 'server');
+/**
+ * Maximum number of items that can be collected into an array via _collectToArray
+ * Prevents unbounded memory growth from malicious or malformed LLM output
+ */
+export const MAX_COLLECTED_ITEMS = 50;
+/**
+ * Maximum number of properties to process from input
+ * Prevents DoS from extremely large objects
+ */
+export const MAX_INPUT_PROPERTIES = 100;
+/**
+ * Parameter name mappings for common LLM variations on ORPAR tools
+ * Maps incorrect/alternative names to the correct schema property names
+ *
+ * Special directives:
+ * - '_remove': Delete this property (not a valid schema field)
+ * - '_extractFirst:fieldName': Extract first element from array to target field
+ * - '_collectToArray:fieldName': Collect numbered properties into target array
+ * - '_stringToArray:fieldName': Convert string value to single-element array
+ */
+export const ORPAR_PARAMETER_MAPPINGS = {
+    orpar_observe: {
+        'observation': 'observations', // Singular vs plural
+        'facts': 'keyFacts',
+        'key_facts': 'keyFacts',
+        // Handle numbered keyFact properties - LLMs output keyFact1, keyFact2 instead of array
+        'keyFact1': '_collectToArray:keyFacts',
+        'keyFact2': '_collectToArray:keyFacts',
+        'keyFact3': '_collectToArray:keyFacts',
+        'keyFact4': '_collectToArray:keyFacts',
+        'keyFact5': '_collectToArray:keyFacts',
+        'keyFact6': '_collectToArray:keyFacts',
+        'keyFact7': '_collectToArray:keyFacts',
+        'keyFact8': '_collectToArray:keyFacts',
+        'keyFact9': '_collectToArray:keyFacts',
+        'keyFact10': '_collectToArray:keyFacts',
+        'confidence': '_remove', // Not a valid field
+    },
+    orpar_reason: {
+        'reasoning': 'analysis', // Common LLM mistake
+        'thinking': 'analysis',
+        'thought': 'analysis',
+        'patterns': 'conclusions',
+        'hypothesis': 'conclusions',
+        'keyFindings': '_stringToArray:conclusions', // Map findings to conclusions
+        'nextStep': 'alternatives',
+        'nextAction': '_remove', // Not a valid field - remove it
+        'nextSteps': '_remove', // Not valid in reason phase
+        'strategy': '_remove', // Not valid in reason phase
+    },
+    orpar_plan: {
+        'strategy': 'plan', // Common synonym
+        'approach': 'plan',
+        'planning': 'plan', // Semantic confusion
+        'nextSteps': 'actions', // Common LLM mistake
+        'steps': 'actions',
+        'questionSequence': 'actions',
+        'nextActions': 'actions',
+        'planDescription': '_remove', // Not valid - remove
+        'immediateNextStep': '_remove', // Not valid - remove
+        'confidence': '_remove', // Not a valid field
+        'keyDecisions': '_remove', // Not valid - remove
+        'readinessCheck': '_remove', // Not valid - remove
+        'description': '_remove', // Not valid - plan already has description
+    },
+    orpar_act: {
+        'toolsUsed': 'toolUsed', // Plural vs singular
+        'tool': 'toolUsed',
+        'executionDetails': 'outcome',
+        'result': 'outcome',
+        'expectedOutcome': 'outcome',
+        'rationale': 'outcome',
+        'actions': '_extractFirst:action', // Array → first element string
+        'confidence': '_remove', // Not a valid field
+    },
+    orpar_reflect: {
+        'reflections': 'reflection', // Plural vs singular
+        'insights': 'learnings',
+        'lessons': 'learnings',
+        'key_learnings': 'learnings',
+        'lessonsLearned': 'learnings', // Common LLM variation
+        'whatLearned': '_stringToArray:learnings', // String to array conversion
+        'keyInsights': '_stringToArray:learnings', // Map insights to learnings array
+        'readinessForNextPhase': '_remove', // Not valid - remove
+        'nextSteps': 'adjustments', // Map to correct field
+        'confidence': '_remove', // Not a valid field
+        'deductions': '_remove', // Not valid - remove
+        'readiness': '_remove', // Not valid - remove
+    }
+};
+/**
+ * Allowed properties for each ORPAR tool (from schema definitions)
+ * Unknown properties will be stripped to prevent additionalProperties errors
+ */
+export const ORPAR_ALLOWED_PROPERTIES = {
+    orpar_observe: ['observations', 'keyFacts', 'context'],
+    orpar_reason: ['analysis', 'conclusions', 'confidence', 'alternatives'],
+    orpar_plan: ['plan', 'actions', 'rationale', 'contingency'],
+    orpar_act: ['action', 'toolUsed', 'outcome', 'success'],
+    orpar_reflect: ['reflection', 'learnings', 'expectationsMet', 'adjustments'],
+};
+/**
+ * Coerce string arrays to actual arrays
+ * Handles cases where LLMs pass arrays as strings
+ */
+export function coerceToArray(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        // Try to parse as JSON array
+        if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (Array.isArray(parsed)) {
+                    return parsed;
+                }
+            }
+            catch {
+                // Not valid JSON, try other formats
+            }
+        }
+        // Handle XML-style items: <item>text</item>
+        const xmlMatches = trimmed.match(/<item>(.*?)<\/item>/g);
+        if (xmlMatches) {
+            return xmlMatches.map(m => m.replace(/<\/?item>/g, '').trim());
+        }
+        // Handle newline-separated items
+        if (trimmed.includes('\n') || trimmed.includes('<item>')) {
+            const lines = trimmed
+                .split(/\n|<item>|<\/item>/)
+                .map(l => l.trim())
+                .filter(l => l.length > 0 && !l.startsWith('<'));
+            if (lines.length > 0) {
+                return lines;
+            }
+        }
+        // Single string - return as single-element array
+        if (trimmed.length > 0) {
+            return [trimmed];
+        }
+    }
+    return undefined;
+}
+/**
+ * Coerce input fields that should be arrays
+ */
+export function coerceArrayFields(input, arrayFields) {
+    const coerced = { ...input };
+    for (const field of arrayFields) {
+        if (field in coerced) {
+            const coercedValue = coerceToArray(coerced[field]);
+            if (coercedValue !== undefined) {
+                coerced[field] = coercedValue;
+            }
+            else {
+                delete coerced[field];
+            }
+        }
+    }
+    return coerced;
+}
+/**
+ * Normalize parameter names for a specific tool
+ * Maps common LLM parameter variations to the correct schema names
+ *
+ * Handles special directives:
+ * - '_remove': Delete this property (not a valid schema field)
+ * - '_extractFirst:fieldName': Extract first element from array to target field
+ * - '_collectToArray:fieldName': Collect numbered properties into target array
+ * - '_stringToArray:fieldName': Convert string value to single-element array
+ *
+ * @param toolName - The name of the tool being processed
+ * @param input - The input parameters from LLM (may be null, undefined, or malformed)
+ * @returns Normalized parameters object, or empty object if input is invalid
+ */
+export function normalizeOrparParameters(toolName, input) {
+    // CRITICAL: Validate input before processing untrusted LLM output
+    // Input could be null, undefined, or not an object
+    if (input === null || input === undefined) {
+        logger.debug(`[ParameterNormalizer] Input is ${input} for ${toolName}, returning empty object`);
+        return {};
+    }
+    if (typeof input !== 'object' || Array.isArray(input)) {
+        logger.debug(`[ParameterNormalizer] Input is not an object for ${toolName} (type: ${typeof input}), returning empty object`);
+        return {};
+    }
+    // Limit number of properties to prevent DoS
+    const inputKeys = Object.keys(input);
+    if (inputKeys.length > MAX_INPUT_PROPERTIES) {
+        logger.warn(`[ParameterNormalizer] Input has ${inputKeys.length} properties (max: ${MAX_INPUT_PROPERTIES}), truncating`);
+    }
+    const mappings = ORPAR_PARAMETER_MAPPINGS[toolName];
+    if (!mappings)
+        return input;
+    const normalized = { ...input };
+    const collectArrays = {}; // For _collectToArray
+    for (const [wrongName, directive] of Object.entries(mappings)) {
+        if (!(wrongName in normalized))
+            continue;
+        if (directive === '_remove') {
+            // Remove invalid property that doesn't map to any schema field
+            delete normalized[wrongName];
+            logger.debug(`[ParameterNormalizer] Removed invalid param from ${toolName}: ${wrongName}`);
+        }
+        else if (directive.startsWith('_collectToArray:')) {
+            // Collect numbered properties into target array (e.g., keyFact1, keyFact2 -> keyFacts[])
+            const targetField = directive.split(':')[1];
+            if (!collectArrays[targetField]) {
+                collectArrays[targetField] = [];
+            }
+            // Enforce MAX_COLLECTED_ITEMS limit to prevent unbounded memory growth
+            if (collectArrays[targetField].length >= MAX_COLLECTED_ITEMS) {
+                logger.warn(`[ParameterNormalizer] Skipping ${wrongName} - ${targetField} array reached max size (${MAX_COLLECTED_ITEMS})`);
+                delete normalized[wrongName];
+                continue;
+            }
+            const value = normalized[wrongName];
+            // Clean up any XML-like syntax that may have bled through
+            const cleanValue = typeof value === 'string'
+                ? value.replace(/<[^>]*>/g, '').trim()
+                : value;
+            if (cleanValue) {
+                collectArrays[targetField].push(cleanValue);
+            }
+            delete normalized[wrongName];
+        }
+        else if (directive.startsWith('_stringToArray:')) {
+            // Convert string to single-element array (e.g., whatLearned: "X" -> learnings: ["X"])
+            const targetField = directive.split(':')[1];
+            const value = normalized[wrongName];
+            if (typeof value === 'string' && value.trim()) {
+                if (!normalized[targetField]) {
+                    normalized[targetField] = [value];
+                }
+                else if (Array.isArray(normalized[targetField])) {
+                    normalized[targetField].push(value);
+                }
+            }
+            delete normalized[wrongName];
+        }
+        else if (directive.startsWith('_extractFirst:')) {
+            // Extract first element from array to target field
+            const targetField = directive.split(':')[1];
+            const value = normalized[wrongName];
+            if (Array.isArray(value) && value.length > 0) {
+                // If first element is object with target key, use that value
+                const first = value[0];
+                normalized[targetField] = typeof first === 'object' && first[targetField]
+                    ? first[targetField]
+                    : typeof first === 'object' && first.action
+                        ? first.action
+                        : String(first);
+            }
+            else if (typeof value === 'string') {
+                // Try to parse JSON string array
+                try {
+                    const parsed = JSON.parse(value);
+                    if (Array.isArray(parsed) && parsed.length > 0) {
+                        const first = parsed[0];
+                        normalized[targetField] = typeof first === 'object' && first[targetField]
+                            ? first[targetField]
+                            : typeof first === 'object' && first.action
+                                ? first.action
+                                : String(first);
+                    }
+                }
+                catch {
+                    // Not valid JSON - use as-is if target doesn't exist
+                    if (!(targetField in normalized)) {
+                        normalized[targetField] = value;
+                    }
+                }
+            }
+            delete normalized[wrongName];
+        }
+        else if (!(directive in normalized)) {
+            // Standard mapping - move value to correct name
+            normalized[directive] = normalized[wrongName];
+            delete normalized[wrongName];
+            logger.debug(`[ParameterNormalizer] Mapped ${wrongName} → ${directive} for ${toolName}`);
+        }
+        else {
+            // Both exist - just remove the wrong one to avoid additionalProperties error
+            delete normalized[wrongName];
+        }
+    }
+    // Merge collected arrays into normalized object with size limits
+    for (const [field, values] of Object.entries(collectArrays)) {
+        if (values.length > 0) {
+            if (normalized[field] && Array.isArray(normalized[field])) {
+                // Append to existing array, respecting MAX_COLLECTED_ITEMS
+                const combined = [...normalized[field], ...values];
+                normalized[field] = combined.slice(0, MAX_COLLECTED_ITEMS);
+                if (combined.length > MAX_COLLECTED_ITEMS) {
+                    logger.warn(`[ParameterNormalizer] Truncated ${field} array to ${MAX_COLLECTED_ITEMS} items`);
+                }
+            }
+            else {
+                // Create new array, respecting MAX_COLLECTED_ITEMS
+                normalized[field] = values.slice(0, MAX_COLLECTED_ITEMS);
+            }
+        }
+    }
+    // Handle confidence field coercion (LLMs often send strings like "100%" or "high")
+    if ('confidence' in normalized && typeof normalized['confidence'] === 'string') {
+        const confStr = normalized['confidence'];
+        // Try to extract a number from the string
+        const percentMatch = confStr.match(/(\d+(?:\.\d+)?)\s*%/);
+        const decimalMatch = confStr.match(/^(\d+(?:\.\d+)?)/);
+        if (percentMatch) {
+            // Convert percentage to 0-1 scale
+            normalized['confidence'] = Math.min(1, parseFloat(percentMatch[1]) / 100);
+        }
+        else if (decimalMatch) {
+            const val = parseFloat(decimalMatch[1]);
+            // If value > 1, assume it's a percentage
+            normalized['confidence'] = val > 1 ? Math.min(1, val / 100) : val;
+        }
+        else {
+            // Can't parse - remove the invalid confidence value
+            delete normalized['confidence'];
+        }
+    }
+    return normalized;
+}
+/**
+ * Strip unknown parameters that are not in the tool's schema
+ * Prevents additionalProperties validation errors from LLM hallucinations
+ *
+ * @param toolName - The name of the tool being processed
+ * @param input - The input parameters (may be null, undefined, or malformed)
+ * @param allowedProperties - Optional list of allowed property names
+ * @returns Filtered object with only allowed properties, or empty object if input invalid
+ */
+export function stripUnknownParameters(toolName, input, allowedProperties) {
+    // Validate input before processing
+    if (input === null || input === undefined) {
+        return {};
+    }
+    if (typeof input !== 'object' || Array.isArray(input)) {
+        return {};
+    }
+    const properties = allowedProperties || ORPAR_ALLOWED_PROPERTIES[toolName];
+    if (!properties)
+        return input;
+    const stripped = {};
+    for (const key of Object.keys(input)) {
+        if (properties.includes(key)) {
+            stripped[key] = input[key];
+        }
+        else {
+            logger.debug(`[ParameterNormalizer] Stripped unknown param from ${toolName}: ${key}`);
+        }
+    }
+    return stripped;
+}
+/**
+ * Full normalization pipeline for ORPAR tool parameters
+ * Combines all normalization steps in the correct order
+ */
+export function normalizeOrparToolInput(toolName, input, arrayFields) {
+    // Step 1: Normalize parameter names
+    let result = normalizeOrparParameters(toolName, input);
+    // Step 2: Coerce array fields if specified
+    if (arrayFields && arrayFields.length > 0) {
+        result = coerceArrayFields(result, arrayFields);
+    }
+    // Step 3: Strip unknown parameters
+    result = stripUnknownParameters(toolName, result);
+    return result;
+}
+//# sourceMappingURL=ParameterNormalizer.js.map