A precedência em quatro regras

// precedência de dispatch (ilustrativa)
function resolveTarget(opts: {
  runtime?: RuntimeKind;
  provider?: string;
  installed: RuntimeKind[];       // binários achados no PATH
  preferCli: boolean;             // padrão: true
  scoreApis: () => DispatchTarget;
}): DispatchTarget {
  if (opts.runtime && opts.provider) throw new Error("use --runtime OU --provider");
  if (opts.runtime) return { type: "runtime", runtime: opts.runtime };
  if (opts.provider) return { type: "provider", provider: opts.provider, model: "default" };
  if (opts.preferCli && opts.installed.length > 0) {
    return { type: "runtime", runtime: opts.installed[0] };
  }
  return opts.scoreApis(); // reserva: pontuação e prontidão das APIs
}

1. --runtime <nome> escolhe só aquele CLI. Binário ausente ou login inválido gera um erro acionável do runtime. Nunca cai para a API.
2. --provider <nome> escolhe só aquela API. Pula a descoberta de CLIs.
3. Sem flag, o modo automático prefere um CLI elegível quando a preferência CLI-first do dispatch está ativa.
4. Se essa preferência estiver desligada ou nenhum runtime elegível for selecionado, o dispatch considera providers HTTP prontos e aplica a pontuação.

As flags --runtime e --provider são mutuamente exclusivas. Passar as duas é erro, de propósito.

Detecção local, sem sondar login

Uma decisão pequena que evitou dor: no modo automático, o lemon-code só verifica se o binário existe no PATH. Ele não tenta abrir sessão nem testar autenticação remota a cada turno. Isso deixa o dispatch rápido e sem efeito colateral.

Para diagnosticar login, existe um comando explícito (lc doctor). Separar "descobrir" de "sondar" mantém o caminho quente barato e o diagnóstico completo disponível quando você precisa.

O que fica registrado

Cada decisão vai para o histórico de dispatch em SQLite com o tipo de alvo (runtime:codex, por exemplo) e o motivo. O que não vai: variáveis de ambiente, chaves, headers, cookies ou saída ilimitada do CLI. A saída do subprocesso é truncada e higienizada antes de qualquer log.

O que deu errado no caminho

• Mesma regra em todo lugar. A primeira versão aplicava CLI-first só ao agente principal. Handoffs entre perfis e o orquestrador de modelos ainda criavam provider HTTP. A ADR passou a exigir a mesma semântica em todos os caminhos.
• Contrato de cada CLI. Os argumentos de linha de comando mudam entre versões. A regra é derivar os argumentos do --help instalado e cobrir cada CLI com um teste de contrato antes de habilitar.
• Mensagem de erro certa. Um --runtime codex sem login precisa dizer "faça login no Codex", e não "configure OPENAI_API_KEY". Parece detalhe; é o que faz a pessoa confiar na regra.

Como saber se a sua regra funciona

Os critérios de aceite da ADR servem como checklist para qualquer orquestrador:

• Modo automático prefere qualquer CLI suportado a qualquer API, mesmo sem chave configurada.
• --runtime X executa só o CLI X.
• --provider Y executa só a API Y.
• As duas flags juntas geram erro.
• Um CLI explícito sem login gera erro de login, nunca mensagem de chave de API.
• Um teste de integração observa uma chamada ao runtime e zero chamadas de completion à API no mesmo turno.

O último item é o que eu recomendo copiar primeiro. Ele pega a classe inteira de bugs de fallback silencioso.

Conclusão

Usar primeiro os CLIs elegíveis parece uma simplificação operacional. O ganho maior foi de clareza: cada turno tem um alvo, e esse alvo não muda sem você saber. O dispatch considera providers HTTP quando a preferência CLI-first está desligada ou nenhum runtime elegível aparece; --provider continua disponível para escolha explícita.

No próximo post, sexta, mudo de camada: como o lemon-code desenha a interface do terminal com React, via Ink, rodando sob Bun.

Se você está desenhando um orquestrador de agentes e quer separar destino, autenticação e roteamento desde o começo, é um dos temas em que ajudo times na LEMON.DEV.

Referências

• Claude Code, documentação oficial
• Codex CLI, repositório oficial
• Gemini CLI, repositório oficial

Leituras relacionadas

• Por que construí meu próprio agente de código
• Sandbox para agentes que executam código