ACP por dentro

O adaptador ACP embrulha o AIAgent síncrono do Hermes num servidor JSON-RPC assíncrono, por stdio.

Arquivos principais:

• acp_adapter/entry.py
• acp_adapter/server.py
• acp_adapter/session.py
• acp_adapter/events.py
• acp_adapter/permissions.py
• acp_adapter/tools.py
• acp_adapter/auth.py

Fluxo de inicialização

hermes acp / hermes-acp / python -m acp_adapter
  -> acp_adapter.entry.main()
  -> trata --version / --check / --setup antes de subir o servidor
  -> carrega ~/.hermes/.env
  -> configura o log na saída de erro
  -> constrói o HermesACPAgent
  -> acp.run_agent(agent, use_unstable_protocol=True)

A saída padrão é reservada para o transporte JSON-RPC do ACP. Logs legíveis por pessoas vão para a saída de erro.

Componentes principais

HermesACPAgent

O acp_adapter/server.py implementa o protocolo de agente do ACP.

Responsabilidades:

• inicializar e autenticar
• métodos de sessão: nova, carregar, retomar, bifurcar, listar, cancelar
• executar prompts
• trocar o modelo da sessão
• ligar os retornos de chamada síncronos do AIAgent às notificações assíncronas do ACP

SessionManager

O acp_adapter/session.py acompanha as sessões ACP vivas.

Cada sessão guarda:

• session_id
• agent
• cwd
• model
• history
• cancel_event

O gerenciador é seguro entre threads e suporta criar, obter, remover, bifurcar, listar, limpar e atualizar o diretório de trabalho.

Ponte de eventos

O acp_adapter/events.py converte os retornos de chamada do AIAgent em eventos session_update do ACP.

Retornos de chamada ligados:

• tool_progress_callback
• thinking_callback (hoje definido como None na ponte do ACP — o raciocínio é repassado pelo step_callback)
• step_callback

Como o AIAgent roda numa thread de trabalho enquanto a entrada e saída do ACP vive no laço de eventos principal, a ponte usa:

asyncio.run_coroutine_threadsafe(...)

Ponte de permissões

O acp_adapter/permissions.py adapta as aprovações de comando perigoso de terminal em pedidos de permissão do ACP.

Mapeamento:

• allow_once → once do Hermes
• allow_always → always do Hermes
• opções de recusa → deny do Hermes

Tempo esgotado e falha na ponte negam por padrão.

Auxiliares de renderização de ferramenta

O acp_adapter/tools.py mapeia as ferramentas do Hermes para os tipos de ferramenta do ACP e monta o conteúdo que o editor mostra.

Exemplos:

• patch e write_file → diffs de arquivo
• terminal → o texto do comando
• read_file e search_files → prévias de texto
• resultados grandes → blocos de texto cortados, por segurança da interface

Ciclo de vida da sessão

new_session(cwd)
  -> cria o SessionState
  -> cria AIAgent(platform="acp", enabled_toolsets=["hermes-acp"])
  -> liga task_id e session_id à sobrescrita de cwd

prompt(..., session_id)
  -> extrai o texto dos blocos de conteúdo do ACP
  -> zera o evento de cancelamento
  -> instala os retornos de chamada e a ponte de aprovação
  -> roda o AIAgent num ThreadPoolExecutor
  -> atualiza o histórico da sessão
  -> emite o trecho final da mensagem do agente

Cancelamento

O cancel(session_id):

• marca o evento de cancelamento da sessão
• chama agent.interrupt() quando disponível
• faz a resposta do prompt voltar com stop_reason="cancelled"

Bifurcação

O fork_session() copia em profundidade o histórico de mensagens para uma sessão viva nova, preservando o estado da conversa e dando à bifurcação um identificador e um diretório de trabalho próprios.

Provedor e autenticação

O ACP não implementa um armazenamento de autenticação próprio. Ele reaproveita o resolvedor de tempo de execução do Hermes:

• acp_adapter/auth.py
• hermes_cli/runtime_provider.py

Então o ACP anuncia e usa o provedor e as credenciais configurados no Hermes. Ele também sempre anuncia um método de autenticação por terminal (hermes-setup, com o argumento --setup), para clientes ACP de primeira execução abrirem a configuração interativa de modelo e provedor antes de começar uma sessão normal.

Vínculo com o diretório de trabalho

Sessões ACP carregam o diretório de trabalho do editor. O gerenciador liga esse diretório ao identificador da sessão ACP, por sobrescritas de terminal e arquivo com escopo de tarefa, então as ferramentas de arquivo e de terminal operam em relação ao espaço de trabalho do editor.

Chamadas repetidas com o mesmo nome de ferramenta

A ponte de eventos acompanha os identificadores de ferramenta numa fila por nome, e não um identificador por nome. Isso importa para:

• chamadas paralelas com o mesmo nome
• chamadas repetidas com o mesmo nome num passo só

Sem as filas, os eventos de conclusão se ligariam à invocação errada.

Restauração do retorno de chamada de aprovação

O ACP instala temporariamente um retorno de chamada de aprovação na ferramenta de terminal enquanto o prompt executa, e restaura o anterior depois. Isso evita deixar manipuladores de aprovação específicos de uma sessão ACP instalados globalmente para sempre.

Limitações atuais

• As sessões ACP são gravadas no ~/.hermes/state.db compartilhado (SessionDB) e restauradas de forma transparente entre reinícios do processo; elas aparecem no session_search
• Blocos de prompt que não são texto são ignorados hoje na extração do texto da requisição
• A experiência varia conforme a implementação de cada cliente ACP

Arquivos relacionados

• tests/acp/ — a suíte de testes do ACP
• toolsets.py — a definição do conjunto hermes-acp
• hermes_cli/main.py — o subcomando hermes acp
• pyproject.toml — a dependência opcional [acp] e o script hermes-acp