Merge pull request #105 from CsBigDataHub/master

custom tools support

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Support user configured custom tools.
+
 ## 0.44.1
 
 - Fix renew token regression.

docs/configuration.md

@@ -158,6 +158,60 @@ Also check the `plan` behavior which is safer.
 
 __The `manualApproval` setting was deprecated and replaced by the `approval` one without breaking changes__
 
+## Custom Tools
+
+You can define your own command-line tools that the LLM can use. These are configured via the `custom-tools` key in your `config.json`.
+
+The `custom-tools` value is an object where each key is the name of your tool. Each tool definition has the following properties:
+
+-   `description`: A clear description of what the tool does. This is crucial for the LLM to decide when to use it.
+-   `command`: An array of strings representing the command and its static arguments.
+-   `schema`: An object that defines the parameters the LLM can provide.
+    -   `properties`: An object where each key is an argument name.
+    -   `required`: An array of required argument names.
+
+Placeholders in the format `{{argument_name}}` within the `command` array will be replaced by the values provided by the LLM.
+
+=== "Example config.json"
+
+    ```javascript
+    {
+      "custom-tools": {
+        "web-search": {
+          "description": "Fetches the content of a URL and returns it in Markdown format.",
+          "command": ["trafilatura", "--output-format=markdown", "-u", "{{url}}"],
+          "schema": {
+            "properties": {
+              "url": {
+                "type": "string",
+                "description": "The URL to fetch content from."
+              }
+            },
+            "required": ["url"]
+          }
+        },
+        "file-search": {
+          "description": "Finds files within a directory that match a specific name pattern.",
+          "command": ["find", "{{directory}}", "-name", "{{pattern}}"],
+          "schema": {
+            "properties": {
+              "directory": {
+                "type": "string",
+                "description": "The directory to start the search from."
+              },
+              "pattern": {
+                "type": "string",
+                "description": "The search pattern for the filename (e.g., '*.clj')."
+              }
+            },
+            "required": ["directory", "pattern"]
+          }
+        }
+      }
+    }
+    ```
+
+
 ## Custom command prompts
 
 You can configure custom command prompts for project, global or via `commands` config pointing to the path of the commands.
@@ -265,6 +319,17 @@ There are 3 possible ways to configure rules following this order of priority:
                     excludeCommands: string[]};
             editor: {enabled: boolean,};
         };
+        customTools?: {[key: string]: {
+            description: string;
+            command: string[];
+            schema: {
+                properties: {[key: string]: {
+                    type: string;
+                    description: string;
+                }};
+                required: string[];
+            };
+        }};
         disabledTools?: string[],
         toolCall?: {
           approval?: {

docs/features.md

@@ -52,6 +52,12 @@ Provides access to get information from editor workspaces.
 
 - `eca_editor_diagnostics`: Ask client about the diagnostics (like LSP diagnostics).
 
+#### Custom Tools
+
+Besides the built-in native tools, ECA allows you to define your own tools by wrapping any command-line executable. This feature enables you to extend ECA's capabilities to match your specific workflows, such as running custom scripts, interacting with internal services, or using your favorite CLI tools.
+
+Custom tools are configured in your `config.json` file. For a detailed guide on how to set them up, check the [Custom Tools configuration documentation](./configuration.md#custom-tools).
+
 ### Contexts
 
 ![](./images/features/contexts.png)

src/eca/features/tools.clj

@@ -3,6 +3,7 @@
    eca native tools and MCP servers."
   (:require
    [clojure.string :as string]
+   [eca.features.tools.custom :as f.tools.custom]
    [eca.features.tools.editor :as f.tools.editor]
    [eca.features.tools.filesystem :as f.tools.filesystem]
    [eca.features.tools.mcp :as f.mcp]
@@ -33,7 +34,8 @@
           (when (get-in config [:nativeTools :shell :enabled])
             f.tools.shell/definitions)
           (when (get-in config [:nativeTools :editor :enabled])
-            f.tools.editor/definitions))))
+            f.tools.editor/definitions)
+          (f.tools.custom/definitions config))))
 
 (defn ^:private native-tools [db config]
   (mapv #(assoc % :server "eca") (vals (native-definitions db config))))

src/eca/features/tools/custom.clj

@@ -0,0 +1,43 @@
+(ns eca.features.tools.custom
+  (:require
+   [babashka.process :as process]
+   [clojure.string :as string]))
+
+(set! *warn-on-reflection* true)
+
+(defn ^:private build-tool-fn
+  "Creates a function that safely executes the command from a custom tool config.
+  It substitutes {{placeholders}} in the command vector with LLM-provided arguments."
+  [{:keys [command]}]
+  ;; The handler function takes arguments and a context map. We only need the arguments.
+  (fn [llm-args _context]
+    (let [resolved-command (mapv
+                            (fn [part]
+                              (if (and (string? part) (string/starts-with? part "{{") (string/ends-with? part "}}"))
+                                (let [key-name (keyword (subs part 2 (- (count part) 2)))]
+                                  (str (get llm-args key-name "")))
+                                part))
+                            command)
+          {:keys [out exit]} (process/sh resolved-command {:error-to-out true})]
+      (if (zero? exit)
+        out
+        (str "Error: Command failed with exit code " exit "\nOutput:\n" out)))))
+
+(defn ^:private custom-tool->tool-def
+  "Transforms a single custom tool from the config map into a full tool definition."
+  [[tool-name tool-config]]
+  (let [schema (:schema tool-config)]
+    {(name tool-name)
+     {:name (name tool-name)
+      :description (:description tool-config)
+      :parameters {:type "object"
+                   :properties (update-keys (:properties schema) keyword)
+                   :required (mapv keyword (:required schema))}
+      :handler (build-tool-fn tool-config)}}))
+
+(defn definitions
+  "Loads all custom tools from the config."
+  [config]
+  (->> (get config :custom-tools {})
+       (map custom-tool->tool-def)
+       (apply merge)))

test/eca/features/tools/custom_test.clj

@@ -0,0 +1,57 @@
+(ns eca.features.tools.custom-test
+  (:require
+   [clojure.string :as string]
+   [clojure.test :refer [deftest is testing]]
+   [babashka.process :as process]
+   [eca.features.tools.custom :as f.tools.custom]))
+
+(deftest definitions-test
+  (testing "when a valid tool is configured"
+    (let [mock-custom-tools {"file-search"
+                             {:description "Finds files."
+                              :command     ["find" "{{directory}}" "-name" "{{pattern}}"]
+                              :schema      {:properties {:directory {:type "string"}
+                                                         :pattern   {:type "string"}}
+                                            :required    ["directory" "pattern"]}}}]
+      (testing "and the command executes successfully"
+        (with-redefs [process/sh (fn [command-vec & _]
+                                   (is (= ["find" "/tmp" "-name" "*.clj"] command-vec))
+                                   {:out "mocked-output" :exit 0})]
+          (let [config {:custom-tools mock-custom-tools}
+                custom-defs (f.tools.custom/definitions config)
+                custom-tool-def (get custom-defs "file-search")]
+            (is (some? custom-tool-def) "The custom tool should be loaded.")
+            (let [result ((:handler custom-tool-def) {:directory "/tmp" :pattern "*.clj"} {})]
+              (is (= "mocked-output" result) "The tool should return the mocked shell output.")))))))
+
+  (testing "when multiple tools are configured"
+    (let [mock-custom-tools {"git-status"
+                             {:description "Gets git status"
+                              :command ["git" "status"]}
+                             "echo-message"
+                             {:description "Echoes a message"
+                              :command ["echo" "{{message}}"]
+                              :schema {:properties {:message {:type "string"}} :required ["message"]}}}]
+      (with-redefs [process/sh (fn [command-vec & _]
+                                 (condp = command-vec
+                                   ["git" "status"] {:out "On branch main" :exit 0}
+                                   ["echo" "Hello World"] {:out "Hello World" :exit 0}
+                                   (is false "Unexpected command received by mock p/sh")))]
+        (let [config {:custom-tools mock-custom-tools}
+              custom-defs (f.tools.custom/definitions config)
+              git-status-handler (get-in custom-defs ["git-status" :handler])
+              echo-handler (get-in custom-defs ["echo-message" :handler])]
+          (is (some? git-status-handler) "Git status tool should be loaded.")
+          (is (some? echo-handler) "Echo message tool should be loaded.")
+          (is (= "On branch main" (git-status-handler {} {})))
+          (is (= "Hello World" (echo-handler {:message "Hello World"} {})))))))
+
+  (testing "when the custom tools config is empty or missing"
+    (testing "with an empty map"
+      (let [config {:custom-tools {}}
+            custom-defs (f.tools.custom/definitions config)]
+        (is (empty? custom-defs) "No custom tools should be loaded.")))
+    (testing "with the key missing from the config"
+      (let [config {}
+            custom-defs (f.tools.custom/definitions config)]
+        (is (empty? custom-defs) "No custom tools should be loaded.")))))