frankenterm

O que frankenterm faz?

Hipervisor de terminal para enxames de agentes de IA: captura de painéis em tempo real, detecção de padrões baseada em máquina de estados e API JSON para coordenar frotas de agentes de codificação no WezTerm.

Visão Geral

O frankenterm permite que agentes de IA supervisionem e controlem vários painéis do terminal WezTerm simultaneamente. Ele oferece:

• Captura em tempo real: Cada painel tem seu conteúdo capturado continuamente (via polling ou eventos).
• Detecção de padrões: Máquina de estados configurável para identificar quando uma tarefa termina, surge um erro ou ocorre um timeout.
• API JSON RESTful: Endpoints para consultar estado dos painéis, enviar comandos e registrar callbacks de eventos.

Como funciona

1. O frankenterm se conecta ao WezTerm via sua API (normalmente usando WebSockets ou Unix sockets).
2. Para cada painel (ou aba), ele mantém um buffer com o histórico de saída.
3. Um mecanismo de máquina de estados (definido em arquivos YAML/JSON) avalia o buffer em busca de padrões (expressões regulares, tokens, etc.).
4. Quando um padrão é detectado, um evento é gerado e pode ser consumido pelos agentes via API ou Webhooks.
5. Os agentes podem enviar comandos para painéis específicos e receber respostas assíncronas.

Exemplo de uso

# Iniciar o frankenterm com configuração padrão
frankenterm start

# Listar painéis disponíveis
curl http://localhost:8000/panels

# Executar comando em um painel
curl -X POST http://localhost:8000/panels/1/send -d '{"command": "npm run build"}'

# Aguardar evento de conclusão
curl http://localhost:8000/panels/1/events?timeout=60

Configuração da máquina de estados

Crie um arquivo patterns.yaml:

patterns:
  - name: "build_success"
    trigger: ".*Build completed successfully.*"
    actions:
      - notify: "webhook"
      - execute: "echo 'Build OK'"
    
  - name: "error_detected"
    trigger: ".*(error|Error|ERROR).*"
    cooldown: 30  # segundos
    actions:
      - notify: "agent"

API JSON

Método	Rota	Descrição
GET	/panels	Lista todos os painéis
GET	/panels/:id	Obtém estado de um painel
POST	/panels/:id/send	Envia comando para o painel
GET	/panels/:id/events	Ouve eventos do painel
POST	/config	Atualiza configuração em tempo real

Requisitos

• WezTerm (versão >= 20230401)
• Python >= 3.9
• Acesso ao socket do WezTerm (configurado em wezterm.lua)

Exemplo de integração com agente

import requests

agent_url = "http://localhost:8000"
panel_id = "2"

# Enviar comando
requests.post(f"{agent_url}/panels/{panel_id}/send", json={"command": "pytest"})

# Aguardar padrão "tests passed"
response = requests.get(f"{agent_url}/panels/{panel_id}/events", params={"pattern": "passed", "timeout": 120})
if response.json()["matched"]:
    print("Testes passaram!")

Licença

MIT