Escribir un proveedor

Un proveedor le enseña a AutoDev a manejar una CLI de agente más. Es un archivo, generado a partir de TypeScript, que convierte un prompt en los argumentos de la CLI y la salida de la CLI en un resultado. Esta guía sigue al proveedor de plantilla desde la primera línea hasta el pull request.

Qué hace un proveedor #

AutoDev nunca ejecuta un modelo propio. Ejecuta las CLI de agente que ya usas, y un proveedor es la parte que conoce una CLI: qué argumentos pasar para un prompt, cómo retomar una sesión y cómo leer lo que la CLI imprime. Entra un argv, sale un resultado.

Un proveedor no tiene lógica de sistema operativo. No busca el programa, no abre una shell ni maneja rutas de Windows: eso lo hace el runner de AutoDev, igual para todo proveedor.

El punto de partida es la plantilla, providers/template-codex, un proveedor real para codex de OpenAI. Copia su carpeta y cámbiale el nombre:

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

Instala el kit en el repositorio: npm i -D @stefanolabs/autodev-provider-kit.

Qué recibe, y qué no puede hacer #

El create(cfg, host) de tu proveedor recibe en host todo lo que usa:

• host.runner(binary, args, onLine?, input?) inicia la CLI. input, cuando lo pasas, se escribe en stdin y el pipe se cierra, así la CLI nunca espera un stdin abierto.
• host.binary es la ruta resuelta de la CLI en esta máquina.
• host.pin es el modelo y el esfuerzo que la persona eligió para este participante. Pásalos tal cual: son texto libre, y una lista de modelos queda mal la mañana en que sale uno nuevo.
• host.mcp es el servidor MCP de AutoDev en una llamada de participante, y null en otro caso. Es por donde el agente llega al hilo compartido. Agrégalo junto a los servidores propios de la persona, nunca con un flag que reemplace su configuración.
• host.platform es la plataforma de la máquina, si los flags de tu CLI cambian con ella.

Un archivo de proveedor no puede hacer nada más, por diseño:

• Sin imports y sin red. Solo importa @stefanolabs/autodev-provider-kit/provider, que el build incluye. No tiene fetch, ni process, ni require. AutoDev revisa el archivo antes de cargarlo y luego lo ejecuta en un sandbox donde nada de eso existe.
• Solo su propia CLI. El runner inicia el programa que el proveedor declara en binary, y ningún otro.
• Los límites vuelven en el resultado. Cuando la CLI avisa de un límite de uso, devuélvelo en el rateLimit de execute, con la hora de volver. detectRateLimit no se llama en un proveedor en sandbox, así que puede devolver null.

La CLI que maneja tu proveedor todavía puede hacer todo lo que esa CLI hace. Por eso un revisor lee los argumentos que pasa cada proveedor.

Declara solo lo que muestra una grabación #

capabilities lista lo que tu CLI sabe hacer: eventos en vivo, retomar sesión, informar tokens, un modo de solo lectura, etc. Cada una es false hasta que una grabación muestre a la CLI haciéndolo. false significa "no verificado", nunca "ausente".

El contrato compara cada declaración con tus grabaciones. Una capacidad declarada que tus grabaciones no muestran es una cláusula reprobada, así que empieza con todo en false y activa solo lo que grabaste.

Graba tu CLI #

El contrato corre sobre llamadas reales, así que primero registra tu proveedor localmente y grábalo:

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

Hay cuatro escenarios:

• hello: una llamada simple. Prueba el id de sesión, el código de salida y la salida.
• resume: una segunda llamada en la sesión que abrió hello.
• tool-notice: una herramienta imprime algo que parece un límite. Prueba que solo lees límites donde la CLI los informa, nunca en la salida de herramientas.
• limit: un límite de uso real. No se puede provocar, así que guarda la salida la próxima vez que pase y conviértela en grabación con --from-log. Sáltalo si tu proveedor no declara detección de límites.

Generar, verificar y un 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

check ejecuta lo mismo que AutoDev antes de registrar un proveedor: la revisión del archivo, el sandbox y las doce cláusulas del contrato sobre tus grabaciones. Cada hallazgo indica una línea o una cláusula.

Después escribe tus propias pruebas en test/. Son obligatorias y deben cubrir al menos el 80% de las líneas de src/: los argumentos que armas, la salida que lees, los caminos de error. Las pruebas de la plantilla muestran el patrón, un host cuyo runner anota los argumentos en lugar de iniciar la CLI:

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

Por último, haz un turno real: agrega un participante con tu proveedor en el panel de AutoDev, inicia una ejecución y guarda la línea que publique en el hilo. Las grabaciones prueban la lectura; un turno prueba que las herramientas del hilo llegan al agente.

Envíalo #

Ejecuta npm run index para regenerar index.json y abre un pull request en stefanolabs/autodev-providers. La lista de verificación pide:

• el contrato en verde sobre grabaciones hechas con la CLI real;
• un turno real en el hilo, como captura de pantalla o la línea de thread.jsonl;
• tus pruebas pasando con 80% de cobertura de líneas de src/;
• provider.mjs generado desde src/, nunca editado a mano (CI lo vuelve a generar y compara byte a byte);
• meta.json completo e index.json regenerado.

Un revisor lee completos los argumentos que arma tu proveedor. Después del merge, cualquiera puede instalarlo con autodev providers add <nombre> o desde la sección Comunidad del panel.