voidx 1.0.0__py3-none-any.whl

voidx/ui/browse.py

@@ -0,0 +1,160 @@
+"""Browse mode — mouse-driven tree expand/collapse after agent output."""
+
+from __future__ import annotations
+
+import sys
+from rich.console import Console
+from voidx.ui.tree import OutputTree
+
+
+def browse(tree: OutputTree, console: Console) -> None:
+    """Enter mouse browse mode. Click nodes to expand/collapse, any key to exit."""
+
+    # Terminal escape sequences
+    ENABLE_MOUSE = "\x1b[?1000h\x1b[?1006h"
+    DISABLE_MOUSE = "\x1b[?1000l\x1b[?1006l"
+    HINT = "[dim]点击节点展开/折叠，按任意键开始输入[/dim]"
+
+    # Initial render — track line count for in-place updates
+    width = console.width or 80
+    lines, line_map = tree.render_with_line_map(width)
+    for line in lines:
+        console.print(line)
+    console.print(HINT)
+    total_lines = len(lines) + 1  # +1 for hint
+
+    # Enable mouse tracking
+    sys.stdout.write(ENABLE_MOUSE)
+    sys.stdout.flush()
+
+    try:
+        if sys.platform == "win32":
+            _browse_windows(tree, console, line_map, total_lines, width)
+        else:
+            _browse_unix(tree, console, line_map, total_lines, width)
+    finally:
+        sys.stdout.write(DISABLE_MOUSE)
+        sys.stdout.flush()
+
+
+def _rerender(tree, console, total_lines, width):
+    """Move cursor up, clear, re-render tree + hint."""
+    # Move up to start of tree
+    sys.stdout.write(f"\x1b[{total_lines}A")
+    sys.stdout.write("\x1b[J")  # Clear from cursor to end
+    sys.stdout.flush()
+
+    lines, line_map = tree.render_with_line_map(width)
+    for line in lines:
+        console.print(line)
+    console.print("[dim]点击节点展开/折叠，按任意键开始输入[/dim]")
+    sys.stdout.flush()
+    return len(lines) + 1, line_map
+
+
+def _browse_windows(tree, console, line_map, total_lines, width):
+    import msvcrt
+
+    while True:
+        ch = msvcrt.getwch()
+        if ch == '\x1b':
+            # Check if mouse event follows: \x1b[<...
+            if msvcrt.kbhit():
+                ch2 = msvcrt.getwch()
+                if ch2 == '[':
+                    if msvcrt.kbhit():
+                        ch3 = msvcrt.getwch()
+                        if ch3 == '<':
+                            # Parse SGR mouse: <button;col;row{M|m}
+                            buf = ''
+                            while True:
+                                c = msvcrt.getwch()
+                                if c in ('M', 'm'):
+                                    break
+                                buf += c
+                            parts = buf.split(';')
+                            if len(parts) >= 3 and parts[0] == '0':
+                                # Left button press
+                                try:
+                                    row = int(parts[2])
+                                    node_id = line_map.get(row - 1)  # 0-based
+                                    if node_id:
+                                        node = tree.get(node_id)
+                                        if node:
+                                            node.collapsed = not node.collapsed
+                                            total_lines, line_map = _rerender(
+                                                tree, console, total_lines, width)
+                                except (ValueError, IndexError):
+                                    pass
+                        else:
+                            # Arrow key or other sequence — exit
+                            return
+                    else:
+                        return
+                else:
+                    return
+            else:
+                # Lone ESC — exit
+                return
+        else:
+            # Any other key — exit
+            return
+
+
+def _browse_unix(tree, console, line_map, total_lines, width):
+    import termios
+    import tty
+    import select
+
+    fd = sys.stdin.fileno()
+    old = termios.tcgetattr(fd)
+    try:
+        tty.setraw(fd)
+        while True:
+            # Use select with short timeout to handle partial reads
+            if not select.select([sys.stdin], [], [], 0.1)[0]:
+                continue
+
+            ch = sys.stdin.buffer.read(1)
+            if ch == b'\x1b':
+                # Check for mouse/arrow sequence
+                ready, _, _ = select.select([sys.stdin], [], [], 0.05)
+                if ready:
+                    ch2 = sys.stdin.buffer.read(1)
+                    if ch2 == b'[':
+                        ready2, _, _ = select.select([sys.stdin], [], [], 0.05)
+                        if ready2:
+                            ch3 = sys.stdin.buffer.read(1)
+                            if ch3 == b'<':
+                                # Mouse event
+                                buf = b''
+                                while True:
+                                    c = sys.stdin.buffer.read(1)
+                                    if c in (b'M', b'm'):
+                                        break
+                                    buf += c
+                                parts = buf.decode().split(';')
+                                if len(parts) >= 3 and parts[0] == '0':
+                                    try:
+                                        row = int(parts[2])
+                                        node_id = line_map.get(row - 1)
+                                        if node_id:
+                                            node = tree.get(node_id)
+                                            if node:
+                                                node.collapsed = not node.collapsed
+                                                total_lines, line_map = _rerender(
+                                                    tree, console, total_lines, width)
+                                    except (ValueError, IndexError):
+                                        pass
+                            else:
+                                return  # Arrow key → exit
+                        else:
+                            return  # [ with nothing → exit
+                    else:
+                        return  # not [ → ESC → exit
+                else:
+                    return  # Lone ESC → exit
+            else:
+                return  # Any other key → exit
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old)

voidx/ui/capture.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+import time
+
+from rich.markup import escape
+
+from voidx.ui.tree import OutputTree, OutputNode
+from voidx.ui.console import _fmt_args, _title, VoidConsole
+from voidx.ui.dock import dock
+from voidx.ui.dock_components.nodes import _bash_markdown_lines
+from voidx.ui.events import (
+    ErrorAppended,
+    SubagentStepStarted,
+    ToolFinished,
+    ToolResultAppended,
+    ToolStarted,
+    WarningAppended,
+    ui_events,
+)
+
+class _DummyConsole:
+    width: int = 80
+
+class CaptureConsole:
+    def __init__(self, tree: OutputTree, parent_node: OutputNode, *, agent_id: int = -1):
+        self._tree = tree
+        self._parent = parent_node
+        self._agent_id = agent_id
+        self._current_tool: OutputNode | None = None
+        self._current_tool_id: str = ""
+        self._tool_nodes: dict[str, OutputNode] = {}
+        self._dummy = _DummyConsole()
+
+    @property
+    def console(self) -> _DummyConsole:
+        return self._dummy
+
+    def step_header(self, n: int, max_n: int, agent: str = "") -> None:
+        if dock.active and ui_events.is_running:
+            ui_events.emit_nowait(SubagentStepStarted(
+                agent_id=self._agent_id,
+                subagent_id=agent or "subagent",
+                name=_title(VoidConsole._AGENT_GERUND.get(agent, agent)),
+                step=n,
+                max_steps=max_n,
+            ))
+            return
+        gerund = _title(VoidConsole._AGENT_GERUND.get(agent, agent))
+        self._tree.new_node(
+            parent=self._parent, node_type="turn",
+            header=f"⟳ {gerund} ({n}/{max_n})",
+            step_info=f"step {n}/{max_n}",
+            agent_name=agent if agent else None,
+            collapsed=False,
+        )
+        dock.refresh()
+
+    def tool_call(self, tool_name: str, args: dict[str, object], tool_call_id: str | None = None) -> None:
+        gerund = _title(VoidConsole._TOOL_GERUND.get(tool_name, tool_name + "ing"))
+        call_id = tool_call_id or f"capture:{tool_name}:{time.time_ns()}"
+        self._current_tool_id = call_id
+        if dock.active and ui_events.is_running:
+            ui_events.emit_nowait(ToolStarted(
+                agent_id=self._agent_id,
+                tool_call_id=call_id,
+                tool_name=tool_name,
+                label=gerund,
+                args=_fmt_args(args),
+                raw_args=args,
+            ))
+            return
+        body_lines = []
+        detail = f"({_fmt_args(args)})"
+        if tool_name == "bash":
+            command = str(args.get("command") or "")
+            detail = ""
+            body_lines = _bash_markdown_lines(command, self._dummy.width)
+        self._current_tool = self._tree.new_node(
+            parent=self._parent, node_type="tool_call",
+            header=f"● {gerund}{detail}",
+            body_lines=body_lines,
+            status="running", collapsed=True,
+        )
+        self._tool_nodes[call_id] = self._current_tool
+        dock.refresh()
+    
+    def tool_done(self, tool_name: str, elapsed: float, ok: bool = True, tool_call_id: str | None = None) -> None:
+        call_id = tool_call_id or self._current_tool_id
+        if dock.active and ui_events.is_running and call_id:
+            ui_events.emit_nowait(ToolFinished(
+                agent_id=self._agent_id,
+                tool_call_id=call_id,
+                label=_title(tool_name),
+                elapsed=elapsed,
+                ok=ok,
+            ))
+            return
+        tool_node = self._tool_nodes.get(call_id) or self._current_tool
+        if not tool_node: return
+        icon = "●" if ok else "✗"
+        tool_node.header += f"  {icon} {_title(tool_name)} ({elapsed:.1f}s)"
+        tool_node.elapsed = elapsed
+        tool_node.status = "done" if ok else "error"
+        self._tree.mark_dirty()
+        dock.refresh()
+    
+    def tool_result(self, text: str, tool_call_id: str | None = None) -> None:
+        call_id = tool_call_id or self._current_tool_id
+        if dock.active and ui_events.is_running:
+            ui_events.emit_nowait(ToolResultAppended(
+                agent_id=self._agent_id,
+                tool_call_id=call_id,
+                text=text,
+            ))
+            return
+        parent = self._tool_nodes.get(call_id) or self._current_tool or self._parent
+        lines = text.split("\n")
+        self._tree.new_node(
+            parent=parent, node_type="tool_result",
+            header=escape(lines[0]) if lines else "",
+            body_lines=[escape(line) for line in lines[1:]], collapsed=False,
+        )
+        dock.refresh()
+    
+    def diff(self, diff_text: str, title: str = "") -> None:
+        if dock.active and ui_events.is_running:
+            text = f"{title}\n{diff_text}" if title else diff_text
+            ui_events.emit_nowait(ToolResultAppended(
+                agent_id=self._agent_id,
+                tool_call_id=self._current_tool_id,
+                text=text,
+                collapsed=True,
+            ))
+            return
+        parent = self._current_tool or self._parent
+        lines = diff_text.split("\n")
+        self._tree.new_node(
+            parent=parent, node_type="diff",
+            header=escape((title or "diff")[:80]),
+            body_lines=[escape(line) for line in lines[:20]], collapsed=True,
+        )
+        dock.refresh()
+    
+    def print(self, *args, **kwargs) -> None:
+        pass
+    
+    def markdown(self, content: str) -> None:
+        pass
+    
+    def thinking(self, text: str) -> None:
+        pass
+    
+    def error(self, message: str) -> None:
+        if dock.active and ui_events.is_running:
+            ui_events.emit_nowait(ErrorAppended(agent_id=self._agent_id, message=message))
+            return
+        self._tree.new_node(parent=self._parent, node_type="error",
+            header=f"[red]✗ {escape(message)}[/]", header_style="red", collapsed=False)
+        dock.refresh()
+    
+    def warn(self, message: str) -> None:
+        if dock.active and ui_events.is_running:
+            ui_events.emit_nowait(WarningAppended(agent_id=self._agent_id, message=message))
+            return
+        self._tree.new_node(parent=self._parent, node_type="warn",
+            header=f"[yellow]! {escape(message)}[/]", header_style="yellow", collapsed=False)
+        dock.refresh()
+    
+    def sep(self) -> None:
+        pass

voidx/ui/code_ide.py

@@ -0,0 +1,251 @@
+"""Open changed files in the user's preferred code IDE."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from voidx.config import CodeIde, Settings
+
+
+@dataclass(frozen=True)
+class IdeCandidate:
+    id: str
+    label: str
+    command: list[str] | None
+    source: str
+    available: bool
+
+
+CLI_IDES: dict[str, tuple[str, list[str]]] = {
+    CodeIde.TRAE.value: ("Trae", ["trae"]),
+    CodeIde.CURSOR.value: ("Cursor", ["cursor"]),
+    CodeIde.CODE.value: ("VS Code", ["code"]),
+    CodeIde.WINDSURF.value: ("Windsurf", ["windsurf"]),
+    CodeIde.ZED.value: ("Zed", ["zed"]),
+    CodeIde.SUBLIME.value: ("Sublime Text", ["subl"]),
+}
+
+APP_IDES: dict[str, tuple[str, list[str]]] = {
+    CodeIde.TRAE.value: ("Trae", ["Trae.app"]),
+    CodeIde.CURSOR.value: ("Cursor", ["Cursor.app"]),
+    CodeIde.CODE.value: ("Visual Studio Code", ["Visual Studio Code.app", "Visual Studio Code - Insiders.app"]),
+    CodeIde.WINDSURF.value: ("Windsurf", ["Windsurf.app"]),
+    CodeIde.ZED.value: ("Zed", ["Zed.app"]),
+    CodeIde.SUBLIME.value: ("Sublime Text", ["Sublime Text.app"]),
+    CodeIde.JETBRAINS.value: ("JetBrains Toolbox", [
+        "IntelliJ IDEA.app",
+        "PyCharm.app",
+        "WebStorm.app",
+        "PhpStorm.app",
+        "GoLand.app",
+        "RustRover.app",
+        "CLion.app",
+    ]),
+    CodeIde.GHOSTTY.value: ("Ghostty", ["Ghostty.app"]),
+}
+
+TERMINAL_IDS = {CodeIde.GHOSTTY.value}
+
+
+def normalize_ide(value: str | CodeIde | None) -> str:
+    raw = str(value.value if isinstance(value, CodeIde) else value or "").strip().lower()
+    return raw or CodeIde.TRAE.value
+
+
+def detect_code_ides() -> list[IdeCandidate]:
+    candidates: list[IdeCandidate] = []
+    seen: set[tuple[str, str]] = set()
+
+    for ide_id, (label, commands) in CLI_IDES.items():
+        for command in commands:
+            resolved = shutil.which(command)
+            if resolved:
+                _append_candidate(candidates, seen, IdeCandidate(
+                    id=ide_id,
+                    label=label,
+                    command=[resolved],
+                    source=f"cli:{command}",
+                    available=True,
+                ))
+                break
+
+    ghostty = shutil.which("ghostty")
+    if ghostty:
+        _append_candidate(candidates, seen, IdeCandidate(
+            id=CodeIde.GHOSTTY.value,
+            label="Ghostty",
+            command=[ghostty],
+            source="cli:ghostty",
+            available=True,
+        ))
+
+    for ide_id, (label, app_names) in APP_IDES.items():
+        for app_name in app_names:
+            app_path = _find_app(app_name)
+            if app_path is not None:
+                _append_candidate(candidates, seen, IdeCandidate(
+                    id=ide_id,
+                    label=label,
+                    command=["open", "-a", app_path.stem],
+                    source=f"app:{app_path}",
+                    available=True,
+                ))
+                break
+
+    _append_candidate(candidates, seen, IdeCandidate(
+        id=CodeIde.SYSTEM.value,
+        label="System default",
+        command=["open"],
+        source="macOS open",
+        available=shutil.which("open") is not None,
+    ))
+    return [candidate for candidate in candidates if candidate.available]
+
+
+def preferred_ide(settings: Settings | None = None) -> str:
+    if settings is None:
+        return CodeIde.TRAE.value
+    return normalize_ide(settings.get_code_ide())
+
+
+def choose_ide(
+    settings: Settings | None = None,
+    detected: list[IdeCandidate] | None = None,
+    preferred: str | CodeIde | None = None,
+) -> IdeCandidate | None:
+    detected = detected if detected is not None else detect_code_ides()
+    if not detected:
+        return None
+    preferred_id = normalize_ide(preferred) if preferred is not None else preferred_ide(settings)
+    if preferred_id != CodeIde.AUTO.value:
+        for candidate in detected:
+            if candidate.id == preferred_id:
+                return candidate
+    priority = [
+        CodeIde.TRAE.value,
+        CodeIde.CURSOR.value,
+        CodeIde.CODE.value,
+        CodeIde.WINDSURF.value,
+        CodeIde.ZED.value,
+        CodeIde.SUBLIME.value,
+        CodeIde.JETBRAINS.value,
+        CodeIde.GHOSTTY.value,
+        CodeIde.SYSTEM.value,
+    ]
+    for ide_id in priority:
+        for candidate in detected:
+            if candidate.id == ide_id:
+                return candidate
+    return detected[0]
+
+
+def code_ide_status(settings: Settings | None = None) -> str:
+    configured = preferred_ide(settings)
+    detected = detect_code_ides()
+    selected = choose_ide(settings, detected)
+    lines = [
+        "[bold]Code IDE[/bold]",
+        f"  Configured: [cyan]{configured}[/cyan]",
+        f"  Selected: [cyan]{selected.label if selected else 'none'}[/cyan]",
+        "",
+        "  Detected:",
+    ]
+    if not detected:
+        lines.append("    [dim]none[/dim]")
+    else:
+        for candidate in detected:
+            marker = "✓" if selected and candidate.id == selected.id else " "
+            lines.append(f"  {marker} [cyan]{candidate.id}[/cyan] — {candidate.label} [dim]({candidate.source})[/dim]")
+    return "\n".join(lines)
+
+
+def open_file_in_code_ide(
+    file_path: str | Path,
+    *,
+    line: int = 1,
+    settings: Settings | None = None,
+    preferred: str | CodeIde | None = None,
+) -> bool:
+    path = Path(file_path).expanduser().resolve()
+    candidate = choose_ide(settings, preferred=preferred)
+    if candidate is None:
+        return False
+    command = build_open_command(candidate, path, line=line)
+    if command is None:
+        return False
+    try:
+        subprocess.Popen(command)
+        return True
+    except Exception:
+        return False
+
+
+def build_open_command(candidate: IdeCandidate, path: Path, *, line: int = 1) -> list[str] | None:
+    if candidate.command is None:
+        return None
+    location = f"{path}:{line}"
+    if _is_app_launcher(candidate.command):
+        return _build_app_open_command(candidate, path, location, line=line)
+    if candidate.id in {CodeIde.TRAE.value, CodeIde.CURSOR.value, CodeIde.CODE.value, CodeIde.WINDSURF.value}:
+        return [*candidate.command, "--goto", location]
+    if candidate.id == CodeIde.ZED.value:
+        return [*candidate.command, str(path)]
+    if candidate.id == CodeIde.SUBLIME.value:
+        return [*candidate.command, location]
+    if candidate.id == CodeIde.JETBRAINS.value:
+        return [*candidate.command, str(path)]
+    if candidate.id in TERMINAL_IDS:
+        editor = _terminal_editor_command()
+        if not editor:
+            return [*candidate.command, str(path)]
+        return [*candidate.command, "-e", *editor, f"+{line}", str(path)]
+    if candidate.id == CodeIde.SYSTEM.value:
+        return [*candidate.command, str(path)]
+    return [*candidate.command, str(path)]
+
+
+def _build_app_open_command(candidate: IdeCandidate, path: Path, location: str, *, line: int) -> list[str]:
+    if candidate.id in {CodeIde.TRAE.value, CodeIde.CURSOR.value, CodeIde.CODE.value, CodeIde.WINDSURF.value}:
+        return [*candidate.command, "--args", "--goto", location]
+    if candidate.id in TERMINAL_IDS:
+        editor = _terminal_editor_command()
+        if editor:
+            return [*candidate.command, "--args", "-e", *editor, f"+{line}", str(path)]
+    return [*candidate.command, str(path)]
+
+
+def _is_app_launcher(command: list[str]) -> bool:
+    return len(command) >= 3 and Path(command[0]).name == "open" and command[1] == "-a"
+
+
+def _append_candidate(candidates: list[IdeCandidate], seen: set[tuple[str, str]], candidate: IdeCandidate) -> None:
+    key = (candidate.id, candidate.source)
+    if key in seen:
+        return
+    seen.add(key)
+    candidates.append(candidate)
+
+
+def _find_app(app_name: str) -> Path | None:
+    for base in (Path("/Applications"), Path.home() / "Applications"):
+        path = base / app_name
+        if path.exists():
+            return path
+    return None
+
+
+def _terminal_editor_command() -> list[str]:
+    for env_name in ("EDITOR", "VISUAL"):
+        value = os.environ.get(env_name)
+        if value:
+            return shlex.split(value)
+    for command in ("nvim", "vim", "nano"):
+        resolved = shutil.which(command)
+        if resolved:
+            return [resolved]
+    return []

voidx/ui/commands.py

@@ -0,0 +1,83 @@
+"""Slash command palette — Claude Code style. / triggers selectable command list."""
+
+from __future__ import annotations
+
+COMMANDS: list[tuple[str, str]] = [
+    ("/allow", "Allow a tool for this session"),
+    ("/approval", "Set approval policy: untrusted|on-failure|on-request|never"),
+    ("/approval never", "Never ask for approval"),
+    ("/approval on-failure", "Auto-allow non-bash tools and report failures"),
+    ("/approval on-request", "Auto-allow unless an explicit request is needed"),
+    ("/approval untrusted", "Ask for write/edit/write-capable bash tools"),
+    ("/clear", "Start a new session with empty context"),
+    ("/code-ide", "Choose app for opening changed files"),
+    ("/code-ide status", "Show detected code IDEs"),
+    ("/compact", "Manually trigger context compaction"),
+    ("/debug", "Toggle verbose step/tool output"),
+    ("/debug off", "Disable verbose step/tool output"),
+    ("/debug on", "Enable verbose step/tool output"),
+    ("/deny", "Deny a tool for this session"),
+    ("/diff", "Show git working tree diff with syntax highlighting"),
+    ("/exit", "Exit voidx"),
+    ("/help", "Show all commands"),
+    ("/goal", "Set or show current goal"),
+    ("/goal clear", "Clear current goal"),
+    ("/list", "List saved sessions"),
+    ("/lsp", "Manage language servers"),
+    ("/lsp doctor", "Check installed language servers"),
+    ("/lsp restart", "Restart language servers"),
+    ("/lsp servers", "List configured LSP servers"),
+    ("/lsp status", "Show LSP server status"),
+    ("/mcp", "Manage MCP servers"),
+    ("/mcp del", "Remove an MCP server"),
+    ("/mcp list", "List configured MCP servers"),
+    ("/mcp new", "Configure a new MCP server"),
+    ("/mcp restart", "Restart an MCP server"),
+    ("/mcp test", "Test an MCP server connection"),
+    ("/mcp tools", "Show MCP server tools"),
+    ("/mode", "Choose interaction mode: auto|plan|goal"),
+    ("/mode auto", "Auto-detect task intent per turn"),
+    ("/mode goal", "Keep multi-step work scoped"),
+    ("/mode plan", "Read-only plan mode"),
+    ("/model", "Switch configured model"),
+    ("/model del", "Remove a profile"),
+    ("/model list", "Show configured model details"),
+    ("/model new", "Create or update a model profile"),
+    ("/model reasoning", "Set reasoning effort level"),
+    ("/model switch", "Switch to a configured provider"),
+    ("/model test", "Test a provider's connectivity"),
+    ("/paste", "Paste an image from the clipboard"),
+    ("/permission-mode", "Choose permission mode"),
+    ("/permission-mode accept-edits", "Allow file edits, ask for bash"),
+    ("/permission-mode auto-review", "Reviewer-assisted approvals"),
+    ("/permission-mode custom", "Use voidx.json config"),
+    ("/permission-mode default", "Ask before write/edit/bash"),
+    ("/permission-mode full-access", "No sandbox or approval prompts"),
+    ("/permission-mode read-only", "Block all writes"),
+    ("/permissions", "Show current permission rules"),
+    ("/plan", "Enter plan mode (writes and write-capable bash blocked)"),
+    ("/resume", "Resume a session by ID"),
+    ("/sandbox", "Set sandbox mode: read-only|workspace-write|danger-full-access"),
+    ("/sandbox danger-full-access", "No sandbox restrictions"),
+    ("/sandbox read-only", "Read-only sandbox"),
+    ("/sandbox workspace-write", "Allow workspace writes"),
+    ("/skills", "Manage local skills"),
+    ("/tavily", "Configure Tavily API key for web search"),
+    ("/tavily delete", "Delete Tavily API key"),
+    ("/tavily set", "Set Tavily API key for web search"),
+    ("/tavily show", "Show Tavily API key status"),
+    ("/title", "Set session title"),
+    ("/unplan", "Return to auto mode"),
+    ("/usage", "Show token usage for this session"),
+]
+
+def filter_commands(prefix: str) -> list[tuple[str, str]]:
+    """Filter commands by prefix. Returns (name, description) pairs.
+
+    Matches both when the input *is* a prefix of a command (e.g. ``/res``
+    matches ``/resume``) and when the input *starts with* a command
+    (e.g. ``/resume abc123`` matches ``/resume``).
+    """
+    p = prefix.lower()
+    return [(n, d) for n, d in COMMANDS
+            if n.lower().startswith(p) or p.startswith(n.lower())]