Visão geral da arquitetura
A inteligência mora no harness; o modelo é uma função estreita e trocável. O loop não confia na prosa do modelo — decide pelo estado e por efeitos observáveis. Prin…
Máquina de estados
Toda tarefa percorre uma máquina de estados explícita. Ela nunca fica IN_PROGRESS para sempre: maxSteps, maxWallClock e o stall detector garantem terminação.
PENDING ─► IN_PROGRESS ─► COMPLETE (exitCriteria verificados)
├─► BLOCKED (razão estruturada)
├─► NEEDS_INPUT
└─► FAILED (orçamento estourado)Action-or-Terminate
Todo turno termina em tool-call OU num sinal terminal (task_complete / task_blocked / need_input). Texto em futuro (“vou”, “let me”, “I'll”) sem ação é detectado por um reconciler intent–action (PT/EN), rejeitado e re-promptado: “Você disse que faria X mas não agiu. Execute agora ou declare bloqueio.”
exitCriteria verificados
task_complete só vale se os exitCriteria baterem: build passa, testes verdes, arquivo existe, gate de contrato. “Concluído” é asserção do harness, nunca só do modelo. Falhou? Volta a lista exata do que falta e o agente retoma.
Anti-loop
Modelo fraco adora repetir a mesma tool e oscilar entre dois estados. O harness detecta e quebra sem depender de o modelo “perceber”:
- Fingerprint + dedup: cada chamada vira hash (tool, args normalizados); repetiu N vezes → bloqueia com nudge.
- Detecção de ciclo: padrões A,B,A,B / A,B,C,A,B,C na janela recente → quebra.
- Circuit breaker: mesmo comando falhando N vezes com o mesmo erro → aquela abordagem é proibida.
- Orçamento por progresso: muito efeito e zero progresso contra os exitCriteria → quebra.
- Tetos duros: maxToolCalls por tarefa + cap por-tool.
- Escada de escalonamento: nudge → re-decompõe → escala p/ modelo mais forte → BLOCKED com diagnóstico.
Anti-alucinação
- Grounding obrigatório: afirmação sobre o código precisa estar lastreada numa observação real (read-before-edit). Tool result é a verdade, não a memória do modelo.
- Checagem de existência de símbolo/import/pacote antes de usar (anti-slopsquatting).
- Abstenção é first-class: “não sei / preciso checar” é mais barato que chutar.
- Gates como filtro: build/typecheck pegam API/import alucinado na hora.
Paridade de capacidade entre LLMs
O capability profile (ver Providers) parametriza decomposição, modo de tool-call, contexto por passo, self-consistency e retries. O resultado tende à paridade porque o harness fornece o que o modelo não tem — o piso da qualidade está no verificador, não no modelo.
Ciclo de vida de uma tarefa
- Mensagem → gateway → profile+workspace, com a identidade do agente e o capability profile do LLM ativo.
- Router seleciona skills (forçadas por contrato ou sob demanda) e injeta o taste se a tarefa é de UI.
- Harness entra em IN_PROGRESS; ação obrigatória a cada turno; watchdog e anti-loop ativos.
- task_complete → gates (hard) + crítico de taste (soft). Falhou? volta às violações.
- COMPLETE → resposta ao canal; pós-tarefa, o learning destila skill/regra e propõe evolução de persona/taste.