Add shell native tool

ericdallo · ericdallo · commit 5695ec07ff40 · 2025-07-06T10:27:03.000-03:00
diff --git a/docs/capabilities.md b/docs/capabilities.md
@@ -18,17 +18,21 @@ Provides access to filesystem under workspace root, listing and reading files an
 - `grep`: ripgrep/grep for paths with specified content.
 - `replace_in_file`: replace a text with another one in file.
 
-### TODO - Shell
+### Shell
+
+Provides access to run shell commands, useful to run build tools, tests, and other common commands, supports exclude/include commands. 
+
+- `shell_command`: run shell command. Supports configs to exclude commands via `:nativeTools :shell :excludeCommands`.
 
 ### TODO - Web
 
 ## Supported LLM models and capaibilities
 
-| model     | MCP / tools | thinking/reasioning | prompt caching |
-|-----------|-------------|---------------------|----------------|
-| OpenAI    | √           | X                   | X              |
-| Anthropic | √           | X                   | √              |
-| Ollama    | √           | X                   | X              |
+| model     | MCP / tools | thinking/reasioning | prompt caching | web_search |
+|-----------|-------------|---------------------|----------------|------------|
+| OpenAI    | √           | X                   | X              | √          |
+| Anthropic | √           | X                   | √              | √          |
+| Ollama    | √           | X                   | X              | X          |
 
 ### OpenAI
 
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -117,7 +117,9 @@ interface Config {
   "openaiApiKey" : null,
   "anthropicApiKey" : null,
   "rules" : [ ],
-  "nativeTools": {"filesystem": {"enabled": true}},
+  "nativeTools": {"filesystem": {"enabled": true}
+                  "shell": {"enabled": true
+                            "excludeCommands": []}},
   "mcpTimeoutSeconds" : 10,
   "mcpServers" : [ ],
   "ollama" : {
diff --git a/src/eca/config.clj b/src/eca/config.clj
@@ -19,7 +19,9 @@
   {:openaiApiKey nil
    :anthropicApiKey nil
    :rules []
-   :nativeTools {:filesystem {:enabled true}}
+   :nativeTools {:filesystem {:enabled true}
+                 :shell {:enabled true
+                         :excludeCommands []}}
    :mcpTimeoutSeconds 60
    :mcpServers {}
    :ollama {:host "http://localhost"
diff --git a/src/eca/features/tools.clj b/src/eca/features/tools.clj
@@ -5,6 +5,7 @@
    [clojure.string :as string]
    [eca.features.tools.filesystem :as f.tools.filesystem]
    [eca.features.tools.mcp :as f.mcp]
+   [eca.features.tools.shell :as f.tools.shell]
    [eca.features.tools.util :as tools.util]
    [eca.logger :as logger])
   (:import
@@ -15,29 +16,31 @@
 (def ^:private logger-tag "[TOOLS]")
 
 (defn native-definitions [db config]
-  (merge {}
-         (when (get-in config [:nativeTools :filesystem :enabled])
-           (into
-            {}
-            (map (fn [[name tool]]
-                   [name (-> tool
-                             (assoc :name name)
-                             (update :description #(-> %
-                                                       (string/replace #"\$workspaceRoots" (constantly (tools.util/workspace-roots-strs db))))))]))
-            f.tools.filesystem/definitions))))
+  (into
+   {}
+   (map (fn [[name tool]]
+          [name (-> tool
+                    (assoc :name name)
+                    (update :description #(-> %
+                                              (string/replace #"\$workspaceRoots" (constantly (tools.util/workspace-roots-strs db))))))]))
+   (merge {}
+          (when (get-in config [:nativeTools :filesystem :enabled])
+            f.tools.filesystem/definitions)
+          (when (get-in config [:nativeTools :shell :enabled])
+            f.tools.shell/definitions))))
 
 (defn all-tools [db config]
   (let [native-tools (concat
-                       []
-                       (mapv #(select-keys % [:name :description :parameters])
-                             (vals (native-definitions db config))))
+                      []
+                      (mapv #(select-keys % [:name :description :parameters])
+                            (vals (native-definitions db config))))
         mcp-tools (f.mcp/all-tools db)]
     (concat
-      (mapv #(assoc % :source :native) native-tools)
-      (mapv #(assoc % :source :mcp) mcp-tools))))
+     (mapv #(assoc % :source :native) native-tools)
+     (mapv #(assoc % :source :mcp) mcp-tools))))
 
 (defn call-tool! [^String name ^Map arguments db config]
   (logger/debug logger-tag (format "Calling tool '%s' with args '%s'" name arguments))
   (if-let [native-tool-handler (get-in (native-definitions db config) [name :handler])]
-    (native-tool-handler arguments db)
+    (native-tool-handler arguments {:db db :config config})
     (f.mcp/call-tool! name arguments db)))
diff --git a/src/eca/features/tools/filesystem.clj b/src/eca/features/tools/filesystem.clj
@@ -9,30 +9,18 @@
 
 (set! *warn-on-reflection* true)
 
-(defn ^:private single-text-content [text & [error]]
-  {:contents [{:type :text
-               :content text
-               :error (boolean error)}]})
-
 (defn ^:private allowed-path? [db path]
   (some #(fs/starts-with? path (shared/uri->filename (:uri %)))
         (:workspace-folders db)))
 
-(defn ^:private invalid-arguments [arguments validator]
-  (first (keep (fn [[key pred error-msg]]
-                 (let [value (get arguments key)]
-                   (when-not (pred value)
-                     (single-text-content (string/replace error-msg (str "$" key) (str value)) :error))))
-               validator)))
-
 (defn ^:private path-validations [db]
   [["path" fs/exists? "$path is not a valid path"]
    ["path" (partial allowed-path? db) (str "Access denied - path $path outside allowed directories: " (tools.util/workspace-roots-strs db))]])
 
-(defn ^:private list-directory [arguments db]
+(defn ^:private list-directory [arguments {:keys [db]}]
   (let [path (delay (fs/canonicalize (get arguments "path")))]
-    (or (invalid-arguments arguments (path-validations db))
-        (single-text-content
+    (or (tools.util/invalid-arguments arguments (path-validations db))
+        (tools.util/single-text-content
          (reduce
           (fn [out path]
             (str out
@@ -42,9 +30,9 @@
           ""
           (fs/list-dir @path))))))
 
-(defn ^:private read-file [arguments db]
-  (or (invalid-arguments arguments (concat (path-validations db)
-                                           [["path" fs/readable? "File $path is not readable"]]))
+(defn ^:private read-file [arguments {:keys [db]}]
+  (or (tools.util/invalid-arguments arguments (concat (path-validations db)
+                                                      [["path" fs/readable? "File $path is not readable"]]))
       (let [head (get arguments "head")
             tail (get arguments "tail")
             content (cond-> (slurp (fs/file (fs/canonicalize (get arguments "path"))))
@@ -54,19 +42,19 @@
                       tail (->> (string/split-lines)
                                 (take-last tail)
                                 (string/join "\n")))]
-        (single-text-content content))))
+        (tools.util/single-text-content content))))
 
-(defn ^:private write-file [arguments db]
-  (or (invalid-arguments arguments [["path" (partial allowed-path? db) (str "Access denied - path $path outside allowed directories: " (tools.util/workspace-roots-strs db))]])
+(defn ^:private write-file [arguments {:keys [db]}]
+  (or (tools.util/invalid-arguments arguments [["path" (partial allowed-path? db) (str "Access denied - path $path outside allowed directories: " (tools.util/workspace-roots-strs db))]])
       (let [path (get arguments "path")
             content (get arguments "content")]
         (fs/create-dirs path)
         (spit path content)
-        (single-text-content (format "Successfully wrote to %s" path)))))
+        (tools.util/single-text-content (format "Successfully wrote to %s" path)))))
 
-(defn ^:private search-files [arguments db]
-  (or (invalid-arguments arguments (concat (path-validations db)
-                                           [["pattern" #(not (string/blank? %)) "Invalid glob pattern '$pattern'"]]))
+(defn ^:private search-files [arguments {:keys [db]}]
+  (or (tools.util/invalid-arguments arguments (concat (path-validations db)
+                                                      [["pattern" #(not (string/blank? %)) "Invalid glob pattern '$pattern'"]]))
       (let [pattern (get arguments "pattern")
             pattern (if (string/includes? pattern "*")
                       pattern
@@ -77,9 +65,9 @@
                                             pattern)))
                    []
                    (:workspace-folders db))]
-        (single-text-content (if (seq paths)
-                               (string/join "\n" paths)
-                               "No matches found")))))
+        (tools.util/single-text-content (if (seq paths)
+                                          (string/join "\n" paths)
+                                          "No matches found")))))
 
 (defn ^:private run-ripgrep [path pattern include]
   (let [cmd (cond-> ["rg" "--files-with-matches" "--no-heading"]
@@ -147,12 +135,12 @@
 
    Returns matching file paths, prioritizing by modification time when possible.
    Validates that the search path is within allowed workspace directories."
-  [arguments db]
-  (or (invalid-arguments arguments (concat (path-validations db)
-                                           [["path" fs/readable? "File $path is not readable"]
-                                            ["pattern" #(and % (not (string/blank? %))) "Invalid content regex pattern '$pattern'"]
-                                            ["include" #(or (nil? %) (not (string/blank? %))) "Invalid file pattern '$include'"]
-                                            ["max_results" #(or (nil? %) number?) "Invalid number '$max_results'"]]))
+  [arguments {:keys [db]}]
+  (or (tools.util/invalid-arguments arguments (concat (path-validations db)
+                                                      [["path" fs/readable? "File $path is not readable"]
+                                                       ["pattern" #(and % (not (string/blank? %))) "Invalid content regex pattern '$pattern'"]
+                                                       ["include" #(or (nil? %) (not (string/blank? %))) "Invalid file pattern '$include'"]
+                                                       ["max_results" #(or (nil? %) number?) "Invalid number '$max_results'"]]))
       (let [path (get arguments "path")
             pattern (get arguments "pattern")
             include (get arguments "include")
@@ -169,19 +157,19 @@
                    (run-java-grep path pattern include))
                  (take max-results))]
         ;; TODO sort by modification time.
-        (single-text-content (if (seq paths)
-                               (string/join "\n" paths)
-                               "No files found for given pattern")))))
+        (tools.util/single-text-content (if (seq paths)
+                                          (string/join "\n" paths)
+                                          "No files found for given pattern")))))
 
-(defn ^:private replace-in-file [arguments db]
-  (or (invalid-arguments arguments (concat (path-validations db)
-                                           [["path" fs/readable? "File $path is not readable"]]))
+(defn ^:private replace-in-file [arguments {:keys [db]}]
+  (or (tools.util/invalid-arguments arguments (concat (path-validations db)
+                                                      [["path" fs/readable? "File $path is not readable"]]))
       (let [path (get arguments "path")
             original-content (get arguments "original_content")
             new-content (get arguments "new_content")
             all? (boolean (get arguments "all_occurrences"))
             content (slurp path)]
-        (single-text-content
+        (tools.util/single-text-content
          (if (string/includes? content original-content)
            (let [content (if all?
                            (string/replace content original-content new-content)
@@ -190,16 +178,16 @@
              (format "Successfully replaced content in %s." path))
            (format "Original content not found in %s" path))))))
 
-(defn ^:private move-file [arguments db]
+(defn ^:private move-file [arguments {:keys [db]}]
   (let [workspace-dirs (tools.util/workspace-roots-strs db)]
-    (or (invalid-arguments arguments [["source" fs/exists? "$source is not a valid path"]
-                                      ["source" (partial allowed-path? db) (str "Access denied - path $source outside allowed directories: " workspace-dirs)]
-                                      ["destination" (partial allowed-path? db) (str "Access denied - path $destination outside allowed directories: " workspace-dirs)]
-                                      ["destination" (complement fs/exists?) "Path $destination already exists"]])
+    (or (tools.util/invalid-arguments arguments [["source" fs/exists? "$source is not a valid path"]
+                                                 ["source" (partial allowed-path? db) (str "Access denied - path $source outside allowed directories: " workspace-dirs)]
+                                                 ["destination" (partial allowed-path? db) (str "Access denied - path $destination outside allowed directories: " workspace-dirs)]
+                                                 ["destination" (complement fs/exists?) "Path $destination already exists"]])
         (let [source (get arguments "source")
               destination (get arguments "destination")]
           (fs/move source destination {:replace-existing false})
-          (single-text-content (format "Successfully moved %s to %s" source destination))))))
+          (tools.util/single-text-content (format "Successfully moved %s to %s" source destination))))))
 
 (def definitions
   {"list_directory"
diff --git a/src/eca/features/tools/shell.clj b/src/eca/features/tools/shell.clj
@@ -0,0 +1,46 @@
+(ns eca.features.tools.shell
+  (:require
+   [babashka.fs :as fs]
+   [clojure.java.shell :as shell]
+   [clojure.string :as string]
+   [eca.features.tools.util :as tools.util]
+   [eca.logger :as logger]
+   [eca.shared :as shared]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private logger-tag "[TOOLS-SHELL]")
+
+(defn ^:private shell-command [arguments {:keys [db config]}]
+  (let [command (get arguments "command")
+        user-work-dir (get arguments "working_directory")
+        exclude-cmds (-> config :nativeTools :shell :excludeCommands set)
+        command-args (string/split command #" ")]
+    (or (tools.util/invalid-arguments arguments [["working_directory" #(or (nil? %)
+                                                                           (fs/exists? %)) "working directory $working_directory does not exist"]
+                                                 ["commmand" (constantly (not (contains? exclude-cmds (first command-args)))) (format "Cannot run command '%s' because it is excluded by eca config."
+                                                                                                                                (first command-args))]])
+        (let [work-dir (or (some-> user-work-dir fs/canonicalize str)
+                           (shared/uri->filename (:uri (first (:workspace-folders db)))))
+              command-and-opts (concat [] command-args [:dir work-dir])
+              _ (logger/debug logger-tag "Running command:" command-and-opts)
+              result (try
+                       (apply shell/sh command-and-opts)
+                       (catch Exception e
+                         {:exit 1 :err (.getMessage e)}))]
+          (logger/debug logger-tag "Command executed:" result)
+          (if (zero? (:exit result))
+            (tools.util/single-text-content (:out result))
+            (tools.util/single-text-content (str "Command failed with exit code " (:exit result) ": " (:err result)) :error))))))
+
+(def definitions
+  {"shell_command"
+   {:description (str "Execute an arbitrary shell command and return the output. "
+                      "Useful to run commands like `ls`, `git status`, etc.")
+    :parameters {:type "object"
+                 :properties {"command" {:type "string"
+                                         :description "The shell command to execute."}
+                              "working_directory" {:type "string"
+                                                   :description "The directory to run the command in. Default to the first workspace root."}}
+                 :required ["command"]}
+    :handler #'shell-command}})
diff --git a/src/eca/features/tools/util.clj b/src/eca/features/tools/util.clj
@@ -4,6 +4,11 @@
    [clojure.string :as string]
    [eca.shared :as shared]))
 
+(defn single-text-content [text & [error]]
+  {:contents [{:type :text
+               :content text
+               :error (boolean error)}]})
+
 (defn workspace-roots-strs [db]
   (->> (:workspace-folders db)
        (map #(shared/uri->filename (:uri %)))
@@ -13,3 +18,11 @@
   (try
     (zero? (:exit (apply shell/sh (concat [command] args))))
     (catch Exception _ false)))
+
+(defn invalid-arguments [arguments validator]
+  (first (keep (fn [[key pred error-msg]]
+                 (let [value (get arguments key)]
+                   (when-not (pred value)
+                     (single-text-content (string/replace error-msg (str "$" key) (str value))
+                                          :error))))
+               validator)))
diff --git a/src/eca/shared.clj b/src/eca/shared.clj
@@ -17,3 +17,11 @@
   (if (seq coll)
     (update coll (dec (count coll)) f)
     coll))
+
+(defn deep-merge [v & vs]
+  (letfn [(rec-merge [v1 v2]
+                     (if (and (map? v1) (map? v2))
+                       (merge-with deep-merge v1 v2)
+                       v2))]
+    (when (some identity vs)
+      (reduce #(rec-merge %1 %2) v vs))))
diff --git a/test/eca/features/tools/filesystem_test.clj b/test/eca/features/tools/filesystem_test.clj
diff --git a/test/eca/features/tools/shell_test.clj b/test/eca/features/tools/shell_test.clj
diff --git a/test/eca/test_helper.clj b/test/eca/test_helper.clj
