Council e a família de adapters de três camadas

A esta altura você já viu o loop entregar um trabalho a um único assistente, e já viu o fusion fazer a mesma pergunta a um pequeno painel de uma vez e ter um juiz a fundir as respostas. O Council é o próximo degrau acima. É uma diretoria permanente de modelos de IA — um grupo configurado, cada um com um papel nomeado, um peso de voto e um orçamento de custo — convocada para decidir as questões importantes demais para deixar a uma só voz.

O formato é deliberadamente parecido com um comitê de verdade. Cada membro lê a pergunta e a evidência, então registra um voto — GO, PIVOT ou NO-GO. Os votos são ponderados (um membro mais confiável conta mais), pontuados contra as dimensões que a diretoria valoriza, e dobrados por um sintetizador em um único veredito escrito: uma recomendação, o quanto a diretoria está confiante, o quanto houve concordância e — crucialmente — a dissidência que não venceu, anotada de propósito para que nunca se perca. A sessão inteira tenta de novo se um membro tropeça, para se estourar seu orçamento de tempo ou de dinheiro, e é registrada por completo para que um humano possa reproduzi-la depois.

Essa última parte é o ponto do Council, e o que o separa de um painel rápido: ele é feito para decisões em nível de doutrina — as regras e grandes apostas pelas quais um projeto se rege — e para atuar como um Validador peso-pesado de consenso quando estar confiantemente errado sairia muito caro. Uma pessoa convoca a diretoria para esses momentos. O fusion é a segunda opinião do dia a dia; o Council é aquele que você chama quando a resposta vira política.

Pense nisso como… um tribunal, não uma conversa de corredor. O fusion é perguntar de passagem a três colegas afiados e captar o sentimento da sala. O Council é uma bancada completa de juízes: cada um tem assento e peso, cada um escreve seu parecer, a maioria forma uma decisão, e os votos dissidentes ficam registrados nos autos oficiais — porque amanhã alguém vai precisar saber não só o que foi decidido, mas por quê, e quem discordou. Onde a analogia se dobra: aqui os juízes são modelos de IA, a "decisão" é um relatório JSON mais um memorando, e a audiência inteira pode ser reexecutada a partir de sua transcrição.

Aqui está a audiência inteira em uma só imagem. A mesma pergunta vai a cada membro de uma vez. Cada um devolve um voto. Os votos são ponderados e pontuados, um sintetizador os redige em um único veredito, e um verificador à parte checa as afirmações antes de qualquer coisa ser assinada. Repare que o verificador é um observador — ele nunca vota sobre o resultado que está checando.

O Council é mais poderoso que o fusion, mas poder tem um preço: mais modelos, mais rodadas, mais tempo, mais dinheiro. Então você não recorre a ele por padrão. A pergunta honesta é o quão caro seria estar errado. Se um erro custa alguns minutos para refazer, uma única verificação — ou um painel rápido de fusion — basta. Se um erro fixaria uma regra que o projeto inteiro segue, ou levaria uma longa execução autônoma pelo caminho errado, é aí que você convoca a diretoria.

Uma IA trabalhando dentro do harness faz exatamente essa escolha o tempo todo, e a regra que ela segue é justamente essa: escolha a ferramenta mais leve que sirva ao que está em jogo. Uma unidade rotineira recebe um assistente. Uma bifurcação arriscada ou genuinamente ambígua recebe o fusion — um painel cego cuja concordância é o sinal barato mais forte que você pode obter. Uma decisão em nível de doutrina, ou um veredito que precisa resistir a escrutínio depois, recebe o Council. Gastar o orçamento de uma diretoria numa pergunta trivial é tão erro quanto carimbar uma mudança de doutrina com uma única opinião.

Pense nisso como… decidir quão séria uma consulta médica precisa ser. Um arranhão é um curativo — resolva você mesmo. Algo incômodo rende uma palavra rápida com um par de médicos que por acaso estão de plantão. Mas um diagnóstico que muda a vida vai para uma conferência de caso completa onde cada especialista opina e a decisão é documentada. Você ajusta a cerimônia ao custo de errar — não ao quão interessante a pergunta parece.

Escolha uma situação, então pressione Próximo para percorrer a decisão que o harness faz. Cada losango é uma pergunta sim/não sobre o que está em jogo; siga por onde um "não" se desvia e observe em qual ferramenta o caminho aterrissa — um assistente, um painel de fusion, ou a diretoria Council completa.

Afaste-se do Council por um momento, porque há uma segunda ideia escondida sob ele — e sob o fusion também. Cada um desses sistemas precisa fazer a mesma coisa humilde: de fato chamar o programa de linha de comando de um modelo de IA e ler o que volta. Essa pecinha de encanamento se chama adapter. E neste conjunto não há um adapter, mas uma família deles, em três camadas, todos comandando as mesmíssimas CLIs de agentes.

Por que três? Porque três partes diferentes do conjunto precisam fazer a mesma chamada com quantidades diferentes de blindagem. A camada bash é a que o fusion usa — scripts de shell rápidos que rodam uma CLI e pegam sua saída. A camada mjs é a que o Council usa — a mesma chamada, agora embrulhada com retentativas, controle de custo e um log de auditoria, devolvendo um objeto de resultado organizado. A camada TypeScript vive numa base de código de produto e adiciona a blindagem mais pesada de todas — validação estrita nas bordas, a garantia de que nunca trava, um "disjuntor" que para de martelar um serviço que está falhando, e testes. Mesmo destino, três espessuras de cinto de segurança.

O que reter: todas discam o mesmo número. O jeito exato e comprovado de invocar cada CLI — quais flags, em que ordem — é compartilhado entre as três camadas. Então, quando você aprende como o harness chama o Kimi ou o Codex uma vez, você aprendeu em todos os lugares.

Pense nisso como… três veículos construídos sobre um único motor. Um kart (bash) é leve e veloz e quase não tem equipamento de segurança. Um carro de família (mjs) acrescenta cintos, airbags e uma luz de revisão. Um carro de corrida com telemetria completa (TypeScript) acrescenta uma gaiola de proteção, um botão de desligamento e uma equipe de boxes vigiando cada leitura. Trabalhos diferentes, proteções diferentes — mas o mesmo bloco do motor, e se você retoca o motor, retoca os três.

Eis por que a família importa, contado como um pequeno desastre. O jeito exato de chamar uma CLI é cheio de detalhes — o Kimi, por exemplo, recusa algumas combinações de flags e falha em silêncio com outras. Uma vez, aquela invocação exata derivou: alguém a ajustou no adapter do Council e, separadamente, na tabela do fusion, e os dois lentamente saíram de sincronia. A correção foi uma regra pela qual o conjunto inteiro agora se rege: há uma única fonte da verdade para as invocações headless comprovadas, e as três camadas devem permanecer em sincronia com ela.

Este é um exemplo perfeito e minúsculo da disciplina anti-suposição do loop aplicada ao encanamento. Você não lembra como chamar uma CLI e torce para que ainda funcione — flags derivam entre versões. Você reprova isso contra a CLI ao vivo, e quando muda uma camada você atualiza as outras duas no mesmo fôlego. Isso é trabalho para um agente: quando uma flag deriva, reprove-a na fronteira real, então propague a correção por bash, mjs e TypeScript para que nunca mais discordem.

Pense nisso como… uma receita pregada numa cozinha compartilhada. Três cozinheiros trabalham a partir dela. No dia em que um cozinheiro rabisca uma mudança na própria cópia, os pratos param de bater. A regra que salva a cozinha: há uma receita-mestra na parede, toda cópia é conferida contra ela, e você só a muda depois de ter de fato cozinhado a nova versão e ela ter funcionado.

Para tornar a camada do meio concreta, eis o formato de um adapter do Council. O detalhe que importa mesmo de relance: ele nunca apenas devolve texto. Ele devolve um Result — ou um sucesso carregando a resposta, seu custo e quanto tempo levou, ou uma falha que diz o que deu errado e se vale a pena tentar de novo. É essa estrutura que permite a uma diretoria acompanhar seu orçamento e escrever uma trilha de auditoria honesta.

export async function invoke({
  memberId, prompt, system = '', model = 'gpt-5.5',
  maxTokens = 128000, reasoningEffort = 'high',
  runId = null, timeoutMs = 300_000,
} = {}) {
  if (!prompt) return { success: false, error: 'prompt is required', retryable: false };

  if (process.env.COUNCIL_CODEX_USE_SUBPROCESS === '1') {       // caminho de CLI opcional
    const bin = CODEX_BIN_CANDIDATES.find(p => existsSync(p));
    if (bin) {
      const r = await withRetry(() => invokeSubprocess({ bin, prompt, system, model, timeoutMs }),
        { adapter: 'codex-cli:exec', model, runId, maxAttempts: 2 });
      if (r.success) return r;
    }
  }
  // padrão: roteia via cliproxyapi, com retry/backoff
  return withRetry(() => invokeProxy({ prompt, system, model, maxTokens, reasoningEffort, timeoutMs }),
    { adapter: 'codex-cli', model, runId, maxAttempts: 3 });
}

Você já conheceu as duas ideias desta lição — a diretoria e a família de adapters — então aqui está como os três tipos de participante as usam, reunidos num só lugar. A divisão é a mesma que percorre o harness inteiro.

Um humano convoca uma diretoria para as maiores decisões — uma mudança de doutrina, uma aposta com que o projeto vai conviver — e então recua para a observabilidade: lê o veredito, a confiança e a dissidência preservada na trilha de auditoria, mas não participa da deliberação. Uma LLM trabalhando no loop escolhe o instrumento certo para o que está em jogo: um assistente para trabalho rotineiro, o fusion para uma bifurcação arriscada ou ambígua, o Council quando a resposta vira política ou precisa resistir a escrutínio depois. E um agente que mantém o conjunto guarda o encanamento: quando uma flag de CLI deriva, ele reprova a invocação na fronteira real e atualiza as três camadas — bash, mjs e TypeScript — para que nunca discordem.

Pense nisso como… a governança de uma empresa. Os membros do conselho (humanos) decidem as grandes votações e leem a ata depois. O gerente de plantão (a LLM) decide, hora a hora, quais decisões precisam de uma conversa rápida e quais precisam do conselho completo. E a equipe de manutenção (o agente) mantém a fiação do prédio dentro das normas — reconferindo após cada mudança para que nada falhe no meio da reunião.

Três perguntas rápidas. Escolha uma resposta para ver se ela acerta — e por quê.