# MISIÓN: Implementar una capa de capacidades resiliente en AgentSquad Eres un ingeniero senior trabajando en **AgentSquad**, una plataforma de orquestación multi-agente para negocios (squads de agentes IA que ejecutan trabajo real: research de leads/mercado, mover datos, publicar en canales de clientes, etc.). Los agentes dependen de **integraciones externas frágiles** (scrapers, APIs sociales, CRMs, canales de mensajería, providers de LLM) — y esa fragilidad es el riesgo operacional #1: una integración cambia o se cae y te enteras por el cliente. Tu tarea: implementar una **capa de capacidades** inspirada en el patrón de un framework de referencia (Agent Reach). NO copies su código ni su catálogo de plataformas — replica el PATRÓN ARQUITECTÓNICO en la arquitectura real de AgentSquad. La idea central: **toda capacidad externa es una lista ordenada de backends con health real y auto-diagnóstico, y su cimiento es siempre un backend CONFIABLE y bajo tu control — nunca algo prestado que puede caer sin aviso.** ## PRINCIPIO RECTOR (leer antes que nada) Ninguna capacidad de la que dependa un cliente puede FUNCIONAR gracias a algo temporal. "Temporal / prestado" = free tier de un tercero sin contrato, endpoint web no-oficial, scraping, reuso de sesión de navegador, cookies. Todo eso funciona hoy y se rompe mañana sin que vos controles el cuándo — sirve como optimización oportunista, JAMÁS como el backend del que cuelga un entregable. El sistema debe seguir funcionando aunque TODOS los backends prestados caigan a la vez. Si una capacidad no tiene al menos un backend confiable, no está lista para producción. ## Reglas duras (no negociables) - Comunicación en español, directo. - NUNCA fabricar stats/estados/credenciales. Un backend está "ok" solo si se PROBÓ ejecutándolo, nunca porque "la config existe". - Verificar antes de afirmar estado (no asumas rutas ni comportamiento del repo). - No imprimir valores de credenciales, solo nombres de variables. Credenciales y cookies se guardan solo local, con permisos 600. - Todo cambio va con tests. Los tests existentes deben seguir en verde. - Sistemas externos = append-only, nunca destructivo sin gate. ## FASE 0 — Reconocimiento (obligatoria, primero) No conoces el repo. Antes de escribir código, descubre y documenta en 1 página: 1. Dónde y cómo se definen hoy las integraciones externas de AgentSquad (scrapers, APIs, canales, providers). ¿Están hardcodeadas? ¿Hay ya algún multi-provider (p.ej. selección de LLM)? 2. El punto único donde una capacidad se invoca (el choke point de ejecución). 3. Cómo se detecta hoy que una integración está caída (¿hay health checks? ¿son "existe la key" o "ejecuta de verdad"?). 4. Dónde está el runner de tests y el CI. Si algo es genuinamente ambiguo y bloquea el diseño, pregunta. Si no, procede. ## FASE 0.5 — Plan Usa el skill `superpowers:writing-plans`. Agrupa las tasks en **waves** con dependencias, y CADA task DEBE tener un bloque **Done when** con 2-5 criterios verificables por comando (no subjetivos). Orden recomendado: A → B → C → D. --- ## A — Capacidad = lista ordenada de backends (primary + fallbacks) **Objetivo:** que cambiar de proveedor de una capacidad sea reordenar una lista, nunca reescribir código, y que el agente no se entere cuando un backend cae y otro toma el relevo. **Mecanismo a replicar:** 1. Una clase base `Capability` (contrato claro, tipo ABC) que cada integración implementa. Contrato mínimo: - `name`, `description`, `tier` (0=gratis-sin-config, 1=key/login gratis, 2=setup mayor). - `backends: List[str]` — lista ORDENADA: `backends[0]` es el preferido, el resto son fallbacks. - `active_backend: Optional[str]` — el backend que está sirviendo AHORA (None si nada usable). Lo fija `check()`. - `check(config) -> (status, message)` — prueba los candidatos EN ORDEN, el primero completamente usable gana. - método de ejecución de la capacidad (o delegación al choke point). 2. `ordered_backends(config)` — permite un override por config (`_backend` / env `_BACKEND`) que mueve el backend nombrado al frente; un override desconocido se ignora (nunca oculta backends que sí funcionan). 3. Cuando un backend cae pero un fallback tiene éxito, el mensaje del canal debe ARRASTRAR la receta de reparación del backend roto (no silenciarla): el fallback te salva hoy, pero quieres saber que el preferido está roto. **Done when:** - [ ] Test: con `backends = [A, B]` y A caído (mockeado), la capacidad selecciona B y `active_backend == "B"`. - [ ] Test: override por config mueve el backend nombrado al frente; override basura se ignora. - [ ] Añadir un backend nuevo a una capacidad = editar su lista, sin tocar el choke point ni otras capacidades. - [ ] Sin regresiones: suite completa en verde. --- ## B — Probe real: "¿ejecuta ahora?", no "¿está configurado?" **Objetivo:** distinguir los modos de fallo que un check ingenuo confunde. **Mecanismo a replicar:** 1. Una función `probe()` que EJECUTA un comando/llamada ligera y side-effect-free (version/status/ping) y clasifica el resultado en cuatro estados: - `missing` — no está instalado / no hay credencial. - `broken` — existe pero no ejecuta. Caso real: un shim de CLI en el PATH cuyo intérprete de venv murió tras un upgrade (exit codes 126/127, o `FileNotFoundError` al exec apuntando al propio shim). "La key existe" pero el cliente HTTP falla al inicializar entra aquí también. - `timeout` — corre pero no responde a tiempo. - `error` — corre pero devuelve mal. 2. Cada estado que no sea `ok` trae un `hint`: la **receta concreta de reparación** (la línea de comando o el paso exacto), no solo "error". 3. Reintentos solo para fallos transitorios (`timeout`/`error`); `missing`/ `broken` no se curan reintentando, así que no se reintentan. 4. Regla dura: `check()` NUNCA marca un backend `ok` por presencia (existe el binario / existe la key). Solo tras un probe ejecutado con éxito. **Done when:** - [ ] Test: cada uno de los 4 estados se produce y se clasifica bien (mockea un binario/credencial en cada modo de fallo). - [ ] Test: un backend "configurado pero no ejecutable" reporta `broken` con su hint, NO `ok`. - [ ] Reintento solo dispara en `timeout`/`error`, nunca en `missing`/`broken`. - [ ] Sin regresiones: suite completa en verde. --- ## C — `doctor`: auto-diagnóstico de capacidades **Objetivo:** un comando (y/o endpoint) que responde "¿qué funciona ahora, con qué backend, qué está roto y cómo se arregla?" — a nivel capacidad, no infra. **Mecanismo a replicar:** 1. `doctor` recorre todas las capacidades, corre su `check()`, y reporta por cada una: status, `active_backend` (cuando hay más de un backend), mensaje y hint de reparación. 2. **Aislamiento de fallos:** una capacidad que lanza excepción degrada a `status="error"` para ESA capacidad — nunca tumba el reporte completo. Cuidar que un `active_backend` viejo de un check previo no se filtre a un resultado errado. 3. Salida legible (agrupada por tier: gratis / necesita login / setup) y una variante `--json` para consumo por la propia plataforma / dashboards / alertas. 4. Conecta `doctor` al monitoring proactivo existente de AgentSquad: si una capacidad crítica cae a su último fallback o a `error`, que dispare alerta. **Done when:** - [ ] `doctor` lista todas las capacidades con status + backend activo + hint. - [ ] Test: una capacidad que lanza excepción sale como `error` y el resto del reporte se genera igual. - [ ] `doctor --json` produce JSON válido consumible por otro proceso. - [ ] Sin regresiones: suite completa en verde. --- ## D — Política de selección: confiabilidad y control primero **Objetivo:** que el sistema FUNCIONE sobre backends que no se te caen sin aviso. El ahorro de costo es bienvenido, pero nunca a costa de que un entregable de cliente cuelgue de algo temporal. (Requisito explícito del dueño del producto: "no basarse en algo temporal para que esto funcione".) **Clasificá cada backend en una de dos categorías:** - **CONFIABLE** — lo controlás o tenés contrato: API oficial con SLA, herramienta open-source auto-hosteada en TU infra (p.ej. yt-dlp / feedparser corriendo en tu servidor, no un servicio ajeno), tu propia base de datos/servicio. Su disponibilidad depende de vos o de un proveedor con el que tenés relación. - **PRESTADO / BEST-EFFORT** — free tier de un tercero sin contrato, endpoint web no-oficial, scraping, reuso de sesión de navegador, cookies. Funciona hoy, sin garantía de mañana, y no controlás el cuándo se rompe. **Orden de preferencia al construir la lista de backends de cada capacidad:** 1. **Backend CONFIABLE como preferido y como cimiento.** Toda capacidad que un cliente use DEBE tener al menos un backend CONFIABLE en su lista, y ese es el que sirve el trabajo de cliente. 2. **Backend PRESTADO solo como optimización opcional** (ahorro de costo cuando está disponible), nunca como único backend ni como preferido de una capacidad crítica. Marcado `best-effort` + `opt-in`. 3. **Regla dura de degradación:** si todos los backends PRESTADOS de una capacidad caen, la capacidad debe seguir operativa vía su backend CONFIABLE. Un test lo demuestra. Si al quitar los prestados la capacidad queda sin backend, esa capacidad NO está lista para producción — `doctor` debe marcarla como tal. 4. **Gate de riesgo:** los backends de scraping/sesión (siempre PRESTADOS) llevan warning explícito de **ToS + riesgo de baneo**; para trabajo de cliente, usar SIEMPRE cuentas/credenciales dedicadas, nunca la principal del cliente. No se activan por default silencioso. 5. `doctor` etiqueta cada backend activo como **CONFIABLE** o **PRESTADO**, para que quede visible de qué está colgando cada capacidad ahora mismo. **Done when:** - [ ] Test: al ordenar backends, un candidato CONFIABLE precede a cualquier PRESTADO. - [ ] Test: quitando todos los backends PRESTADOS (mockeados como caídos), toda capacidad marcada "producción" sigue resolviendo vía uno CONFIABLE. - [ ] Test: una capacidad cuyo único backend es PRESTADO se reporta en `doctor` como NO lista para producción. - [ ] Test: un backend `opt-in` (scraping/sesión) NO se selecciona sin la opción explícita activada; su warning de ToS/baneo aparece asociado. - [ ] Sin regresiones: suite completa en verde. --- ## Entrega final 1. El plan (waves + Done-when) aprobado antes de implementar. 2. La capa implementada (A–D) con tests en verde y corriendo en CI. 3. Un resumen: qué integraciones migraste al patrón de backends, cuáles quedaron pendientes, qué reporta `doctor`, y — por cada capacidad — cuál es su backend CONFIABLE de base y qué backends PRESTADOS tiene como optimización opcional. Marca explícitamente cualquier capacidad que hoy dependa de algo temporal. 4. Reporta honestamente: si algo quedó parcial, dilo con el motivo.