# YoRobot — instrucciones para agentes de código

Este proyecto usa YoRobot (https://yorobot.ai), una plataforma de agentes digitales gobernados. Cómo trabajar con ella:

## Conexión

- Servidor MCP: `https://yorobot.ai/api/mcp` (Streamable HTTP). Autenticación por OAuth 2.1 (el cliente la descubre solo en `/.well-known/oauth-protected-resource`) o `Authorization: Bearer <token>`; si hay token, vive en la variable `YOROBOT_MCP_TOKEN`, no en el código ni en este archivo.
- Documentación como MCP público (sin login): `https://yorobot.ai/api/mcp/docs`.
- Antes que nada, llamá `quien_soy`: confirma con qué cuenta y en qué organización quedaste conectado, tu rol, hasta dónde llegás y si el token vence o se renueva solo (OAuth).
- Si el MCP no está conectado, decíselo a la persona; no intentes reproducir las operaciones por HTTP a mano.

## Dónde leer

- `https://yorobot.ai/llms.txt` enumera la documentación. Cada página está en Markdown con `.md`.
- `https://yorobot.ai/docs/mcp.md` es la referencia de las 218 herramientas, generada del código.
- `https://yorobot.ai/openapi.json` es el contrato de la API REST v1, para integraciones desde sistemas: cada ruta con el esquema de su respuesta.
- Para mostrar los agentes en una app (una tarjeta por agente, como Che Tienda): `GET /api/v1/agentes` y `GET /api/v1/agentes/{id}` traen la última actividad, el gasto del mes contra su tope, si frena (`bloqueado`) y lo que espera la firma con `aprobar_en`; `GET /api/v1/aprobaciones?agente=<id>` y `GET /api/v1/membresia` completan la tarjeta. El tope del mes de un agente se fija con `PUT /api/v1/agentes/{id}/tope` (alcance `topes` o `escritura`) o, por MCP, con `fijar_tope_de_agente`; la membresía por MCP es `ver_membresia`.

## Reglas

- **El ambiente por defecto es `dev`.** No pases `ambiente: 'prod'` ni `hasta: 'prod'` sin que la persona lo pida en esa conversación.
- **No podés aprobar**, y no es un hueco: la aprobación es de una persona en el portal. Si algo espera firma, avisá y frená; si la persona quiere decidir ya, `aprobar` le da un enlace de un solo uso para que lo haga ella.
- **Usá `clave`** en `crear_agente` y `crear_rutina` para que repetir sea idempotente.
- **Las instrucciones de un agente van en segunda persona**, dirigidas al agente, y `como_se_verifica` tiene que nombrar una herramienta de lectura de su caja o una entidad de Datos.
- **Nunca escribas un secreto en un argumento** salvo en `cargar_credencial`, que lo sella en la bóveda. Si un token quedó en un log, llamá `revocar_mi_token`.
- **Un error trae `codigo` y `que_hacer`.** `no_existe` → listá y volvé con un id real. `sin_alcance` → hace falta otro token, no reintentes. `requiere_persona` → esto lo decide alguien en la pantalla. `en_curso` → esperá y volvé a preguntar.
- **Probá antes de promover:** `cargar_caso` + `ensayar_agente`, y `probar_agente` devuelve la traza.

## Flujo típico

1. `quien_soy` → 2. `listar_herramientas` y `listar_agentes` → 3. `crear_agente` o `editar_agente` (con `clave`) → 4. `probar_agente` en `dev` (`en_seco: true` la primera vez) y corregir con `editar_agente` hasta que haga lo esperado → 5. educarlo: reglas y lecciones con `proponer_memoria`, documentos del negocio con `cargar_documento` → 6. `cargar_caso` y `ensayar_agente` → 7. la persona promueve o pide `promover_agente`.

Las respuestas de crear, editar y educar traen `siguiente`: la llamada que sigue, ya armada. Una memoria propuesta o un documento cargado no llegan a ninguna tarea hasta que la persona los activa; `siguiente` dice cómo.

## Aplicaciones conectadas

Una aplicación conocida se conecta a una organización **sin que nadie copie un token**: YoRobot le entrega uno nuevo de servidor a servidor, firmado, y la app le devuelve su propia credencial por el mismo camino. Ninguna credencial pasa por el chat ni por la pantalla de nadie. Desde la IA es `conectar_aplicacion` (MCP); desde la app, un botón que lleva a `https://yorobot.ai/conectar/<clave>`. La carga manual —crear un token en Ajustes → Accesos y copiarlo una vez— queda como alternativa en Ajustes → Aplicaciones.

### Registro

Lo carga YoRobot, no el usuario: el destino de un token es siempre una dirección revisada.

| Clave | Nombre | Entrega | Página de vuelta | Alcances del token |
|---|---|---|---|---|
| `che-tienda` | Che Tienda | `https://www.chetienda.com/api/yorobot/vinculo` | `https://www.chetienda.com/estudio` | `lectura`, `topes` |

### Firma

- Ed25519, sin secretos compartidos. La llave pública está en `https://yorobot.ai/.well-known/jwks.json`: `{ "keys": [{ "kty": "OKP", "crv": "Ed25519", "x": "…", "kid": "…", "use": "sig" }] }`. Mientras no esté configurada, contesta `503`.
- Cada entrega trae `YoRobot-Firma: t=<unix en segundos>,kid=<kid>,v1=<firma>`. La firma es Ed25519 sobre los bytes de `"<t>.<cuerpo crudo>"`, en base64url sin relleno. El `kid` es el thumbprint RFC 7638 de la llave.
- La app busca la llave por `kid`, verifica sobre el cuerpo crudo (antes de parsearlo) y rechaza un `t` de más de 5 minutos.
- Para rotar, la llave nueva se publica en el JWKS **antes** de firmar con ella: un `kid` desconocido es motivo para releer el JWKS.

### Entrega (YoRobot → app)

`POST <entrega>`, `Content-Type: application/json`, 10 s de tiempo máximo y sin seguir redirecciones:

```json
{
  "evento": "vinculo.creado",
  "vinculo_id": "uuid, nuevo en cada intento",
  "organizacion": { "id": "uuid", "nombre": "…" },
  "cuenta": { "email": "persona@dominio", "email_verificado": true },
  "tienda": "lo que dijo la persona, o null",
  "estado": "el estado opaco del botón, tal cual, o null",
  "token": "el token de API nuevo",
  "alcances": ["lectura", "topes"]
}
```

- El token es nuevo y exclusivo del vínculo, de la persona que conectó (ve lo mismo que ella), no vence, se puede revocar y figura en Accesos como «<Nombre> (aplicación conectada)».
- Si la app no contesta 200, el token se revoca y el vínculo no queda. El cuerpo de la entrega no se guarda en ningún registro: lleva el token.
- No se reintenta con el mismo `vinculo_id`: un reintento es un vínculo nuevo, con otro token.
- Un vínculo nuevo de la misma organización y aplicación reemplaza al anterior: su token se revoca y las conexiones pasan al nuevo, con la credencial nueva.

### Respuestas de la app

A la IA y a la persona les llega sólo `mensaje`. Nunca el token ni la credencial.

| Código | Cuerpo | Qué hace YoRobot |
|---|---|---|
| `200` | `{ "estado": "conectada", "tienda": { "id", "nombre" }, "mensaje", "credencial": { "tipo": "openapi", "openapi_url", "cabecera": "Authorization", "valor": "Bearer …" } }` | Sella `credencial.valor` en la bóveda y declara como conexiones activas, de riesgo `read`, todas las lecturas (GET) del documento. El documento tiene que estar en el host de la app, y sus servidores también; tiene que declarar cómo viaja la credencial (`securitySchemes`, p. ej. `http bearer`). Sin `credencial`, el vínculo queda sin conexiones. |
| `409` | `{ "estado": "varias_tiendas", "tiendas": [...], "mensaje" }` | Revoca el token. La IA pregunta cuál y reintenta con `tienda` (vínculo nuevo). |
| `409` | `{ "estado": "repetido", "mensaje" }` | Revoca el token. |
| `404` | `{ "estado": "sin_tienda", "mensaje", "conectar_en" }` | Revoca el token. |
| `403` | `{ "estado": "correo_sin_verificar", "mensaje" }` | Revoca el token. |
| `400` | `{ "estado": "estado_vencido", "mensaje" }` | Revoca el token; el botón vuelve con `motivo=estado_vencido`. |
| `400` | `{ "estado": "entrega_invalida", "mensaje" }` | Revoca el token. |
| `401` | `{ "estado": "firma_invalida", "mensaje" }` | Revoca el token. |
| `503` | `{ "estado": "jwks_no_disponible", "mensaje" }` | Revoca el token; se puede reintentar como vínculo nuevo. |
| otro, o sin respuesta | — | Revoca el token (`estado`: el de la respuesta, `http_<código>`, `redireccion` o `sin_respuesta`). |

### Conexión con un botón

`GET https://yorobot.ai/conectar/<clave>?estado=<opaco>&volver=<url>`

1. `volver` tiene que ser la página de vuelta registrada; si no, se rechaza ahí mismo.
2. Sin sesión, la persona pasa por el login y vuelve. Con varias organizaciones elige una (sólo donde es técnico o admin).
3. Ve qué va a poder hacer la app y toca **Conectar**. YoRobot hace la entrega con el `estado` tal como llegó.
4. Vuelve a `volver?yorobot=conectada`, a `volver?yorobot=error&motivo=<estado de la respuesta>` o, si cancela, a `volver?yorobot=cancelada`.

### Baja

- **Desde YoRobot** (`desconectar_aplicacion` o Ajustes → Aplicaciones): revoca el token, borra la credencial sellada y las conexiones que creó el vínculo, y le manda a la app una entrega firmada igual, sin token: `{ "evento": "vinculo.revocado", "vinculo_id", "organizacion": { "id", "nombre" } }`. La app contesta `200 { "estado": "desconectada", "mensaje" }`, también si ese vínculo ya no existía.
- **Desde la app:** `DELETE /api/v1/vinculos/{vinculo_id}` con `Authorization: Bearer <token del vínculo>`. Hace lo mismo y contesta `204`; sólo sirve el token de ese mismo vínculo.

### Por MCP

- `conectar_aplicacion { aplicacion, tienda? }` (técnico o admin): crea el vínculo y hace la entrega. Devuelve `conectada`, `estado`, `mensaje` y, si conectó, la tienda y las conexiones creadas.
- `listar_aplicaciones_conectadas`: cada vínculo con la tienda, quién lo conectó, cuándo, los últimos 4 del token y sus conexiones.
- `desconectar_aplicacion { vinculo_id }`: la baja desde YoRobot.
- La IA nunca pide un token en el chat ni lo muestra: «conectá mi tienda de Che Tienda con YoRobot» es `conectar_aplicacion { aplicacion: "che-tienda" }`.

## Este proyecto

Completá con la organización de YoRobot, los agentes que se armaron para este proyecto (nombre y `clave`) y qué hace cada uno. Sin claves ni tokens.
