Merge branch 'master' into skill-base-dir-path-resolution

ericdallo · web-flow · commit 3394aca7edfb · 2026-05-04T15:39:40.000-03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- `variantsByModel` entries now support an optional `:api` filter (string or vector) to restrict variant matching by provider API type.
+- Custom commands and skills now expose `:arguments` metadata inferred from their content. Previously they always reported empty arguments.
+- Native `skill-create`, `plugin-install`, and `plugin-uninstall` commands now declare `:required true` on their arguments in the command listing.
+- Fix documentation link in `--help` output.
+- Add built-in variants for `deepseek-v4-pro` (`none`, `high`, `max`).
 - Improve skill tool description to resolve file paths and scripts mentioned in skill content against the skill's base directory.
 
 ## 0.131.1
diff --git a/docs/config.json b/docs/config.json
@@ -475,6 +475,17 @@
           "items": {
             "type": "string"
           }
+        },
+        "api": {
+          "type": [
+            "string",
+            "array"
+          ],
+          "description": "Restrict variants to the given API type(s). String for exact match, array for any-of. Absent = match all.",
+          "markdownDescription": "Restrict variants to the given API type(s). String for exact match, array for any-of. Absent = match all.",
+          "items": {
+            "type": "string"
+          }
         }
       },
       "additionalProperties": false
diff --git a/docs/config/variants.md b/docs/config/variants.md
@@ -35,6 +35,16 @@ ECA ships with built-in variants for some known models via the `variantsByModel`
     | `high`     | `{"reasoning": {"effort": "high", "summary": "auto"}}` |
     | `xhigh`    | `{"reasoning": {"effort": "xhigh", "summary": "auto"}}` |
 
+=== "DeepSeek"
+
+    Applies to models matching `deepseek-v4-pro`. Only for providers using the `openai-chat` API.
+
+    | Variant    | Payload |
+    | ---------- | ------- |
+    | `none`     | `{"thinking": {"type": "disabled"}}` |
+    | `high`     | `{"reasoning_effort": "high"}` |
+    | `max`      | `{"reasoning_effort": "max"}}` |
+
 ## Custom Variants
 
 You can define your own variants per model under `providers.<provider>.models.<model>.variants`. Custom variants are merged with built-in ones — if names clash, your definition wins.
diff --git a/docs/protocol.md b/docs/protocol.md
@@ -1474,7 +1474,7 @@ interface ChatCommand {
     arguments: [{
        name: string;
        description?: string;
-       required: boolean; 
+       required?: boolean;
     }];
 }
 ```
diff --git a/src/eca/config.clj b/src/eca/config.clj
@@ -72,6 +72,11 @@
    "xhigh" {:output_config {:effort "xhigh"} :thinking {:type "adaptive" :display "summarized"}}
    "max" {:output_config {:effort "max"} :thinking {:type "adaptive" :display "summarized"}}})
 
+(def ^:private deepseek-variants
+  {"none" {:thinking {:type "disabled"}}
+   "high" {:reasoning_effort "high"}
+   "max" {:reasoning_effort "max"}})
+
 (def ^:private initial-config*
   {:providers {"openai" {:api "openai-responses"
                          :url "${env:OPENAI_API_URL:https://api.openai.com}"
@@ -188,7 +193,9 @@
    :variantsByModel {".*sonnet[-._]4[-._]6|opus[-._]4[-._][56]" {:variants anthropic-variants}
                      ".*opus[-._]4[-._]7" {:variants anthropic-v2-variants}
                      ".*gpt[-._]5(?:[-._](?:2|4|5)(?!\\d)|[-._]3[-._]codex)" {:variants openai-variants
-                                                                            :excludeProviders ["github-copilot"]}}
+                                                                              :excludeProviders ["github-copilot"]}
+                     ".*deepseek[-._]v4[-._]pro" {:variants deepseek-variants
+                                                  :api "openai-chat"}}
    :mcpTimeoutSeconds 60
    :lspTimeoutSeconds 30
    :streamIdleTimeoutSeconds 120
@@ -243,10 +250,16 @@
    A variant set to {} is removed from the result, allowing users to disable
    built-in variants."
   [config provider model-name user-variants]
-  (let [builtin (when model-name
-                  (some (fn [[pattern-str {:keys [variants excludeProviders]}]]
+  (let [provider-api (get-in config [:providers provider :api])
+        api-match? (fn [api config-val]
+                     (cond (sequential? config-val) (some #{api} config-val)
+                           config-val (= api config-val)
+                           :else true))
+        builtin (when model-name
+                  (some (fn [[pattern-str {:keys [variants excludeProviders api]}]]
                           (when (and (regex-matches? pattern-str model-name)
-                                     (not (some #{provider} excludeProviders)))
+                                     (not (some #{provider} excludeProviders))
+                                     (api-match? provider-api api))
                             variants))
                         (:variantsByModel config)))
         merged (cond
diff --git a/src/eca/features/commands.clj b/src/eca/features/commands.clj
@@ -37,15 +37,6 @@
 (defn ^:private normalize-command-name [f]
   (string/lower-case (fs/strip-ext (fs/file-name f))))
 
-(defn ^:private prefixed-command-name
-  "Builds the user-invocation name for a plugin-sourced command.
-   Returns just the plugin name when it equals the command name,
-   otherwise 'plugin:command'."
-  [plugin-name command-name]
-  (if (= plugin-name command-name)
-    plugin-name
-    (str plugin-name ":" command-name)))
-
 (defn ^:private markdown-file? [file]
   (and (not (fs/directory? file))
        (string/ends-with? (string/lower-case (str file)) ".md")))
@@ -60,11 +51,12 @@
   (let [base (normalize-command-name file)
         content (interpolation/replace-dynamic-strings (slurp (str file)) (str (fs/parent file)) nil)]
     (cond-> {:name (if-let [plugin (:plugin opts)]
-                     (prefixed-command-name plugin base)
+                     (shared/prefixed-name plugin base)
                      base)
              :path (str (fs/canonicalize file))
              :type type
-             :content content}
+             :content content
+             :arguments (shared/extract-args-from-content content)}
       (:plugin opts) (assoc :plugin (:plugin opts)))))
 
 (defn ^:private global-file-commands []
@@ -125,8 +117,8 @@
                       {:name "skill-create"
                        :type :native
                        :description "Create a skill considering a user request"
-                       :arguments [{:name "name" :description "The skill name"}
-                                   {:name "prompt" :description "What to consider as this skill content"}]}
+                       :arguments [{:name "name" :description "The skill name" :required true}
+                                   {:name "prompt" :description "What to consider as this skill content" :required true}]}
                       {:name "costs"
                        :type :native
                        :description "Total costs of the current chat session."
@@ -178,23 +170,23 @@
                       {:name "plugin-install"
                        :type :native
                        :description "Install a plugin (e.g. /plugin-install my-plugin or /plugin-install my-plugin@marketplace)"
-                       :arguments [{:name "plugin" :description "Plugin name or plugin@marketplace"}]}
+                       :arguments [{:name "plugin" :description "Plugin name or plugin@marketplace" :required true}]}
                       {:name "plugin-uninstall"
                        :type :native
                        :description "Uninstall a plugin (e.g. /plugin-uninstall my-plugin)"
-                       :arguments [{:name "plugin" :description "Plugin name"}]}]
+                       :arguments [{:name "plugin" :description "Plugin name" :required true}]}]
         custom-cmds (map (fn [custom]
                            {:name (:name custom)
                             :type :custom-prompt
                             :description (:path custom)
-                            :arguments []})
+                            :arguments (:arguments custom)})
                          (custom-commands config (:workspace-folders db)))
         skills-cmds (->> (f.skills/all config (:workspace-folders db))
                          (mapv (fn [skill]
                                  {:name (:name skill)
                                   :type :skill
                                   :description (:description skill)
-                                  :arguments []})))]
+                                  :arguments (:arguments skill)})))]
     (concat mcp-prompts
             eca-commands
             skills-cmds
diff --git a/src/eca/features/skills.clj b/src/eca/features/skills.clj
@@ -19,6 +19,7 @@
         {:name name
          :description description
          :body body
+         :arguments (shared/extract-args-from-content body)
          :dir (str (fs/canonicalize (fs/parent skill-file)))}))
     (catch Exception e
       (logger/warn logger-tag (format "Error parsing skill file '%s': %s" (str skill-file) (.getMessage e)))
@@ -39,20 +40,11 @@
     (fs/directory? path) (filter skill-file? (fs/glob path "**" {:follow-links true}))
     :else [path]))
 
-(defn ^:private prefixed-skill-name
-  "Builds the user-invocation name for a plugin skill.
-   Returns just the plugin name when it equals the skill name,
-   otherwise 'plugin:skill'."
-  [plugin-name skill-name]
-  (if (= plugin-name skill-name)
-    plugin-name
-    (str plugin-name ":" skill-name)))
-
 (defn ^:private plugin-skill [plugin file]
   (when-let [skill (skill-file->skill file)]
     (cond-> skill
       plugin (assoc :plugin plugin
-                    :name (prefixed-skill-name plugin (:name skill))))))
+                    :name (shared/prefixed-name plugin (:name skill))))))
 
 (defn ^:private global-skills []
   (keep skill-file->skill
diff --git a/src/eca/main.clj b/src/eca/main.clj
@@ -33,7 +33,7 @@
         "Available commands:"
         "  server        Start eca as server, listening to stdin."
         ""
-        "See https://eca.dev/settings/ for detailed documentation."]
+        "See https://eca.dev/config/introduction/ for detailed documentation."]
        (string/join \newline)))
 
 (defn ^:private error-msg [errors]
diff --git a/src/eca/shared.clj b/src/eca/shared.clj
@@ -63,6 +63,27 @@
           (assoc metadata :body (string/trim (string/join "\n" body-lines)))))
       {:body (string/trim content)})))
 
+(defn extract-args-from-content
+  "Parses command/skill content for $ARGN, $N, $ARGS, and $ARGUMENTS placeholders
+   and returns the corresponding :arguments vector for command metadata.
+   Returns an empty vector when no argument placeholders are found."
+  [content]
+  (if (string/blank? content)
+    []
+    (let [content (str content)
+          nums (keep (fn [[_ n]] (parse-long n))
+                     (re-seq #"\$(?:ARG)?(\d+)" content))
+          has-varargs (some #(string/includes? content %)
+                            ["$ARGS" "$ARGUMENTS"])
+          max-n (when (seq nums) (apply max nums))
+          declared-count (cond
+                           max-n     max-n
+                           has-varargs 1)]
+      (if declared-count
+        (vec (for [i (range 1 (inc declared-count))]
+               {:name (str "arg" i) :required true}))
+        []))))
+
 ;; Walks up from a non-existing path to find the nearest existing ancestor,
 ;; canonicalizes it (resolving symlinks), then re-attaches the missing segments.
 ;; This is needed because workspace roots can be symlinks — for write_file
@@ -116,6 +137,14 @@
   "The system's line separator."
   (System/lineSeparator))
 
+(defn prefixed-name
+  "Builds a plugin-prefixed name. Returns the bare name when it
+   equals the plugin name, otherwise 'plugin:name'."
+  [plugin-name capability-name]
+  (if (= plugin-name capability-name)
+    plugin-name
+    (str plugin-name ":" capability-name)))
+
 (defn normalize-api-url [api-url]
   (some-> api-url
           string/trim
diff --git a/test/eca/features/commands_test.clj b/test/eca/features/commands_test.clj
@@ -5,6 +5,7 @@
    [clojure.test :refer [deftest is testing]]
    [eca.features.commands :as f.commands]
    [eca.features.rules :as f.rules]
+   [eca.shared :as shared]
    [eca.test-helper :as h]))
 
 (h/reset-components-before-test)
@@ -116,6 +117,29 @@
       (finally
         (fs/delete-tree tmp-dir)))))
 
+(deftest command-arguments-test
+  (let [tmp-dir (fs/create-temp-dir)]
+    (try
+      (testing "command with $ARG1 placeholder detects arguments"
+        (let [cmd-file (fs/file tmp-dir "greet.md")]
+          (spit cmd-file "Greet $ARG1!")
+          (let [config {:pureConfig true :commands [{:path (str cmd-file)}]}
+                result (vec (#'f.commands/custom-commands config []))]
+            (is (= 1 (count result)))
+            (is (= "greet" (:name (first result))))
+            (is (= [{:name "arg1" :required true}]
+                   (:arguments (first result)))))))
+
+      (testing "command without placeholders has empty arguments"
+        (let [cmd-file (fs/file tmp-dir "simple.md")]
+          (spit cmd-file "Simple body")
+          (let [config {:pureConfig true :commands [{:path (str cmd-file)}]}
+                result (vec (#'f.commands/custom-commands config []))]
+            (is (= [] (:arguments (first result)))))))
+
+      (finally
+        (fs/delete-tree tmp-dir)))))
+
 (deftest all-commands-include-model-command-test
   (let [commands (f.commands/all-commands {:workspace-folders []} {})]
     (is (some #(= {:name "model"
@@ -305,3 +329,49 @@
                                                   :metrics (h/metrics)})
             text (get-in result [:chats "chat-1" :messages 0 :content 0 :text])]
         (is (= "No rules available for the current agent and model." text))))))
+
+(deftest extract-args-from-content-test
+  (testing "detects $ARG1 placeholder"
+    (is (= [{:name "arg1" :required true}]
+           (shared/extract-args-from-content "Respond with $ARG1"))))
+
+  (testing "detects multiple $ARGn placeholders"
+    (is (= [{:name "arg1" :required true}
+            {:name "arg2" :required true}
+            {:name "arg3" :required true}]
+           (shared/extract-args-from-content "First:$ARG1 Second:$ARG2 Third:$ARG3"))))
+
+  (testing "detects $ARGS without $ARGn"
+    (is (= [{:name "arg1" :required true}]
+           (shared/extract-args-from-content "Use all args: $ARGS"))))
+
+  (testing "detects $ARGUMENTS without $ARGn"
+    (is (= [{:name "arg1" :required true}]
+           (shared/extract-args-from-content "Process $ARGUMENTS here"))))
+
+  (testing "detects Claude Code style $1 and $2"
+    (is (= [{:name "arg1" :required true}
+            {:name "arg2" :required true}]
+           (shared/extract-args-from-content "First:$1 Second:$2"))))
+
+  (testing "uses max of all placeholder styles"
+    (is (= [{:name "arg1" :required true}]
+           (shared/extract-args-from-content "$ARG1 $1"))))
+
+  (testing "returns empty vector when no placeholders present"
+    (is (= []
+           (shared/extract-args-from-content "No placeholders here"))))
+
+  (testing "returns empty vector for nil/blank content"
+    (is (= [] (shared/extract-args-from-content nil)))
+    (is (= [] (shared/extract-args-from-content ""))))
+
+  (testing "$ARGn takes precedence over $ARGS for argument count"
+    (is (= [{:name "arg1" :required true}]
+           (shared/extract-args-from-content "Single:$ARG1 All:$ARGS"))))
+
+  (testing "detects $ARG10 and declares all args up to 10"
+    (let [result (shared/extract-args-from-content "Use $ARG10")]
+      (is (= 10 (count result)))
+      (is (= {:name "arg1" :required true} (first result)))
+      (is (= {:name "arg10" :required true} (last result))))))

Original file line number	Diff line number	Diff line change
`@@ -1474,7 +1474,7 @@ interface ChatCommand {`
`1474`	`1474`	`arguments: [{`
`1475`	`1475`	`name: string;`
`1476`	`1476`	`description?: string;`
`1477`		`- required: boolean;`
	`1477`	`+ required?: boolean;`
`1478`	`1478`	`}];`
`1479`	`1479`	`}`
`1480`	`1480`	```