feat(commands): centralized command registry with sub-command routing

[mingmxren]

Description

Introduces a centralized pkg/commands package that serves as the single source of truth for all slash command metadata, parsing, and dispatch. Replaces scattered inline command handling across loop.go and channel adapters with a unified architecture.

Architecture

+=====================================================================+
|                           pkg/commands                              |
|                                                                     |
|  +--------------+    +---------------+    +-----------------------+ |
|  | Definition   |    | Registry      |    | Executor              | |
|  |              |    |               |    |                       | |
|  | Name         |--->| index: map    |--->| Execute(req)          | |
|  | SubCommands  |    | [name]->def   |    |   |- parseCommandName | |
|  | Handler      |    |               |    |   |- Lookup O(1)      | |
|  |              |    | Lookup()      |    |   '- sub-cmd routing  | |
|  | Effective    |    | Definitions() |    |                       | |
|  | Usage()      |    +---------------+    | Reply nil guard       | |
|  +--------------+                         | (centralized)         | |
|                                           +-----------------------+ |
|  +----------------------------------------------------------------+ |
|  | Command Groups (stateless definitions)                         | |
|  |                                                                | |
|  | cmd_start.go       /start                                      | |
|  | cmd_help.go        /help            (auto-generated usage)     | |
|  | cmd_show.go        /show [model|channel|agents]                | |
|  | cmd_list.go        /list [models|channels|agents]              | |
|  | cmd_switch.go      /switch [model to <name>|channel to <name>] | |
|  | handler_agents.go  shared agentsHandler (dedup)                | |
|  +----------------------------------------------------------------+ |
|                                                                     |
|  +-------------+  +------------+  +-------------------------------+ |
|  | Runtime     |  | request.go |  | Request / ExecuteResult       | |
|  | (per-req)   |  |            |  |                               | |
|  |             |  | HasCommand |  | Channel, ChatID, SenderID     | |
|  | GetModel    |  |  Prefix()  |  | Text, Reply callback          | |
|  | ListAgent   |  | nthToken() |  |                               | |
|  | ListDefs    |  | parseCmd() |  | Outcome: Handled/Passthrough  | |
|  | GetChan     |  +------------+  +-------------------------------+ |
|  | SwitchMod   |                                                     |
|  | SwitchCh    |                                                     |
|  +-------------+                                                     |
+=====================================================================+
        |                                       |
        | func fields                           | []Definition
        | built per-request                     | (stateless)
        v                                       v
+----------------------+             +--------------------------+
| pkg/agent            |             | pkg/channels/telegram    |
|                      |             |                          |
| AgentLoop            |             | startCommandRegistration |
| |- cmdRegistry       |             | (async + backoff)        |
| |  (cached, once)    |             |                          |
| |- handleCommand()   |             | Derives Telegram         |
| |  HasCommandPrefix  |             | BotCommand menu from     |
| |  (supports / !)    |             | Definition metadata      |
| |- buildCommandsRuntime()          +--------------------------+
| |  (per-request)     |
| '- NewExecutor       |
|    (registry,runtime)|
+----------------------+


Data Flow (processMessage)
==========================

  User message ("/show model" or "!switch model to gpt-4")
       |
       v
  resolveMessageRoute()  -->  (route, agent, routeErr)
       |
       v
  handleCommand()  <-- runs BEFORE routeErr check
       |                so /help, /show, /switch work even when routing fails
       |
       |- commands.HasCommandPrefix()  -->  supports "/" and "!"
       |- buildCommandsRuntime()       -->  creates Runtime with current state
       |
       v
  NewExecutor(registry, runtime).Execute()
       |
       |- parseCommandName()   -->  normalize, strip @bot suffix
       |- Registry.Lookup()    -->  O(1) map lookup
       '- executeDefinition()
            |
            |- nil Reply guard (centralized)
            |- simple cmd  ->  Handler(ctx, req, rt)
            '- sub-cmd     ->  match SubCommand.Name -> Handler(ctx, req, rt)
                                    |
                                    v
                          Runtime callbacks
                          e.g. rt.SwitchModel()
       |
       v
  routeErr != nil?  -->  return error (non-command messages need routing)
       |
       v
  runAgentLoop(agent, ...)

Key Design Decisions

• Registry / Runtime separation: Registry holds stateless command metadata (cached once on AgentLoop). Runtime carries per-request dependencies (built fresh each handleCommand call). This cleanly separates "what commands exist" from "what resources they need".
• Per-request Executor: NewExecutor(registry, runtime) is created per-request, binding the stateless Registry with the current Runtime. This enables future session management to inject per-request context (e.g. session scope) without modifying the registry.
• Handler signature func(ctx, req, rt) error: Handlers receive Runtime as an explicit parameter instead of closing over deps. This makes dependencies visible, testable, and per-request.
• SubCommand pattern: Sub-commands are declared structurally within Definition. EffectiveUsage() auto-generates help text from sub-command names, preventing metadata/handler drift.
• Centralized nil guard: req.Reply nil check is done once in executeDefinition, not in every handler.
• Commands before route gate: handleCommand() runs before checking routeErr, so global commands (/help, /show, /switch) remain available even when routing fails. Context-dependent commands that need a routed agent report "unavailable" via their nil-Runtime guards.

Changes

New package: pkg/commands

• definition.go — Definition, SubCommand, EffectiveUsage() auto-generation
• registry.go — O(1) map-based command lookup with alias support
• executor.go — Two-outcome dispatch (Handled/Passthrough) with sub-command routing and Reply error propagation
• request.go — Request/Handler types, shared parsing: HasCommandPrefix(), nthToken(), parseCommandName()
• runtime.go — Per-request runtime dependency struct (ListDefinitions, SwitchModel, SwitchChannel, etc.)
• cmd_*.go — Per-group command definitions (start, help, show, list, switch)
• handler_agents.go — Shared agentsHandler used by both /show agents and /list agents
• builtin.go — Aggregates all built-in definitions (stateless, no parameters)

Modified: pkg/agent/loop.go

• Cache cmdRegistry as AgentLoop field (created once in struct init)
• buildCommandsRuntime() constructs per-request Runtime; wires ListDefinitions from registry
• handleCommand() runs before route error check — global commands work even when routing fails
• modelMu mutex protects AgentInstance.Model writes in SwitchModel callback

Modified: pkg/channels/telegram

• Async startCommandRegistration with exponential backoff replaces blocking initBotCommands
• Derives Telegram BotCommand menu from BuiltinDefinitions() metadata

New: pkg/channels/interfaces.go

• CommandRegistrarCapable interface for platform menu registration

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Code refactoring (no functional changes, no api changes)

AI Code Generation

• Mostly AI-generated (AI draft, Human verified/modified)

Related Issue

• [Feature] Unify slash commands across all channels #570 [Feature] Unify slash commands across all channels
• [BUG] Telegram /help command references may be incomplete #579 [BUG] Telegram /help command references may be incomplete

Technical Context

• Reference: pkg/commands/definition.go, pkg/commands/registry.go, pkg/commands/executor.go, pkg/commands/runtime.go
• Reasoning: Keep command metadata, dispatch behavior, and platform registration synchronized from one canonical source. SubCommand pattern prevents help text / handler drift. Registry/Runtime separation enables future session management without architectural changes.

Test Environment

• Hardware: Mac mini
• OS: macOS 26.3
• Channels: Telegram, WhatsApp

Checklist

• My code/docs follow the style of this project.
• I have performed a self-review of my own changes.
• I have updated the documentation accordingly.

[mingmxren]

Addressed remaining review comments.

[CLAassistant]

All committers have signed the CLA.

[yinwm]

`/switch channel` Semantic Issue

Noticed that `/switch channel` only validates if a channel exists, but doesn't actually switch anything. This is a historical issue (not introduced by this PR).
PR has already made the message more honest (from "Switched target channel to X" to "Channel 'X' is available and enabled"), which is a good improvement.
However, the command name `/switch` is still misleading: users see "switch" and expect a state change, but it only validates existence.

Suggestion

This is a historical issue, not introduced by this PR. Consider creating a follow-up issue to discuss:

• Is actual "switch" functionality needed?
• If not, consider renaming to `/check channel` or `/verify channel` (possibly keeping `/switch` as an alias)
• If needed, implement actual switch logic
• Or at least clarify in help docs that this only validates availability, not actual switching
  This is a minor issue that doesn't block merging this valuable architectural refactoring PR.

[mingmxren]

/switch channel Semantic Issue

Noticed that /switch channel only validates if a channel exists, but doesn't actually switch anything. This is a historical issue (not introduced by this PR). PR has already made the message more honest (from "Switched target channel to X" to "Channel 'X' is available and enabled"), which is a good improvement. However, the command name /switch is still misleading: users see "switch" and expect a state change, but it only validates existence.

Suggestion

This is a historical issue, not introduced by this PR. Consider creating a follow-up issue to discuss:

* Is actual "switch" functionality needed?

* If not, consider renaming to `/check channel` or `/verify channel` (possibly keeping `/switch` as an alias)

* If needed, implement actual switch logic

* Or at least clarify in help docs that this only validates availability, not actual switching
  This is a minor issue that doesn't block merging this valuable architectural refactoring PR.

@yinwm
Solved by a963826

[yinwm]

LGTM

[Orgmar]

@mingmxren 把分散在各处的slash command处理统一到一个registry，架构清晰多了。之前命令解析散落在loop.go和各个adapter里确实不太好维护，这次重构很有必要。

我们有个 PicoClaw Dev Group Discord群，方便贡献者之间交流协作。感兴趣的话发封邮件到 support@sipeed.com，主题写 [Join PicoClaw Dev Group] mingmxren，我们会把邀请链接发给你！

[mingmxren]

@mingmxren 把分散在各处的slash command处理统一到一个registry，架构清晰多了。之前命令解析散落在loop.go和各个adapter里确实不太好维护，这次重构很有必要。

我们有个 PicoClaw Dev Group Discord群，方便贡献者之间交流协作。感兴趣的话发封邮件到 support@sipeed.com，主题写 [Join PicoClaw Dev Group] mingmxren，我们会把邀请链接发给你！

Thanks, I'm already in the group.