Skip to content

Agent Zero AI framework

Improve built-in command management

Alessandro56608489401f
diff --git a/plugins/_commands/AGENTS.md b/plugins/_commands/AGENTS.md
index f9c0a0e61..d40b57e1c 100644
--- a/plugins/_commands/AGENTS.md
+++ b/plugins/_commands/AGENTS.md
@@ -12,7 +12,7 @@
- `api/commands.py` owns the Commands API actions used by the WebUI.
- `webui/` owns the manager/editor modal stores, HTML surfaces, and thumbnail asset.
- `commands/` owns bundled read-only slash command definitions shipped by `_commands`.
-- `extensions/` owns the chat composer picker and sidebar quick-action entry.
+- `extensions/` owns the chat composer slash picker.
- `extensions/python/startup_migration/` owns one-time migration from the legacy community `commands` plugin namespace.
- `skills/commands-create-slash-command/` owns the agent-facing authoring workflow for reusable slash commands.
- `tests/` owns regression coverage for parsing, CRUD, scope precedence, plugin-distributed commands, legacy migration, and skill discovery.
@@ -23,6 +23,7 @@
- Each command is one `.command.yaml` config plus one same-directory `.txt` text template or `.py` script hook.
- Project commands override global commands, global commands override bundled `_commands/commands/` defaults, and bundled defaults override other plugin-distributed commands with the same name.
- Bundled `_commands/commands/` definitions and commands contributed by other plugins are read-only from this manager.
+- The manager lists bundled commands separately; editing one copies it unchanged into the selected project or global scope under the same name, then edits that higher-precedence override.
- Bundled command files use canonical command names only; do not ship alias-only built-ins such as `/img` for `/attach`.
- Command configs may set `webui_hidden: true` to stay resolvable but be omitted from the chat composer picker.
- Commands contributed by enabled plugins live in their `commands/` directory and must not be rediscovered through the generic plugin-distributed path from `_commands` itself.
@@ -34,6 +35,7 @@
- Keep the command storage and route namespace aligned with `_commands`.
- Preserve unknown command config keys when editing commands.
+- Keep built-in source files immutable; user edits must be same-name scope overrides.
- Keep WebUI paths pointed at `/plugins/_commands/...`.
## Verification
diff --git a/plugins/_commands/README.md b/plugins/_commands/README.md
index 6758987da..68e16352a 100644
--- a/plugins/_commands/README.md
+++ b/plugins/_commands/README.md
@@ -137,8 +137,7 @@ When the built-in `_commands` plugin starts, it migrates files from the older co
## UI Surfaces
-- Plugin modal: open the Commands manager from the Plugins dialog
-- Sidebar quick action: terminal icon next to the Plugins button
+- Plugin modal: manage project/global commands and create editable same-name overrides of bundled commands
- Chat composer: type `/` at the start of the inline input to browse commands
## Agent Skill
diff --git a/plugins/_commands/api/commands.py b/plugins/_commands/api/commands.py
index 9faf00315..e2f3b6461 100644
--- a/plugins/_commands/api/commands.py
+++ b/plugins/_commands/api/commands.py
@@ -51,6 +51,7 @@ class Commands(ApiHandler):
return {
"ok": True,
"commands": commands,
+ "builtin_commands": commands_helper.list_builtin_commands(),
"scope": scope,
}
diff --git a/plugins/_commands/extensions/webui/sidebar-quick-actions-main-start/commands-entry.html b/plugins/_commands/extensions/webui/sidebar-quick-actions-main-start/commands-entry.html
deleted file mode 100644
index f8be2790f..000000000
--- a/plugins/_commands/extensions/webui/sidebar-quick-actions-main-start/commands-entry.html
+++ /dev/null
@@ -1,9 +0,0 @@
-<div x-data>
- <button x-move-after=".config-button#plugins"
- class="config-button"
- id="commands-plugin"
- title="Commands"
- @click="import('/plugins/_commands/webui/commands-store.js').then(({ store }) => store.openManager())">
- <span class="material-symbols-outlined">terminal</span>
- </button>
-</div>
diff --git a/plugins/_commands/helpers/commands.py b/plugins/_commands/helpers/commands.py
index 24544c1aa..1c3b95e30 100644
--- a/plugins/_commands/helpers/commands.py
+++ b/plugins/_commands/helpers/commands.py
@@ -336,6 +336,11 @@ def list_effective_commands(
return effective, strip_private_scope(resolved_scope)
+def list_builtin_commands() -> list[dict[str, Any]]:
+ """Return bundled commands for display in the command manager."""
+ return sorted(_discover_builtin_commands(), key=lambda item: item["name"])
+
+
def get_command(
path: str,
project_name: str = "",
@@ -489,7 +494,7 @@ def duplicate_command(
project_name: str = "",
agent_profile: str = "",
) -> dict[str, Any]:
- """Duplicate an existing command, assigning it a unique ``-copy`` suffixed name.
+ """Duplicate a command, preserving built-in names so the copy overrides the default.
Returns the newly created command dict.
@@ -499,7 +504,11 @@ def duplicate_command(
"""
command = get_command(path, project_name, "")
- duplicated_name = _generate_duplicate_name(command["name"], project_name=project_name)
+ duplicated_name = (
+ command["name"]
+ if command.get("scope_key") == "builtin"
+ else _generate_duplicate_name(command["name"], project_name=project_name)
+ )
return save_command(
project_name=project_name,
name=duplicated_name,
diff --git a/plugins/_commands/tests/test_commands_plugin.py b/plugins/_commands/tests/test_commands_plugin.py
index 7cb4333a2..7143cfaa5 100644
--- a/plugins/_commands/tests/test_commands_plugin.py
+++ b/plugins/_commands/tests/test_commands_plugin.py
@@ -190,6 +190,32 @@ def test_list_effective_commands_project_overrides_global(
assert scoped_command["override_scopes"] == ["Global"]
+def test_duplicate_builtin_creates_same_name_project_override(
+ scope_fixture: ScopeFixture,
+) -> None:
+ builtin = next(
+ command
+ for command in commands_helper.list_builtin_commands()
+ if command["name"] == "new"
+ )
+
+ override = _track_paths(
+ scope_fixture,
+ commands_helper.duplicate_command(
+ builtin["path"],
+ project_name=scope_fixture.project_name,
+ ),
+ )
+
+ assert override["name"] == builtin["name"]
+ assert override["scope_label"] == "Project"
+ assert override["body"] == builtin["body"]
+
+ effective, _ = commands_helper.list_effective_commands(scope_fixture.project_name)
+ resolved = next(command for command in effective if command["name"] == "new")
+ assert resolved["path"] == override["path"]
+
+
def test_models_command_always_opens_modal():
result = connector_commands.run(
{
diff --git a/plugins/_commands/tests/test_plugin_command_discovery.py b/plugins/_commands/tests/test_plugin_command_discovery.py
index 9a371ef1c..a918f0597 100644
--- a/plugins/_commands/tests/test_plugin_command_discovery.py
+++ b/plugins/_commands/tests/test_plugin_command_discovery.py
@@ -147,6 +147,9 @@ def test_discover_builtin_commands_marks_own_commands_read_only():
with pytest.raises(ValueError, match="Built-in commands are read-only"):
commands_helper.delete_command(command["path"])
+ response = object.__new__(Commands)._list_scope({"project_name": ""})
+ assert "new" in {item["name"] for item in response["builtin_commands"]}
+
def test_builtin_commands_use_canonical_names_only():
discovered = commands_helper._discover_builtin_commands()
diff --git a/plugins/_commands/webui/commands-store.js b/plugins/_commands/webui/commands-store.js
index 8cae2b843..7006960e4 100644
--- a/plugins/_commands/webui/commands-store.js
+++ b/plugins/_commands/webui/commands-store.js
@@ -81,6 +81,7 @@ const model = {
scope: null,
contextScope: { project_name: "" },
commands: [],
+ builtinCommands: [],
pendingScope: null,
pendingCreate: null,
editor: createEmptyEditor(),
@@ -90,10 +91,6 @@ const model = {
return this.scope?.scope_label || "Global";
},
- get selectedScopeDirectory() {
- return this.scope?.directory_path || "";
- },
-
get hasCommands() {
return (this.commands || []).length > 0;
},
@@ -139,6 +136,7 @@ const model = {
console.error("Failed to initialize commands manager:", error);
this.scope = null;
this.commands = [];
+ this.builtinCommands = [];
notifyError(error?.message || "Failed to open the commands manager.");
}
@@ -157,6 +155,7 @@ const model = {
this.scope = null;
this.contextScope = { project_name: "" };
this.commands = [];
+ this.builtinCommands = [];
this.pendingScope = null;
this.pendingCreate = null;
this.resetEditor();
@@ -205,10 +204,14 @@ const model = {
});
this.commands = Array.isArray(response?.commands) ? response.commands : [];
+ this.builtinCommands = Array.isArray(response?.builtin_commands)
+ ? response.builtin_commands
+ : [];
this.scope = response?.scope || null;
} catch (error) {
console.error("Failed to load commands:", error);
this.commands = [];
+ this.builtinCommands = [];
this.scope = null;
notifyError(error?.message || "Failed to load commands.");
} finally {
@@ -225,13 +228,31 @@ const model = {
await this.loadCommands();
},
- overrideBadgeLabel(command) {
- const count = Number(command?.override_count || 0);
- if (!count) return "";
- if (count === 1) {
- return `Overrides ${command.override_scopes[0]}`;
+ scopedOverride(command) {
+ return (this.commands || []).find((item) => item.name === command?.name);
+ },
+
+ async editBuiltinCommand(command) {
+ const existing = this.scopedOverride(command);
+ if (existing) {
+ await this.openEditCommand(existing);
+ return;
+ }
+
+ try {
+ const response = await callJsonApi(COMMANDS_API_PATH, {
+ action: "duplicate",
+ path: command.path,
+ project_name: this.projectName || "",
+ });
+ await this.loadCommands();
+ emitCommandsUpdated();
+ notifySuccess(`Created ${this.selectedScopeLabel} override for /${command.name}`);
+ if (response?.command) await this.openEditCommand(response.command);
+ } catch (error) {
+ console.error("Failed to create command override:", error);
+ notifyError(error?.message || "Failed to create command override.");
}
- return `Overrides ${count} lower scopes`;
},
async browseScopeFolder() {
diff --git a/plugins/_commands/webui/main.html b/plugins/_commands/webui/main.html
index dde4b6e62..0f7322264 100644
--- a/plugins/_commands/webui/main.html
+++ b/plugins/_commands/webui/main.html
@@ -45,20 +45,17 @@
</div>
</div>
- <div class="commands-scope-banner" x-show="$store.commandsManager.scope">
- <div class="commands-scope-banner-label">
- <span class="material-symbols-outlined">target</span>
- <span x-text="$store.commandsManager.selectedScopeLabel"></span>
- </div>
- <div class="commands-scope-banner-path" x-text="$store.commandsManager.selectedScopeDirectory"></div>
- </div>
-
<div class="commands-loading" x-show="$store.commandsManager.loading">
<span class="material-symbols-outlined spinning">progress_activity</span>
<span>Loading commands...</span>
</div>
<div class="commands-list" x-show="!$store.commandsManager.loading">
+ <div class="commands-section-heading">
+ <div class="commands-section-title" x-text="`${$store.commandsManager.selectedScopeLabel} commands`"></div>
+ <div class="commands-section-copy">Editable commands saved in the selected scope.</div>
+ </div>
+
<template x-if="$store.commandsManager.hasCommands">
<div class="commands-grid">
<template x-for="command in $store.commandsManager.commands" :key="command.path">
@@ -84,21 +81,6 @@
</div>
</div>
- <div class="commands-card-badges">
- <span class="commands-badge scope" x-text="command.scope_label"></span>
- <span class="commands-badge type" x-text="command.command_type === 'script' ? 'Python Hook' : 'Text Template'"></span>
- <template x-if="command.override_count">
- <span class="commands-badge override" x-text="$store.commandsManager.overrideBadgeLabel(command)"></span>
- </template>
- </div>
-
- <template x-if="command.argument_hint">
- <div class="commands-card-hint">
- <span class="material-symbols-outlined">subdirectory_arrow_right</span>
- <span x-text="command.argument_hint"></span>
- </div>
- </template>
-
<div class="commands-card-path" x-text="command.path"></div>
</article>
</template>
@@ -117,6 +99,41 @@
</button>
</div>
</template>
+
+ <template x-if="$store.commandsManager.builtinCommands.length">
+ <section class="commands-section">
+ <div class="commands-section-heading">
+ <div class="commands-section-title">Built-in commands</div>
+ <div class="commands-section-copy">
+ Editing creates an override in <span x-text="$store.commandsManager.selectedScopeLabel"></span>; core files stay unchanged.
+ </div>
+ </div>
+
+ <div class="commands-grid">
+ <template x-for="command in $store.commandsManager.builtinCommands" :key="command.path">
+ <article class="commands-card">
+ <div class="commands-card-header">
+ <div class="commands-card-copy">
+ <div class="commands-card-title">
+ <span class="commands-slash">/</span><span x-text="command.name"></span>
+ </div>
+ <div class="commands-card-description" x-text="command.description"></div>
+ </div>
+
+ <button type="button"
+ class="button icon"
+ :title="$store.commandsManager.scopedOverride(command) ? 'Edit override' : 'Create editable override'"
+ :aria-label="$store.commandsManager.scopedOverride(command) ? `Edit /${command.name} override` : `Create editable /${command.name} override`"
+ @click="$store.commandsManager.editBuiltinCommand(command)">
+ <span class="material-symbols-outlined">edit</span>
+ </button>
+ </div>
+
+ </article>
+ </template>
+ </div>
+ </section>
+ </template>
</div>
</div>
</template>
@@ -184,31 +201,6 @@
margin-left: auto;
}
- .commands-scope-banner {
- display: flex;
- flex-wrap: wrap;
- gap: 0.75rem;
- align-items: center;
- padding: 0.85rem 1rem;
- border: 1px solid var(--color-border);
- border-radius: 12px;
- background: color-mix(in srgb, var(--color-background) 84%, var(--color-panel));
- }
-
- .commands-scope-banner-label {
- display: inline-flex;
- align-items: center;
- gap: 0.45rem;
- font-weight: 600;
- }
-
- .commands-scope-banner-path {
- color: var(--color-text-secondary);
- font-family: "Roboto Mono", monospace;
- font-size: 0.82rem;
- word-break: break-all;
- }
-
.commands-loading {
display: flex;
align-items: center;
@@ -228,6 +220,25 @@
gap: 0.9rem;
}
+ .commands-section {
+ margin-top: 1.25rem;
+ }
+
+ .commands-section-heading {
+ margin-bottom: 0.75rem;
+ }
+
+ .commands-section-title {
+ font-size: 1rem;
+ font-weight: 600;
+ }
+
+ .commands-section-copy {
+ margin-top: 0.2rem;
+ color: var(--color-text-secondary);
+ font-size: 0.86rem;
+ }
+
.commands-card {
display: flex;
flex-direction: column;
@@ -262,8 +273,8 @@
.commands-card-description {
margin-top: 0.25rem;
color: var(--color-text-secondary);
- font-size: 0.9rem;
- line-height: 1.45;
+ font-size: 0.82rem;
+ line-height: 1.35;
}
.commands-card-actions {
@@ -272,50 +283,6 @@
flex-shrink: 0;
}
- .commands-card-badges {
- display: flex;
- flex-wrap: wrap;
- gap: 0.45rem;
- }
-
- .commands-badge {
- display: inline-flex;
- align-items: center;
- padding: 0.22rem 0.5rem;
- border-radius: 999px;
- font-size: 0.74rem;
- font-weight: 600;
- border: 1px solid transparent;
- }
-
- .commands-badge.scope {
- background: color-mix(in srgb, var(--color-highlight) 12%, transparent);
- border-color: color-mix(in srgb, var(--color-highlight) 24%, transparent);
- }
-
- .commands-badge.override {
- background: color-mix(in srgb, #f39c12 12%, transparent);
- border-color: color-mix(in srgb, #f39c12 28%, transparent);
- }
-
- .commands-badge.type {
- background: color-mix(in srgb, #5b8def 12%, transparent);
- border-color: color-mix(in srgb, #5b8def 30%, transparent);
- }
-
- .commands-card-hint {
- display: inline-flex;
- align-items: flex-start;
- gap: 0.35rem;
- color: var(--color-text-secondary);
- font-size: 0.86rem;
- }
-
- .commands-card-hint .material-symbols-outlined {
- font-size: 1rem;
- margin-top: 0.05rem;
- }
-
.commands-card-path {
color: var(--color-text-secondary);
font-family: "Roboto Mono", monospace;