Skip to content

Agent Zero AI framework

Add built-in slash commands plugin

Alessandro9c9a4e00ca84
diff --git a/plugins/AGENTS.md b/plugins/AGENTS.md
index c5f604708..c913b12f1 100644
--- a/plugins/AGENTS.md
+++ b/plugins/AGENTS.md
@@ -70,6 +70,7 @@ Direct child DOX files:
| [_browser/AGENTS.md](_browser/AGENTS.md) | Playwright browser tool, helpers, viewer, and browser panel UI. |
| [_chat_branching/AGENTS.md](_chat_branching/AGENTS.md) | Chat branching from an existing message. |
| [_chat_compaction/AGENTS.md](_chat_compaction/AGENTS.md) | Full-chat compaction into a summary message. |
+| [_commands/AGENTS.md](_commands/AGENTS.md) | Built-in slash command manager, command file discovery, and chat composer slash picker. |
| [_code_execution/AGENTS.md](_code_execution/AGENTS.md) | Terminal, Python, and Node.js execution tools and shell runtimes. |
| [_desktop/AGENTS.md](_desktop/AGENTS.md) | Linux desktop runtime, sessions, and desktop surface. |
| [_discovery/AGENTS.md](_discovery/AGENTS.md) | Welcome-screen plugin discovery cards and promotions. |
diff --git a/plugins/_commands/AGENTS.md b/plugins/_commands/AGENTS.md
new file mode 100644
index 000000000..92b2a89e7
--- /dev/null
+++ b/plugins/_commands/AGENTS.md
@@ -0,0 +1,44 @@
+# Commands Plugin DOX
+
+## Purpose
+
+- Own the built-in slash command manager and chat composer slash picker.
+- Keep file-backed `/command` discovery consistent across project, global, and plugin-provided scopes.
+
+## Ownership
+
+- `plugin.yaml` owns the built-in `_commands` plugin metadata.
+- `helpers/commands.py` owns command name sanitization, argument parsing, scope resolution, file persistence, plugin command discovery, and command invocation resolution.
+- `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/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.
+
+## Local Contracts
+
+- The plugin identity is `_commands`; user-created command files live under `usr/plugins/_commands/commands/` or `usr/projects/<project>/.a0proj/plugins/_commands/commands/`.
+- 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.
+- 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.
+- On startup, `_commands` copies legacy `usr/plugins/commands` command and skill files into `usr/plugins/_commands` without overwriting existing files, copies scoped legacy command folders to `_commands`, and disables the legacy `commands` plugin roots to prevent duplicate WebUI popovers.
+- Script commands must expose `run(payload)` and return a string or a dict with `text` and optional `effects`; `show_markdown` effects render as auto-dismissing toast notifications.
+
+## Work Guidance
+
+- Keep the command storage and route namespace aligned with `_commands`.
+- Preserve unknown command config keys when editing commands.
+- Keep WebUI paths pointed at `/plugins/_commands/...`.
+
+## Verification
+
+- Run `conda run -n a0 pytest plugins/_commands/tests` after backend or command contract changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_commands/LICENSE b/plugins/_commands/LICENSE
new file mode 100644
index 000000000..e4e068e76
--- /dev/null
+++ b/plugins/_commands/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Commands plugin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/plugins/_commands/README.md b/plugins/_commands/README.md
new file mode 100644
index 000000000..6758987da
--- /dev/null
+++ b/plugins/_commands/README.md
@@ -0,0 +1,146 @@
+# Commands
+
+YAML-configured slash commands for Agent Zero.
+
+This plugin lets you define reusable `/commands` as `.command.yaml` files with either:
+
+- a `.txt` template body
+- a `.py` script hook
+
+Commands are managed from the plugin modal and can be inserted directly from the chat composer when the first token starts with `/`.
+
+## Features
+
+- `.command.yaml` config files with command metadata
+- Text template commands with `{}` placeholders and parsed args
+- Python hook commands with parsed args and optional chat history payload
+- Unified parser for positional args, free-form tail, and flags
+- Scope-aware command resolution across project and global scopes
+- Built-in A0 CLI connector command pack for common session, queue, model, project, browser, and connector status commands
+- Slash picker in the chat composer with keyboard navigation and create-on-empty flow
+
+## Command File Model
+
+Each command is defined by one config file plus one content file in the same scope directory.
+Set `webui_hidden: true` to keep a command resolvable while omitting it from the chat composer picker.
+
+Example text command:
+
+`scan.command.yaml`
+
+```yaml
+name: scan
+description: Scan a Git repository.
+argument_hint: /scan --git-url https://github.com/org/repo
+type: text
+template_path: scan.txt
+```
+
+`scan.txt`
+
+```txt
+Please scan repository: {args.flags.git_url}
+
+Raw input:
+{raw}
+```
+
+Example python hook command:
+
+`optimize.command.yaml`
+
+```yaml
+name: optimize
+description: Optimize the current request.
+argument_hint: /optimize 30%
+type: script
+script_path: optimize.py
+include_history: true
+```
+
+`optimize.py`
+
+```python
+def run(payload):
+ args = payload["arguments"]
+ pct = args["positional"][0] if args["positional"] else "10%"
+ return {
+ "text": f"Optimize this response by {pct}.",
+ "effects": [],
+ }
+```
+
+## Argument Parsing
+
+The parser supports:
+
+- Positional input: `/scan https://github.com/org/repo`
+- Long flags: `/scan --git-url https://github.com/org/repo`
+- Long flags with equals: `/scan --git-url=https://github.com/org/repo`
+- Short flags and bundles: `/scan -v -q` or `/scan -vq`
+
+Parsed data is available to:
+
+- Text templates via `{}` placeholders:
+ - `{raw}`
+ - `{args.positional.0}`
+ - `{args.flags.git_url}`
+- Python scripts via `payload["arguments"]`
+
+## Script Hook Contract
+
+Python hook file must expose:
+
+```python
+def run(payload): ...
+```
+
+It can return:
+
+- `str` (used as replacement text)
+- `dict` with:
+ - `text: str` (replacement text)
+ - `effects: list[dict]`
+
+Supported frontend effects:
+
+- `{"type": "replace_input", "text": "..."}`
+- `{"type": "append_input", "text": "..."}`
+- `{"type": "toast", "level": "info|error|success", "message": "..."}`
+- Built-in UI effects for existing WebUI actions such as chat switching, modals, attachments, compaction, queue actions, transcript copy, and toast output
+
+## Scope Resolution
+
+Commands are discovered from these scope folders:
+
+- Project: `usr/projects/<project>/.a0proj/plugins/_commands/commands/`
+- Global fallback: `usr/plugins/_commands/commands/`
+- Built-in defaults: `plugins/_commands/commands/`
+- Other enabled plugins: `plugins/<plugin>/commands/` or `usr/plugins/<plugin>/commands/`
+
+Precedence in the chat picker:
+
+1. Project
+2. Global
+3. Built-in `_commands`
+4. Other plugin-distributed commands
+
+## Legacy Community Plugin Migration
+
+When the built-in `_commands` plugin starts, it migrates files from the older community `commands` plugin namespace:
+
+- Copies `usr/plugins/commands/commands/` into `usr/plugins/_commands/commands/`
+- Copies `usr/plugins/commands/skills/` into `usr/plugins/_commands/skills/`
+- Copies project and agent scoped `plugins/commands/commands/` folders to matching `plugins/_commands/commands/` folders
+- Skips existing destination files
+- Disables the legacy `commands` plugin roots so the WebUI does not load two slash-command popovers
+
+## UI Surfaces
+
+- Plugin modal: open the Commands manager from the Plugins dialog
+- Sidebar quick action: terminal icon next to the Plugins button
+- Chat composer: type `/` at the start of the inline input to browse commands
+
+## Agent Skill
+
+The plugin ships with `commands-create-slash-command`, a plugin-scoped skill that helps Agent Zero create or update command files.
diff --git a/plugins/_commands/__init__.py b/plugins/_commands/__init__.py
new file mode 100644
index 000000000..87a5785df
--- /dev/null
+++ b/plugins/_commands/__init__.py
@@ -0,0 +1 @@
+"""Commands plugin package."""
diff --git a/plugins/_commands/api/commands.py b/plugins/_commands/api/commands.py
new file mode 100644
index 000000000..9faf00315
--- /dev/null
+++ b/plugins/_commands/api/commands.py
@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from helpers.api import ApiHandler, Request, Response
+
+from plugins._commands.helpers import commands as commands_helper
+
+
+class Commands(ApiHandler):
+ async def process(self, input: dict, request: Request) -> dict | Response:
+ action = str(input.get("action", "") or "").strip()
+
+ if action == "list_effective":
+ return self._list_effective(input)
+ if action == "list_scope":
+ return self._list_scope(input)
+ if action == "get":
+ return self._get(input)
+ if action == "save":
+ return self._save(input)
+ if action == "delete":
+ return self._delete(input)
+ if action == "duplicate":
+ return self._duplicate(input)
+ if action == "scope_info":
+ return self._scope_info(input)
+ if action == "resolve":
+ return await self._resolve(input)
+
+ return Response(status=400, response=f"Unknown action: {action}")
+
+ def _list_effective(self, input: dict) -> dict | Response:
+ context_scope = commands_helper.get_context_scope(str(input.get("context_id", "") or ""))
+ commands, scope = commands_helper.list_effective_commands(
+ project_name=context_scope["project_name"],
+ )
+ commands = [
+ command
+ for command in commands
+ if not command.get("frontmatter_extra", {}).get("webui_hidden")
+ ]
+ return {
+ "ok": True,
+ "commands": commands,
+ "scope": scope,
+ }
+
+ def _list_scope(self, input: dict) -> dict | Response:
+ commands, scope = commands_helper.list_scope_commands(
+ project_name=str(input.get("project_name", "") or ""),
+ )
+ return {
+ "ok": True,
+ "commands": commands,
+ "scope": scope,
+ }
+
+ def _get(self, input: dict) -> dict | Response:
+ path = str(input.get("path", "") or "")
+ if not path:
+ return Response(status=400, response="Missing path")
+
+ try:
+ command = commands_helper.get_command(
+ path,
+ project_name=str(input.get("project_name", "") or ""),
+ )
+ except FileNotFoundError:
+ return Response(status=404, response="Command not found")
+ except ValueError as error:
+ return Response(status=400, response=str(error))
+
+ return {"ok": True, "command": command}
+
+ def _save(self, input: dict) -> dict | Response:
+ try:
+ command = commands_helper.save_command(
+ project_name=str(input.get("project_name", "") or ""),
+ existing_path=str(input.get("existing_path", "") or ""),
+ name=str(input.get("name", "") or ""),
+ description=str(input.get("description", "") or ""),
+ argument_hint=str(input.get("argument_hint", "") or ""),
+ command_type=str(input.get("command_type", "text") or "text"),
+ body=str(input.get("body", "") or ""),
+ include_history=bool(input.get("include_history", False)),
+ extra_frontmatter=input.get("extra_frontmatter", {}) or {},
+ )
+ except FileExistsError as error:
+ return Response(status=409, response=str(error))
+ except ValueError as error:
+ return Response(status=400, response=str(error))
+
+ return {"ok": True, "command": command}
+
+ def _delete(self, input: dict) -> dict | Response:
+ path = str(input.get("path", "") or "")
+ if not path:
+ return Response(status=400, response="Missing path")
+
+ try:
+ commands_helper.delete_command(
+ path,
+ project_name=str(input.get("project_name", "") or ""),
+ )
+ except FileNotFoundError:
+ return Response(status=404, response="Command not found")
+ except ValueError as error:
+ return Response(status=400, response=str(error))
+
+ return {"ok": True}
+
+ def _duplicate(self, input: dict) -> dict | Response:
+ path = str(input.get("path", "") or "")
+ if not path:
+ return Response(status=400, response="Missing path")
+
+ try:
+ command = commands_helper.duplicate_command(
+ path,
+ project_name=str(input.get("project_name", "") or ""),
+ )
+ except FileNotFoundError:
+ return Response(status=404, response="Command not found")
+ except ValueError as error:
+ return Response(status=400, response=str(error))
+
+ return {"ok": True, "command": command}
+
+ def _scope_info(self, input: dict) -> dict | Response:
+ explicit_project = str(input.get("project_name", "") or "")
+ context_scope = commands_helper.get_context_scope(str(input.get("context_id", "") or ""))
+
+ project_name = explicit_project if "project_name" in input else context_scope["project_name"]
+
+ scope = commands_helper.get_scope_payload(
+ project_name=project_name,
+ ensure_directory=bool(input.get("ensure_directory", False)),
+ )
+ return {
+ "ok": True,
+ "scope": commands_helper.strip_private_scope(scope),
+ "context_scope": context_scope,
+ }
+
+ async def _resolve(self, input: dict) -> dict | Response:
+ path = str(input.get("path", "") or "")
+ if not path:
+ return Response(status=400, response="Missing path")
+
+ slash_text = str(input.get("slash_text", "") or "")
+ if not slash_text:
+ return Response(status=400, response="Missing slash_text")
+
+ try:
+ resolution = await commands_helper.resolve_command_invocation(
+ path=path,
+ slash_text=slash_text,
+ project_name=str(input.get("project_name", "") or ""),
+ context_id=str(input.get("context_id", "") or ""),
+ )
+ except FileNotFoundError:
+ return Response(status=404, response="Command not found")
+ except ValueError as error:
+ return Response(status=400, response=str(error))
+
+ return {"ok": True, "resolution": resolution}
diff --git a/plugins/_commands/commands/attach.command.yaml b/plugins/_commands/commands/attach.command.yaml
new file mode 100644
index 000000000..081ca8426
--- /dev/null
+++ b/plugins/_commands/commands/attach.command.yaml
@@ -0,0 +1,5 @@
+name: attach
+description: Attach local image file(s) to the next message.
+argument_hint: Choose local file(s) from the WebUI picker.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/browser.command.yaml b/plugins/_commands/commands/browser.command.yaml
new file mode 100644
index 000000000..09755852a
--- /dev/null
+++ b/plugins/_commands/commands/browser.command.yaml
@@ -0,0 +1,5 @@
+name: browser
+description: Choose Browser host/container mode and manage host-browser control.
+argument_hint: "[host|container|status]"
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/chat.command.yaml b/plugins/_commands/commands/chat.command.yaml
new file mode 100644
index 000000000..f65ef20bc
--- /dev/null
+++ b/plugins/_commands/commands/chat.command.yaml
@@ -0,0 +1,5 @@
+name: chat
+description: Switch to a chat context by id.
+argument_hint: "<context_id>"
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/chats.command.yaml b/plugins/_commands/commands/chats.command.yaml
new file mode 100644
index 000000000..85b18b9a9
--- /dev/null
+++ b/plugins/_commands/commands/chats.command.yaml
@@ -0,0 +1,6 @@
+name: chats
+description: List previous chats (default sorted by last updated). Use --project to filter by active project.
+argument_hint: "[--project|--all-projects] [--sort=updated|created|name]"
+type: script
+script_path: connector_commands.py
+webui_hidden: true
diff --git a/plugins/_commands/commands/clear.command.yaml b/plugins/_commands/commands/clear.command.yaml
new file mode 100644
index 000000000..0b52d1464
--- /dev/null
+++ b/plugins/_commands/commands/clear.command.yaml
@@ -0,0 +1,4 @@
+name: clear
+description: Clear the visible chat log.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/compact.command.yaml b/plugins/_commands/commands/compact.command.yaml
new file mode 100644
index 000000000..afd41eb92
--- /dev/null
+++ b/plugins/_commands/commands/compact.command.yaml
@@ -0,0 +1,4 @@
+name: compact
+description: Open the connector-backed compaction confirmation flow.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/computer-use.command.yaml b/plugins/_commands/commands/computer-use.command.yaml
new file mode 100644
index 000000000..f0b4e68ce
--- /dev/null
+++ b/plugins/_commands/commands/computer-use.command.yaml
@@ -0,0 +1,5 @@
+name: computer-use
+description: Turn local Computer Use on or off.
+argument_hint: "[on|off|status]"
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/connector_commands.py b/plugins/_commands/commands/connector_commands.py
new file mode 100644
index 000000000..1f2073e98
--- /dev/null
+++ b/plugins/_commands/commands/connector_commands.py
@@ -0,0 +1,305 @@
+from __future__ import annotations
+
+from typing import Any
+
+from agent import AgentContext
+from helpers import message_queue as mq
+from helpers import plugins, projects
+from helpers.integration_commands import try_handle_command
+from helpers.state_monitor_integration import mark_dirty_for_context
+
+CLI_ONLY = {
+ "quit": "Quit is an A0 CLI shell command. Close this browser tab or stop the WebUI session when you are done.",
+}
+
+
+def run(payload: dict[str, Any]) -> dict[str, Any]:
+ invocation = payload.get("invocation") or {}
+ raw_name = str(invocation.get("command_name") or "").strip().lower()
+ command = raw_name
+ raw_args = str(invocation.get("raw_arguments") or "").strip()
+ arguments = invocation.get("arguments") if isinstance(invocation.get("arguments"), dict) else {}
+ context_id = str((payload.get("context") or {}).get("context_id") or "").strip()
+ context = _context(context_id)
+
+ if command == "new":
+ return _effects(_toast("Created a new chat."), {"type": "new_chat"})
+ if command == "chat":
+ return _handle_chat(arguments)
+ if command == "chats":
+ return _show_markdown("Chats", _chat_list(context, arguments))
+ if command == "clear":
+ return _effects(_toast("Visible transcript cleared."), {"type": "clear_transcript"})
+ if command == "project":
+ return _handle_project(context, raw_args)
+ if command == "profile":
+ return _handle_profile(context, raw_args)
+ if command == "plugins":
+ return _effects({"type": "open_modal", "path": "/components/plugins/list/plugin-list.html"})
+ if command == "compact":
+ return _effects({"type": "compact_chat"})
+ if command == "pause":
+ return _effects(_toast("Pause requested."), {"type": "pause_agent", "paused": True})
+ if command == "resume":
+ return _effects(_toast("Resume requested."), {"type": "pause_agent", "paused": False})
+ if command == "nudge":
+ return _effects(_toast("Nudge sent."), {"type": "nudge_agent"})
+ if command == "send":
+ return _handle_queue(context, ["send"])
+ if command == "queue":
+ return _handle_queue(context, list(arguments.get("tokens") or []))
+ if command == "presets":
+ return _effects({"type": "open_modal", "path": "/plugins/_model_config/webui/main.html"})
+ if command == "models":
+ return _handle_models(context, raw_args)
+ if command == "browser":
+ return _handle_browser(context, raw_args)
+ if command == "attach":
+ return _effects({"type": "attach_files"})
+ if command == "computer-use":
+ return _show_markdown("Computer Use", _computer_use_status(context_id, raw_args))
+ if command == "copy":
+ return _effects({"type": "copy_transcript"})
+ if command == "status":
+ return _show_markdown("Status", _status(context))
+ if command in CLI_ONLY:
+ return _effects(_toast(CLI_ONLY[command], level="info"))
+
+ return _effects(_toast(f"Unknown command: /{raw_name or command}", level="error"))
+
+
+def _context(context_id: str) -> AgentContext | None:
+ if context_id:
+ return AgentContext.get(context_id)
+ return AgentContext.current() or AgentContext.first()
+
+
+def _require_context(context: AgentContext | None) -> str | None:
+ if context:
+ return None
+ return "Open or create a chat context first."
+
+
+def _effects(*effects: dict[str, Any]) -> dict[str, Any]:
+ return {"text": "", "effects": [effect for effect in effects if effect]}
+
+
+def _toast(message: str, *, level: str = "success") -> dict[str, Any]:
+ return {"type": "toast", "message": message, "level": level}
+
+
+def _show_markdown(title: str, content: str) -> dict[str, Any]:
+ return _effects({"type": "show_markdown", "title": title, "content": content})
+
+
+def _handle_chat(arguments: dict[str, Any]) -> dict[str, Any]:
+ selector = str((arguments.get("positional") or [""])[0] or "").strip()
+ if not selector:
+ return _effects(_toast("Usage: /chat <context_id>", level="error"))
+ if not AgentContext.get(selector):
+ return _effects(_toast(f"Chat context '{selector}' was not found.", level="error"))
+ return _effects(_toast(f"Switched to {selector}."), {"type": "select_chat", "context_id": selector})
+
+
+def _handle_project(context: AgentContext | None, raw_args: str) -> dict[str, Any]:
+ if not raw_args:
+ return _effects({"type": "open_modal", "path": "/components/projects/project-list.html"})
+ error = _require_context(context)
+ if error:
+ return _effects(_toast(error, level="error"))
+ return _show_markdown("Project", try_handle_command(context, f"/project {raw_args}") or "")
+
+
+def _handle_profile(context: AgentContext | None, raw_args: str) -> dict[str, Any]:
+ if not raw_args:
+ return _effects({"type": "open_modal", "path": "/components/settings/settings.html"})
+ error = _require_context(context)
+ if error:
+ return _effects(_toast(error, level="error"))
+ return _show_markdown("Agent Profile", try_handle_command(context, f"/agent {raw_args}") or "")
+
+
+def _handle_models(context: AgentContext | None, raw_args: str) -> dict[str, Any]:
+ return _effects({"type": "open_plugin_config", "plugin": "_model_config"})
+
+
+def _handle_browser(context: AgentContext | None, raw_args: str) -> dict[str, Any]:
+ args = raw_args.strip().lower().replace("-", "_").split()
+ action = args[0] if args else ""
+ if not action:
+ return _effects({"type": "open_modal", "path": "/plugins/_browser/webui/main.html"})
+ if action in {"status", "state"}:
+ return _show_markdown("Browser", _browser_status(context))
+ if action not in {"host", "container", "docker"}:
+ return _effects(_toast("Usage: /browser [host|container|status]", level="error"))
+
+ project_name = projects.get_context_project_name(context) if context else ""
+ settings = plugins.get_plugin_config("_browser", project_name=project_name or "", agent_profile="") or {}
+ settings["runtime_backend"] = "host_required" if action == "host" else "container"
+ plugins.save_plugin_config("_browser", project_name or "", "", settings)
+ if context:
+ mark_dirty_for_context(context.id, reason="plugins._commands.browser_runtime")
+ label = "Host browser through A0 CLI" if settings["runtime_backend"] == "host_required" else "Internal Docker browser"
+ return _effects(_toast(f"Browser runtime set to {label}."))
+
+
+def _browser_status(context: AgentContext | None) -> str:
+ project_name = projects.get_context_project_name(context) if context else ""
+ settings = plugins.get_plugin_config("_browser", project_name=project_name or "", agent_profile="") or {}
+ runtime = str(settings.get("runtime_backend") or "container")
+ label = "Host browser through A0 CLI" if runtime == "host_required" else "Internal Docker browser"
+ return f"Browser runtime: {label}\n\nUse `/browser host` or `/browser container` to switch."
+
+
+def _handle_queue(context: AgentContext | None, tokens: list[str]) -> dict[str, Any]:
+ error = _require_context(context)
+ if error:
+ return _effects(_toast(error, level="error"))
+
+ queue = mq.get_queue(context)
+ if not tokens:
+ return _show_markdown("Queue", _queue_summary(queue))
+
+ action = str(tokens[0] or "").lower()
+ if action in {"send", "all", "flush"}:
+ if not queue:
+ return _effects(_toast("No queued messages."))
+ sent_count = mq.send_all_aggregated(context)
+ mark_dirty_for_context(context.id, reason="plugins._commands.queue_send")
+ noun = "message" if sent_count == 1 else "messages"
+ return _effects(_toast(f"Sent {sent_count} queued {noun}."))
+
+ if action in {"clear", "delete"} and len(tokens) == 1:
+ mq.remove(context)
+ mark_dirty_for_context(context.id, reason="plugins._commands.queue_clear")
+ return _effects(_toast("Queue cleared."))
+
+ if action in {"remove", "rm", "delete"}:
+ if len(tokens) < 2:
+ return _effects(_toast("Usage: /queue remove <number|id>", level="error"))
+ item_id = _queue_selector_to_id(queue, str(tokens[1]))
+ if not item_id:
+ return _effects(_toast(f"No queued message matches '{tokens[1]}'.", level="error"))
+ mq.remove(context, item_id)
+ mark_dirty_for_context(context.id, reason="plugins._commands.queue_remove")
+ return _effects(_toast("Queued message removed."))
+
+ return _effects(_toast("Usage: /queue [send|clear|remove <number|id>]", level="error"))
+
+
+def _queue_summary(queue: list[dict[str, Any]]) -> str:
+ if not queue:
+ return "No queued messages."
+ lines = [f"Queued messages ({len(queue)}):"]
+ for index, item in enumerate(queue, start=1):
+ text = str(item.get("text") or "").strip() or "(attachment only)"
+ if len(text) > 100:
+ text = text[:97].rstrip() + "..."
+ attachments = item.get("attachments") or []
+ suffix = f" [{len(attachments)} files]" if attachments else ""
+ lines.append(f"{index}. {text}{suffix}")
+ return "\n".join(lines)
+
+
+def _queue_selector_to_id(queue: list[dict[str, Any]], selector: str) -> str:
+ value = selector.strip()
+ if value.isdigit():
+ index = int(value) - 1
+ if 0 <= index < len(queue):
+ return str(queue[index].get("id") or "")
+ return ""
+ return value
+
+
+def _chat_list(context: AgentContext | None, arguments: dict[str, Any]) -> str:
+ items = list(AgentContext.all())
+ flags = arguments.get("flags") or {}
+ active_project_only = bool(flags.get("project") or flags.get("active_project") or flags.get("p"))
+ sort_by = str(flags.get("sort") or "").lower()
+ positional = [str(item).lower() for item in (arguments.get("positional") or [])]
+ if not sort_by:
+ sort_by = next((item for item in positional if item in {"updated", "created", "name"}), "updated")
+ if sort_by not in {"updated", "created", "name"}:
+ return "Usage: /chats [--project|--all-projects] [--sort=updated|created|name]"
+
+ if active_project_only and context:
+ project_name = projects.get_context_project_name(context) or ""
+ items = [item for item in items if (projects.get_context_project_name(item) or "") == project_name]
+
+ def sort_key(item: AgentContext) -> Any:
+ output = item.output()
+ if sort_by == "name":
+ return (item.name or item.id).casefold()
+ if sort_by == "created":
+ return str(output.get("created_at") or "")
+ return str(output.get("last_message") or output.get("created_at") or "")
+
+ items = sorted(items, key=sort_key, reverse=sort_by != "name")
+ if not items:
+ return "No chats found."
+
+ lines = ["| Chat | Context | State |", "| --- | --- | --- |"]
+ for item in items[:30]:
+ marker = "current" if context and item.id == context.id else ("running" if item.is_running() else "idle")
+ lines.append(f"| {_escape_cell(item.name or item.id)} | `{item.id}` | {marker} |")
+ if len(items) > 30:
+ lines.append(f"\nShowing 30 of {len(items)} chats.")
+ return "\n".join(lines)
+
+
+def _status(context: AgentContext | None) -> str:
+ error = _require_context(context)
+ if error:
+ return error
+ project_name = projects.get_context_project_name(context) or "none"
+ profile = getattr(context.agent0.config, "profile", "default") if context.agent0 else "default"
+ running = "running" if context.is_running() else "idle"
+ if getattr(context, "paused", False):
+ running = "paused"
+ return "\n".join(
+ [
+ f"Context: `{context.id}`",
+ f"State: {running}",
+ f"Project: {project_name}",
+ f"Agent profile: {profile}",
+ f"Queued messages: {len(mq.get_queue(context))}",
+ ]
+ )
+
+
+def _computer_use_status(context_id: str, raw_args: str) -> str:
+ from plugins._a0_connector.helpers import ws_runtime
+
+ action = "-".join(part.strip().lower().replace("_", "-") for part in raw_args.split()) or "status"
+ sids = ws_runtime.remote_tool_sids_for_context(context_id) if context_id else sorted(ws_runtime.connected_sids())
+ if not sids:
+ return (
+ "No A0 CLI is connected to this WebUI session.\n\n"
+ "Computer Use requires the CLI because the desktop permission prompt and native backend live on the CLI host. "
+ "Start A0 CLI, connect it to this Agent Zero instance, then run `/computer-use on` in the CLI."
+ )
+
+ if action in {"on", "off", "enable", "disable", "enabled", "disabled", "true", "false", "yes", "no", "1", "0"}:
+ return (
+ "Computer Use must be armed from the connected A0 CLI because it controls local desktop permissions.\n\n"
+ "Run `/computer-use on` or `/computer-use off` in the CLI terminal."
+ )
+
+ lines = ["Connected A0 CLI sessions:"]
+ for sid in sids:
+ metadata = ws_runtime.computer_use_metadata_for_sid(sid) or {}
+ if not metadata:
+ lines.append(f"- `{sid}`: connected, but not advertising Computer Use metadata.")
+ continue
+ state = "enabled" if metadata.get("enabled") else "disabled"
+ supported = "supported" if metadata.get("supported") else "unsupported"
+ status = str(metadata.get("status") or "unknown")
+ detail = str(metadata.get("last_error") or metadata.get("support_reason") or "").strip()
+ suffix = f" ({detail})" if detail else ""
+ lines.append(f"- `{sid}`: {state}, {supported}, status: {status}{suffix}")
+ lines.append("\nUse `/computer-use on|off|status` in the CLI to change local Computer Use.")
+ return "\n".join(lines)
+
+
+def _escape_cell(value: str) -> str:
+ return str(value).replace("|", "\\|")
diff --git a/plugins/_commands/commands/copy.command.yaml b/plugins/_commands/commands/copy.command.yaml
new file mode 100644
index 000000000..dca727448
--- /dev/null
+++ b/plugins/_commands/commands/copy.command.yaml
@@ -0,0 +1,4 @@
+name: copy
+description: Copy the currently visible transcript text to the clipboard.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/models.command.yaml b/plugins/_commands/commands/models.command.yaml
new file mode 100644
index 000000000..4efdcd59a
--- /dev/null
+++ b/plugins/_commands/commands/models.command.yaml
@@ -0,0 +1,4 @@
+name: models
+description: Open Main/Utility model runtime editor.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/new.command.yaml b/plugins/_commands/commands/new.command.yaml
new file mode 100644
index 000000000..0f8cf5610
--- /dev/null
+++ b/plugins/_commands/commands/new.command.yaml
@@ -0,0 +1,4 @@
+name: new
+description: Create a brand-new empty chat context.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/nudge.command.yaml b/plugins/_commands/commands/nudge.command.yaml
new file mode 100644
index 000000000..753aa1326
--- /dev/null
+++ b/plugins/_commands/commands/nudge.command.yaml
@@ -0,0 +1,4 @@
+name: nudge
+description: Nudge the current agent run.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/pause.command.yaml b/plugins/_commands/commands/pause.command.yaml
new file mode 100644
index 000000000..7c47ccb3c
--- /dev/null
+++ b/plugins/_commands/commands/pause.command.yaml
@@ -0,0 +1,4 @@
+name: pause
+description: Pause the active agent run.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/plugins.command.yaml b/plugins/_commands/commands/plugins.command.yaml
new file mode 100644
index 000000000..aa4f730b4
--- /dev/null
+++ b/plugins/_commands/commands/plugins.command.yaml
@@ -0,0 +1,4 @@
+name: plugins
+description: Open the installed-only Agent Zero plugin toggle view.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/presets.command.yaml b/plugins/_commands/commands/presets.command.yaml
new file mode 100644
index 000000000..fb9184e3f
--- /dev/null
+++ b/plugins/_commands/commands/presets.command.yaml
@@ -0,0 +1,4 @@
+name: presets
+description: Open preset picker with Main/Utility model details.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/profile.command.yaml b/plugins/_commands/commands/profile.command.yaml
new file mode 100644
index 000000000..082585831
--- /dev/null
+++ b/plugins/_commands/commands/profile.command.yaml
@@ -0,0 +1,5 @@
+name: profile
+description: Pick or set the active Agent Zero Core profile.
+argument_hint: "[profile]"
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/project.command.yaml b/plugins/_commands/commands/project.command.yaml
new file mode 100644
index 000000000..9d86c7785
--- /dev/null
+++ b/plugins/_commands/commands/project.command.yaml
@@ -0,0 +1,5 @@
+name: project
+description: Open the project menu, or switch directly with /project <name>.
+argument_hint: "[name]"
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/queue.command.yaml b/plugins/_commands/commands/queue.command.yaml
new file mode 100644
index 000000000..4e87774c4
--- /dev/null
+++ b/plugins/_commands/commands/queue.command.yaml
@@ -0,0 +1,5 @@
+name: queue
+description: Show, send, clear, or remove queued messages.
+argument_hint: "[send|clear|remove <number|id>]"
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/quit.command.yaml b/plugins/_commands/commands/quit.command.yaml
new file mode 100644
index 000000000..e7f6c7373
--- /dev/null
+++ b/plugins/_commands/commands/quit.command.yaml
@@ -0,0 +1,4 @@
+name: quit
+description: Disconnect and exit the CLI.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/resume.command.yaml b/plugins/_commands/commands/resume.command.yaml
new file mode 100644
index 000000000..76c1587a6
--- /dev/null
+++ b/plugins/_commands/commands/resume.command.yaml
@@ -0,0 +1,4 @@
+name: resume
+description: Resume a paused agent run.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/send.command.yaml b/plugins/_commands/commands/send.command.yaml
new file mode 100644
index 000000000..12d69252e
--- /dev/null
+++ b/plugins/_commands/commands/send.command.yaml
@@ -0,0 +1,4 @@
+name: send
+description: Send all queued messages now.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/commands/status.command.yaml b/plugins/_commands/commands/status.command.yaml
new file mode 100644
index 000000000..c3e240325
--- /dev/null
+++ b/plugins/_commands/commands/status.command.yaml
@@ -0,0 +1,4 @@
+name: status
+description: Show this chat's project, model, agent, and queue state.
+type: script
+script_path: connector_commands.py
diff --git a/plugins/_commands/extensions/python/startup_migration/_20_migrate_legacy_commands.py b/plugins/_commands/extensions/python/startup_migration/_20_migrate_legacy_commands.py
new file mode 100644
index 000000000..0216cfdeb
--- /dev/null
+++ b/plugins/_commands/extensions/python/startup_migration/_20_migrate_legacy_commands.py
@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from helpers import cache, files, plugins
+from helpers.extension import Extension
+from helpers.print_style import PrintStyle
+
+
+LEGACY_PLUGIN_NAME = "commands"
+PLUGIN_NAME = "_commands"
+COMMANDS_DIR = "commands"
+SKILLS_DIR = "skills"
+
+
+class LegacyCommandsMigration(Extension):
+ def execute(self, **kwargs):
+ result = migrate_legacy_commands()
+ if result["copied_commands"] or result["copied_skills"] or result["disabled_roots"]:
+ PrintStyle.info("Migrated legacy commands plugin data:", result)
+
+
+def migrate_legacy_commands(base_dir: str | Path | None = None) -> dict[str, Any]:
+ root = Path(base_dir or files.get_abs_path("")).resolve()
+ result: dict[str, Any] = {
+ "copied_commands": 0,
+ "copied_skills": 0,
+ "disabled_roots": 0,
+ }
+
+ legacy_plugin_dir = root / "usr" / "plugins" / LEGACY_PLUGIN_NAME
+ if not legacy_plugin_dir.exists() and not _legacy_scoped_plugin_dirs(root):
+ return result
+
+ for legacy_commands_dir in _legacy_command_dirs(root):
+ target = _replace_plugin_segment(legacy_commands_dir, PLUGIN_NAME)
+ result["copied_commands"] += _copy_tree_files(legacy_commands_dir, target)
+
+ result["copied_skills"] += _copy_tree_files(
+ legacy_plugin_dir / SKILLS_DIR,
+ root / "usr" / "plugins" / PLUGIN_NAME / SKILLS_DIR,
+ )
+
+ for legacy_plugin_root in _legacy_plugin_roots(root):
+ if _disable_legacy_plugin_root(legacy_plugin_root):
+ result["disabled_roots"] += 1
+
+ if result["disabled_roots"]:
+ _clear_runtime_caches()
+
+ return result
+
+
+def _legacy_command_dirs(root: Path) -> list[Path]:
+ return [
+ plugin_root / COMMANDS_DIR
+ for plugin_root in _legacy_plugin_roots(root)
+ if (plugin_root / COMMANDS_DIR).is_dir()
+ ]
+
+
+def _legacy_plugin_roots(root: Path) -> list[Path]:
+ roots = []
+ for candidate in [
+ root / "usr" / "plugins" / LEGACY_PLUGIN_NAME,
+ *root.glob(f"usr/projects/*/.a0proj/plugins/{LEGACY_PLUGIN_NAME}"),
+ *root.glob(f"usr/projects/*/.a0proj/agents/*/plugins/{LEGACY_PLUGIN_NAME}"),
+ *root.glob(f"usr/agents/*/plugins/{LEGACY_PLUGIN_NAME}"),
+ ]:
+ if candidate.exists() and candidate not in roots:
+ roots.append(candidate)
+ return roots
+
+
+def _legacy_scoped_plugin_dirs(root: Path) -> list[Path]:
+ return [
+ *root.glob(f"usr/projects/*/.a0proj/plugins/{LEGACY_PLUGIN_NAME}"),
+ *root.glob(f"usr/projects/*/.a0proj/agents/*/plugins/{LEGACY_PLUGIN_NAME}"),
+ *root.glob(f"usr/agents/*/plugins/{LEGACY_PLUGIN_NAME}"),
+ ]
+
+
+def _replace_plugin_segment(path: Path, plugin_name: str) -> Path:
+ parts = list(path.parts)
+ for index in range(len(parts) - 1):
+ if parts[index] == "plugins" and parts[index + 1] == LEGACY_PLUGIN_NAME:
+ parts[index + 1] = plugin_name
+ return Path(*parts)
+ return path
+
+
+def _copy_tree_files(source: Path, target: Path) -> int:
+ if not source.is_dir():
+ return 0
+
+ copied = 0
+ for source_file in source.rglob("*"):
+ if not source_file.is_file():
+ continue
+ relative_path = source_file.relative_to(source)
+ target_file = target / relative_path
+ if target_file.exists():
+ continue
+ target_file.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(source_file, target_file)
+ copied += 1
+ return copied
+
+
+def _disable_legacy_plugin_root(plugin_root: Path) -> bool:
+ plugin_root.mkdir(parents=True, exist_ok=True)
+ enabled_file = plugin_root / plugins.ENABLED_FILE_NAME
+ disabled_file = plugin_root / plugins.DISABLED_FILE_NAME
+ changed = enabled_file.exists() or not disabled_file.exists()
+ enabled_file.unlink(missing_ok=True)
+ disabled_file.write_text("", encoding="utf-8")
+ return changed
+
+
+def _clear_runtime_caches() -> None:
+ cache.clear("*(plugins)*")
+ cache.clear("*(extensions)*")
diff --git a/plugins/_commands/extensions/webui/chat-input-box-start/commands-menu.html b/plugins/_commands/extensions/webui/chat-input-box-start/commands-menu.html
new file mode 100644
index 000000000..69e67f561
--- /dev/null
+++ b/plugins/_commands/extensions/webui/chat-input-box-start/commands-menu.html
@@ -0,0 +1,192 @@
+<html>
+<head>
+ <script type="module">
+ import { store } from "/plugins/_commands/webui/commands-slash-store.js";
+ </script>
+</head>
+<body>
+ <div x-data>
+ <template x-if="$store.commandsSlash">
+ <div class="commands-slash-menu-root" x-create="$store.commandsSlash.onMount()" x-destroy="$store.commandsSlash.cleanup()">
+ <div class="commands-slash-menu" x-show="$store.commandsSlash.menuVisible" x-transition.opacity.duration.120ms>
+ <template x-if="$store.commandsSlash.loading">
+ <div class="commands-slash-loading">
+ <span class="material-symbols-outlined spinning">progress_activity</span>
+ <span>Loading slash commands...</span>
+ </div>
+ </template>
+
+ <template x-if="!$store.commandsSlash.loading && $store.commandsSlash.filteredCommands.length > 0">
+ <div class="commands-slash-results">
+ <template x-for="(command, index) in $store.commandsSlash.filteredCommands" :key="command.path">
+ <button type="button"
+ class="commands-slash-item"
+ :class="{ active: index === $store.commandsSlash.selectedIndex }"
+ @mouseenter="$store.commandsSlash.selectedIndex = index"
+ @mousedown.prevent
+ @click.prevent="$store.commandsSlash.applySelection(command)">
+ <div class="commands-slash-item-header">
+ <div class="commands-slash-item-name">
+ <span class="commands-slash-prefix">/</span><span x-text="command.name"></span>
+ </div>
+ <span class="commands-slash-scope" x-text="command.source_scope_label"></span>
+ </div>
+ <div class="commands-slash-item-description" x-text="command.description"></div>
+ <template x-if="command.argument_hint">
+ <div class="commands-slash-item-hint" x-text="command.argument_hint"></div>
+ </template>
+ </button>
+ </template>
+ </div>
+ </template>
+
+ <template x-if="!$store.commandsSlash.loading && $store.commandsSlash.filteredCommands.length === 0">
+ <div class="commands-slash-empty">
+ <div class="commands-slash-empty-copy">
+ No matching slash commands.
+ </div>
+ <button type="button"
+ class="commands-slash-create"
+ @mousedown.prevent
+ @click.prevent="$store.commandsSlash.openCreateCommand()">
+ <span class="material-symbols-outlined">add</span>
+ <span x-text="$store.commandsSlash.emptyStateLabel"></span>
+ </button>
+ </div>
+ </template>
+ </div>
+ </div>
+ </template>
+ </div>
+
+ <style>
+ .commands-slash-menu-root {
+ position: relative;
+ z-index: 30;
+ }
+
+ .commands-slash-menu {
+ margin-bottom: 0.55rem;
+ border: 1px solid var(--color-border);
+ border-radius: 8px;
+ background: color-mix(in srgb, var(--color-panel) 96%, var(--color-background));
+ box-shadow: 0 14px 32px rgba(0, 0, 0, 0.14);
+ overflow: hidden;
+ }
+
+ .commands-slash-results {
+ max-height: 18rem;
+ overflow-y: auto;
+ }
+
+ .commands-slash-item {
+ display: flex;
+ flex-direction: column;
+ gap: 0.32rem;
+ width: 100%;
+ padding: var(--spacing-sm) 0.8rem;
+ border: 0;
+ border-bottom: 1px solid color-mix(in srgb, var(--color-border) 60%, transparent);
+ background: transparent;
+ color: inherit;
+ text-align: left;
+ cursor: pointer;
+ }
+
+ .commands-slash-item:last-child {
+ border-bottom: 0;
+ }
+
+ .commands-slash-item.active,
+ .commands-slash-item:hover {
+ background: color-mix(in srgb, var(--color-highlight) 10%, transparent);
+ }
+
+ .commands-slash-item-header {
+ display: flex;
+ justify-content: space-between;
+ gap: 0.75rem;
+ align-items: center;
+ }
+
+ .commands-slash-item-name {
+ font-weight: 600;
+ }
+
+ .commands-slash-prefix {
+ color: var(--color-highlight);
+ }
+
+ .commands-slash-scope {
+ padding: 0.18rem 0.45rem;
+ border-radius: 999px;
+ background: color-mix(in srgb, var(--color-highlight) 12%, transparent);
+ font-size: 0.72rem;
+ font-weight: 600;
+ white-space: nowrap;
+ }
+
+ .commands-slash-item-description {
+ color: var(--color-text-secondary);
+ font-size: 0.86rem;
+ line-height: 1.4;
+ }
+
+ .commands-slash-item-hint {
+ color: var(--color-text-secondary);
+ font-family: "Roboto Mono", monospace;
+ font-size: 0.77rem;
+ opacity: 0.85;
+ }
+
+ .commands-slash-empty,
+ .commands-slash-loading {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 0.75rem;
+ padding: 0.9rem 1rem;
+ }
+
+ .commands-slash-empty-copy,
+ .commands-slash-loading {
+ color: var(--color-text-secondary);
+ }
+
+ .commands-slash-create {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.35rem;
+ padding: 0.5rem 0.75rem;
+ border: 1px solid var(--color-border);
+ border-radius: 999px;
+ background: transparent;
+ color: var(--color-text);
+ cursor: pointer;
+ font-weight: 600;
+ white-space: nowrap;
+ }
+
+ .spinning {
+ animation: commands-slash-spin 1s linear infinite;
+ }
+
+ @keyframes commands-slash-spin {
+ from { transform: rotate(0deg); }
+ to { transform: rotate(360deg); }
+ }
+
+ @media (max-width: 640px) {
+ .commands-slash-empty,
+ .commands-slash-loading {
+ flex-direction: column;
+ align-items: stretch;
+ }
+
+ .commands-slash-create {
+ justify-content: center;
+ }
+ }
+ </style>
+</body>
+</html>
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
new file mode 100644
index 000000000..f8be2790f
--- /dev/null
+++ b/plugins/_commands/extensions/webui/sidebar-quick-actions-main-start/commands-entry.html
@@ -0,0 +1,9 @@
+<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/__init__.py b/plugins/_commands/helpers/__init__.py
new file mode 100644
index 000000000..390522358
--- /dev/null
+++ b/plugins/_commands/helpers/__init__.py
@@ -0,0 +1 @@
+"""Helpers for the commands plugin."""
diff --git a/plugins/_commands/helpers/commands.py b/plugins/_commands/helpers/commands.py
new file mode 100644
index 000000000..24544c1aa
--- /dev/null
+++ b/plugins/_commands/helpers/commands.py
@@ -0,0 +1,1150 @@
+from __future__ import annotations
+
+import inspect
+import json
+import os
+import re
+import runpy
+import shlex
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from agent import AgentContext
+from helpers import files, plugins, projects, yaml as yaml_helper
+from helpers.skills import split_frontmatter
+
+
+PLUGIN_NAME = "_commands"
+COMMANDS_DIR = "commands"
+COMMAND_CONFIG_SUFFIX = ".command.yaml"
+LEGACY_COMMAND_FILE_SUFFIX = ".command.md"
+TEXT_TEMPLATE_SUFFIX = ".txt"
+SCRIPT_TEMPLATE_SUFFIX = ".py"
+STANDARD_CONFIG_KEYS = {
+ "name",
+ "description",
+ "argument_hint",
+ "type",
+ "template_path",
+ "script_path",
+ "include_history",
+}
+_INVALID_COMMAND_CHARS_RE = re.compile(r"[^a-z0-9_-]+")
+_MULTI_DASH_RE = re.compile(r"-{2,}")
+_PLACEHOLDER_RE = re.compile(r"\{([a-zA-Z0-9_.-]+)\}")
+
+
+def sanitize_command_name(raw_name: str) -> str:
+ """Sanitize a raw command name to a lowercase, hyphen-separated slug.
+
+ Strips whitespace, lowercases, replaces spaces and invalid characters with hyphens,
+ collapses consecutive hyphens, and strips leading/trailing hyphens and underscores.
+
+ Raises:
+ ValueError: If the resulting name is empty.
+
+ """
+ raw = (raw_name or "").strip().lower()
+ name = raw.replace(" ", "-")
+ name = _INVALID_COMMAND_CHARS_RE.sub("-", name)
+ name = _MULTI_DASH_RE.sub("-", name).strip("-_")
+ if not name:
+ raise ValueError("Command name must contain at least one letter or number")
+ return name
+
+
+def normalize_command_type(raw_type: str) -> str:
+ """Normalize a command type string to either ``"text"`` or ``"script"``."""
+ command_type = (raw_type or "text").strip().lower()
+ if command_type not in {"text", "script"}:
+ raise ValueError('Command type must be either "text" or "script"')
+ return command_type
+
+
+def command_file_name(command_name: str) -> str:
+ """Return the ``.command.yaml`` config filename for *command_name*."""
+ return f"{sanitize_command_name(command_name)}{COMMAND_CONFIG_SUFFIX}"
+
+
+def command_content_file_name(command_name: str, command_type: str) -> str:
+ """Return the content filename (``.txt`` or ``.py``) for *command_name* and *command_type*."""
+ suffix = (
+ TEXT_TEMPLATE_SUFFIX
+ if normalize_command_type(command_type) == "text"
+ else SCRIPT_TEMPLATE_SUFFIX
+ )
+ return f"{sanitize_command_name(command_name)}{suffix}"
+
+
+def parse_slash_invocation(raw_message: str, *, fallback_command: str = "") -> dict[str, Any]:
+ """Parse a raw slash-command message into its component parts.
+
+ Returns a dict with keys: ``raw_text``, ``command_name``, ``raw_arguments``,
+ and ``arguments`` (parsed by :func:`parse_arguments`).
+
+ Args:
+ raw_message: The full message string, e.g. ``"/scan --url https://example.com"``.
+ fallback_command: Command name to use when no slash prefix is found.
+
+ """
+ text = (raw_message or "").strip()
+ slash_match = re.match(r"^/([^\s]+)(?:\s+([\s\S]*))?$", text)
+ if slash_match:
+ try:
+ command_name = sanitize_command_name(slash_match.group(1))
+ except ValueError:
+ command_name = sanitize_command_name(fallback_command) if fallback_command else ""
+ raw_arguments = (slash_match.group(2) or "").strip()
+ else:
+ command_name = sanitize_command_name(fallback_command) if fallback_command else ""
+ raw_arguments = text
+
+ parsed_arguments = parse_arguments(raw_arguments)
+ return {
+ "raw_text": text,
+ "command_name": command_name,
+ "raw_arguments": raw_arguments,
+ "arguments": parsed_arguments,
+ }
+
+
+def parse_arguments(raw_arguments: str) -> dict[str, Any]:
+ """Parse a raw argument string into positional args, flags, and tokens.
+
+ Supports positional values, long flags (``--key value``, ``--key=value``),
+ short flags (``-f``), and short flag bundles (``-vq``).
+
+ Returns a dict with keys: ``raw``, ``tokens``, ``positional``, ``flags``.
+
+ """
+ normalized_arguments = (raw_arguments or "").strip()
+ tokens = _split_arguments(normalized_arguments)
+ positional: list[str] = []
+ flags: dict[str, Any] = {}
+
+ index = 0
+ while index < len(tokens):
+ token = tokens[index]
+ if token.startswith("--") and len(token) > 2:
+ key, value, consumed = _parse_long_flag(token, tokens, index)
+ _set_flag_value(flags, key, value)
+ index += consumed
+ continue
+
+ if token.startswith("-") and len(token) > 1:
+ consumed = _parse_short_flag_bundle(token, tokens, index, flags)
+ index += consumed
+ continue
+
+ positional.append(token)
+ index += 1
+
+ return {
+ "raw": normalized_arguments,
+ "tokens": tokens,
+ "positional": positional,
+ "flags": flags,
+ }
+
+
+def render_command_body(
+ body: str,
+ raw_arguments: str,
+ *,
+ command_name: str = "",
+ raw_message: str = "",
+) -> str:
+ """Render *body* as a text template substituting placeholders from *raw_arguments*.
+
+ Args:
+ body: Template string with ``{placeholder}`` markers.
+ raw_arguments: Unparsed argument string from the command invocation.
+ command_name: Optional command name used for slash-invocation parsing fallback.
+ raw_message: Full original message; when provided takes precedence over raw_arguments.
+
+ """
+ invocation = parse_slash_invocation(
+ raw_message or raw_arguments,
+ fallback_command=command_name,
+ )
+ if not raw_message:
+ invocation["raw_arguments"] = (raw_arguments or "").strip()
+ invocation["arguments"] = parse_arguments(invocation["raw_arguments"])
+ return render_text_template(body, invocation)
+
+
+def render_text_template(body: str, invocation: dict[str, Any]) -> str:
+ """Render *body* as a template substituting placeholders from *invocation* context.
+
+ Unrecognised placeholders resolve to empty string. If *raw_arguments* is present
+ and the template contains no argument references, the arguments are appended.
+
+ """
+ template = body or ""
+ rendered = template
+
+ context = _build_template_context(invocation)
+ rendered = _PLACEHOLDER_RE.sub(
+ lambda match: _resolve_placeholder(match.group(1), context),
+ rendered,
+ )
+ rendered = _render_legacy_placeholders(rendered, invocation)
+ rendered = rendered.strip()
+
+ raw_arguments = invocation["raw_arguments"]
+ if raw_arguments and not _template_references_arguments(template):
+ suffix = f"Arguments:\n{raw_arguments}"
+ rendered = f"{rendered}\n\n{suffix}" if rendered else suffix
+
+ return rendered.strip()
+
+
+def get_scope_key(project_name: str = "", agent_profile: str = "") -> str:
+ """Return the scope identifier key: ``'project'`` when a project is active, else ``'global'``."""
+ if project_name:
+ return "project"
+ return "global"
+
+
+def get_scope_label(project_name: str = "", agent_profile: str = "") -> str:
+ """Return the human-readable scope label: ``'Project'`` or ``'Global'``."""
+ if project_name:
+ return "Project"
+ return "Global"
+
+
+def get_scope_directory(project_name: str = "", agent_profile: str = "") -> str:
+ """Return the absolute filesystem path to the commands directory for the given scope."""
+ return plugins.determine_plugin_asset_path(
+ PLUGIN_NAME,
+ project_name,
+ "",
+ COMMANDS_DIR,
+ )
+
+
+def ensure_scope_directory(project_name: str = "", agent_profile: str = "") -> str:
+ """Ensure the commands directory for the given scope exists, creating it when absent.
+
+ Returns the absolute path to the directory.
+
+ """
+ directory = get_scope_directory(project_name, "")
+ Path(directory).mkdir(parents=True, exist_ok=True)
+ return directory
+
+
+def get_scope_payload(
+ project_name: str = "",
+ agent_profile: str = "",
+ *,
+ ensure_directory: bool = False,
+) -> dict[str, Any]:
+ """Build a scope descriptor dict for the given project/agent context.
+
+ Returns a dict containing ``project_name``, ``scope_key``, ``scope_label``,
+ ``directory_path``, ``exists``, and the private ``_directory_abs_path`` key.
+
+ Args:
+ ensure_directory: When ``True``, create the directory if it does not exist.
+
+ """
+ directory_path = (
+ ensure_scope_directory(project_name, "")
+ if ensure_directory
+ else get_scope_directory(project_name, "")
+ )
+ return {
+ "project_name": project_name,
+ "scope_key": get_scope_key(project_name, ""),
+ "scope_label": get_scope_label(project_name, ""),
+ "directory_path": _normalize_client_path(directory_path),
+ "exists": os.path.isdir(directory_path),
+ "_directory_abs_path": directory_path,
+ }
+
+
+def get_context_scope(context_id: str = "") -> dict[str, str]:
+ """Resolve the active project name for *context_id* and return a scope mapping.
+
+ Returns ``{"project_name": str}`` — empty string when no project is associated.
+
+ """
+ context = _get_context(context_id)
+ if not context:
+ return {"project_name": ""}
+
+ return {
+ "project_name": projects.get_context_project_name(context) or "",
+ }
+
+
+def list_scope_commands(
+ project_name: str = "",
+ agent_profile: str = "",
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+ """List all commands defined in *project_name* scope (not merged with global).
+
+ Each command entry includes ``override_scopes`` and ``override_count`` fields
+ indicating lower-scoped commands with the same name.
+
+ Returns:
+ Tuple of (commands list, stripped scope payload dict).
+
+ """
+ scope = get_scope_payload(project_name, "")
+ commands = _load_scope_commands(project_name)
+ overrides = _collect_lower_scope_matches(project_name)
+
+ for command in commands:
+ override_scopes = overrides.get(command["name"], [])
+ command["override_scopes"] = override_scopes
+ command["override_count"] = len(override_scopes)
+
+ return commands, strip_private_scope(scope)
+
+
+def list_effective_commands(
+ project_name: str = "",
+ agent_profile: str = "",
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+ """Return the merged effective command list for *project_name* scope.
+
+ Project-scoped commands take precedence over global commands of the same name.
+ Commands are sorted alphabetically by name.
+
+ Returns:
+ Tuple of (sorted commands list, stripped scope payload dict).
+
+ """
+ resolved_scope = get_scope_payload(project_name, "")
+ merged: dict[str, dict[str, Any]] = {}
+
+ for scope_project in _iter_precedence_scopes(project_name):
+ for command in _load_scope_commands(scope_project):
+ merged.setdefault(command["name"], command)
+
+ for command in _discover_builtin_commands():
+ merged.setdefault(command["name"], command)
+
+ for command in _discover_plugin_commands():
+ merged.setdefault(command["name"], command)
+
+ effective = sorted(merged.values(), key=lambda item: item["name"])
+ return effective, strip_private_scope(resolved_scope)
+
+
+def get_command(
+ path: str,
+ project_name: str = "",
+ agent_profile: str = "",
+) -> dict[str, Any]:
+ """Load and return a single command by its config file *path*.
+
+ Validates that *path* belongs to an effective scope for *project_name*.
+
+ Raises:
+ FileNotFoundError: If the command file does not exist.
+ ValueError: If the path is outside all valid scopes, not a recognised
+ config suffix, or the file content is invalid.
+
+ """
+ command_path = _validate_command_path(path, project_name, "", allow_plugin=True)
+ # Determine actual scope from the resolved path to get correct metadata.
+ # A global command loaded with a project context must report scope=global.
+ actual_project = ""
+ for scope in _iter_precedence_scopes(project_name):
+ scope_dir = get_scope_directory(scope, "")
+ if files.is_in_dir(command_path, scope_dir):
+ actual_project = scope
+ break
+ command = _load_command_file(command_path, project_name=actual_project)
+ if not command:
+ raise ValueError("Command file is invalid or missing required configuration")
+ if _is_builtin_command_path(command_path):
+ return _mark_builtin_command(command)
+ plugin_name = _plugin_name_for_commands_path(command_path)
+ if plugin_name:
+ _mark_plugin_command(command, plugin_name)
+ return command
+
+
+def save_command(
+ *,
+ project_name: str = "",
+ agent_profile: str = "",
+ existing_path: str = "",
+ name: str,
+ description: str,
+ argument_hint: str = "",
+ command_type: str = "text",
+ body: str = "",
+ include_history: bool = False,
+ extra_frontmatter: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+ """Create or update a command, writing both the config and content files.
+
+ When *existing_path* is provided, the old files are removed after the new
+ files are written (rename/move semantics).
+
+ Returns:
+ The fully-loaded command dict for the saved command.
+
+ Raises:
+ FileExistsError: If a command with the same name already exists in scope.
+ ValueError: If required fields are missing or values are invalid.
+
+ """
+ command_name = sanitize_command_name(name)
+ command_description = (description or "").strip()
+ if not command_description:
+ raise ValueError("Command description is required")
+
+ normalized_type = normalize_command_type(command_type)
+ scope_dir = ensure_scope_directory(project_name, "")
+ target_config_path = files.get_abs_path(scope_dir, command_file_name(command_name))
+ target_content_name = command_content_file_name(command_name, normalized_type)
+ target_content_path = files.get_abs_path(scope_dir, target_content_name)
+ existing_abs_path = ""
+ existing_command: dict[str, Any] | None = None
+ if existing_path:
+ try:
+ existing_abs_path = _validate_command_path(existing_path, project_name, "")
+ existing_command = _load_command_file(existing_abs_path, project_name=project_name)
+ except FileNotFoundError:
+ existing_abs_path = ""
+ existing_command = None
+
+ if existing_abs_path and not os.path.exists(existing_abs_path):
+ existing_abs_path = ""
+ existing_command = None
+
+ if os.path.exists(target_config_path) and not _paths_equal(
+ target_config_path, existing_abs_path
+ ):
+ raise FileExistsError(f'A command named "{command_name}" already exists in this scope')
+
+ existing_content_path = _to_abs_path(existing_command.get("content_path", "")) if existing_command else ""
+ if os.path.exists(target_content_path) and not _paths_equal(
+ target_content_path, existing_content_path
+ ):
+ raise FileExistsError(
+ f'Command content file "{Path(target_content_path).name}" already exists in this scope'
+ )
+
+ content_key = "template_path" if normalized_type == "text" else "script_path"
+ config = _build_command_config(
+ name=command_name,
+ description=command_description,
+ argument_hint=argument_hint,
+ command_type=normalized_type,
+ content_path=target_content_name,
+ include_history=include_history,
+ extra_config=extra_frontmatter or {},
+ )
+ if content_key not in config:
+ config[content_key] = target_content_name
+
+ files.write_file(target_content_path, _normalize_command_body(body, normalized_type))
+ files.write_file(target_config_path, _build_command_yaml(config))
+
+ if existing_abs_path and not _paths_equal(existing_abs_path, target_config_path):
+ files.delete_file(existing_abs_path)
+
+ if (
+ existing_content_path
+ and os.path.exists(existing_content_path)
+ and not _paths_equal(existing_content_path, target_content_path)
+ ):
+ files.delete_file(existing_content_path)
+
+ return get_command(target_config_path, project_name, "")
+
+
+def delete_command(
+ path: str,
+ project_name: str = "",
+ agent_profile: str = "",
+) -> None:
+ """Delete the config file and associated content file for *path*.
+
+ Raises:
+ FileNotFoundError: If the command file does not exist.
+ ValueError: If *path* is invalid or outside the allowed scope.
+
+ """
+ command = get_command(path, project_name, "")
+ command_path = _validate_command_path(path, project_name, "")
+ files.delete_file(command_path)
+
+ content_path = _to_abs_path(command.get("content_path", ""))
+ if content_path and os.path.exists(content_path):
+ files.delete_file(content_path)
+
+
+def duplicate_command(
+ path: str,
+ project_name: str = "",
+ agent_profile: str = "",
+) -> dict[str, Any]:
+ """Duplicate an existing command, assigning it a unique ``-copy`` suffixed name.
+
+ Returns the newly created command dict.
+
+ Raises:
+ FileNotFoundError: If the source command does not exist.
+ ValueError: If the source path is invalid.
+
+ """
+ command = get_command(path, project_name, "")
+ duplicated_name = _generate_duplicate_name(command["name"], project_name=project_name)
+ return save_command(
+ project_name=project_name,
+ name=duplicated_name,
+ description=command["description"],
+ argument_hint=command.get("argument_hint", ""),
+ command_type=command.get("command_type", "text"),
+ body=command.get("body", ""),
+ include_history=bool(command.get("include_history", False)),
+ extra_frontmatter=command.get("frontmatter_extra", {}),
+ )
+
+
+async def resolve_command_invocation(
+ *,
+ path: str,
+ slash_text: str,
+ project_name: str = "",
+ context_id: str = "",
+) -> dict[str, Any]:
+ """Resolve a slash command invocation, executing text rendering or a Python script hook.
+
+ Args:
+ path: Path to the command config file.
+ slash_text: The full slash text entered by the user.
+ project_name: Active project name (empty string for global scope).'
+ context_id: Agent context ID, used for script commands that request history.
+
+ Returns:
+ Dict with keys ``command``, ``invocation``, and ``result``
+ (``{"text": str, "effects": list}``).
+
+ Raises:
+ FileNotFoundError: If the command file is not found.
+ ValueError: If path or slash_text is invalid.
+
+ """
+ command = get_command(path, project_name, "")
+ invocation = parse_slash_invocation(slash_text, fallback_command=command["name"])
+
+ if command.get("command_type") == "script":
+ result = await _run_script_command(
+ command=command,
+ invocation=invocation,
+ project_name=project_name,
+ context_id=context_id,
+ )
+ else:
+ text = render_text_template(command.get("body", ""), invocation)
+ result = {"text": text, "effects": []}
+
+ return {
+ "command": _public_command_payload(command),
+ "invocation": invocation,
+ "result": result,
+ }
+
+
+def _build_command_config(
+ *,
+ name: str,
+ description: str,
+ argument_hint: str,
+ command_type: str,
+ content_path: str,
+ include_history: bool,
+ extra_config: dict[str, Any],
+) -> dict[str, Any]:
+ config: dict[str, Any] = {
+ "name": name,
+ "description": description,
+ "type": command_type,
+ }
+ clean_argument_hint = (argument_hint or "").strip()
+ if clean_argument_hint:
+ config["argument_hint"] = clean_argument_hint
+
+ if command_type == "text":
+ config["template_path"] = content_path
+ else:
+ config["script_path"] = content_path
+ if include_history:
+ config["include_history"] = True
+
+ for key, value in (extra_config or {}).items():
+ if key in STANDARD_CONFIG_KEYS:
+ continue
+ config[key] = value
+
+ return config
+
+
+def _build_command_yaml(config: dict[str, Any]) -> str:
+ return f"{yaml_helper.dumps(config).strip()}\n"
+
+
+def _normalize_command_body(body: str, command_type: str) -> str:
+ cleaned = (body or "").lstrip("\n").rstrip()
+ if cleaned:
+ return f"{cleaned}\n"
+ return ""
+
+
+def _load_command_file(
+ file_path: str,
+ *,
+ project_name: str = "",
+) -> dict[str, Any] | None:
+ if file_path.endswith(COMMAND_CONFIG_SUFFIX):
+ return _load_yaml_command_file(file_path, project_name=project_name)
+ if file_path.endswith(LEGACY_COMMAND_FILE_SUFFIX):
+ return _load_legacy_markdown_file(file_path, project_name=project_name)
+ return None
+
+
+def _load_yaml_command_file(
+ file_path: str,
+ *,
+ project_name: str = "",
+) -> dict[str, Any] | None:
+ try:
+ raw_content = files.read_file(file_path)
+ except FileNotFoundError:
+ return None
+
+ try:
+ parsed = yaml.safe_load(raw_content) or {}
+ except yaml.YAMLError:
+ return None
+ if not isinstance(parsed, dict):
+ return None
+
+ raw_name = str(parsed.get("name") or "").strip()
+ description = str(parsed.get("description") or "").strip()
+ if not raw_name or not description:
+ return None
+
+ try:
+ command_name = sanitize_command_name(raw_name)
+ command_type = normalize_command_type(str(parsed.get("type") or "text"))
+ except ValueError:
+ return None
+
+ directory_path = str(Path(file_path).parent)
+ content_key = "template_path" if command_type == "text" else "script_path"
+ configured_content_path = str(parsed.get(content_key) or "").strip() or command_content_file_name(
+ command_name, command_type
+ )
+ content_abs_path = files.get_abs_path(directory_path, configured_content_path)
+ # Content file must live in the same directory as its config file.
+ # Using directory_path (not the project scope root) allows global commands
+ # to load correctly even when a project context is active.
+ if not files.is_in_dir(content_abs_path, directory_path):
+ return None
+
+ try:
+ body = files.read_file(content_abs_path)
+ except FileNotFoundError:
+ body = ""
+
+ argument_hint = str(parsed.get("argument_hint") or "").strip()
+ include_history = bool(parsed.get("include_history", False))
+ extra_config = {
+ key: value for key, value in parsed.items() if key not in STANDARD_CONFIG_KEYS
+ }
+
+ return {
+ "name": command_name,
+ "description": description,
+ "argument_hint": argument_hint,
+ "command_type": command_type,
+ "include_history": include_history,
+ "body": body,
+ "path": _normalize_client_path(file_path),
+ "config_path": _normalize_client_path(file_path),
+ "content_path": _normalize_client_path(content_abs_path),
+ "directory_path": _normalize_client_path(directory_path),
+ "project_name": project_name,
+ "scope_key": get_scope_key(project_name, ""),
+ "scope_label": get_scope_label(project_name, ""),
+ "source_scope_key": get_scope_key(project_name, ""),
+ "source_scope_label": get_scope_label(project_name, ""),
+ "frontmatter_extra": extra_config,
+ }
+
+
+def _load_legacy_markdown_file(
+ file_path: str,
+ *,
+ project_name: str = "",
+) -> dict[str, Any] | None:
+ try:
+ content = files.read_file(file_path)
+ except FileNotFoundError:
+ return None
+
+ frontmatter, body, errors = split_frontmatter(content)
+ if errors:
+ return None
+
+ raw_name = str(frontmatter.get("name") or "").strip()
+ description = str(frontmatter.get("description") or "").strip()
+ if not raw_name or not description:
+ return None
+
+ try:
+ command_name = sanitize_command_name(raw_name)
+ except ValueError:
+ return None
+
+ argument_hint = str(frontmatter.get("argument_hint") or "").strip()
+ extra_frontmatter = {
+ key: value for key, value in frontmatter.items() if key not in {"name", "description", "argument_hint"}
+ }
+ directory_path = str(Path(file_path).parent)
+ return {
+ "name": command_name,
+ "description": description,
+ "argument_hint": argument_hint,
+ "command_type": "text",
+ "include_history": False,
+ "body": body,
+ "path": _normalize_client_path(file_path),
+ "config_path": _normalize_client_path(file_path),
+ "content_path": _normalize_client_path(file_path),
+ "directory_path": _normalize_client_path(directory_path),
+ "project_name": project_name,
+ "scope_key": get_scope_key(project_name, ""),
+ "scope_label": get_scope_label(project_name, ""),
+ "source_scope_key": get_scope_key(project_name, ""),
+ "source_scope_label": get_scope_label(project_name, ""),
+ "frontmatter_extra": extra_frontmatter,
+ }
+
+
+def _validate_command_path(
+ path: str,
+ project_name: str = "",
+ agent_profile: str = "",
+ *,
+ allow_plugin: bool = False,
+) -> str:
+ command_path = _to_abs_path(path)
+ # Allow commands from any effective scope (project overrides global, but global is also valid)
+ valid_roots = [get_scope_directory(scope, "") for scope in _iter_precedence_scopes(project_name)]
+ if not any(files.is_in_dir(command_path, scope_root) for scope_root in valid_roots):
+ is_builtin = _is_builtin_command_path(command_path)
+ plugin_name = "" if is_builtin else _plugin_name_for_commands_path(command_path)
+ if plugin_name:
+ if not allow_plugin:
+ raise ValueError("Plugin commands are read-only")
+ elif is_builtin:
+ if not allow_plugin:
+ raise ValueError("Built-in commands are read-only")
+ else:
+ raise ValueError("Command path is outside the selected scope")
+ if not (
+ command_path.endswith(COMMAND_CONFIG_SUFFIX)
+ or command_path.endswith(LEGACY_COMMAND_FILE_SUFFIX)
+ ):
+ raise ValueError("Command path must point to a .command.yaml or .command.md file")
+ if not os.path.exists(command_path):
+ raise FileNotFoundError("Command file not found")
+ return command_path
+
+
+def _iter_precedence_scopes(project_name: str) -> list[str]:
+ if project_name:
+ return [project_name, ""]
+ return [""]
+
+
+def _list_scope_files(scope_dir: str) -> list[str]:
+ if not os.path.isdir(scope_dir):
+ return []
+ files_in_scope = [
+ str(path)
+ for suffix in (COMMAND_CONFIG_SUFFIX, LEGACY_COMMAND_FILE_SUFFIX)
+ for path in Path(scope_dir).glob(f"*{suffix}")
+ if path.is_file()
+ ]
+ files_in_scope.sort(key=lambda item: Path(item).name.lower())
+ return files_in_scope
+
+
+def _load_scope_commands(project_name: str = "") -> list[dict[str, Any]]:
+ commands: list[dict[str, Any]] = []
+ scope_dir = get_scope_directory(project_name, "")
+
+ for file_path in _list_scope_files(scope_dir):
+ command = _load_command_file(file_path, project_name=project_name)
+ if command:
+ commands.append(command)
+
+ commands.sort(key=lambda item: item["name"])
+ return commands
+
+
+def _discover_plugin_commands() -> list[dict[str, Any]]:
+ """Discover commands contributed by enabled plugins."""
+ commands: list[dict[str, Any]] = []
+ for plugin_name in plugins.get_enabled_plugins(None):
+ if plugin_name == PLUGIN_NAME:
+ continue
+ plugin_dir = plugins.find_plugin_dir(plugin_name)
+ if not plugin_dir:
+ continue
+ plugin_commands_dir = files.get_abs_path(plugin_dir, COMMANDS_DIR)
+ if not os.path.isdir(plugin_commands_dir):
+ continue
+ for file_path in _list_scope_files(plugin_commands_dir):
+ command = _load_command_file(file_path, project_name="")
+ if command:
+ commands.append(_mark_plugin_command(command, plugin_name))
+ return commands
+
+
+def _discover_builtin_commands() -> list[dict[str, Any]]:
+ plugin_dir = plugins.find_plugin_dir(PLUGIN_NAME)
+ if not plugin_dir:
+ return []
+ commands_dir = files.get_abs_path(plugin_dir, COMMANDS_DIR)
+ commands: list[dict[str, Any]] = []
+ for file_path in _list_scope_files(commands_dir):
+ command = _load_command_file(file_path, project_name="")
+ if command:
+ commands.append(_mark_builtin_command(command))
+ return commands
+
+
+def _collect_lower_scope_matches(project_name: str = "") -> dict[str, list[str]]:
+ lower_scope_matches: dict[str, list[str]] = {}
+ if not project_name:
+ return lower_scope_matches
+
+ for command in _load_scope_commands(""):
+ lower_scope_matches.setdefault(command["name"], []).append(get_scope_label("", ""))
+
+ return lower_scope_matches
+
+
+def _generate_duplicate_name(
+ command_name: str,
+ *,
+ project_name: str = "",
+) -> str:
+ base_name = sanitize_command_name(f"{command_name}-copy")
+ candidate = base_name
+ counter = 2
+ scope_dir = ensure_scope_directory(project_name, "")
+
+ while os.path.exists(files.get_abs_path(scope_dir, command_file_name(candidate))):
+ candidate = f"{base_name}-{counter}"
+ counter += 1
+
+ return candidate
+
+
+def _build_template_context(invocation: dict[str, Any]) -> dict[str, Any]:
+ arguments = invocation.get("arguments", {})
+ return {
+ "full": invocation.get("raw_text", ""),
+ "raw": invocation.get("raw_arguments", ""),
+ "command": invocation.get("command_name", ""),
+ "args": {
+ "raw": arguments.get("raw", ""),
+ "tokens": arguments.get("tokens", []),
+ "positional": arguments.get("positional", []),
+ "flags": arguments.get("flags", {}),
+ },
+ }
+
+
+def _resolve_placeholder(path: str, context: dict[str, Any]) -> str:
+ resolved = _resolve_path(context, path)
+ if resolved is None:
+ return ""
+ if isinstance(resolved, (dict, list)):
+ return json.dumps(resolved, ensure_ascii=False)
+ return str(resolved)
+
+
+def _resolve_path(value: Any, path: str) -> Any:
+ current = value
+ for part in path.split("."):
+ if isinstance(current, dict):
+ if part in current:
+ current = current[part]
+ continue
+ part_with_dash = part.replace("_", "-")
+ if part_with_dash in current:
+ current = current[part_with_dash]
+ continue
+ return None
+
+ if isinstance(current, list):
+ if not part.isdigit():
+ return None
+ index = int(part)
+ if index < 0 or index >= len(current):
+ return None
+ current = current[index]
+ continue
+
+ return None
+ return current
+
+
+def _render_legacy_placeholders(template: str, invocation: dict[str, Any]) -> str:
+ rendered = template
+ arguments = invocation.get("arguments", {})
+ positional = arguments.get("positional", [])
+ for index in range(10):
+ rendered = rendered.replace(f"${index}", positional[index] if index < len(positional) else "")
+ rendered = rendered.replace("$ARGUMENTS", invocation.get("raw_arguments", ""))
+ return rendered
+
+
+def _template_references_arguments(template: str) -> bool:
+ if "$ARGUMENTS" in template:
+ return True
+ if any(f"${index}" in template for index in range(10)):
+ return True
+ if "{raw}" in template:
+ return True
+ return "{args." in template
+
+
+def _parse_long_flag(token: str, tokens: list[str], index: int) -> tuple[str, Any, int]:
+ flag_token = token[2:]
+ if "=" in flag_token:
+ key, value = flag_token.split("=", 1)
+ return _normalize_flag_name(key), value, 1
+
+ key = _normalize_flag_name(flag_token)
+ next_index = index + 1
+ if next_index < len(tokens) and not tokens[next_index].startswith("-"):
+ return key, tokens[next_index], 2
+ return key, True, 1
+
+
+def _parse_short_flag_bundle(
+ token: str, tokens: list[str], index: int, flags: dict[str, Any]
+) -> int:
+ short_token = token[1:]
+ if len(short_token) > 1 and "=" not in short_token:
+ for char in short_token:
+ _set_flag_value(flags, _normalize_flag_name(char), True)
+ return 1
+
+ if "=" in short_token:
+ key, value = short_token.split("=", 1)
+ _set_flag_value(flags, _normalize_flag_name(key), value)
+ return 1
+
+ key = _normalize_flag_name(short_token)
+ _set_flag_value(flags, key, True)
+ return 1
+
+
+def _set_flag_value(flags: dict[str, Any], key: str, value: Any) -> None:
+ if key in flags:
+ current = flags[key]
+ if isinstance(current, list):
+ current.append(value)
+ else:
+ flags[key] = [current, value]
+ return
+ flags[key] = value
+
+
+def _normalize_flag_name(raw_flag: str) -> str:
+ return (raw_flag or "").strip().lower().replace("-", "_")
+
+
+def _split_arguments(raw_arguments: str) -> list[str]:
+ if not raw_arguments:
+ return []
+ try:
+ return shlex.split(raw_arguments)
+ except ValueError:
+ return raw_arguments.split()
+
+
+async def _run_script_command(
+ *,
+ command: dict[str, Any],
+ invocation: dict[str, Any],
+ project_name: str,
+ context_id: str,
+) -> dict[str, Any]:
+ script_path = _to_abs_path(command.get("content_path", ""))
+ if not script_path:
+ raise ValueError("Script command is missing script_path")
+ if not os.path.exists(script_path):
+ raise ValueError("Script file not found for this command")
+
+ module_globals = runpy.run_path(script_path)
+ hook = module_globals.get("run")
+ if not callable(hook):
+ raise ValueError('Script command must expose a callable "run(payload)" function')
+
+ context = _get_context(context_id)
+ history = _extract_chat_history(context) if command.get("include_history") else []
+ payload = {
+ "command": _public_command_payload(command),
+ "invocation": invocation,
+ "arguments": invocation.get("arguments", {}),
+ "context": {
+ "context_id": context_id,
+ "project_name": project_name,
+ "agent": getattr(context, "agent0", None) if context else None,
+ "chat_history": history,
+ },
+ }
+
+ result = hook(payload)
+ if inspect.isawaitable(result):
+ result = await result
+ return _normalize_script_result(result)
+
+
+def _normalize_script_result(result: Any) -> dict[str, Any]:
+ if isinstance(result, str):
+ return {"text": result, "effects": []}
+
+ if isinstance(result, dict):
+ text = result.get("text")
+ if text is None:
+ text = result.get("replacement_text")
+
+ effects = result.get("effects")
+ if effects is None:
+ effects = []
+ if not isinstance(effects, list):
+ raise ValueError("Script result.effects must be an array when provided")
+
+ normalized_text = str(text) if text is not None else ""
+ return {"text": normalized_text, "effects": effects}
+
+ raise ValueError("Script run(payload) must return either a string or an object")
+
+
+def _extract_chat_history(context: AgentContext | None) -> list[Any]:
+ if not context:
+ return []
+
+ for attribute in ("chat_history", "history", "messages"):
+ value = getattr(context, attribute, None)
+ if isinstance(value, list):
+ return value
+
+ getter = getattr(context, "get_data", None)
+ if callable(getter):
+ for key in ("chat_history", "messages", "history"):
+ value = getter(key)
+ if isinstance(value, list):
+ return value
+
+ return []
+
+
+def _public_command_payload(command: dict[str, Any]) -> dict[str, Any]:
+ payload = dict(command)
+ payload.pop("body", None)
+ return payload
+
+
+def _normalize_client_path(path: str) -> str:
+ return files.normalize_a0_path(path).replace("\\", "/")
+
+
+def _paths_equal(path_a: str, path_b: str) -> bool:
+ if not path_a or not path_b:
+ return False
+ return os.path.normcase(os.path.normpath(path_a)) == os.path.normcase(
+ os.path.normpath(path_b)
+ )
+
+
+def _get_context(context_id: str = "") -> AgentContext | None:
+ if context_id:
+ return AgentContext.get(context_id)
+ return AgentContext.current() or AgentContext.first()
+
+
+def _to_abs_path(path: str) -> str:
+ return files.fix_dev_path(path)
+
+
+def _plugin_scope_label(plugin_name: str) -> str:
+ return f"Plugin: {plugin_name}"
+
+
+def _mark_plugin_command(command: dict[str, Any], plugin_name: str) -> dict[str, Any]:
+ scope_label = _plugin_scope_label(plugin_name)
+ command["source_plugin"] = plugin_name
+ command["scope_key"] = "plugin"
+ command["scope_label"] = scope_label
+ command["source_scope_key"] = "plugin"
+ command["source_scope_label"] = scope_label
+ return command
+
+
+def _mark_builtin_command(command: dict[str, Any]) -> dict[str, Any]:
+ command["source_plugin"] = PLUGIN_NAME
+ command["scope_key"] = "builtin"
+ command["scope_label"] = "Built-in"
+ command["source_scope_key"] = "builtin"
+ command["source_scope_label"] = "Built-in"
+ return command
+
+
+def _builtin_commands_dir() -> str:
+ plugin_dir = plugins.find_plugin_dir(PLUGIN_NAME)
+ return files.get_abs_path(plugin_dir, COMMANDS_DIR) if plugin_dir else ""
+
+
+def _is_builtin_command_path(path: str) -> bool:
+ commands_dir = _builtin_commands_dir()
+ return bool(commands_dir and files.is_in_dir(_to_abs_path(path), commands_dir))
+
+
+def _plugin_name_for_commands_path(path: str) -> str:
+ abs_path = _to_abs_path(path)
+ for plugin_name in plugins.get_enabled_plugins(None):
+ if plugin_name == PLUGIN_NAME:
+ continue
+ plugin_dir = plugins.find_plugin_dir(plugin_name)
+ if not plugin_dir:
+ continue
+ plugin_commands_dir = files.get_abs_path(plugin_dir, COMMANDS_DIR)
+ if files.is_in_dir(abs_path, plugin_commands_dir):
+ return plugin_name
+ return ""
+
+
+def _is_plugin_commands_dir(path: str) -> bool:
+ """Check if a path is inside any installed plugin's commands/ subdirectory."""
+ return bool(_plugin_name_for_commands_path(path))
+
+
+def strip_private_scope(scope: dict[str, Any]) -> dict[str, Any]:
+ """Return a copy of *scope* with all keys prefixed by ``_`` removed."""
+ return {key: value for key, value in scope.items() if not key.startswith("_")}
+
+
+def _strip_private_scope(scope: dict[str, Any]) -> dict[str, Any]:
+ return strip_private_scope(scope)
diff --git a/plugins/_commands/plugin.yaml b/plugins/_commands/plugin.yaml
new file mode 100644
index 000000000..799c0b43e
--- /dev/null
+++ b/plugins/_commands/plugin.yaml
@@ -0,0 +1,8 @@
+name: _commands
+title: Commands
+description: YAML-configured slash commands with text templates or Python hooks.
+version: 0.5.0
+settings_sections: []
+per_project_config: false
+per_agent_config: false
+always_enabled: false
diff --git a/plugins/_commands/skills/commands-create-slash-command/SKILL.md b/plugins/_commands/skills/commands-create-slash-command/SKILL.md
new file mode 100644
index 000000000..a594038bc
--- /dev/null
+++ b/plugins/_commands/skills/commands-create-slash-command/SKILL.md
@@ -0,0 +1,72 @@
+---
+name: commands-create-slash-command
+description: Create or update Agent Zero slash commands for the built-in Commands plugin. Use when the user asks to add, edit, duplicate, or refine a reusable /command backed by YAML config plus text/python content files.
+version: 1.0.0
+tags: ["commands", "slash-commands", "plugin", "yaml", "python", "templates"]
+triggers:
+ - create slash command
+ - add slash command
+ - update slash command
+ - edit slash command
+ - commands plugin
+---
+
+# Commands Plugin Slash Command Authoring
+
+Use this skill when the user wants a reusable `/command` for Agent Zero's built-in `_commands` plugin.
+
+## Source Of Truth
+
+- Slash commands are file-backed, not database rows.
+- Each command uses:
+ - one config file: `<slug>.command.yaml`
+ - one content file:
+ - text template: `<slug>.txt`, or
+ - python hook: `<slug>.py`
+- Required config keys:
+ - `name`
+ - `description`
+ - `type` (`text` or `script`)
+- Optional config keys:
+ - `argument_hint`
+ - `include_history` (script commands)
+- Preserve unknown config keys when editing existing commands.
+
+## Scope Resolution
+
+Choose the target folder from the requested scope:
+
+- Project: `usr/projects/<project>/.a0proj/plugins/_commands/commands/`
+- Global fallback: `usr/plugins/_commands/commands/`
+
+If the user does not specify a scope, prefer the active chat scope when it is clear. Otherwise use the global scope.
+
+## File Rules
+
+- Config file format: `<slug>.command.yaml`
+- Slash command name should be lowercase and hyphenated, for example `explain-code`
+- For text commands, keep the `.txt` template concise and directly reusable
+- For script commands, implement `run(payload)` in the `.py` file
+- If the command expects trailing input, use `{raw}`, `{args.positional.0}`, or `{args.flags.some_flag}`
+
+Use the bundled templates in `template.command.yaml` and `template.command.txt` when creating a new text command from scratch.
+
+## Editing Workflow
+
+1. Determine scope and final slash command name.
+2. Check whether a command file already exists in that scope.
+3. If it exists, load the file first and preserve unknown frontmatter keys.
+4. Update YAML config and template/script content.
+5. Save the file in the correct scope folder.
+6. Report:
+ - the saved config path
+ - the saved content path
+ - the slash command name in `/name` form
+
+## Output Contract
+
+After saving, explicitly state the final file path and the exact slash command invocation, for example:
+
+- `Saved config: /a0/usr/plugins/_commands/commands/explain-code.command.yaml`
+- `Saved content: /a0/usr/plugins/_commands/commands/explain-code.txt`
+- `Invoke with: /explain-code`
diff --git a/plugins/_commands/skills/commands-create-slash-command/template.command.txt b/plugins/_commands/skills/commands-create-slash-command/template.command.txt
new file mode 100644
index 000000000..312a318a3
--- /dev/null
+++ b/plugins/_commands/skills/commands-create-slash-command/template.command.txt
@@ -0,0 +1,3 @@
+Describe the work to perform here.
+
+{raw}
diff --git a/plugins/_commands/skills/commands-create-slash-command/template.command.yaml b/plugins/_commands/skills/commands-create-slash-command/template.command.yaml
new file mode 100644
index 000000000..ee8b4150f
--- /dev/null
+++ b/plugins/_commands/skills/commands-create-slash-command/template.command.yaml
@@ -0,0 +1,5 @@
+name: example-command
+description: Briefly describe what this slash command does.
+argument_hint: Optional free-form text after /example-command
+type: text
+template_path: example-command.txt
diff --git a/plugins/_commands/tests/conftest.py b/plugins/_commands/tests/conftest.py
new file mode 100644
index 000000000..c9831dbb4
--- /dev/null
+++ b/plugins/_commands/tests/conftest.py
@@ -0,0 +1,11 @@
+# tests/conftest.py
+import sys
+from pathlib import Path
+
+# Ensure A0 framework root is first in sys.path so that
+# `from helpers import ...` resolves to A0's helpers/, not
+# the Commands plugin's local helpers/ directory.
+a0_root = str(Path(__file__).resolve().parents[3]) # tests/ → _commands → plugins → a0
+while a0_root in sys.path:
+ sys.path.remove(a0_root)
+sys.path.insert(0, a0_root)
diff --git a/plugins/_commands/tests/test_commands_plugin.py b/plugins/_commands/tests/test_commands_plugin.py
new file mode 100644
index 000000000..7cb4333a2
--- /dev/null
+++ b/plugins/_commands/tests/test_commands_plugin.py
@@ -0,0 +1,367 @@
+from __future__ import annotations
+
+import threading
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+import sys
+
+import pytest
+from flask import Flask
+
+PROJECT_ROOT = Path(__file__).resolve().parents[4]
+if str(PROJECT_ROOT) not in sys.path:
+ sys.path.insert(0, str(PROJECT_ROOT))
+
+from agent import AgentContext
+from helpers import files, projects, skills as skills_helper
+from initialize import initialize_agent
+from plugins._commands.api.commands import Commands
+from plugins._commands.commands import connector_commands
+from plugins._commands.helpers import commands as commands_helper
+
+
+@dataclass
+class ScopeFixture:
+ prefix: str
+ project_name: str
+ created_paths: list[str] = field(default_factory=list)
+
+
+def _track_paths(scope: ScopeFixture, command: dict) -> dict:
+ for key in ("path", "config_path", "content_path"):
+ command_path = files.fix_dev_path(command.get(key, ""))
+ if command_path and command_path not in scope.created_paths:
+ scope.created_paths.append(command_path)
+ return command
+
+
+def _save_command(
+ scope: ScopeFixture,
+ *,
+ project_name: str = "",
+ name: str,
+ description: str,
+ body: str = "",
+ argument_hint: str = "",
+ command_type: str = "text",
+ include_history: bool = False,
+ extra_frontmatter: dict | None = None,
+) -> dict:
+ command = commands_helper.save_command(
+ project_name=project_name,
+ name=name,
+ description=description,
+ body=body,
+ argument_hint=argument_hint,
+ command_type=command_type,
+ include_history=include_history,
+ extra_frontmatter=extra_frontmatter or {},
+ )
+ return _track_paths(scope, command)
+
+
+def scope_fixture() -> ScopeFixture:
+ suffix = uuid.uuid4().hex[:8]
+ scope = ScopeFixture(
+ prefix=f"commands-test-{suffix}",
+ project_name=f"commands_project_{suffix}",
+ )
+
+ yield scope
+
+ for path in reversed(scope.created_paths):
+ files.delete_file(path)
+
+ files.delete_dir(files.get_abs_path("usr", "projects", scope.project_name))
+
+
+def _new_handler() -> Commands:
+ app = Flask("commands_plugin_tests")
+ app.secret_key = "commands-plugin-tests"
+ return Commands(app, threading.RLock())
+
+
+def test_command_config_and_template_files_round_trip(
+ scope_fixture: ScopeFixture,
+) -> None:
+ command = _save_command(
+ scope_fixture,
+ name=f"Explain {scope_fixture.prefix}",
+ description="Explain a code sample clearly.",
+ body="Explain the sample.\n\n{raw}",
+ argument_hint="Paste code or describe the module.",
+ command_type="text",
+ extra_frontmatter={"category": "analysis", "audience": "team"},
+ )
+
+ config_path = Path(files.fix_dev_path(command["path"]))
+ content_path = Path(files.fix_dev_path(command["content_path"]))
+ assert config_path.name == f"explain-{scope_fixture.prefix}.command.yaml"
+ assert content_path.name == f"explain-{scope_fixture.prefix}.txt"
+
+ loaded = commands_helper.get_command(command["path"])
+ assert loaded["frontmatter_extra"] == {
+ "category": "analysis",
+ "audience": "team",
+ }
+
+ config_yaml = files.read_file(str(config_path))
+ assert "category: analysis" in config_yaml
+ assert "audience: team" in config_yaml
+ assert f"name: explain-{scope_fixture.prefix}" in config_yaml
+ assert "type: text" in config_yaml
+
+ template_text = files.read_file(str(content_path))
+ assert "Explain the sample." in template_text
+
+
+def test_parse_arguments_and_render_template_support_flags() -> None:
+ parsed = commands_helper.parse_arguments(
+ '--git-url=https://github.com/acme/repo "quoted phrase" -v 30%'
+ )
+ assert parsed["flags"]["git_url"] == "https://github.com/acme/repo"
+ assert parsed["flags"]["v"] is True
+ assert parsed["positional"] == ["quoted phrase", "30%"]
+
+ invocation = commands_helper.parse_slash_invocation(
+ '/optimize 30% --mode fast --git-url=https://github.com/acme/repo'
+ )
+ rendered = commands_helper.render_text_template(
+ "Pct: {args.positional.0}\nMode: {args.flags.mode}\nURL: {args.flags.git_url}\nRaw: {raw}",
+ invocation,
+ )
+ assert rendered == (
+ "Pct: 30%\n"
+ "Mode: fast\n"
+ "URL: https://github.com/acme/repo\n"
+ "Raw: 30% --mode fast --git-url=https://github.com/acme/repo"
+ )
+
+ appended = commands_helper.render_text_template(
+ "Summarize this request.",
+ commands_helper.parse_slash_invocation("/summarize alpha beta"),
+ )
+ assert appended == "Summarize this request.\n\nArguments:\nalpha beta"
+
+ invalid_invocation = commands_helper.parse_slash_invocation("/?")
+ assert invalid_invocation["command_name"] == ""
+
+
+def test_list_effective_commands_project_overrides_global(
+ scope_fixture: ScopeFixture,
+) -> None:
+ shared_name = f"{scope_fixture.prefix}-shared"
+
+ _save_command(
+ scope_fixture,
+ name=shared_name,
+ description="global description",
+ body="global body",
+ command_type="text",
+ )
+ _save_command(
+ scope_fixture,
+ project_name=scope_fixture.project_name,
+ name=shared_name,
+ description="project description",
+ body="project body",
+ command_type="text",
+ )
+
+ project_commands, _ = commands_helper.list_effective_commands(
+ scope_fixture.project_name
+ )
+ global_commands, _ = commands_helper.list_effective_commands("")
+
+ assert {command["name"]: command for command in project_commands}[shared_name][
+ "description"
+ ] == "project description"
+ assert {command["name"]: command for command in global_commands}[shared_name][
+ "description"
+ ] == "global description"
+
+ scoped_commands, _ = commands_helper.list_scope_commands(scope_fixture.project_name)
+ scoped_command = next(
+ command for command in scoped_commands if command["name"] == shared_name
+ )
+ assert scoped_command["override_count"] == 1
+ assert scoped_command["override_scopes"] == ["Global"]
+
+
+def test_models_command_always_opens_modal():
+ result = connector_commands.run(
+ {
+ "invocation": {
+ "command_name": "models",
+ "raw_arguments": "default",
+ },
+ "context": {"context_id": ""},
+ }
+ )
+
+ assert result == {
+ "text": "",
+ "effects": [{"type": "open_plugin_config", "plugin": "_model_config"}],
+ }
+
+
+async def test_commands_api_crud_and_resolve_text_and_script(
+ scope_fixture: ScopeFixture,
+) -> None:
+ handler = _new_handler()
+ command_name = f"{scope_fixture.prefix}-context"
+
+ context = AgentContext(
+ config=initialize_agent({}),
+ set_current=True,
+ )
+ context.set_data(projects.CONTEXT_DATA_KEY_PROJECT, scope_fixture.project_name)
+
+ try:
+ saved = await handler.process(
+ {
+ "action": "save",
+ "project_name": scope_fixture.project_name,
+ "name": command_name,
+ "description": "context override",
+ "command_type": "text",
+ "body": (
+ "Repo: {args.flags.git_url}\n"
+ "Mode: {args.flags.mode}\n"
+ "Raw: {raw}"
+ ),
+ },
+ None,
+ )
+ assert isinstance(saved, dict)
+ assert saved["ok"] is True
+ saved_command = _track_paths(scope_fixture, saved["command"])
+
+ loaded = await handler.process(
+ {
+ "action": "get",
+ "project_name": scope_fixture.project_name,
+ "path": saved_command["path"],
+ },
+ None,
+ )
+ assert isinstance(loaded, dict)
+ assert loaded["command"]["description"] == "context override"
+
+ resolved_text = await handler.process(
+ {
+ "action": "resolve",
+ "project_name": scope_fixture.project_name,
+ "path": saved_command["path"],
+ "slash_text": f"/{command_name} --git-url=https://github.com/acme/repo --mode deep",
+ "context_id": context.id,
+ },
+ None,
+ )
+ assert isinstance(resolved_text, dict)
+ assert resolved_text["ok"] is True
+ rendered_text = resolved_text["resolution"]["result"]["text"]
+ assert "Repo: https://github.com/acme/repo" in rendered_text
+ assert "Mode: deep" in rendered_text
+
+ script_saved = await handler.process(
+ {
+ "action": "save",
+ "project_name": scope_fixture.project_name,
+ "name": f"{command_name}-script",
+ "description": "script command",
+ "command_type": "script",
+ "include_history": True,
+ "body": (
+ "def run(payload):\n"
+ " flags = payload['arguments'].get('flags', {})\n"
+ " return {\n"
+ " 'text': f\"Script mode: {flags.get('mode', 'none')}\",\n"
+ " 'effects': [\n"
+ " {'type': 'toast', 'level': 'success', 'message': 'Script executed'}\n"
+ " ],\n"
+ " }\n"
+ ),
+ },
+ None,
+ )
+ assert isinstance(script_saved, dict)
+ assert script_saved["ok"] is True
+ script_command = _track_paths(scope_fixture, script_saved["command"])
+
+ resolved_script = await handler.process(
+ {
+ "action": "resolve",
+ "project_name": scope_fixture.project_name,
+ "path": script_command["path"],
+ "slash_text": f"/{command_name}-script --mode turbo",
+ "context_id": context.id,
+ },
+ None,
+ )
+ assert isinstance(resolved_script, dict)
+ assert resolved_script["ok"] is True
+ assert resolved_script["resolution"]["result"]["text"] == "Script mode: turbo"
+ assert resolved_script["resolution"]["result"]["effects"] == [
+ {
+ "type": "toast",
+ "level": "success",
+ "message": "Script executed",
+ }
+ ]
+
+ duplicated = await handler.process(
+ {
+ "action": "duplicate",
+ "project_name": scope_fixture.project_name,
+ "path": saved_command["path"],
+ },
+ None,
+ )
+ assert isinstance(duplicated, dict)
+ assert duplicated["ok"] is True
+ assert duplicated["command"]["name"].startswith(f"{command_name}-copy")
+ duplicated_command = _track_paths(scope_fixture, duplicated["command"])
+
+ effective_list = await handler.process(
+ {"action": "list_effective", "context_id": context.id},
+ None,
+ )
+ assert isinstance(effective_list, dict)
+ effective_by_name = {
+ command["name"]: command for command in effective_list["commands"]
+ }
+ assert effective_by_name[command_name]["description"] == "context override"
+ assert effective_by_name[command_name]["source_scope_key"] == "project"
+
+ scope_info = await handler.process(
+ {"action": "scope_info", "context_id": context.id},
+ None,
+ )
+ assert isinstance(scope_info, dict)
+ assert scope_info["scope"]["project_name"] == scope_fixture.project_name
+
+ deleted = await handler.process(
+ {
+ "action": "delete",
+ "project_name": scope_fixture.project_name,
+ "path": duplicated_command["path"],
+ },
+ None,
+ )
+ assert isinstance(deleted, dict)
+ assert deleted["ok"] is True
+ finally:
+ AgentContext.remove(context.id)
+ AgentContext.set_current("")
+
+
+def test_plugin_scoped_skill_is_discoverable() -> None:
+ skill = skills_helper.find_skill("commands-create-slash-command")
+ assert skill is not None
+ assert skill.skill_md_path.as_posix().endswith(
+ "plugins/_commands/skills/commands-create-slash-command/SKILL.md"
+ )
diff --git a/plugins/_commands/tests/test_legacy_migration.py b/plugins/_commands/tests/test_legacy_migration.py
new file mode 100644
index 000000000..8242db5b2
--- /dev/null
+++ b/plugins/_commands/tests/test_legacy_migration.py
@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+PROJECT_ROOT = Path(__file__).resolve().parents[4]
+if str(PROJECT_ROOT) not in sys.path:
+ sys.path.insert(0, str(PROJECT_ROOT))
+
+from helpers import plugins
+from plugins._commands.extensions.python.startup_migration._20_migrate_legacy_commands import (
+ migrate_legacy_commands,
+)
+
+
+def test_migrate_legacy_commands_copies_user_data_and_disables_old_plugin(tmp_path: Path):
+ legacy_root = tmp_path / "usr" / "plugins" / "commands"
+ legacy_commands = legacy_root / "commands"
+ legacy_skills = legacy_root / "skills" / "custom-skill"
+ project_commands = (
+ tmp_path
+ / "usr"
+ / "projects"
+ / "demo"
+ / ".a0proj"
+ / "plugins"
+ / "commands"
+ / "commands"
+ )
+ new_commands = tmp_path / "usr" / "plugins" / "_commands" / "commands"
+
+ legacy_commands.mkdir(parents=True)
+ legacy_skills.mkdir(parents=True)
+ project_commands.mkdir(parents=True)
+ new_commands.mkdir(parents=True)
+
+ (legacy_root / "plugin.yaml").write_text("name: commands\n", encoding="utf-8")
+ (legacy_root / plugins.ENABLED_FILE_NAME).write_text("", encoding="utf-8")
+ (legacy_commands / "demo.command.yaml").write_text(
+ "name: demo\ndescription: Demo\ntype: text\ntemplate_path: demo.txt\n",
+ encoding="utf-8",
+ )
+ (legacy_commands / "demo.txt").write_text("legacy demo\n", encoding="utf-8")
+ (legacy_commands / "keep.command.yaml").write_text(
+ "name: keep\ndescription: Keep\ntype: text\ntemplate_path: keep.txt\n",
+ encoding="utf-8",
+ )
+ (new_commands / "keep.command.yaml").write_text("existing\n", encoding="utf-8")
+ (project_commands / "project.command.yaml").write_text(
+ "name: project\ndescription: Project\ntype: text\ntemplate_path: project.txt\n",
+ encoding="utf-8",
+ )
+ (legacy_skills / "SKILL.md").write_text("---\nname: custom-skill\n---\n", encoding="utf-8")
+
+ result = migrate_legacy_commands(tmp_path)
+
+ assert result["copied_commands"] == 3
+ assert result["copied_skills"] == 1
+ assert result["disabled_roots"] == 2
+
+ assert (new_commands / "demo.command.yaml").read_text(encoding="utf-8").startswith(
+ "name: demo"
+ )
+ assert (new_commands / "demo.txt").read_text(encoding="utf-8") == "legacy demo\n"
+ assert (new_commands / "keep.command.yaml").read_text(encoding="utf-8") == "existing\n"
+ assert (
+ tmp_path
+ / "usr"
+ / "projects"
+ / "demo"
+ / ".a0proj"
+ / "plugins"
+ / "_commands"
+ / "commands"
+ / "project.command.yaml"
+ ).exists()
+ assert (
+ tmp_path
+ / "usr"
+ / "plugins"
+ / "_commands"
+ / "skills"
+ / "custom-skill"
+ / "SKILL.md"
+ ).exists()
+ assert not (legacy_root / plugins.ENABLED_FILE_NAME).exists()
+ assert (legacy_root / plugins.DISABLED_FILE_NAME).exists()
+ assert (
+ tmp_path
+ / "usr"
+ / "projects"
+ / "demo"
+ / ".a0proj"
+ / "plugins"
+ / "commands"
+ / plugins.DISABLED_FILE_NAME
+ ).exists()
diff --git a/plugins/_commands/tests/test_plugin_command_discovery.py b/plugins/_commands/tests/test_plugin_command_discovery.py
new file mode 100644
index 000000000..9a371ef1c
--- /dev/null
+++ b/plugins/_commands/tests/test_plugin_command_discovery.py
@@ -0,0 +1,337 @@
+from __future__ import annotations
+
+import os
+import shutil
+import uuid
+from pathlib import Path
+import sys
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).resolve().parents[4]
+if str(PROJECT_ROOT) not in sys.path:
+ sys.path.insert(0, str(PROJECT_ROOT))
+
+from helpers import cache, files, plugins
+from plugins._commands.api.commands import Commands
+from plugins._commands.helpers import commands as commands_helper
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
[email protected](autouse=True)
+def _clear_plugin_cache():
+ """Ensure plugin list cache is fresh for every test."""
+ cache.clear("*(plugins)*")
+ yield
+ cache.clear("*(plugins)*")
+
+
+def fake_plugin():
+ """Create a temporary plugin in usr/plugins/ with a commands/ directory."""
+ suffix = uuid.uuid4().hex[:8]
+ plugin_name = f"_test_cmd_disc_{suffix}"
+ plugin_dir = files.get_abs_path(files.USER_DIR, files.PLUGINS_DIR, plugin_name)
+ commands_dir = os.path.join(plugin_dir, "commands")
+ os.makedirs(commands_dir, exist_ok=True)
+
+ # Write plugin.yaml so the plugin is discoverable
+ files.write_file(
+ os.path.join(plugin_dir, "plugin.yaml"),
+ f"name: {plugin_name}\ntitle: Test\ndescription: Test\n",
+ )
+
+ yield {"name": plugin_name, "dir": plugin_dir, "commands_dir": commands_dir}
+
+ # Cleanup
+ shutil.rmtree(plugin_dir, ignore_errors=True)
+ cache.remove(plugins.PLUGINS_LIST_CACHE_AREA, "")
+
+
+def _write_plugin_command(
+ fake_plugin: dict,
+ *,
+ name: str,
+ description: str,
+ body: str = "default body",
+) -> str:
+ """Write a .command.yaml + .txt into the fake plugin's commands/ dir.
+
+ Returns the config file path.
+ """
+ slug = commands_helper.sanitize_command_name(name)
+ cdir = fake_plugin["commands_dir"]
+ config_path = os.path.join(cdir, f"{slug}.command.yaml")
+ content_path = os.path.join(cdir, f"{slug}.txt")
+
+ files.write_file(
+ config_path,
+ f"name: {slug}\ndescription: {description}\ntype: text\ntemplate_path: {slug}.txt\n",
+ )
+ files.write_file(content_path, body)
+ return config_path
+
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+
+def test_discover_plugin_commands_finds_plugin_commands(fake_plugin: dict):
+ """Plugin commands must be discovered without relying on real installs."""
+ _write_plugin_command(
+ fake_plugin,
+ name=f"{fake_plugin['name']}-build",
+ description="build test",
+ )
+
+ discovered = commands_helper._discover_plugin_commands()
+ names = {c["name"] for c in discovered}
+ expected = commands_helper.sanitize_command_name(f"{fake_plugin['name']}-build")
+ assert expected in names, f"Expected {expected!r} in discovered names, got {names}"
+
+ for cmd in discovered:
+ if cmd["name"] == expected:
+ assert cmd["source_plugin"] == fake_plugin["name"]
+ assert cmd["scope_key"] == "plugin"
+ assert cmd["scope_label"] == f"Plugin: {fake_plugin['name']}"
+ assert cmd["source_scope_key"] == "plugin"
+ assert cmd["source_scope_label"] == f"Plugin: {fake_plugin['name']}"
+ break
+
+
+def test_discover_plugin_commands_skips_own_plugin():
+ """The commands plugin itself must NOT appear in _discover_plugin_commands."""
+ discovered = commands_helper._discover_plugin_commands()
+ for cmd in discovered:
+ assert cmd.get("source_plugin") != "_commands"
+
+
+def test_discover_plugin_commands_skips_disabled_plugins(fake_plugin: dict):
+ """Disabled plugins must not contribute slash commands to the picker."""
+ _write_plugin_command(
+ fake_plugin,
+ name=f"{fake_plugin['name']}-disabled",
+ description="disabled command",
+ )
+ files.write_file(os.path.join(fake_plugin["dir"], plugins.DISABLED_FILE_NAME), "")
+ cache.clear("*(plugins)*")
+
+ discovered = commands_helper._discover_plugin_commands()
+ names = {command["name"] for command in discovered}
+ expected = commands_helper.sanitize_command_name(f"{fake_plugin['name']}-disabled")
+ assert expected not in names
+
+
+def test_discover_builtin_commands_marks_own_commands_read_only():
+ """Bundled _commands command files are discoverable as built-ins, not plugin commands."""
+ discovered = commands_helper._discover_builtin_commands()
+ command = next((cmd for cmd in discovered if cmd["name"] == "new"), None)
+
+ assert command is not None
+ assert command["source_plugin"] == "_commands"
+ assert command["scope_key"] == "builtin"
+ assert command["scope_label"] == "Built-in"
+
+ loaded = commands_helper.get_command(command["path"])
+ assert loaded["name"] == "new"
+ assert loaded["scope_key"] == "builtin"
+
+ with pytest.raises(ValueError, match="Built-in commands are read-only"):
+ commands_helper.save_command(
+ existing_path=command["path"],
+ name="new",
+ description="updated description",
+ body="updated body",
+ )
+
+ with pytest.raises(ValueError, match="Built-in commands are read-only"):
+ commands_helper.delete_command(command["path"])
+
+
+def test_builtin_commands_use_canonical_names_only():
+ discovered = commands_helper._discover_builtin_commands()
+ names = {command["name"] for command in discovered}
+
+ assert {"attach", "computer-use", "models", "plugins", "project"} <= names
+ assert {
+ "computer",
+ "cu",
+ "disconnect",
+ "exit",
+ "help",
+ "image",
+ "img",
+ "keys",
+ "model",
+ "plugin",
+ "projects",
+ }.isdisjoint(names)
+
+
+def test_webui_effective_list_hides_webui_hidden_commands():
+ effective, _ = commands_helper.list_effective_commands("")
+ chats = next(command for command in effective if command["name"] == "chats")
+ response = object.__new__(Commands)._list_effective({"context_id": ""})
+ names = {command["name"] for command in response["commands"]}
+
+ assert chats["frontmatter_extra"]["webui_hidden"] is True
+ assert "chats" not in names
+
+
+def test_list_effective_includes_plugin_commands(fake_plugin: dict):
+ """list_effective_commands must include commands from other plugins."""
+ _write_plugin_command(
+ fake_plugin,
+ name=f"{fake_plugin['name']}-effective",
+ description="effective test",
+ )
+
+ effective, _ = commands_helper.list_effective_commands("")
+ expected = commands_helper.sanitize_command_name(f"{fake_plugin['name']}-effective")
+ command = next((item for item in effective if item["name"] == expected), None)
+ assert command is not None
+ assert command["scope_key"] == "plugin"
+ assert command["scope_label"] == f"Plugin: {fake_plugin['name']}"
+
+
+def test_plugin_commands_appear_in_effective_list(fake_plugin: dict):
+ """Commands from a freshly-created plugin appear in effective list."""
+ _write_plugin_command(
+ fake_plugin,
+ name=f"{fake_plugin['name']}-hello",
+ description="A test command from a plugin",
+ body="Hello from plugin",
+ )
+
+ effective, _ = commands_helper.list_effective_commands("")
+ expected = commands_helper.sanitize_command_name(f"{fake_plugin['name']}-hello")
+ command = next((item for item in effective if item["name"] == expected), None)
+ assert command is not None
+ assert command["source_plugin"] == fake_plugin["name"]
+
+
+def test_precedence_global_overrides_plugin(fake_plugin: dict):
+ """A global command with the same name takes precedence over a plugin command."""
+ shared_name = f"{fake_plugin['name']}-shared"
+ slug = commands_helper.sanitize_command_name(shared_name)
+
+ # 1. Plugin command (lowest precedence)
+ _write_plugin_command(
+ fake_plugin,
+ name=shared_name,
+ description="plugin version",
+ body="plugin body",
+ )
+
+ # 2. Global command (higher precedence)
+ try:
+ commands_helper.save_command(
+ name=shared_name,
+ description="global version",
+ body="global body",
+ )
+
+ effective, _ = commands_helper.list_effective_commands("")
+ by_name = {c["name"]: c for c in effective}
+ assert slug in by_name
+ assert by_name[slug]["description"] == "global version"
+ finally:
+ scope_dir = commands_helper.get_scope_directory("")
+ files.delete_file(os.path.join(scope_dir, f"{slug}.command.yaml"))
+ files.delete_file(os.path.join(scope_dir, f"{slug}.txt"))
+
+
+def test_source_plugin_field_on_discovered_command(fake_plugin: dict):
+ """Discovered commands must carry the source_plugin field."""
+ _write_plugin_command(
+ fake_plugin,
+ name=f"{fake_plugin['name']}-src-test",
+ description="source plugin test",
+ )
+
+ discovered = commands_helper._discover_plugin_commands()
+ slug = commands_helper.sanitize_command_name(f"{fake_plugin['name']}-src-test")
+ match = next((c for c in discovered if c["name"] == slug), None)
+ assert match is not None
+ assert match["source_plugin"] == fake_plugin["name"]
+ assert match["scope_key"] == "plugin"
+ assert match["scope_label"] == f"Plugin: {fake_plugin['name']}"
+ assert match["source_scope_key"] == "plugin"
+ assert match["source_scope_label"] == f"Plugin: {fake_plugin['name']}"
+
+
+def test_is_plugin_commands_dir_recognises_plugin_path(fake_plugin: dict):
+ """_is_plugin_commands_dir must return True for files inside plugin commands/ dirs."""
+ _write_plugin_command(
+ fake_plugin,
+ name=f"{fake_plugin['name']}-path-check",
+ description="path test",
+ )
+ slug = commands_helper.sanitize_command_name(f"{fake_plugin['name']}-path-check")
+ config_path = os.path.join(fake_plugin["commands_dir"], f"{slug}.command.yaml")
+ normalized = commands_helper._normalize_client_path(config_path)
+
+ assert commands_helper._is_plugin_commands_dir(normalized) is True
+
+
+def test_is_plugin_commands_dir_rejects_non_plugin_path(tmp_path: Path):
+ """_is_plugin_commands_dir must return False for arbitrary paths."""
+ non_plugin_path = tmp_path / "not-a-plugin" / "commands" / "foo.txt"
+ assert commands_helper._is_plugin_commands_dir(str(non_plugin_path)) is False
+
+
+def test_get_command_can_load_plugin_command(fake_plugin: dict):
+ """get_command must work for commands inside plugin directories."""
+ _write_plugin_command(
+ fake_plugin,
+ name=f"{fake_plugin['name']}-loadable",
+ description="loadable test",
+ body="load me",
+ )
+ slug = commands_helper.sanitize_command_name(f"{fake_plugin['name']}-loadable")
+ config_path = os.path.join(fake_plugin["commands_dir"], f"{slug}.command.yaml")
+ normalized = commands_helper._normalize_client_path(config_path)
+
+ command = commands_helper.get_command(normalized, project_name="demo-project")
+ assert command["name"] == slug
+ assert command["description"] == "loadable test"
+ assert command["body"] == "load me"
+ assert command["source_plugin"] == fake_plugin["name"]
+ assert command["scope_key"] == "plugin"
+ assert command["scope_label"] == f"Plugin: {fake_plugin['name']}"
+ assert command["source_scope_key"] == "plugin"
+ assert command["source_scope_label"] == f"Plugin: {fake_plugin['name']}"
+
+
+def test_save_command_rejects_plugin_existing_path(fake_plugin: dict):
+ """Editing a plugin command must fail because plugin commands are read-only."""
+ config_path = _write_plugin_command(
+ fake_plugin,
+ name=f"{fake_plugin['name']}-readonly-edit",
+ description="read-only test",
+ body="plugin body",
+ )
+ normalized = commands_helper._normalize_client_path(config_path)
+
+ with pytest.raises(ValueError, match="Plugin commands are read-only"):
+ commands_helper.save_command(
+ existing_path=normalized,
+ name=f"{fake_plugin['name']}-readonly-edit",
+ description="updated description",
+ body="updated body",
+ )
+
+
+def test_delete_command_rejects_plugin_command(fake_plugin: dict):
+ """Deleting a plugin command must fail because plugin commands are read-only."""
+ config_path = _write_plugin_command(
+ fake_plugin,
+ name=f"{fake_plugin['name']}-readonly-delete",
+ description="read-only delete",
+ )
+ normalized = commands_helper._normalize_client_path(config_path)
+
+ with pytest.raises(ValueError, match="Plugin commands are read-only"):
+ commands_helper.delete_command(normalized)
+
+ assert os.path.exists(config_path)
diff --git a/plugins/_commands/webui/commands-slash-store.js b/plugins/_commands/webui/commands-slash-store.js
new file mode 100644
index 000000000..0d43de546
--- /dev/null
+++ b/plugins/_commands/webui/commands-slash-store.js
@@ -0,0 +1,513 @@
+import { createStore } from "/js/AlpineStore.js";
+import { callJsonApi } from "/js/api.js";
+import { store as chatsStore } from "/components/sidebar/chats/chats-store.js";
+import { store as chatInputStore } from "/components/chat/input/input-store.js";
+import { store as attachmentsStore } from "/components/chat/attachments/attachmentsStore.js";
+import {
+ toastFrontendError,
+ toastFrontendInfo,
+ toastFrontendSuccess,
+} from "/components/notifications/notification-store.js";
+import { store as commandsManagerStore } from "/plugins/_commands/webui/commands-store.js";
+
+const COMMANDS_API_PATH = "/plugins/_commands/commands";
+
+function sanitizeCommandName(rawName) {
+ return (rawName || "")
+ .trim()
+ .toLowerCase()
+ .replace(/\s+/g, "-")
+ .replace(/[^a-z0-9_-]+/g, "-")
+ .replace(/-{2,}/g, "-")
+ .replace(/^[-_]+|[-_]+$/g, "");
+}
+
+function parseSlashInput(message) {
+ const text = String(message || "");
+ const match = text.match(/^\s*\/([^\s]*)(?:\s+([\s\S]*))?$/);
+ if (!match) {
+ return {
+ active: false,
+ query: "",
+ rawArguments: "",
+ rawMessage: text,
+ };
+ }
+
+ return {
+ active: true,
+ query: (match[1] || "").trim().toLowerCase(),
+ rawArguments: match[2] || "",
+ rawMessage: text,
+ };
+}
+
+function notifyError(message) {
+ void toastFrontendError(message, "Commands");
+}
+
+function notifySuccess(message) {
+ void toastFrontendSuccess(message, "Commands");
+}
+
+const HTML_ESCAPE = {
+ "&": "&amp;",
+ "<": "&lt;",
+ ">": "&gt;",
+ '"': "&quot;",
+ "'": "&#39;",
+};
+
+function escapeHtml(value) {
+ return String(value || "").replace(/[&<>"']/g, (char) => HTML_ESCAPE[char]);
+}
+
+function notifyInfo(title, message) {
+ const formatted = escapeHtml(message).replace(/\n/g, "<br>");
+ void toastFrontendInfo(formatted, title || "Commands", 3, "", undefined, true);
+}
+
+const model = {
+ loading: false,
+ applying: false,
+ commands: [],
+ contextScope: { project_name: "" },
+ lastContextId: "",
+ active: false,
+ dismissed: false,
+ query: "",
+ rawArguments: "",
+ rawMessage: "",
+ selectedIndex: 0,
+ boundInput: null,
+ keydownHandler: null,
+ inputHandler: null,
+ focusHandler: null,
+ commandsUpdatedHandler: null,
+
+ get menuVisible() {
+ return this.active && !this.dismissed;
+ },
+
+ get filteredCommands() {
+ const needle = (this.query || "").trim().toLowerCase();
+ const commands = Array.isArray(this.commands) ? this.commands : [];
+
+ if (!needle) return commands;
+
+ return commands.filter((command) => {
+ const haystack = `${command?.name || ""} ${command?.description || ""}`.toLowerCase();
+ return haystack.includes(needle);
+ });
+ },
+
+ get selectedCommand() {
+ const commands = this.filteredCommands;
+ if (!commands.length) return null;
+ return commands[this.selectedIndex] || commands[0] || null;
+ },
+
+ get emptyStateLabel() {
+ const name = sanitizeCommandName(this.query || "");
+ return name ? `Create /${name}` : "Create slash command";
+ },
+
+ onMount() {
+ this.ensureBindings();
+
+ this.keydownHandler = (event) => this.handleKeydown(event);
+ this.commandsUpdatedHandler = () => {
+ this.commands = [];
+ if (this.menuVisible) {
+ void this.loadCommands(true);
+ }
+ };
+
+ document.addEventListener("keydown", this.keydownHandler, true);
+ window.addEventListener("commands:updated", this.commandsUpdatedHandler);
+ this.handleInput();
+ },
+
+ cleanup() {
+ this.removeBindings();
+ if (this.keydownHandler) {
+ document.removeEventListener("keydown", this.keydownHandler, true);
+ }
+ if (this.commandsUpdatedHandler) {
+ window.removeEventListener("commands:updated", this.commandsUpdatedHandler);
+ }
+ this.keydownHandler = null;
+ this.commandsUpdatedHandler = null;
+ this.dismissed = false;
+ this.active = false;
+ this.query = "";
+ this.rawArguments = "";
+ this.rawMessage = "";
+ this.selectedIndex = 0;
+ this.applying = false;
+ },
+
+ ensureBindings() {
+ const input = this.getInputElement();
+ if (!input || input === this.boundInput) return;
+
+ this.removeBindings();
+
+ this.inputHandler = (event) => this.handleInput(event);
+ this.focusHandler = () => this.handleInput();
+ input.addEventListener("input", this.inputHandler);
+ input.addEventListener("focus", this.focusHandler);
+ this.boundInput = input;
+ },
+
+ removeBindings() {
+ if (this.boundInput && this.inputHandler) {
+ this.boundInput.removeEventListener("input", this.inputHandler);
+ }
+ if (this.boundInput && this.focusHandler) {
+ this.boundInput.removeEventListener("focus", this.focusHandler);
+ }
+ this.boundInput = null;
+ this.inputHandler = null;
+ this.focusHandler = null;
+ },
+
+ getInputElement() {
+ return document.getElementById("chat-input");
+ },
+
+ getInputMessage(event = null) {
+ const target = event?.target || null;
+ const targetEditor = target?.closest?.("#chat-input");
+ if (targetEditor?.isContentEditable || target?.isContentEditable) {
+ return (
+ chatInputStore?._editorToMarkdown?.() ||
+ targetEditor?.textContent ||
+ target?.textContent ||
+ ""
+ );
+ }
+ if (typeof target?.value === "string") return target.value;
+
+ const input = this.getInputElement();
+ if (input?.isContentEditable) {
+ return chatInputStore?._editorToMarkdown?.() ?? input.textContent ?? "";
+ }
+ if (typeof input?.value === "string") return input.value;
+ return chatInputStore?.message ?? "";
+ },
+
+ getContextId() {
+ return chatsStore?.getSelectedChatId?.() || globalThis.getContext?.() || "";
+ },
+
+ async loadCommands(force = false) {
+ const contextId = this.getContextId();
+
+ if (!force && this.commands.length && contextId === this.lastContextId) {
+ this.ensureSelection();
+ return;
+ }
+
+ this.loading = true;
+ try {
+ const response = await callJsonApi(COMMANDS_API_PATH, {
+ action: "list_effective",
+ context_id: contextId,
+ });
+ this.commands = Array.isArray(response?.commands) ? response.commands : [];
+ this.contextScope = response?.scope || {
+ project_name: "",
+ };
+ this.lastContextId = contextId;
+ this.ensureSelection();
+ } catch (error) {
+ console.error("Failed to load effective commands:", error);
+ this.commands = [];
+ this.contextScope = { project_name: "" };
+ } finally {
+ this.loading = false;
+ }
+ },
+
+ handleInput(event = null) {
+ this.ensureBindings();
+ this.dismissed = false;
+
+ const message = this.getInputMessage(event);
+ const parsed = parseSlashInput(message);
+
+ this.active = parsed.active;
+ this.query = parsed.query;
+ this.rawArguments = parsed.rawArguments;
+ this.rawMessage = parsed.rawMessage;
+
+ if (!this.active) {
+ this.selectedIndex = 0;
+ return;
+ }
+
+ this.ensureSelection();
+ void this.loadCommands();
+ },
+
+ handleKeydown(event) {
+ const input = this.getInputElement();
+ if (!this.menuVisible || !input || document.activeElement !== input) return;
+ if (event.isComposing || event.keyCode === 229) return;
+
+ if (event.key === "ArrowDown") {
+ event.preventDefault();
+ event.stopPropagation();
+ this.moveSelection(1);
+ return;
+ }
+
+ if (event.key === "ArrowUp") {
+ event.preventDefault();
+ event.stopPropagation();
+ this.moveSelection(-1);
+ return;
+ }
+
+ if (event.key === "Escape") {
+ event.preventDefault();
+ event.stopPropagation();
+ this.dismissed = true;
+ return;
+ }
+
+ if (event.key === "Enter" && this.selectedCommand) {
+ event.preventDefault();
+ event.stopPropagation();
+ void this.applySelection(this.selectedCommand);
+ }
+ },
+
+ ensureSelection() {
+ const commands = this.filteredCommands;
+ if (!commands.length) {
+ this.selectedIndex = 0;
+ return;
+ }
+ if (this.selectedIndex >= commands.length) {
+ this.selectedIndex = 0;
+ }
+ },
+
+ moveSelection(delta) {
+ const commands = this.filteredCommands;
+ if (!commands.length) return;
+ const nextIndex =
+ (this.selectedIndex + delta + commands.length) % commands.length;
+ this.selectedIndex = nextIndex;
+ this.scrollSelectedIntoView();
+ },
+
+ scrollSelectedIntoView() {
+ requestAnimationFrame(() => {
+ document
+ .querySelector(".commands-slash-results .commands-slash-item.active")
+ ?.scrollIntoView({ block: "nearest" });
+ });
+ },
+
+ async applySelection(command) {
+ if (!command || this.applying) return;
+ const input = this.getInputElement();
+ if (!input) return;
+
+ this.applying = true;
+ try {
+ const contextId = this.getContextId();
+ const fallbackSlash = this.rawMessage?.trim()
+ ? this.rawMessage
+ : this.rawArguments
+ ? `/${command.name} ${this.rawArguments}`
+ : `/${command.name}`;
+
+ const response = await callJsonApi(COMMANDS_API_PATH, {
+ action: "resolve",
+ path: command.path,
+ slash_text: fallbackSlash,
+ project_name: this.contextScope?.project_name || "",
+ context_id: contextId,
+ });
+
+ const applied = await this.applyResolution(response?.resolution, input);
+ if (!applied?.hadToast && !applied?.hadError) {
+ notifySuccess(`Applied /${command.name}`);
+ }
+ } catch (error) {
+ console.error("Failed to apply slash command:", error);
+ notifyError(error?.message || "Failed to apply slash command.");
+ } finally {
+ this.applying = false;
+ }
+ },
+
+ async applyResolution(resolution, input) {
+ const result = resolution?.result || {};
+ const hasText = typeof result.text === "string";
+ let nextText = hasText ? result.text : this.getInputMessage();
+ const effects = Array.isArray(result.effects) ? result.effects : [];
+ let hadToast = false;
+ let hadError = false;
+
+ for (const effect of effects) {
+ if (!effect || typeof effect !== "object") continue;
+ const type = String(effect.type || "").trim().toLowerCase();
+ if (type === "replace_input") {
+ nextText = String(effect.text || "");
+ continue;
+ }
+ if (type === "append_input") {
+ const chunk = String(effect.text || "");
+ nextText = nextText ? `${nextText}\n${chunk}` : chunk;
+ continue;
+ }
+ if (type === "toast") {
+ hadToast = true;
+ const level = String(effect.level || "info").toLowerCase();
+ const message = String(effect.message || "");
+ if (!message) continue;
+ if (level === "error") {
+ hadError = true;
+ notifyError(message);
+ } else {
+ notifySuccess(message);
+ }
+ continue;
+ }
+ if (type === "new_chat") {
+ await chatsStore?.newChat?.();
+ continue;
+ }
+ if (type === "select_chat") {
+ const contextId = String(effect.context_id || "").trim();
+ if (contextId) await chatsStore?.selectChat?.(contextId);
+ continue;
+ }
+ if (type === "reset_chat") {
+ await chatsStore?.resetChat?.(String(effect.context_id || "") || null);
+ continue;
+ }
+ if (type === "pause_agent") {
+ await chatInputStore?.pauseAgent?.(Boolean(effect.paused));
+ continue;
+ }
+ if (type === "nudge_agent") {
+ await chatInputStore?.nudge?.();
+ continue;
+ }
+ if (type === "open_modal") {
+ const path = String(effect.path || "").trim();
+ if (path) await window.openModal?.(path);
+ continue;
+ }
+ if (type === "show_markdown") {
+ hadToast = true;
+ notifyInfo(
+ String(effect.title || "Slash Command"),
+ String(effect.content || ""),
+ );
+ continue;
+ }
+ if (type === "open_plugin_config") {
+ const pluginName = String(effect.plugin || "").trim();
+ if (pluginName) {
+ const { store } = await import("/components/plugins/plugin-settings-store.js");
+ await store.openConfig(
+ pluginName,
+ String(effect.project_name || ""),
+ String(effect.agent_profile || ""),
+ );
+ }
+ continue;
+ }
+ if (type === "compact_chat") {
+ const { store } = await import("/plugins/_chat_compaction/webui/compact-store.js");
+ await store.fetchStats();
+ continue;
+ }
+ if (type === "attach_files") {
+ await this.openAttachmentPicker(effect);
+ continue;
+ }
+ if (type === "copy_transcript") {
+ await this.copyTranscript();
+ hadToast = true;
+ continue;
+ }
+ if (type === "clear_transcript") {
+ const history = document.getElementById("chat-history");
+ if (history) history.innerHTML = "";
+ continue;
+ }
+ }
+
+ if (typeof input.value === "string") input.value = nextText;
+ chatInputStore.message = nextText;
+ input.dispatchEvent(new Event("input", { bubbles: true }));
+ chatInputStore.adjustTextareaHeight();
+ input.focus();
+ if (typeof input.setSelectionRange === "function") {
+ input.setSelectionRange(nextText.length, nextText.length);
+ } else {
+ chatInputStore?._setEditorCaret?.(nextText.length);
+ }
+
+ this.active = false;
+ this.dismissed = false;
+ this.query = "";
+ this.rawArguments = "";
+ this.rawMessage = nextText;
+ this.selectedIndex = 0;
+ return { hadToast, hadError };
+ },
+
+ openAttachmentPicker(effect = {}) {
+ return new Promise((resolve) => {
+ const picker = document.createElement("input");
+ let settled = false;
+ const done = () => {
+ if (settled) return;
+ settled = true;
+ picker.remove();
+ resolve();
+ };
+ picker.type = "file";
+ picker.multiple = true;
+ picker.accept = String(effect.accept || "*");
+ picker.style.display = "none";
+ picker.addEventListener("change", () => {
+ attachmentsStore?.handleFiles?.(picker.files || []);
+ done();
+ }, { once: true });
+ window.addEventListener("focus", () => setTimeout(done, 500), { once: true });
+ document.body.appendChild(picker);
+ picker.click();
+ });
+ },
+
+ async copyTranscript() {
+ const text = document.getElementById("chat-history")?.innerText?.trim() || "";
+ if (!text) {
+ notifyError("No visible transcript to copy.");
+ return;
+ }
+ await navigator.clipboard.writeText(text);
+ notifySuccess("Transcript copied.");
+ },
+
+ openCreateCommand() {
+ commandsManagerStore.openManager({
+ projectName: this.contextScope?.project_name || "",
+ prefillName: sanitizeCommandName(this.query || ""),
+ openEditor: true,
+ });
+ this.dismissed = true;
+ },
+};
+
+export const store = createStore("commandsSlash", model);
diff --git a/plugins/_commands/webui/commands-store.js b/plugins/_commands/webui/commands-store.js
new file mode 100644
index 000000000..8cae2b843
--- /dev/null
+++ b/plugins/_commands/webui/commands-store.js
@@ -0,0 +1,417 @@
+import { createStore } from "/js/AlpineStore.js";
+import { callJsonApi } from "/js/api.js";
+import {
+ toastFrontendError,
+ toastFrontendSuccess,
+} from "/components/notifications/notification-store.js";
+import { store as chatsStore } from "/components/sidebar/chats/chats-store.js";
+import { store as fileBrowserStore } from "/components/modals/file-browser/file-browser-store.js";
+
+const COMMANDS_API_PATH = "/plugins/_commands/commands";
+const MAIN_MODAL_PATH = "/plugins/_commands/webui/main.html";
+const EDITOR_MODAL_PATH = "/plugins/_commands/webui/editor.html";
+
+function createEmptyEditor() {
+ return {
+ mode: "create",
+ existingPath: "",
+ path: "",
+ name: "",
+ description: "",
+ argumentHint: "",
+ commandType: "text",
+ includeHistory: false,
+ body: "",
+ extraFrontmatter: {},
+ };
+}
+
+function safeStringify(value) {
+ try {
+ return JSON.stringify(value ?? {});
+ } catch {
+ return "";
+ }
+}
+
+function sanitizeCommandName(rawName) {
+ return (rawName || "")
+ .trim()
+ .toLowerCase()
+ .replace(/\s+/g, "-")
+ .replace(/[^a-z0-9_-]+/g, "-")
+ .replace(/-{2,}/g, "-")
+ .replace(/^[-_]+|[-_]+$/g, "");
+}
+
+function buildDefaultBody(commandType = "text") {
+ if (commandType === "script") {
+ return [
+ "def run(payload):",
+ " args = payload.get('arguments', {})",
+ " flags = args.get('flags', {})",
+ " positional = args.get('positional', [])",
+ " return {",
+ " 'text': f\"Script command received args: {positional} flags: {flags}\",",
+ " 'effects': [],",
+ " }",
+ "",
+ ].join("\n");
+ }
+ return "Describe the work to perform here.\n\n{raw}";
+}
+
+function notifyError(message) {
+ void toastFrontendError(message, "Commands");
+}
+
+function notifySuccess(message) {
+ void toastFrontendSuccess(message, "Commands");
+}
+
+function emitCommandsUpdated() {
+ window.dispatchEvent(new CustomEvent("commands:updated"));
+}
+
+const model = {
+ loading: false,
+ saving: false,
+ projects: [],
+ projectName: "",
+ scope: null,
+ contextScope: { project_name: "" },
+ commands: [],
+ pendingScope: null,
+ pendingCreate: null,
+ editor: createEmptyEditor(),
+ editorSnapshot: "",
+
+ get selectedScopeLabel() {
+ return this.scope?.scope_label || "Global";
+ },
+
+ get selectedScopeDirectory() {
+ return this.scope?.directory_path || "";
+ },
+
+ get hasCommands() {
+ return (this.commands || []).length > 0;
+ },
+
+ get editorTitle() {
+ return this.editor.mode === "edit" ? "Edit Slash Command" : "Create Slash Command";
+ },
+
+ get editorDirty() {
+ return this._serializeEditor() !== this.editorSnapshot;
+ },
+
+ get editorBodyLabel() {
+ return this.editor.commandType === "script" ? "Python hook" : "Text template";
+ },
+
+ openManager(options = {}) {
+ const hasExplicitScope = Object.prototype.hasOwnProperty.call(options, "projectName");
+
+ this.pendingScope = hasExplicitScope
+ ? {
+ projectName: options.projectName || "",
+ }
+ : null;
+
+ this.pendingCreate =
+ options.openEditor || options.prefillName
+ ? {
+ name: options.prefillName || "",
+ }
+ : null;
+
+ return window.openModal?.(MAIN_MODAL_PATH);
+ },
+
+ async onOpen() {
+ await this.loadProjects();
+
+ try {
+ await this.resolveInitialScope();
+ await this.loadCommands();
+ } catch (error) {
+ console.error("Failed to initialize commands manager:", error);
+ this.scope = null;
+ this.commands = [];
+ notifyError(error?.message || "Failed to open the commands manager.");
+ }
+
+ if (this.pendingCreate) {
+ const pendingCreate = { ...this.pendingCreate };
+ this.pendingCreate = null;
+ await this.openCreateCommand({ name: pendingCreate.name });
+ }
+ },
+
+ cleanup() {
+ this.loading = false;
+ this.saving = false;
+ this.projects = [];
+ this.projectName = "";
+ this.scope = null;
+ this.contextScope = { project_name: "" };
+ this.commands = [];
+ this.pendingScope = null;
+ this.pendingCreate = null;
+ this.resetEditor();
+ },
+
+ async loadProjects() {
+ try {
+ const response = await callJsonApi("projects", { action: "list_options" });
+ this.projects = Array.isArray(response?.data) ? response.data : [];
+ } catch {
+ this.projects = [];
+ }
+ },
+
+ normalizeProject(projectName) {
+ if (!projectName) return "";
+ return (this.projects || []).some((project) => project?.key === projectName)
+ ? projectName
+ : "";
+ },
+
+ async resolveInitialScope() {
+ const contextId =
+ chatsStore?.getSelectedChatId?.() || globalThis.getContext?.() || "";
+ const scopeInfo = await callJsonApi(COMMANDS_API_PATH, {
+ action: "scope_info",
+ context_id: contextId,
+ });
+
+ this.contextScope = scopeInfo?.context_scope || {
+ project_name: "",
+ };
+
+ const preferredScope = this.pendingScope || scopeInfo?.scope || {};
+ this.projectName = this.normalizeProject(preferredScope.project_name || "");
+ this.pendingScope = null;
+ },
+
+ async loadCommands() {
+ this.loading = true;
+
+ try {
+ const response = await callJsonApi(COMMANDS_API_PATH, {
+ action: "list_scope",
+ project_name: this.projectName || "",
+ });
+
+ this.commands = Array.isArray(response?.commands) ? response.commands : [];
+ this.scope = response?.scope || null;
+ } catch (error) {
+ console.error("Failed to load commands:", error);
+ this.commands = [];
+ this.scope = null;
+ notifyError(error?.message || "Failed to load commands.");
+ } finally {
+ this.loading = false;
+ }
+ },
+
+ async refresh() {
+ await this.loadCommands();
+ },
+
+ async onScopeChanged() {
+ this.projectName = this.normalizeProject(this.projectName);
+ await this.loadCommands();
+ },
+
+ overrideBadgeLabel(command) {
+ const count = Number(command?.override_count || 0);
+ if (!count) return "";
+ if (count === 1) {
+ return `Overrides ${command.override_scopes[0]}`;
+ }
+ return `Overrides ${count} lower scopes`;
+ },
+
+ async browseScopeFolder() {
+ try {
+ const response = await callJsonApi(COMMANDS_API_PATH, {
+ action: "scope_info",
+ project_name: this.projectName || "",
+ ensure_directory: true,
+ });
+ if (response?.scope?.directory_path) {
+ await fileBrowserStore.open(response.scope.directory_path);
+ }
+ } catch (error) {
+ console.error("Failed to open scope folder:", error);
+ notifyError(error?.message || "Failed to open scope folder.");
+ }
+ },
+
+ async openCreateCommand(options = {}) {
+ if (Object.prototype.hasOwnProperty.call(options, "projectName")) {
+ this.projectName = this.normalizeProject(options.projectName || "");
+ await this.loadCommands();
+ }
+
+ const suggestedName = sanitizeCommandName(options.name || "");
+ this.editor = {
+ ...createEmptyEditor(),
+ mode: "create",
+ name: suggestedName,
+ commandType: "text",
+ body: buildDefaultBody("text"),
+ };
+ this.editorSnapshot = this._serializeEditor();
+ await this.openEditorModal();
+ },
+
+ async openEditCommand(command) {
+ if (!command?.path) return;
+
+ try {
+ const response = await callJsonApi(COMMANDS_API_PATH, {
+ action: "get",
+ path: command.path,
+ project_name: this.projectName || "",
+ });
+ const loaded = response?.command || command;
+ this.editor = {
+ mode: "edit",
+ existingPath: loaded.path || "",
+ path: loaded.path || "",
+ name: loaded.name || "",
+ description: loaded.description || "",
+ argumentHint: loaded.argument_hint || "",
+ commandType: loaded.command_type || "text",
+ includeHistory: Boolean(loaded.include_history),
+ body: loaded.body || "",
+ extraFrontmatter: loaded.frontmatter_extra || {},
+ };
+ this.editorSnapshot = this._serializeEditor();
+ await this.openEditorModal();
+ } catch (error) {
+ console.error("Failed to load command:", error);
+ notifyError(error?.message || "Failed to load command.");
+ }
+ },
+
+ async duplicateCommand(command) {
+ if (!command?.path) return;
+
+ try {
+ const response = await callJsonApi(COMMANDS_API_PATH, {
+ action: "duplicate",
+ path: command.path,
+ project_name: this.projectName || "",
+ });
+ await this.loadCommands();
+ emitCommandsUpdated();
+ notifySuccess(`Duplicated /${response?.command?.name || command.name}`);
+ if (response?.command) {
+ await this.openEditCommand(response.command);
+ }
+ } catch (error) {
+ console.error("Failed to duplicate command:", error);
+ notifyError(error?.message || "Failed to duplicate command.");
+ }
+ },
+
+ async deleteCommand(command) {
+ if (!command?.path) return;
+
+ try {
+ await callJsonApi(COMMANDS_API_PATH, {
+ action: "delete",
+ path: command.path,
+ project_name: this.projectName || "",
+ });
+ await this.loadCommands();
+ emitCommandsUpdated();
+ notifySuccess(`Deleted /${command.name}`);
+ } catch (error) {
+ console.error("Failed to delete command:", error);
+ notifyError(error?.message || "Failed to delete command.");
+ }
+ },
+
+ async openEditorModal() {
+ await window.openModal?.(EDITOR_MODAL_PATH, () => this.confirmCloseEditor());
+ this.resetEditor();
+ },
+
+ confirmCloseEditor() {
+ if (!this.editorDirty) return true;
+ return window.confirm("Discard unsaved slash command changes?");
+ },
+
+ async closeEditor() {
+ await window.closeModal?.(EDITOR_MODAL_PATH);
+ },
+
+ setEditorType(nextType) {
+ const normalizedType = nextType === "script" ? "script" : "text";
+ if (this.editor.commandType === normalizedType) return;
+ this.editor.commandType = normalizedType;
+ this.editor.includeHistory =
+ normalizedType === "script" ? this.editor.includeHistory : false;
+ this.editor.body = buildDefaultBody(normalizedType);
+ },
+
+ async saveEditor() {
+ this.saving = true;
+
+ try {
+ const response = await callJsonApi(COMMANDS_API_PATH, {
+ action: "save",
+ project_name: this.projectName || "",
+ existing_path: this.editor.existingPath || "",
+ name: this.editor.name || "",
+ description: this.editor.description || "",
+ argument_hint: this.editor.argumentHint || "",
+ command_type: this.editor.commandType || "text",
+ include_history:
+ this.editor.commandType === "script" ? Boolean(this.editor.includeHistory) : false,
+ body: this.editor.body || "",
+ extra_frontmatter: this.editor.extraFrontmatter || {},
+ });
+
+ this.editor.path = response?.command?.path || "";
+ this.editor.existingPath = response?.command?.path || "";
+ this.editorSnapshot = this._serializeEditor();
+ await this.loadCommands();
+ emitCommandsUpdated();
+ notifySuccess(
+ `${this.editor.mode === "edit" ? "Updated" : "Saved"} /${response?.command?.name || this.editor.name}`,
+ );
+ await window.closeModal?.(EDITOR_MODAL_PATH);
+ } catch (error) {
+ console.error("Failed to save command:", error);
+ notifyError(error?.message || "Failed to save command.");
+ } finally {
+ this.saving = false;
+ }
+ },
+
+ resetEditor() {
+ this.editor = createEmptyEditor();
+ this.editorSnapshot = this._serializeEditor();
+ },
+
+ _serializeEditor() {
+ return safeStringify({
+ existingPath: this.editor.existingPath || "",
+ name: this.editor.name || "",
+ description: this.editor.description || "",
+ argumentHint: this.editor.argumentHint || "",
+ commandType: this.editor.commandType || "text",
+ includeHistory: Boolean(this.editor.includeHistory),
+ body: this.editor.body || "",
+ extraFrontmatter: this.editor.extraFrontmatter || {},
+ });
+ },
+};
+
+export const store = createStore("commandsManager", model);
diff --git a/plugins/_commands/webui/editor.html b/plugins/_commands/webui/editor.html
new file mode 100644
index 000000000..8d6725a2f
--- /dev/null
+++ b/plugins/_commands/webui/editor.html
@@ -0,0 +1,240 @@
+<html>
+<head>
+ <title>Slash Command</title>
+ <script type="module">
+ import { store } from "/plugins/_commands/webui/commands-store.js";
+ </script>
+</head>
+<body>
+ <div x-data>
+ <template x-if="$store.commandsManager">
+ <div class="commands-editor"
+ x-create="$el.closest('.modal')?.querySelector('.modal-title') && ($el.closest('.modal').querySelector('.modal-title').textContent = $store.commandsManager.editorTitle)">
+ <div class="commands-editor-header">
+ <div class="commands-editor-copy">
+ <div class="commands-editor-title" x-text="$store.commandsManager.editorTitle"></div>
+ <div class="commands-editor-subtitle">
+ Saving writes a <code>.command.yaml</code> config plus a template file in <span x-text="$store.commandsManager.selectedScopeLabel"></span>.
+ </div>
+ </div>
+ </div>
+
+ <div class="commands-editor-grid">
+ <label class="commands-field">
+ <span>Command name</span>
+ <input type="text"
+ x-model="$store.commandsManager.editor.name"
+ placeholder="explain-code"
+ autocomplete="off">
+ </label>
+
+ <label class="commands-field">
+ <span>Description</span>
+ <input type="text"
+ x-model="$store.commandsManager.editor.description"
+ placeholder="Explain code clearly with examples.">
+ </label>
+ </div>
+
+ <label class="commands-field">
+ <span>Argument hint or example</span>
+ <input type="text"
+ x-model="$store.commandsManager.editor.argumentHint"
+ placeholder="Optional free-form text after /command">
+ </label>
+
+ <div class="commands-editor-grid">
+ <label class="commands-field">
+ <span>Command type</span>
+ <select x-model="$store.commandsManager.editor.commandType"
+ @change="$store.commandsManager.setEditorType($store.commandsManager.editor.commandType)">
+ <option value="text">Text template (.txt)</option>
+ <option value="script">Python hook (.py)</option>
+ </select>
+ </label>
+
+ <template x-if="$store.commandsManager.editor.commandType === 'script'">
+ <label class="commands-field commands-field-checkbox">
+ <span>Script context</span>
+ <div class="commands-checkbox-inline">
+ <input type="checkbox" x-model="$store.commandsManager.editor.includeHistory">
+ <span>Include chat history payload</span>
+ </div>
+ </label>
+ </template>
+ </div>
+
+ <label class="commands-field commands-field-body">
+ <span x-text="$store.commandsManager.editorBodyLabel"></span>
+ <textarea x-model="$store.commandsManager.editor.body"
+ rows="14"
+ :placeholder="$store.commandsManager.editor.commandType === 'script'
+ ? 'Implement run(payload) and return { text, effects }.'
+ : 'Write reusable text. Use {raw}, {args.positional.0}, {args.flags.some_flag}.'"></textarea>
+ </label>
+
+ <template x-if="$store.commandsManager.editor.commandType === 'text'">
+ <div class="commands-editor-help">
+ <span class="commands-help-chip">{raw}</span>
+ <span class="commands-help-chip">{args.positional.0}</span>
+ <span class="commands-help-chip">{args.flags.git_url}</span>
+ <span class="commands-help-copy">
+ Trailing command input is parsed once and exposed to template placeholders and python payloads.
+ </span>
+ </div>
+ </template>
+
+ <template x-if="$store.commandsManager.editor.commandType === 'script'">
+ <div class="commands-editor-help">
+ <span class="commands-help-chip">run(payload)</span>
+ <span class="commands-help-chip">payload.arguments</span>
+ <span class="commands-help-chip">result.effects</span>
+ <span class="commands-help-copy">
+ Return a string or <code>{ text, effects }</code>. Effects support <code>replace_input</code>, <code>append_input</code>, and <code>toast</code>.
+ </span>
+ </div>
+ </template>
+
+ <template x-if="$store.commandsManager.editor.path">
+ <div class="commands-editor-path">
+ <span class="material-symbols-outlined">description</span>
+ <span x-text="$store.commandsManager.editor.path"></span>
+ </div>
+ </template>
+ </div>
+ </template>
+ </div>
+
+ <div class="modal-footer" data-modal-footer>
+ <button class="btn btn-ok"
+ @click="$store.commandsManager.saveEditor()"
+ :disabled="$store.commandsManager.saving">
+ Save
+ </button>
+ <button class="btn btn-cancel" @click="$store.commandsManager.closeEditor()">
+ Cancel
+ </button>
+ </div>
+
+ <style>
+ .commands-editor {
+ display: flex;
+ flex-direction: column;
+ gap: 1rem;
+ padding: 1rem 1.1rem 1.2rem;
+ }
+
+ .commands-editor-header {
+ display: flex;
+ justify-content: space-between;
+ gap: 1rem;
+ align-items: flex-start;
+ }
+
+ .commands-editor-copy {
+ min-width: 0;
+ }
+
+ .commands-editor-title {
+ font-size: 1.02rem;
+ font-weight: 600;
+ }
+
+ .commands-editor-subtitle {
+ margin-top: 0.25rem;
+ color: var(--color-text-secondary);
+ font-size: 0.88rem;
+ line-height: 1.45;
+ }
+
+ .commands-editor-grid {
+ display: grid;
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ gap: 0.85rem;
+ }
+
+ .commands-field {
+ display: flex;
+ flex-direction: column;
+ gap: 0.4rem;
+ }
+
+ .commands-field span {
+ font-size: 0.82rem;
+ font-weight: 600;
+ color: var(--color-text-secondary);
+ }
+
+ .commands-field textarea,
+ .commands-field input {
+ width: 100%;
+ }
+
+ .commands-field select {
+ width: 100%;
+ }
+
+ .commands-field-checkbox {
+ justify-content: flex-end;
+ }
+
+ .commands-checkbox-inline {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.45rem;
+ color: var(--color-text-primary);
+ font-size: 0.86rem;
+ font-weight: 500;
+ }
+
+ .commands-checkbox-inline input {
+ width: auto;
+ }
+
+ .commands-field-body textarea {
+ min-height: 18rem;
+ resize: vertical;
+ font-family: "Roboto Mono", monospace;
+ }
+
+ .commands-editor-help {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.5rem;
+ align-items: center;
+ }
+
+ .commands-help-chip {
+ display: inline-flex;
+ align-items: center;
+ padding: 0.22rem 0.55rem;
+ border-radius: 999px;
+ background: color-mix(in srgb, var(--color-highlight) 12%, transparent);
+ border: 1px solid color-mix(in srgb, var(--color-highlight) 24%, transparent);
+ font-family: "Roboto Mono", monospace;
+ font-size: 0.8rem;
+ }
+
+ .commands-help-copy {
+ color: var(--color-text-secondary);
+ font-size: 0.85rem;
+ }
+
+ .commands-editor-path {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.45rem;
+ color: var(--color-text-secondary);
+ font-family: "Roboto Mono", monospace;
+ font-size: 0.78rem;
+ word-break: break-all;
+ }
+
+ @media (max-width: 760px) {
+ .commands-editor-grid {
+ grid-template-columns: 1fr;
+ }
+ }
+ </style>
+</body>
+</html>
diff --git a/plugins/_commands/webui/main.html b/plugins/_commands/webui/main.html
new file mode 100644
index 000000000..dde4b6e62
--- /dev/null
+++ b/plugins/_commands/webui/main.html
@@ -0,0 +1,395 @@
+<html>
+<head>
+ <title>Commands</title>
+ <script type="module">
+ import { store } from "/plugins/_commands/webui/commands-store.js";
+ </script>
+</head>
+<body>
+ <div x-data>
+ <template x-if="$store.commandsManager">
+ <div class="commands-manager" x-create="$store.commandsManager.onOpen()" x-destroy="$store.commandsManager.cleanup()">
+ <div class="commands-toolbar">
+ <div class="commands-toolbar-copy">
+ <div class="commands-title">Slash Commands</div>
+ <div class="commands-subtitle">
+ YAML-configured commands for the inline chat composer.
+ </div>
+ </div>
+
+ <div class="commands-toolbar-controls">
+ <label class="commands-select">
+ <span>Project</span>
+ <select x-model="$store.commandsManager.projectName" @change="$store.commandsManager.onScopeChanged()">
+ <option value="">Global</option>
+ <template x-for="project in $store.commandsManager.projects" :key="project.key">
+ <option :value="project.key" x-text="project.label"></option>
+ </template>
+ </select>
+ </label>
+
+ <div class="commands-toolbar-actions">
+ <button type="button" class="button secondary" @click="$store.commandsManager.refresh()">
+ <span class="material-symbols-outlined">refresh</span>
+ <span>Refresh</span>
+ </button>
+ <button type="button" class="button secondary" @click="$store.commandsManager.browseScopeFolder()">
+ <span class="material-symbols-outlined">folder_open</span>
+ <span>Browse Scope Folder</span>
+ </button>
+ <button type="button" class="button primary" @click="$store.commandsManager.openCreateCommand()">
+ <span class="material-symbols-outlined">add</span>
+ <span>Create Command</span>
+ </button>
+ </div>
+ </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">
+ <template x-if="$store.commandsManager.hasCommands">
+ <div class="commands-grid">
+ <template x-for="command in $store.commandsManager.commands" :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>
+
+ <div class="commands-card-actions">
+ <button type="button" class="button icon" title="Edit command" @click="$store.commandsManager.openEditCommand(command)">
+ <span class="material-symbols-outlined">edit</span>
+ </button>
+ <button type="button" class="button icon" title="Duplicate command" @click="$store.commandsManager.duplicateCommand(command)">
+ <span class="material-symbols-outlined">content_copy</span>
+ </button>
+ <button type="button" class="button icon danger" title="Delete command" @click.stop="$confirmClick($event, () => $store.commandsManager.deleteCommand(command))">
+ <span class="material-symbols-outlined">delete</span>
+ </button>
+ </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>
+ </div>
+ </template>
+
+ <template x-if="!$store.commandsManager.hasCommands">
+ <div class="commands-empty-state">
+ <div class="commands-empty-title">No commands in this scope yet.</div>
+ <div class="commands-empty-copy">
+ Create YAML-configured slash commands here and they will appear from <code>/</code> in chat.
+ </div>
+ <button type="button" class="button primary" @click="$store.commandsManager.openCreateCommand()">
+ <span class="material-symbols-outlined">add</span>
+ <span>Create Slash Command</span>
+ </button>
+ </div>
+ </template>
+ </div>
+ </div>
+ </template>
+ </div>
+
+ <style>
+ .commands-manager {
+ display: flex;
+ flex-direction: column;
+ gap: 1rem;
+ padding: 1rem;
+ }
+
+ .commands-toolbar {
+ display: flex;
+ flex-direction: column;
+ gap: 1rem;
+ padding: 1rem;
+ border: 1px solid var(--color-border);
+ border-radius: 12px;
+ background: color-mix(in srgb, var(--color-panel) 88%, transparent);
+ }
+
+ .commands-toolbar-copy {
+ display: flex;
+ flex-direction: column;
+ gap: 0.25rem;
+ }
+
+ .commands-title {
+ font-size: 1.1rem;
+ font-weight: 600;
+ }
+
+ .commands-subtitle {
+ color: var(--color-text-secondary);
+ font-size: 0.92rem;
+ }
+
+ .commands-toolbar-controls {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.75rem;
+ align-items: end;
+ }
+
+ .commands-select {
+ display: flex;
+ flex-direction: column;
+ gap: 0.35rem;
+ min-width: 14rem;
+ flex: 1 1 14rem;
+ }
+
+ .commands-select span {
+ color: var(--color-text-secondary);
+ font-size: 0.82rem;
+ font-weight: 600;
+ }
+
+ .commands-toolbar-actions {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.5rem;
+ 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;
+ gap: 0.5rem;
+ padding: 0.9rem 1rem;
+ border-radius: 10px;
+ }
+
+ .commands-loading {
+ color: var(--color-text-secondary);
+ border: 1px dashed var(--color-border);
+ }
+
+ .commands-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(18rem, 1fr));
+ gap: 0.9rem;
+ }
+
+ .commands-card {
+ display: flex;
+ flex-direction: column;
+ gap: 0.75rem;
+ padding: 1rem;
+ border: 1px solid var(--color-border);
+ border-radius: 12px;
+ background: color-mix(in srgb, var(--color-panel) 90%, transparent);
+ }
+
+ .commands-card-header {
+ display: flex;
+ gap: 0.75rem;
+ justify-content: space-between;
+ align-items: flex-start;
+ }
+
+ .commands-card-copy {
+ min-width: 0;
+ }
+
+ .commands-card-title {
+ font-size: 1rem;
+ font-weight: 600;
+ word-break: break-word;
+ }
+
+ .commands-slash {
+ color: var(--color-highlight);
+ }
+
+ .commands-card-description {
+ margin-top: 0.25rem;
+ color: var(--color-text-secondary);
+ font-size: 0.9rem;
+ line-height: 1.45;
+ }
+
+ .commands-card-actions {
+ display: inline-flex;
+ gap: 0.35rem;
+ 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;
+ font-size: 0.78rem;
+ word-break: break-all;
+ }
+
+ .commands-empty-state {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ gap: 0.75rem;
+ padding: 1.4rem;
+ border: 1px dashed var(--color-border);
+ border-radius: 12px;
+ background: color-mix(in srgb, var(--color-background) 84%, var(--color-panel));
+ }
+
+ .commands-empty-title {
+ font-size: 1rem;
+ font-weight: 600;
+ }
+
+ .commands-empty-copy {
+ color: var(--color-text-secondary);
+ max-width: 42rem;
+ }
+
+ .button.primary,
+ .button.secondary,
+ .button.icon {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.35rem;
+ }
+
+ .button.icon {
+ padding: 0.45rem;
+ min-width: 2.25rem;
+ justify-content: center;
+ }
+
+ .button.icon.danger {
+ color: var(--color-accent);
+ }
+
+ .spinning {
+ animation: commands-spin 1s linear infinite;
+ }
+
+ @keyframes commands-spin {
+ from { transform: rotate(0deg); }
+ to { transform: rotate(360deg); }
+ }
+
+ @media (max-width: 760px) {
+ .commands-toolbar-actions {
+ margin-left: 0;
+ }
+
+ .commands-select {
+ min-width: 0;
+ flex-basis: 100%;
+ }
+
+ .commands-toolbar-actions {
+ width: 100%;
+ }
+
+ .commands-toolbar-actions .button {
+ flex: 1 1 100%;
+ justify-content: center;
+ }
+ }
+ </style>
+</body>
+</html>
diff --git a/plugins/_commands/webui/thumbnail.png b/plugins/_commands/webui/thumbnail.png
new file mode 100644
index 000000000..428b2b9bd
Binary files /dev/null and b/plugins/_commands/webui/thumbnail.png differ