kagent-ts 0.1.3 → 0.1.5

package/dist/tools/tool-output-truncator.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolOutputTruncator = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Truncator for tool outputs that exceed a byte threshold.
+ *
+ * When a tool returns a very large result it fills the context window
+ * and wastes tokens. This component saves the full result to disk and
+ * returns a short preview + a file path, so the LLM can decide whether
+ * to read the full content via the normal file-reading tools.
+ */
+class ToolOutputTruncator {
+    maxBytes;
+    keepBytes;
+    outputDir;
+    /**
+     * @param maxBytes   Outputs larger than this are truncated (0 = off).
+     * @param keepBytes  How many bytes to keep from the start of the output
+     *                   when truncating.
+     * @param outputDir  Directory where full outputs are saved.
+     */
+    constructor(maxBytes = 0, keepBytes = 2048, outputDir) {
+        this.maxBytes = maxBytes;
+        this.keepBytes = keepBytes;
+        this.outputDir = path.resolve(outputDir ?? ".kagent-tool-outputs");
+    }
+    /**
+     * Whether truncation is active (maxBytes > 0).
+     */
+    get enabled() {
+        return this.maxBytes > 0;
+    }
+    /**
+     * Truncate a tool result string if it exceeds the configured threshold.
+     *
+     * - If the result is within `maxBytes`, returns it unchanged.
+     * - Otherwise saves the full output to disk and returns the first
+     *   `keepBytes` bytes + a marker pointing to the saved file.
+     *
+     * @param toolName  Name of the tool that produced this result.
+     * @param result    The raw result string from tool execution.
+     */
+    truncate(toolName, result) {
+        if (!this.enabled)
+            return result;
+        const byteLength = Buffer.byteLength(result, "utf-8");
+        if (byteLength <= this.maxBytes)
+            return result;
+        // Ensure output directory exists
+        fs.mkdirSync(this.outputDir, { recursive: true });
+        // Generate a unique filename: toolname_<timestamp>_<hash>.txt
+        const now = Date.now();
+        const hash = djb2(toolName + now + result.slice(0, 128));
+        const filename = `${sanitizeFilename(toolName)}_${now}_${hash}.txt`;
+        const filePath = path.join(this.outputDir, filename);
+        fs.writeFileSync(filePath, result, "utf-8");
+        const preview = result.slice(0, this.keepBytes);
+        const truncatedSize = byteLength - this.keepBytes;
+        const marker = `\n\n---\n` +
+            `[Output truncated: ${(byteLength / 1024).toFixed(1)} KB total | ` +
+            `showing first ${(this.keepBytes / 1024).toFixed(1)} KB | ` +
+            `${truncatedSize} bytes truncated.]\n` +
+            `[Full output saved to: ${filePath}]\n` +
+            `[Use the read_file tool with file_path="${filePath}" to read the complete output.]`;
+        return preview + marker;
+    }
+}
+exports.ToolOutputTruncator = ToolOutputTruncator;
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/** Simple djb2 hash (non-crypto, for filename dedup). */
+function djb2(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) + hash + str.charCodeAt(i)) & 0xffffffff;
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/** Replace non-filename-safe characters. */
+function sanitizeFilename(name) {
+    return name.replace(/[^a-zA-Z0-9_\-.]/g, "_");
+}
+//# sourceMappingURL=tool-output-truncator.js.map

package/dist/tools/tool-output-truncator.js.map

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

package/dist/tools/tool-registry.d.ts

@@ -1,5 +1,7 @@
-import { Tool, BreakerStatus } from "./types";
+import { Tool, ToolResult, BreakerStatus } from "./types";
 import { ToolErrorTracker } from "./error-tracker";
+import { ToolOutputTruncator } from "./tool-output-truncator";
+import { ToolFilter } from "./tool-filter";
 /**
  * Registry that manages tool definitions together with circuit breakers.
  *
@@ -13,12 +15,15 @@ export declare class ToolRegistry {
     private breakers;
     private retryCount;
     private errorTracker?;
+    private truncator;
     /**
      * @param retryCount Number of retries allowed after the first failure
      *                    (default: 2 → 3 total attempts before circuit opens).
      * @param errorTracker Optional ToolErrorTracker for recording failure chains.
+     * @param truncator   Optional ToolOutputTruncator for truncating large
+     *                    tool outputs (default: enabled with default limits).
      */
-    constructor(retryCount?: number, errorTracker?: ToolErrorTracker);
+    constructor(retryCount?: number, errorTracker?: ToolErrorTracker, truncator?: ToolOutputTruncator);
     /**
      * Register a tool. Creates a circuit breaker for it automatically.
      */
@@ -51,18 +56,29 @@ export declare class ToolRegistry {
      * Get all registered tool names.
      */
     get toolNames(): string[];
+    /**
+     * Create a new ToolRegistry containing only tools that pass the given
+     * filter. Circuit breaker state is NOT copied — each filtered registry
+     * starts fresh (appropriate for sub-agents).
+     *
+     * @param filter The filter to apply.
+     * @returns A new ToolRegistry with the filtered tool set.
+     */
+    filter(filter: ToolFilter): ToolRegistry;
     /**
      * Execute a tool with circuit-breaker protection and retry guidance.
      *
-     * - If the circuit is OPEN, returns an error message with a recommendation
-     *   to try a different approach.
-     * - If execution fails and retries remain, returns a message telling the LLM
-     *   to analyze the error and retry with corrected parameters.
-     * - If execution succeeds, records a success (resets failure count).
+     * Returns a structured {@link ToolResult} with a machine-readable
+     * {@link ToolErrorCode} so callers can react precisely.
      *
-     * @returns The tool's result string, or an error message with retry guidance.
+     * Possible error codes:
+     * - `SUCCESS`            — tool completed normally.
+     * - `UNKNOWN_TOOL`       — tool name not registered.
+     * - `CIRCUIT_OPEN`       — tool is disabled (too many failures).
+     * - `EXECUTION_FAILURE`  — tool threw an exception; retries may remain.
+     * - `TRUNCATED_OUTPUT`   — tool output was truncated.
      */
-    execute(name: string, args: Record<string, unknown>): Promise<string>;
+    execute(name: string, args: Record<string, unknown>): Promise<ToolResult>;
     /**
      * Get the error tracker instance, if one is configured.
      */

package/dist/tools/tool-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/tools/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAC,CAAmB;IAExC;;;;OAIG;gBACS,UAAU,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,gBAAgB;IAKhE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAc1B;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAMjC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIvC;;OAEG;IACH,QAAQ,IAAI,IAAI,EAAE;IAIlB;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAK7B;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;IAID;;;;;;;;;;OAUG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IA6E3E;;OAEG;IACH,eAAe,IAAI,gBAAgB,GAAG,SAAS;IAI/C;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIzD;;OAEG;IACH,qBAAqB,IAAI,aAAa,EAAE;IAIxC;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIhC;;OAEG;IACH,gBAAgB,IAAI,IAAI;CAKzB"}
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/tools/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAyC,aAAa,EAAE,MAAM,SAAS,CAAC;AAEjG,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAC,CAAmB;IACxC,OAAO,CAAC,SAAS,CAAsB;IAEvC;;;;;;OAMG;gBAED,UAAU,CAAC,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,gBAAgB,EAC/B,SAAS,CAAC,EAAE,mBAAmB;IAOjC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAc1B;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAMjC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIvC;;OAEG;IACH,QAAQ,IAAI,IAAI,EAAE;IAIlB;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAK7B;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;IAID;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY;IAgBxC;;;;;;;;;;;;OAYG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IA+G/E;;OAEG;IACH,eAAe,IAAI,gBAAgB,GAAG,SAAS;IAI/C;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIzD;;OAEG;IACH,qBAAqB,IAAI,aAAa,EAAE;IAIxC;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIhC;;OAEG;IACH,gBAAgB,IAAI,IAAI;CAKzB"}

package/dist/tools/tool-registry.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolRegistry = void 0;
+const types_1 = require("./types");
 const circuit_breaker_1 = require("./circuit-breaker");
+const tool_output_truncator_1 = require("./tool-output-truncator");
 /**
  * Registry that manages tool definitions together with circuit breakers.
  *
@@ -15,14 +17,18 @@ class ToolRegistry {
     breakers = new Map();
     retryCount;
     errorTracker;
+    truncator;
     /**
      * @param retryCount Number of retries allowed after the first failure
      *                    (default: 2 → 3 total attempts before circuit opens).
      * @param errorTracker Optional ToolErrorTracker for recording failure chains.
+     * @param truncator   Optional ToolOutputTruncator for truncating large
+     *                    tool outputs (default: enabled with default limits).
      */
-    constructor(retryCount, errorTracker) {
+    constructor(retryCount, errorTracker, truncator) {
         this.retryCount = retryCount ?? 2;
         this.errorTracker = errorTracker;
+        this.truncator = truncator ?? new tool_output_truncator_1.ToolOutputTruncator();
     }
     /**
      * Register a tool. Creates a circuit breaker for it automatically.
@@ -82,73 +88,116 @@ class ToolRegistry {
     get toolNames() {
         return Array.from(this.tools.keys());
     }
+    // ─── Tool Filter ───────────────────────────────────────────────────────
+    /**
+     * Create a new ToolRegistry containing only tools that pass the given
+     * filter. Circuit breaker state is NOT copied — each filtered registry
+     * starts fresh (appropriate for sub-agents).
+     *
+     * @param filter The filter to apply.
+     * @returns A new ToolRegistry with the filtered tool set.
+     */
+    filter(filter) {
+        const registry = new ToolRegistry(this.retryCount, this.errorTracker, this.truncator);
+        for (const tool of this.tools.values()) {
+            if (filter.filter(tool)) {
+                registry.register(tool);
+            }
+        }
+        return registry;
+    }
     // ─── Circuit Breaker ───────────────────────────────────────────────────
     /**
      * Execute a tool with circuit-breaker protection and retry guidance.
      *
-     * - If the circuit is OPEN, returns an error message with a recommendation
-     *   to try a different approach.
-     * - If execution fails and retries remain, returns a message telling the LLM
-     *   to analyze the error and retry with corrected parameters.
-     * - If execution succeeds, records a success (resets failure count).
+     * Returns a structured {@link ToolResult} with a machine-readable
+     * {@link ToolErrorCode} so callers can react precisely.
      *
-     * @returns The tool's result string, or an error message with retry guidance.
+     * Possible error codes:
+     * - `SUCCESS`            — tool completed normally.
+     * - `UNKNOWN_TOOL`       — tool name not registered.
+     * - `CIRCUIT_OPEN`       — tool is disabled (too many failures).
+     * - `EXECUTION_FAILURE`  — tool threw an exception; retries may remain.
+     * - `TRUNCATED_OUTPUT`   — tool output was truncated.
      */
     async execute(name, args) {
         const tool = this.tools.get(name);
         if (!tool) {
-            return (`Error: Unknown tool "${name}". Available tools: ${this.toolNames.join(", ")}. ` +
-                `Please check the tool name and try again.`);
+            return (0, types_1.toolError)(types_1.ToolErrorCode.UNKNOWN_TOOL, `[FATAL:UNKNOWN_TOOL] The tool "${name}" is not registered. ` +
+                `Available tools: ${this.toolNames.join(", ")}. ` +
+                `Please use one of the available tools instead.`, "fatal");
         }
         const breaker = this.breakers.get(name);
         // Circuit breaker check — circuit is OPEN
         if (!breaker.isAvailable) {
             const status = breaker.getStatus();
-            return (`Error: Tool "${name}" has been automatically disabled after ${status.failureCount} consecutive failures. ` +
+            return (0, types_1.toolError)(types_1.ToolErrorCode.CIRCUIT_OPEN, `[FATAL:CIRCUIT_OPEN] Tool "${name}" has been disabled after ${status.failureCount} consecutive failures. ` +
                 `It cannot be used again in this session. ` +
-                `Please try a completely different approach that does not rely on this tool. ` +
-                `Available alternatives: ${this.toolNames.filter((n) => n !== name).join(", ") || "none — try a different method."}`);
+                `Please find a completely different approach. ` +
+                `Available alternatives: ${this.toolNames.filter((n) => n !== name).join(", ") || "none — try a different method."}`, "fatal");
         }
         // Execute with failure tracking and retry guidance
         try {
-            const result = await tool.execute(args);
-            // Success after previous failures — record recovery + reset breaker
+            const rawResult = await tool.execute(args);
+            const truncated = this.truncator.truncate(name, rawResult);
+            const wasTruncated = truncated !== rawResult;
+            // Success after previous failures — record recovery + reset breaker.
+            // Only include the recovery message in the LLM context when an
+            // error tracker is active (meaning the LLM was previously informed
+            // of the failures via error-analysis injection).
             if (breaker.currentFailureCount > 0) {
-                // Record recovery in the error tracker
+                let hadActiveTrace = false;
                 if (this.errorTracker) {
                     const activeTrace = this.errorTracker.getActiveTraceId(name);
                     if (activeTrace) {
                         this.errorTracker.recordRecovery(name, activeTrace, `Tool "${name}" executed successfully after ${breaker.currentFailureCount} failure(s).`);
+                        hadActiveTrace = true;
                     }
                 }
                 breaker.recordSuccess();
-                return (`${result}\n\n` +
-                    `[Tool "${name}" has recovered after previous failures. The failure counter has been reset.]`);
+                if (hadActiveTrace) {
+                    const content = wasTruncated
+                        ? `${truncated}\n\n[Tool "${name}" has recovered after previous failures. The failure counter has been reset.]\n[Note: Output was truncated due to size limits.]`
+                        : `${truncated}\n\n[Tool "${name}" has recovered after previous failures. The failure counter has been reset.]`;
+                    return {
+                        success: true,
+                        severity: "success",
+                        errorCode: wasTruncated ? types_1.ToolErrorCode.TRUNCATED_OUTPUT : types_1.ToolErrorCode.SUCCESS,
+                        content,
+                    };
+                }
+                // Breaker was reset but no active error trace — silent recovery.
+                return (0, types_1.toolSuccess)(truncated);
             }
             breaker.recordSuccess();
-            return result;
+            return (0, types_1.toolSuccess)(truncated);
         }
         catch (err) {
             const rawMessage = err instanceof Error ? err.message : String(err);
             const remaining = breaker.recordFailure();
             // Record the failure in the error tracker
             if (this.errorTracker) {
-                this.errorTracker.recordFailure(name, args, rawMessage, remaining);
+                this.errorTracker.recordFailure(name, args, rawMessage, remaining, breaker.state);
             }
             // Circuit just opened — no retries left
             if (!breaker.isAvailable) {
-                return (`Error executing tool "${name}": ${rawMessage}\n\n` +
-                    `This was the final attempt. The tool "${name}" is now disabled after ${breaker.currentFailureCount} consecutive failures. ` +
-                    `Please do NOT try to use "${name}" again. Instead, try a different approach or a different tool.`);
+                return (0, types_1.toolError)(types_1.ToolErrorCode.EXECUTION_FAILURE, `[FATAL:EXECUTION_FAILURE] Tool "${name}" threw an exception: ${rawMessage}\n\n` +
+                    `This was the final attempt. The tool is now disabled after ${breaker.currentFailureCount} consecutive failures. ` +
+                    `Do NOT retry "${name}". Find a different approach or tool.`, "fatal");
             }
-            // Retries still available — guide the LLM to re-analyze
+            // Retries still available — circuit is HALF_OPEN (degraded)
             const attemptNum = breaker.currentFailureCount;
             const totalAllowed = breaker.effectiveThreshold;
-            return (`Error executing tool "${name}": ${rawMessage}\n\n` +
-                `[Retry Guidance] This is attempt ${attemptNum} of ${totalAllowed}. ` +
-                `You have ${remaining} retry attempt${remaining > 1 ? "s" : ""} remaining.\n` +
-                `Please analyze the error above carefully, correct the parameters, and retry. ` +
-                `If you believe the issue is with the input, try a different approach or different arguments.`);
+            const stateWarning = remaining === 0
+                ? `\n⚠️  The circuit breaker for "${name}" is now in a degraded state (HALF_OPEN). ` +
+                    `The NEXT failure will permanently disable this tool. Proceed with extreme caution.`
+                : `\n⚠️  The circuit breaker for "${name}" is now in a degraded state (HALF_OPEN). ` +
+                    `After ${remaining} more failure(s), the tool will be permanently disabled.`;
+            return (0, types_1.toolError)(types_1.ToolErrorCode.EXECUTION_FAILURE, `[RETRYABLE:EXECUTION_FAILURE] Tool "${name}" threw an exception: ${rawMessage}\n\n` +
+                `This is attempt ${attemptNum} of ${totalAllowed}. ` +
+                `You have ${remaining} retry attempt${remaining > 1 ? "s" : ""} remaining.${stateWarning}\n` +
+                `Analyze the error, correct the parameters, and retry. ` +
+                `If the approach is fundamentally wrong, try a different method.`, "retryable");
         }
     }
     /**

package/dist/tools/tool-registry.js.map

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

package/dist/tools/tool-validator.d.ts

@@ -0,0 +1,13 @@
+import { ToolResult } from "./types";
+/**
+ * Validate tool arguments against the tool's JSON Schema.
+ *
+ * @param toolName   — The tool's name (for error messages).
+ * @param parameters — The tool's JSON Schema definition (`Tool.parameters`).
+ * @param args       — The parsed arguments from the LLM.
+ *
+ * @returns `null` when validation passes (no error), or a {@link ToolResult}
+ *          with `VALIDATION_ERROR` when the arguments are invalid.
+ */
+export declare function validateToolArgs(toolName: string, parameters: Record<string, unknown>, args: Record<string, unknown>): ToolResult | null;
+//# sourceMappingURL=tool-validator.d.ts.map

package/dist/tools/tool-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-validator.d.ts","sourceRoot":"","sources":["../../src/tools/tool-validator.ts"],"names":[],"mappings":"AACA,OAAO,EAA4B,UAAU,EAAE,MAAM,SAAS,CAAC;AA2D/D;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,UAAU,GAAG,IAAI,CAqDnB"}

package/dist/tools/tool-validator.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateToolArgs = validateToolArgs;
+const ajv_1 = __importDefault(require("ajv"));
+const types_1 = require("./types");
+/**
+ * Validates tool arguments against the tool's JSON Schema definition.
+ *
+ * Uses ajv to compile each tool's `parameters` schema once, then validates
+ * incoming arguments before the tool is executed — catching missing required
+ * params, wrong types, etc. before wasting an LLM round-trip on a call that
+ * would fail.
+ */
+const ajv = new ajv_1.default({
+    allErrors: true, // collect all errors, not just the first
+    strict: false, // allow non-strict JSON Schema keywords LLMs may emit
+    coerceTypes: false, // don't silently coerce — surface type errors
+});
+/** Cache of compiled validators keyed by a per-tool stable key. */
+const validatorCache = new Map();
+/**
+ * Build a stable cache key from a tool's name and parameters hash.
+ *
+ * We hash `JSON.stringify(parameters)` so that if a tool's schema changes at
+ * runtime (e.g. MCP tools reconnecting with a different schema) the cache
+ * invalidates automatically.
+ */
+function cacheKey(toolName, parameters) {
+    return `${toolName}::${JSON.stringify(parameters)}`;
+}
+/**
+ * Check whether the JSON Schema has any real constraints worth validating.
+ *
+ * An empty schema (`{}` or `{"type": "object"}` with no properties/required)
+ * imposes no constraints, so we skip compilation.
+ */
+function hasConstraints(schema) {
+    const keys = Object.keys(schema);
+    if (keys.length === 0)
+        return false;
+    if (keys.length === 1 && keys[0] === "type")
+        return false;
+    return true;
+}
+/**
+ * Format ajv errors into a human-readable (and LLM-readable) message.
+ *
+ * Each error line follows the pattern:
+ *   - /fieldName: <message>
+ *   - /: <message>  (root-level errors)
+ */
+function formatErrors(errors) {
+    const lines = errors.map((err) => {
+        const path = err.instancePath || "/";
+        return `  - ${path}: ${err.message}`;
+    });
+    return lines.join("\n");
+}
+/**
+ * Validate tool arguments against the tool's JSON Schema.
+ *
+ * @param toolName   — The tool's name (for error messages).
+ * @param parameters — The tool's JSON Schema definition (`Tool.parameters`).
+ * @param args       — The parsed arguments from the LLM.
+ *
+ * @returns `null` when validation passes (no error), or a {@link ToolResult}
+ *          with `VALIDATION_ERROR` when the arguments are invalid.
+ */
+function validateToolArgs(toolName, parameters, args) {
+    // ── Guard: nothing to validate ────────────────────────────────────────
+    if (!hasConstraints(parameters)) {
+        return null;
+    }
+    // ── Compile (or fetch cached) validator ───────────────────────────────
+    const key = cacheKey(toolName, parameters);
+    let validate;
+    if (validatorCache.has(key)) {
+        validate = validatorCache.get(key);
+    }
+    else {
+        try {
+            validate = ajv.compile(parameters);
+            validatorCache.set(key, validate);
+        }
+        catch (compileErr) {
+            // Schema itself is malformed — log and skip validation for this tool.
+            // The LLM will still get error feedback from the actual tool call.
+            const msg = compileErr instanceof Error ? compileErr.message : String(compileErr);
+            console.warn(`[tool-validator] Failed to compile schema for tool "${toolName}": ${msg}`);
+            return null;
+        }
+    }
+    // ── Validate ──────────────────────────────────────────────────────────
+    const valid = validate(args);
+    if (valid) {
+        return null; // all good
+    }
+    // ── Build structured error for the LLM ────────────────────────────────
+    const errors = validate.errors ?? [];
+    const errorList = formatErrors(errors);
+    const requiredFields = parameters.required && Array.isArray(parameters.required)
+        ? parameters.required.join('", "')
+        : "";
+    let content = `[RETRYABLE:VALIDATION_ERROR] Tool "${toolName}" was called with invalid arguments.\n\n`;
+    content += `Validation errors:\n${errorList}\n`;
+    if (requiredFields) {
+        content += `\nRequired fields: "${requiredFields}"\n`;
+    }
+    content += `\nReceived arguments: ${JSON.stringify(args, null, 2)}\n\n`;
+    content += `Please correct the arguments and re-invoke the tool with valid parameters.`;
+    return (0, types_1.toolError)(types_1.ToolErrorCode.VALIDATION_ERROR, content, "retryable");
+}
+//# sourceMappingURL=tool-validator.js.map

package/dist/tools/tool-validator.js.map

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