Escrever um provedor

Um provedor ensina o AutoDev a conduzir mais uma CLI de agente. É um arquivo, gerado a partir de TypeScript, que transforma um prompt nos argumentos da CLI e a saída da CLI num resultado. Este guia segue o provedor de modelo da primeira linha até o pull request.

O que um provedor faz #

O AutoDev nunca roda um modelo próprio. Ele roda as CLIs de agente que você já usa, e um provedor é a parte que conhece uma CLI: quais argumentos passar para um prompt, como retomar uma sessão e como ler o que a CLI imprime. Entra um argv, sai um resultado.

Um provedor não tem lógica de sistema operacional. Ele não procura o programa, não abre shell e não trata caminhos do Windows: o runner do AutoDev faz isso, do mesmo jeito para todo provedor.

O ponto de partida é o modelo, providers/template-codex, um provedor real para o codex da OpenAI. Copie a pasta dele e renomeie:

providers/<your-name>/
  src/index.ts     the source
  captures/        real calls to your CLI, recorded below
  test/            your own tests
  meta.json        description, author, homepage
  provider.mjs     the built file, the only file anyone installs

Instale o kit no repositório: npm i -D @stefanolabs/autodev-provider-kit.

O que ele recebe, e o que não pode fazer #

O create(cfg, host) do seu provedor recebe em host tudo o que ele usa:

• host.runner(binary, args, onLine?, input?) inicia a CLI. input, quando você passa, é escrito no stdin e o pipe é fechado, então a CLI nunca fica esperando um stdin aberto.
• host.binary é o caminho resolvido da CLI nesta máquina.
• host.pin é o modelo e o esforço que a pessoa escolheu para este participante. Repasse como vierem: são texto livre, e uma lista de modelos fica errada na manhã em que sai um novo.
• host.mcp é o servidor MCP do AutoDev numa chamada de participante, e null fora disso. É por ele que o agente chega à thread compartilhada. Adicione-o ao lado dos servidores da própria pessoa, nunca com uma flag que substitui a configuração dela.
• host.platform é a plataforma da máquina, se as flags da sua CLI mudam com ela.

Um arquivo de provedor não pode fazer mais nada, por projeto:

• Sem imports e sem rede. Ele importa só @stefanolabs/autodev-provider-kit/provider, que o build embute. Não tem fetch, nem process, nem require. O AutoDev verifica o arquivo antes de carregar e depois o roda num sandbox onde nada disso existe.
• Só a própria CLI. O runner inicia o programa que o provedor declara em binary, e nenhum outro.
• Limites voltam no resultado. Quando a CLI avisa de um limite de uso, devolva-o no rateLimit do execute, com a hora de voltar. O detectRateLimit não é chamado num provedor em sandbox, então pode devolver null.

A CLI que seu provedor conduz ainda pode fazer tudo o que essa CLI faz. Por isso um revisor lê os argumentos que todo provedor passa.

Declare só o que uma gravação mostra #

capabilities lista o que sua CLI sabe fazer: eventos ao vivo, retomar sessão, informar tokens, um modo só leitura e assim por diante. Cada um é false até uma gravação mostrar a CLI fazendo aquilo. false quer dizer "não verificado", nunca "ausente".

O contrato confere cada declaração contra suas gravações. Uma capacidade declarada que as gravações não mostram é uma cláusula reprovada, então comece com tudo false e ligue só o que você gravou.

Grave sua CLI #

O contrato roda sobre chamadas reais, então primeiro registre seu provedor localmente e grave:

npx autodev-provider-kit build providers/<name>/src/index.ts -o providers/<name>/provider.mjs
autodev providers add providers/<name>/provider.mjs
autodev providers capture <name> hello --out providers/<name>/captures
autodev providers capture <name> resume --out providers/<name>/captures
autodev providers capture <name> tool-notice --out providers/<name>/captures

São quatro cenários:

• hello: uma chamada simples. Prova o id da sessão, o código de saída e a saída.
• resume: uma segunda chamada na sessão que o hello abriu.
• tool-notice: uma ferramenta imprime algo parecido com um limite. Prova que você só lê limites onde a CLI os informa, nunca na saída de ferramentas.
• limit: um limite de uso real. Não dá para provocar um, então guarde a saída da próxima vez que acontecer e transforme-a em gravação com --from-log. Pule este se o seu provedor não declara detecção de limite.

Gerar, verificar e um turno real #

npx autodev-provider-kit build providers/<name>/src/index.ts -o providers/<name>/provider.mjs
npx autodev-provider-kit check providers/<name>/provider.mjs --captures providers/<name>/captures

O check roda o que o AutoDev roda antes de registrar um provedor: a verificação do arquivo, o sandbox e as doze cláusulas do contrato sobre suas gravações. Cada problema aponta uma linha ou uma cláusula.

Depois escreva seus próprios testes em test/. Eles são obrigatórios e precisam cobrir pelo menos 80% das linhas de src/: os argumentos que você monta, a saída que você lê, os caminhos de falha. Os testes do modelo mostram o padrão, um host cujo runner anota os argumentos em vez de iniciar a CLI:

npx vitest run providers/<name>/test --coverage.enabled --coverage.provider=v8 --coverage.include="providers/<name>/src/**" --coverage.thresholds.lines=80

Por último, rode um turno real: adicione um participante no seu provedor pelo painel do AutoDev, comece uma execução e guarde a linha que ele publicar na thread. As gravações provam a leitura; um turno prova que as ferramentas da thread chegam ao agente.

Envie #

Rode npm run index para regenerar o index.json e abra um pull request em stefanolabs/autodev-providers. O checklist pede:

• o contrato verde sobre gravações feitas com a CLI real;
• um turno real na thread, como captura de tela ou a linha do thread.jsonl;
• seus testes passando com 80% de cobertura de linhas de src/;
• o provider.mjs gerado a partir de src/, nunca editado à mão (o CI gera de novo e compara byte a byte);
• o meta.json preenchido e o index.json regenerado.

Um revisor lê os argumentos que seu provedor monta, por inteiro. Depois do merge, qualquer pessoa pode instalá-lo com autodev providers add <nome> ou pela seção Comunidade do painel.