docs(addons): document the execution descriptor of a commands tool

Describe the descriptor for add-on authors: its fields, what the host
does with them, the API 2 requirement and the behavior of a manifest
that declares none. Add the new fields to the generated API docs.

Assisted-by: Claude Code:claude-sonnet-5-5
Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

docs/content/features/addons.md

@@ -139,7 +139,8 @@ and reconciling the operation before further use.
 ## Optional typed manifest extensions
 
 These declarations extend the strict manifest contract. They keep
-`schemaVersion: 1`, host/API/protocol/data-format level 1 and UI SDK 2.
+`schemaVersion: 1`, host/protocol/data-format level 1 and UI SDK 2. The manifest
+`api` range is 1 to 2: only the execution descriptor below needs 2.
 The Go contract parser is authoritative; there is no separate JSON Schema.
 The fragments below merge into an otherwise valid manifest, not a complete
 installable package. Existing executable, identity, compatibility and UI
@@ -287,6 +288,53 @@ list and rejects its pending responses, even before effect cleanup. A new list
 request can populate the refreshed session. These in-memory scopes contain no
 credentials.
 
+### Execution descriptor of a commands tool
+
+Needs manifest `api` 2. On the definition of a tool that shadows `bash`:
+
+```json
+{
+  "name": "bash",
+  "kind": "action",
+  "shadows": "bash",
+  "description": "...",
+  "inputSchema": { "...": "..." },
+  "execution": {
+    "class": "commands",
+    "title": "Runbox",
+    "note": "The environment has python3, jq and sqlite3.",
+    "skills": { "providesRuntimeFor": ["documents"] }
+  }
+}
+```
+
+The descriptor says what the add-on is, so that the host can write about it
+without knowing its ID. It grants no authority. Whether commands are ready and
+isolated stays what the provider reports in its execution status (see above);
+the host decides from that report.
+
+| Field | Meaning |
+|---|---|
+| `class` | Required. `commands`: the tool runs shell commands and code. |
+| `title` | Optional, at most 40 characters of plain text. The host calls the provider by this name in the prompt and in the Tools menu text ("Runbox runs commands in an isolated environment", "switch the Runbox add-on on"). Without it, the host uses the add-on's own title. |
+| `note` | Optional, at most 600 characters of plain text. One sentence for the model, such as the programs the environment has. The host adds it to the Commands block only while the provider reports `isolated`. |
+| `skills.providesRuntimeFor` | Optional list of skill kinds. `documents` means the add-on's document skills (`xlsx`, `docx`, `pptx`, `pdf`) run on this provider. |
+
+The host offers the document skills of an add-on only while that add-on serves
+the chat's commands and its status reports `isolated`. When the status is
+`host` or unknown, or another provider serves the commands, the skills are left
+out and the chat says why. A tool descriptor may leave `providesRuntimeFor`
+out to opt out of that check, because its skills do not need its commands.
+
+The field is optional and does not change the protocol. A manifest that
+declares a descriptor must accept API 2 (`"api": {"min": 1, "max": 2}`). The
+host speaks API 2 and still accepts add-ons that declare `{1,1}`. An add-on
+whose commands tool declares no descriptor works as before: the host treats it
+as a provider of commands under the add-on's own title, with no note, and keeps
+the isolation check for its document skills. The host never compares the add-on
+ID with a fixed name for any of this, so a second add-on that runs commands gets
+the same behavior with its own title.
+
 ### Requested host operations are not grants
 
 Inside `capabilities`:

swagger/docs.go

@@ -15140,6 +15140,43 @@ const docTemplate = `{
                 }
             }
         },
+        "contract.ExecutionDescriptor": {
+            "type": "object",
+            "properties": {
+                "class": {
+                    "description": "Class is ExecutionClassCommands.",
+                    "type": "string"
+                },
+                "note": {
+                    "description": "Note is one plain sentence for the model when the provider reports\nisolated execution, such as the programs its environment has.",
+                    "type": "string"
+                },
+                "skills": {
+                    "description": "Skills says which skills run on this provider.",
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/contract.ExecutionSkills"
+                        }
+                    ]
+                },
+                "title": {
+                    "description": "Title names the provider in the text the host shows the person and the\nmodel, for example \"Sandbox\". It falls back to the add-on's title.",
+                    "type": "string"
+                }
+            }
+        },
+        "contract.ExecutionSkills": {
+            "type": "object",
+            "properties": {
+                "providesRuntimeFor": {
+                    "description": "ProvidesRuntimeFor lists skill kinds (SkillKindDocuments). The host\noffers the add-on's skills of those kinds only while the provider\nreports isolated execution.",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
         "contract.OutputDescription": {
             "type": "object",
             "properties": {
@@ -15271,6 +15308,14 @@ const docTemplate = `{
                     "description": "Description is plain text for the model.",
                     "type": "string"
                 },
+                "execution": {
+                    "description": "Execution declares that this tool runs commands and what the host may\nsay about the provider. Only a tool that shadows bash may declare it, and\nthe manifest must then accept API 2 (see MinExecutionAPI).",
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/contract.ExecutionDescriptor"
+                        }
+                    ]
+                },
                 "inputSchema": {
                     "description": "InputSchema is the JSON schema of the arguments object. It is an\nobject schema with explicit properties, additionalProperties false at\nthe top level and the keywords the host allows only.",
                     "type": "object"

swagger/swagger.json

@@ -15137,6 +15137,43 @@
                 }
             }
         },
+        "contract.ExecutionDescriptor": {
+            "type": "object",
+            "properties": {
+                "class": {
+                    "description": "Class is ExecutionClassCommands.",
+                    "type": "string"
+                },
+                "note": {
+                    "description": "Note is one plain sentence for the model when the provider reports\nisolated execution, such as the programs its environment has.",
+                    "type": "string"
+                },
+                "skills": {
+                    "description": "Skills says which skills run on this provider.",
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/contract.ExecutionSkills"
+                        }
+                    ]
+                },
+                "title": {
+                    "description": "Title names the provider in the text the host shows the person and the\nmodel, for example \"Sandbox\". It falls back to the add-on's title.",
+                    "type": "string"
+                }
+            }
+        },
+        "contract.ExecutionSkills": {
+            "type": "object",
+            "properties": {
+                "providesRuntimeFor": {
+                    "description": "ProvidesRuntimeFor lists skill kinds (SkillKindDocuments). The host\noffers the add-on's skills of those kinds only while the provider\nreports isolated execution.",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
         "contract.OutputDescription": {
             "type": "object",
             "properties": {
@@ -15268,6 +15305,14 @@
                     "description": "Description is plain text for the model.",
                     "type": "string"
                 },
+                "execution": {
+                    "description": "Execution declares that this tool runs commands and what the host may\nsay about the provider. Only a tool that shadows bash may declare it, and\nthe manifest must then accept API 2 (see MinExecutionAPI).",
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/contract.ExecutionDescriptor"
+                        }
+                    ]
+                },
                 "inputSchema": {
                     "description": "InputSchema is the JSON schema of the arguments object. It is an\nobject schema with explicit properties, additionalProperties false at\nthe top level and the keywords the host allows only.",
                     "type": "object"

swagger/swagger.yaml

@@ -627,6 +627,37 @@ definitions:
       name:
         type: string
     type: object
+  contract.ExecutionDescriptor:
+    properties:
+      class:
+        description: Class is ExecutionClassCommands.
+        type: string
+      note:
+        description: |-
+          Note is one plain sentence for the model when the provider reports
+          isolated execution, such as the programs its environment has.
+        type: string
+      skills:
+        allOf:
+        - $ref: '#/definitions/contract.ExecutionSkills'
+        description: Skills says which skills run on this provider.
+      title:
+        description: |-
+          Title names the provider in the text the host shows the person and the
+          model, for example "Sandbox". It falls back to the add-on's title.
+        type: string
+    type: object
+  contract.ExecutionSkills:
+    properties:
+      providesRuntimeFor:
+        description: |-
+          ProvidesRuntimeFor lists skill kinds (SkillKindDocuments). The host
+          offers the add-on's skills of those kinds only while the provider
+          reports isolated execution.
+        items:
+          type: string
+        type: array
+    type: object
   contract.OutputDescription:
     properties:
       handle:
@@ -724,6 +755,13 @@ definitions:
       description:
         description: Description is plain text for the model.
         type: string
+      execution:
+        allOf:
+        - $ref: '#/definitions/contract.ExecutionDescriptor'
+        description: |-
+          Execution declares that this tool runs commands and what the host may
+          say about the provider. Only a tool that shadows bash may declare it, and
+          the manifest must then accept API 2 (see MinExecutionAPI).
       inputSchema:
         description: |-
           InputSchema is the JSON schema of the arguments object. It is an