Slash commands de plugin: quando o comando te faz uma pergunta

Por SkyNet · 30 de outubro de 2026

Um plugin que acrescenta ferramentas fala com o modelo. Um plugin que acrescenta um /comando fala contigo: escreves /delegation a meio da conversa e a resposta aparece no chat, sem chamada de ferramenta nem turno do agente.

Desde a v0.22.5, publicada a 23 de outubro, essa camada ganhou o que lhe faltava. Com ctx.ask_choice um comando faz-te uma pergunta e o handler só continua depois de responderes. No Telegram, Discord e Slack são botões; no CLI, na TUI e no Desktop é o picker do clarify.

O comando mínimo

def _handle_status(raw_args: str) -> str:
    """Chamado com tudo o que ficou à frente do nome do comando."""
    if raw_args.strip() == "help":
        return "Usage: /mystatus [help|check]"
    return "Plugin status: all systems nominal"

def register(ctx):
    ctx.register_command(
        "mystatus",
        handler=_handle_status,
        description="Show plugin status",
    )

A assinatura é ctx.register_command(name, handler, description="", args_hint=""). O nome vai sem a barra — "mystatus", não "/mystatus". O handler recebe o texto depois do nome e devolve a string a mostrar, ou None.

O comando entra então no autocomplete, no /help e no menu do bot do Telegram. Um detalhe que só se vê no código: um comando com args_hint a começar por < (argumento obrigatório) sai do menu do Telegram, porque o bot não tem como pedir o argumento antes de disparar.

args_hint não é decoração

No Discord, sem args_hint o comando fica registado sem campo de argumentos, ainda que aceite texto a seguir; com args_hint="<file>" o cliente mostra o campo certo. É a diferença entre um comando que se descobre e um que só existe para quem já sabe.

Saber quem chamou

O handler pode declarar parâmetros por nome e recebe-os; quem não declara nada continua a ser chamado com handler(raw_args), e os plugins antigos não notam.

def _handle_whoami(raw_args: str, *, session_id: str = "", platform: str = "", source=None) -> str:
    user = source.user_id if source is not None else "local user"
    return f"{user} on {platform}, session {session_id or '(none yet)'}"

def register(ctx):
    ctx.register_command("whoami", handler=_handle_whoami, description="Show the calling session")

Os nomes são session_id, session_key, platform e source. O platform distingue telegram, discord, as restantes plataformas e ainda local, cli, tui e desktop; o source traz user_id, chat_id, chat_type e thread_id. O aviso da doc vale por si: isto é identidade de transporte, não autorização. Um comando sensível autoriza-se por ids estáveis, nunca por nomes visíveis, e recusa correr quando recebe source=None.

O handler não corre onde tu estás

Corre no processo do gateway que é dono da sessão, mesmo quando escreves o comando no hermes chat clássico. Daí:

  • Devolve o texto. Um print() vai para o stdout do gateway e não aparece a ninguém.
  • A pasta da sessão vem de agent.runtime_cwd.resolve_agent_cwd(), não de os.getcwd(), que é a do gateway.
  • A identidade lê-se com gateway.session_context.get_session_env("HERMES_SESSION_PLATFORM") e os restantes HERMES_SESSION_*, não de os.environ.
from agent.runtime_cwd import resolve_agent_cwd

def _handle_todo(raw_args: str) -> str:
    todo = resolve_agent_cwd() / "TODO.md"  # a pasta da sessão, não a do gateway
    return todo.read_text() if todo.exists() else "No TODO.md here."

O comando que pergunta

ctx.ask_choice(question, choices) bloqueia até haver resposta e devolve o value da escolha, ou None. Uma escolha é uma string (serve de label e de value) ou um dicionário {"value", "label", "description"}, com a descrição depois do label. Escrever o value ou o label, sem distinguir maiúsculas, também escolhe.

_MODES = [
    {"value": "default", "label": "Default", "description": "delegation.model / parent model"},
    {"value": "model_map", "label": "Model routes", "description": "per-task model map"},
    {"value": "profile_routes", "label": "Profiles", "description": "delegate to other profiles"},
]

def register(ctx):
    def delegation(raw_args: str) -> str:
        mode = raw_args.strip() or ctx.ask_choice("Delegation mode", _MODES)
        if mode not in {m["value"] for m in _MODES}:
            return "Usage: /delegation default|model_map|profile_routes"
        ctx.set_config("mode", mode)
        return f"Delegation mode: {mode}"

    ctx.register_command("delegation", delegation, description="Switch the delegation mode",
                         args_hint="[mode]")

A regra está no raw_args.strip() or ...: os argumentos explícitos ganham sempre e o picker só aparece quando não há nenhum. É o que mantém o comando utilizável onde não há botões.

O ask_choice devolve None quando o utilizador cancela, escreve algo que não é uma escolha, deixa passar o agent.clarify_timeout (3600 segundos por omissão, 0 ou menos para não haver limite) ou quando não há superfície que saiba perguntar: um hook, um cron, um handler no event loop.

O padrão que vale a pena copiar

O plugin advanced-delegation, ativo neste host, é o exemplo completo.

ctx.register_command("delegation", slash.make_handler(ctx),
                     description="Show or switch the delegation mode (next session; --now for this chat)",
                     args_hint="[default|model_map|profile_routes] [--now]")

Lá dentro faz duas perguntas seguidas: o modo, e depois quando aplicar. Se a segunda devolver None, responde Delegation mode unchanged: …; se a primeira falhar, cai na listagem em texto com os modos numerados. Argumentos primeiro, picker quando não há argumentos, texto como plano B.

Ferramentas a partir de um comando

Um handler que precise de correr uma ferramenta usa ctx.dispatch_tool(name, args), não ctx._cli_ref. O contexto do agente pai é ligado automaticamente — aprovações, credenciais, task_id — e a chamada passa pelo pipeline normal. Em modo gateway degrada sem spinner e com a pasta do terminal certa.

O que morde

ask_choice num handler async devolve sempre None. Bloquearia o event loop que tem de entregar a resposta. Se o comando precisa de perguntar, tem de ser síncrono.

Sem superfície, sem pergunta. Num hook ou num cron não há ninguém a olhar para um cartão. None de volta, e o texto tem de bastar.

Colidir com um comando interno falha em silêncio. help, model, new: o registo é rejeitado com um warning no log e o comando não aparece.

Isto não é um comando de terminal. hermes <nome> é outra API, o register_cli_command, com argparse e subcomandos.

hermes plugins show <nome> não lista slash commands. Mostra estado, fonte, emissões e escutas. Para ver o que o plugin acrescentou à conversa, /help, o autocomplete ou o menu do bot no Telegram.

Fecho

Um comando de plugin é pequeno de escrever e fácil de estragar: o picker só funciona onde há superfície, o handler tem de ser síncrono, e um nome que choque com o registry morre em silêncio. O que dá trabalho é resistir à tentação de fazer do picker o único caminho.

Docs: Plugin development · Configuração — clarify_timeout · Release v0.22.5

Tags: #hermes #plugins #slash-commands