# Referencia MCP

Servidor: `https://yorobot.ai/api/mcp` (Streamable HTTP). 218 herramientas, generadas desde el código que las sirve.

Se entra con `Authorization: Bearer <token>`; el token se genera en el Inicio o en Accesos y actúa en nombre de una persona con su rol. Un token de **lectura** ve; uno de **escritura** además crea trabajo, o sea gasta. Ninguna herramienta aprueba trabajo: `aprobar` devuelve un enlace de un solo uso y la aprobación la firma la persona en el portal, con su sesión. La excepción es la segunda firma de una promoción a producción (`aprobar_promocion`), que da otra persona que la que la pidió.

## El catálogo chico

`tools/list` no trae las 218: trae un **núcleo** de lo que se usa en casi toda sesión (`quien_soy`, `inicio`, `listar_agentes`, `crear_agente`, `editar_agente`, `probar_agente`, `pedir_tarea`, `estado_de_tarea`, `listar_tareas`, `ver_actividad`, `aprobaciones_pendientes`, `listar_herramientas`, `proponer_memoria`, `cargar_documento`; sin alcance de escritura, sólo las de lectura) y tres meta-herramientas:

- `buscar_herramientas` — por `intencion` en castellano («conectar WhatsApp», «cuánto gasté») y/o por `area`. Devuelve las que ese token puede llamar, mejor puntuadas primero, con descripción, alcance y esquema completo; si recorta, lo dice en la respuesta y nombra el resto.
- `usar_herramienta_lectura` — ejecuta una herramienta del catálogo que sólo lee, con `{ nombre, argumentos }`. Rechaza las que escriben. Es la que conviene aprobar «siempre» en el editor: no abre nada que cambie algo.
- `usar_herramienta` — ejecuta una herramienta del catálogo que escribe, con `{ nombre, argumentos }`, por el mismo camino que la llamada directa: alias, alcance de la herramienta de destino, freno por minuto, idempotencia con `clave_de_pedido` (dentro de `argumentos`) y auditoría. No se ofrece a un token sin escritura.

Están separadas porque los editores piden permiso por nombre de herramienta: con una sola para todo, aprobarla «siempre» para leer abría también las que borran. `buscar_herramientas` dice en `usar_con` cuál corresponde a cada una.

Cualquier herramienta de esta página se sigue pudiendo llamar **directo por su nombre** con `tools/call`, esté o no en la lista: el CLI y los clientes que ya conocen los nombres no cambian nada. Las áreas de búsqueda son las secciones de esta página: `empezar`, `agentes`, `evaluaciones`, `equipos`, `copilotos`, `trabajo`, `conexiones`, `canales`, `automatizaciones`, `webhooks`, `datos`, `consolas`, `conocimiento`, `consumo`.

## Errores

Una herramienta que falla vuelve con `isError: true` y un objeto `{ codigo, mensaje, que_hacer, link? }`. El `codigo` es estable y cada uno lleva a un próximo paso distinto:

- `falta_argumento`
- `argumento_invalido`
- `no_existe`
- `estado_invalido`
- `sin_alcance`
- `demasiados_pedidos`
- `clave_reusada`
- `en_curso`
- `requiere_persona`
- `herramienta_desconocida`
- `no_valida`
- `falla`

## Índice

- **Empezar** (`empezar`) — `instalar_ejemplo`, `quien_soy`, `revocar_mi_token`, `inicio`, `como_vamos`, `consultar_numeros`, `proximo_paso`, `explicar_yorobot`, `buscar_herramientas`, `usar_herramienta_lectura`, `usar_herramienta`
- **Agentes** (`agentes`) — `crear_agente`, `hablar_con_el_constructor`, `editar_agente`, `promover_agente`, `listar_promociones`, `aprobar_promocion`, `rechazar_promocion`, `volver_a_version`, `metricas_por_version`, `politica_de_publicacion`, `configurar_publicacion`, `exportar_agente`, `importar_agente`, `listar_componentes`, `ver_componente`, `listar_trabajos`, `crear_agente_desde_trabajo`, `ensayar_agente`, `camino_a_produccion`, `listar_agentes`, `transferir_agente`, `eliminar_agente`, `traspasar_agentes`, `historial_de_traspasos`, `ranking_de_agentes`, `agentes`, `resumen_de_agente`, `tareas_del_agente`, `calidad_del_agente`
- **Probar** (`evaluaciones`) — `ensayar_y_publicar`, `cargar_caso`, `listar_casos`, `habilitar_caso`, `deshabilitar_caso`, `probar_agente`
- **Equipos y reparto** (`equipos`) — `fijar_autonomia_del_proyecto`, `declarar_equipo`, `listar_equipos`, `ver_equipo`, `exportar_equipo`, `importar_equipo`, `descomponer_tarea`, `mandar_mensaje`, `ver_comunicacion`, `arbol_de_tarea`, `armar_vigia_de_mercado`, `pedir_al_vigia`
- **Copilotos por persona** (`copilotos`) — `mi_perfil`, `editar_mi_perfil`, `asignar_copiloto`, `programar_briefings`, `listar_objetivos`, `ver_objetivo`, `definir_objetivo`, `medir_objetivo`, `pausar_objetivo`, `configurar_despertadores`, `ver_diario_de_sueno`, `configurar_sueno`, `listar_aprendizajes`, `aceptar_aprendizaje`, `rechazar_aprendizaje`
- **Tareas** (`trabajo`) — `pedir_tarea`, `preguntar_a_agente`, `listar_hilos`, `ver_hilo`, `escribir_en_hilo`, `generar_pdf`, `listar_recordatorios`, `pausar_recordatorio`, `borrar_recordatorio`, `ver_traza`, `ver_actividad`, `listar_tareas`, `estado_de_tarea`, `tareas_estancadas`, `repetir_tarea`, `contestar_pregunta`, `seguir_tarea`, `aprobaciones_pendientes`, `resolver_efecto_incierto`, `aprobar`, `rechazar`, `hallazgos`, `que_paso_en_la_tarea`, `traza_de_la_tarea`, `herramientas_de_la_tarea`
- **Conexiones y credenciales** (`conexiones`) — `crear_funcion`, `ver_funcion`, `crear_herramienta`, `listar_servidores_mcp`, `conectar_servidor_mcp`, `conectar_base`, `conectar_aplicacion`, `listar_aplicaciones_conectadas`, `desconectar_aplicacion`, `probar_conexion`, `redescubrir_servidor_mcp`, `estado_descubrimiento_mcp`, `autorizar_servidor_mcp`, `estado_oauth_mcp`, `desconectar_servidor_mcp`, `listar_herramientas`, `habilitar_herramienta`, `elegir_modelo`, `prender_herramienta`, `apagar_herramienta`, `cargar_credencial`, `editar_herramienta`, `simular_herramienta`, `quitar_simulacion`, `pedir_conexion`, `crear_link_de_credencial`, `listar_pedidos_de_conexion`, `rechazar_pedido_de_conexion`
- **Canales y avisos** (`canales`) — `listar_canales`, `abrir_canal`, `conectar_canal`, `conectar_whatsapp`, `conectar_instagram`, `estado_de_conexion`, `configurar_canal`, `probar_canal`, `prender_canal`, `apagar_canal`, `listar_conversaciones`, `ver_conversacion`, `cerrar_conversacion`, `listar_destinatarios`, `avisar_a`, `prender_destinatario`, `apagar_destinatario`, `borrar_destinatario`, `probar_destinatario`
- **Automatizaciones** (`automatizaciones`) — `crear_rutina`, `editar_rutina`, `listar_cajas`, `agregar_disparador`, `prender_rutina`, `apagar_rutina`, `borrar_rutina`, `listar_workers`, `desplegar_workers`, `salud_de_la_instalacion`, `listar_rutinas`, `disparar_rutina`
- **Webhooks** (`webhooks`) — `listar_webhooks`, `listar_entregas_de_webhook`, `ver_entrega_de_webhook`, `reenviar_entrega_de_webhook`, `disparar_evento_de_prueba`
- **Datos** (`datos`) — `listar_entidades`, `definir_entidad`, `consultar_registros`, `ver_registro`, `guardar_registro`, `importar_registros`
- **Consolas** (`consolas`) — `catalogo_de_consola`, `biblioteca_de_consolas`, `arrancar_consola`, `listar_consolas`, `ver_consola`, `proponer_consola`, `publicar_consola`, `descartar_borrador`
- **Cerebro y memoria** (`conocimiento`) — `listar_memorias`, `proponer_memoria`, `medir_memoria`, `decidir_memoria`, `listar_skills`, `cargar_skill`, `asignar_skill`, `listar_fuentes`, `ver_documento`, `cargar_documento`, `listar_colecciones`, `crear_coleccion`, `cargar_documentos`, `configurar_extraccion`, `extraer_pendientes`, `comparar_documentos`, `publicar_documento`, `despublicar_documento`, `alcance_de_documento`, `medicion_del_cerebro`, `grafo_del_cerebro`, `listar_fuentes_vivas`, `conectar_fuente_viva`, `catalogo_de_fuentes_vivas`, `configurar_fuente_viva`, `sincronizar_fuente_viva`, `desconectar_fuente_viva`, `buscar_en_cerebro`
- **Consumo y límites** (`consumo`) — `fijar_cuota_mensual`, `fijar_tope_diario`, `ver_cuotas`, `ver_plan`, `ver_membresia`, `fijar_tope_de_agente`, `listar_pedidos`, `fijar_cuota_por_ventana`, `consumo_por_esfuerzo`, `mi_cartera`, `instalar_en_clientes`, `promover_en_cliente`, `retencion`, `actividad_por_dia`

## Empezar

Quién sos, qué hay, cómo vamos y las cuentas de la organización, qué es YoRobot, la tienda de ejemplo y cómo encontrar el resto del catálogo. Área de búsqueda: `empezar`.

### `instalar_ejemplo`

_alcance: escritura · idempotente_

El sandbox: instala la tienda de ejemplo de YoRobot —dos conexiones sin llave contra un sistema de pedidos de mentira que sirve YoRobot, un agente de plantilla que las usa (no ocupa lugar en el plan) y cuatro casos— con la versión en prueba, lista para `probar_agente`. Una conexión consulta pedidos; la otra le «avisa» al cliente y, como un aviso no se deshace, espera la aprobación de una persona (el aviso no le llega a nadie). Las organizaciones nuevas ya la traen; esto la instala en las de antes. No crea tareas ni resultados.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `quien_soy`

_alcance: lectura · sólo lee · idempotente_

Confirma la conexión: la cuenta (`cuenta.email`) y la organización (`organizacion.nombre`) de este token —la que se eligió al autorizar, o donde se creó en Accesos; nunca otra de la persona—, con `resumen` listo para decírselo a la persona.
Además, el rol de la persona en esa organización hoy, si publica a producción y aprueba (técnico y admin) o sólo arma y ensaya (desarrollador) y a qué agentes llega (`null` = todos).
Y el token: cómo se llama, si es una conexión OAuth que se renueva sola (`token.se_renueva_solo`: entonces no hay nada que rotar) o uno de Accesos que vence (`token.vence`, `token.dias_restantes`, `token.vence_hoy`), y qué hacer cuando venza.
Llamala primero: lo que el token puede hacer no es del token, es de la persona, y puede haber cambiado desde que se emitió.

Sin argumentos.

### `revocar_mi_token`

_alcance: lectura · destructiva · idempotente_

Revoca ESTE token —el que autenticó esta llamada— en el acto: la próxima llamada con él da 401. No pide id ni acepta otro: para revocar el de otra persona está Accesos en el portal.
Usala cuando el token quedó pegado en un transcript, un log o un mensaje. Cualquier alcance alcanza: apagarse uno mismo es siempre seguro.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `inicio`

_alcance: lectura · sólo lee · idempotente_

Lo mismo que la pantalla de Inicio: casos cerrados y verificados este mes, discrepancias (el agente dijo una cosa y la verificación otra; no se facturan), tareas que esperan una aprobación, frenadas que nadie mueve, y el gasto contra el tope mensual con porcentaje. Más el desglose por agente.
Y `ahora`, como el cockpit del Inicio: cuántos agentes trabajan y cada corrida en vivo con su tarea, desde cuándo y el silencio (`sospechoso` a los 5 min, `critico` a los 15); la madre que espera a sus hijas (`espera_hijas`).
La primera para «¿cómo vamos?». Esfuerzo: `consumo_por_esfuerzo`; cola: `aprobaciones_pendientes`; frenadas: `tareas_estancadas`.

Sin argumentos.

### `como_vamos`

_alcance: lectura · sólo lee · idempotente_

La organización entera en el mes en curso: cuántos agentes hay, casos cerrados y verificados, discrepancias, tareas que esperan aprobación, tareas frenadas, gasto contra el tope y el desglose por agente. Es la respuesta a «¿cómo vamos?»; para un agente en particular seguí con `resumen_de_agente`.

Sin argumentos.

### `consultar_numeros`

_alcance: lectura · sólo lee · idempotente_

Cuenta o suma sobre una vista cerrada —tareas (tareas o frenadas), gasto (costo o ejecuciones) o aprobaciones (aprobadas o rechazadas)— por agente, columna, día o semana y en un período, sin escribir SQL. Es la respuesta a «¿cuántas tareas frenadas por agente este mes?» o «¿qué agente gastó más?»: el número lo calcula el servidor y llega con el total ya sumado, el nombre de cada grupo y lo que no entró. Frenada es la columna Frenada de Tareas (nada la mueve). El período se corta en la zona horaria de la organización (por defecto este_mes; «todo» es sin corte). `agente_id` la acota a un agente, por su id o su nombre.

| Argumento | Tipo | Qué es |
|---|---|---|
| `vista` **(requerido)** | `tareas` · `gasto` · `aprobaciones` | De dónde se cuenta: tareas, gasto (las ejecuciones) o aprobaciones. |
| `medida` | `tareas` · `frenadas` · `costo` · `ejecuciones` · `aprobadas` · `rechazadas` | Qué se cuenta. tareas: tareas o frenadas. gasto: costo o ejecuciones. aprobaciones: aprobadas o rechazadas. Sin ella, la primera de la vista. |
| `por` | `agente` · `columna` · `dia` · `semana` | Cómo se agrupa: agente, columna (sólo tareas), dia o semana. Sin él, el total. |
| `periodo` | `hoy` · `ayer` · `esta_semana` · `semana_pasada` · `este_mes` · `mes_pasado` · `ultimos_7_dias` · `ultimos_30_dias` · `este_trimestre` · `este_anio` · `todo` | Qué período. Por defecto este_mes. |
| `agente_id` | string | Sólo la de este agente: su id (de `agentes`) o su nombre. |

### `proximo_paso`

_alcance: lectura · sólo lee · idempotente_

El camino de la organización hacia «Implementador certificado», medido sobre lo que hizo de verdad: los siete ejercicios de la Academia y los módulos de la Escuela, cada uno con si está hecho o falta, dónde se hace y cuál es el PRÓXIMO PASO. Es la respuesta a «¿qué me falta para certificarme?», «¿cuál es mi próximo paso?» o «¿por dónde sigo?». No recomienda: lee los hechos.

Sin argumentos.

### `explicar_yorobot`

_alcance: lectura · sólo lee · idempotente_

Qué es YoRobot y cómo se vende: qué hace, los precios y la prueba, la Escuela y la Academia. Es para preguntas sobre la plataforma misma —qué es, cuánto cuesta, cómo empieza un implementador—, no sobre esta organización; contestá con lo que dice y citalo.

Sin argumentos.

### `buscar_herramientas`

_alcance: lectura · sólo lee · idempotente_

Esta lista trae sólo el núcleo. El resto del catálogo de YoRobot (canales como WhatsApp o Slack, conexiones, Datos, consolas, automatizaciones, evaluaciones, equipos, webhooks, consumo, producción…) se encuentra acá: describí lo que querés hacer en `intencion` («conectar WhatsApp», «cuánto gasté este mes») y/o elegí un `area`. Vuelven las que ESTE token puede llamar, mejor puntuadas primero, con descripción y esquema completo; ejecutalas con `usar_herramienta` o directo por su nombre.

| Argumento | Tipo | Qué es |
|---|---|---|
| `intencion` | string | Qué querés hacer, en castellano y con tus palabras. Se busca por palabras en nombre, descripción y área. |
| `area` | `empezar` · `agentes` · `evaluaciones` · `equipos` · `copilotos` · `trabajo` · `conexiones` · `canales` · `automatizaciones` · `webhooks` · `datos` · `consolas` · `conocimiento` · `consumo` | Limita a un área: empezar (Quién sos, qué hay, cómo vamos y las cuentas de la organización, qué es YoRobot, la tienda de ejemplo y cómo encontrar el resto del catálogo); agentes (Crear (también conversando con el Constructor), editar, versionar, llevar a producción y traspasar agentes); evaluaciones (Evaluaciones: ensayos, casos y la prueba con traza); equipos (Equipos de agentes, partir una tarea entre varios, pedirle algo a un par, ver el árbol y cuánta autonomía tiene el equipo técnico sobre cada proyecto); copilotos (El perfil de cada persona —canal, hora, intereses—, su copiloto, su North Star medido y el briefing diario con sus decisiones); trabajo (Pedir trabajo, seguirlo, leer su traza, las fallas que se repiten, preguntarle algo a un agente, tu conversación con cada agente, tus recordatorios y ver qué espera aprobación); conexiones (Herramientas, funciones propias, servidores MCP ajenos, aplicaciones conectadas (Che Tienda), credenciales, simulaciones y el modelo); canales (Por dónde entra la gente (chat, WhatsApp, Slack…) y a quién se le avisa); automatizaciones (Rutinas, disparadores, cajas y workers); webhooks (Avisos firmados hacia afuera: entregas, reenvío y el aviso de prueba); datos (Entidades y registros de la organización); consolas (Las pantallas declaradas del equipo del cliente); conocimiento (Conocimiento: documentos, fuentes vivas, memorias y skills); consumo (El plan y la membresía, gasto, topes (también el de cada agente), cuotas, el registro de pedidos, retención y la cartera partner). Sin `intencion`, trae el área entera. |
| `limite` | number | Cuántas traer con esquema completo. Por defecto 5, máximo 10; las demás que coinciden vienen sólo por nombre. |

### `usar_herramienta_lectura`

_alcance: lectura · sólo lee · idempotente_

Ejecuta por su nombre una herramienta del catálogo que SÓLO LEE, aunque no esté en esta lista (la encontrás con `buscar_herramientas`, que en `usar_con` te dice cuál usar). Si la de destino escribe, la rechaza: esas van por `usar_herramienta`. Pasa por el mismo camino que llamarla directo: alcance, validación, freno por minuto y auditoría. No sirve para llamar a `buscar_herramientas` ni a las otras dos de este tipo.

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | El nombre exacto de la herramienta, como lo devuelve `buscar_herramientas`. |
| `argumentos` | object | Los argumentos de esa herramienta, con la forma de su `inputSchema`. Vacío si no lleva. |

### `usar_herramienta`

_alcance: lectura · destructiva · toca sistemas ajenos_

Ejecuta por su nombre una herramienta del catálogo que ESCRIBE (crea, cambia, borra, conecta, publica), aunque no esté en esta lista (la encontrás con `buscar_herramientas`). Para las que sólo leen usá `usar_herramienta_lectura`: así tu editor te pide permiso sólo cuando algo va a cambiar. Pasa por el mismo camino que llamarla directo: alcance, validación, freno por minuto, idempotencia y auditoría, y exige el alcance de la herramienta de destino. Mandá `clave_de_pedido` adentro de `argumentos`. No sirve para llamar a `buscar_herramientas` ni a las otras dos de este tipo.

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | El nombre exacto de la herramienta, como lo devuelve `buscar_herramientas`. |
| `argumentos` | object | Los argumentos de esa herramienta, con la forma de su `inputSchema`. Vacío si no lleva. |


## Agentes

Crear (también conversando con el Constructor), editar, versionar, llevar a producción y traspasar agentes. Área de búsqueda: `agentes`.

### `crear_agente`

_alcance: escritura_

Crea un agente: un trabajador digital con oficio, instrucciones y herramientas. Queda activo pero sin credenciales: puede razonar y no toca nada real hasta que alguien las conecte. Con `clave`, volver a declararlo con la misma clave lo ACTUALIZA (versión nueva en dev) en vez de crear otro: es lo que hace que una terminal pueda repetir la llamada sin llenar la organización de duplicados.

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | Cómo se lo va a llamar en la pantalla. Corto y humano. |
| `clave` | string | Clave estable elegida por vos (p. ej. «triaje-guardia»), única en la organización. Si ya hay un agente con esa clave, se actualiza en vez de crear otro; la respuesta dice `creado` o `actualizado`. Opcional. |
| `instruccion` **(requerido)** | string | Escrita EN SEGUNDA PERSONA, dirigida al agente: qué hace, en qué orden, cuándo frena y pide aprobación, y qué no debe hacer nunca. |
| `conocimiento` | string | Lo que necesita saber del negocio. Vacío si no aplica. |
| `como_se_verifica` | string | Qué consulta de sólo lectura, contra qué sistema, demuestra que el trabajo se hizo. Es lo que va a releer el verificador: obligatorio si pedís verificacion distinta de «ninguna», y tiene que NOMBRAR una herramienta de riesgo read de `herramientas` o una entidad de Datos (por clave o nombre); si no cita ninguna, se rechaza y el error dice cuáles puede citar. La respuesta trae `criterio_de_verificacion.releible`. |
| `aceptar_sin_relectura` | boolean | true para guardar un `como_se_verifica` que ninguna lectura de la caja puede releer, a sabiendas de que toda tarea va a terminar en «lo mira una persona». Por defecto false. |
| `human_in_the_loop` | `siempre` · `excepciones` · `solo_irreversible` | Cuándo entra una persona: «siempre» (toda acción con efecto y todo cierre esperan aprobación), «excepciones» (lo irreversible, montos fuera de tope, fallos y discrepancias) o «solo_irreversible» (default: el agente nace barato y se sube después con editar_agente). Lo destructivo, el guardarriel y las herramientas en cuarentena piden persona con cualquier valor. |
| `verificacion` | `completa` · `relectura` · `muestreo` · `ninguna` | Qué relee el verificador independiente después de cada tarea: «completa» (antes y después, 2 corridas), «relectura» (1 corrida), «muestreo» (relectura en un porcentaje de las tareas) o «ninguna» (default: la tarea cierra sin verificar y no cuenta como verificada). Cada nivel arriba de «ninguna» es una corrida más que se cobra; se prende con editar_agente cuando el proceso lo amerita. |
| `verificacion_muestreo` | integer | Sólo con verificacion=muestreo: porcentaje de tareas que se releen (1–99). Default 20. |
| `herramientas` | lista | Nombres de conexiones ya existentes en la organización (`listar_herramientas`). Un nombre que no exista es un ERROR (el mensaje dice cuáles y qué hay), salvo `ignorar_desconocidas: true`. |
| `ignorar_desconocidas` | boolean | true para crearlo igual, sin las herramientas que no existan. La respuesta las lista en `ignoradas_porque_no_existen`. Por defecto false. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `hablar_con_el_constructor`

_alcance: escritura_

La misma entrevista que el Constructor de la app, turno a turno: le contás qué tarea querés sacarte de encima y te pregunta lo que falta —qué sistemas toca, dónde se comprueba el trabajo, un ejemplo excelente y uno inaceptable, qué no puede hacer solo—. Cada respuesta trae `plan_parcial`: la ficha del agente como va, con lo entendido, lo que falta y, cuando hay plan, los sistemas en palabras, el escalón de autonomía, qué le va a preguntar a la persona antes de actuar (`que_te_pregunta`), el tope y los actos. El tope solo no dice qué espera aprobación: leé `todo_con_efecto_espera_aprobacion` y `el_tope_decide_algo`.
El primer turno va sin `sesion` y la respuesta trae una: mandala en los siguientes. Cuando alcanza, arma el plan con la misma validación que la app y lo deja como BORRADOR: `creado` es false y `confirmar_en` es el link donde la persona lo revisa y lo confirma con su sesión. Ningún agente se crea desde acá: mostrale el link tal cual.
Si ya tenés el agente escrito entero, `crear_agente`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `mensaje` **(requerido)** | string | Lo que le decís al Constructor, en lenguaje natural. Hasta 4000 caracteres. |
| `sesion` | string | La `sesion` que devolvió el turno anterior. Sin ella, arranca una charla nueva. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `editar_agente`

_alcance: escritura_

Cambia lo que un agente ya existente sabe y hace: su instrucción, su conocimiento, cómo se verifica, Human in the Loop y verificación (o `modo`), y qué herramientas usa. Queda versionado, así que se puede ver qué cambió y cuándo. La versión nueva va a dev, y en el modo Libre también a producción (la respuesta trae `deshacer`); con `desplegar_hasta` («staging» o «prod») se promueve en la misma llamada, con los chequeos de promover_agente. La correa (`nivel`, `tope_sin_firma_usd`, `presupuesto_por_tarea_usd`) también se edita acá, con una asimetría: APRETAR (bajar nivel, tope o presupuesto) lo puede cualquier operador; AFLOJAR exige técnico o admin, igual que sacar una herramienta de cuarentena, y deja su propio evento en la bitácora.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id que devolvió crear_agente o listar_agentes. |
| `nombre` | string | Sólo si querés renombrarlo. |
| `instruccion` | string | Reemplaza la instrucción entera, en segunda persona. No se concatena a la anterior. |
| `conocimiento` | string | Reemplaza el conocimiento entero. |
| `como_se_verifica` | string | Reemplaza la verificación. Vaciarlo deja al agente sin poder medirse. Tiene que nombrar una herramienta read de la caja o una entidad de Datos; si con el cambio (de este campo, de `herramientas` o de `verificacion`) el criterio deja de poder releerse, se rechaza salvo `aceptar_sin_relectura: true`. |
| `aceptar_sin_relectura` | boolean | true para guardar igual un criterio que ninguna lectura de la caja puede releer. Por defecto false. |
| `modo` | `libre` · `con_controles` · `regulado` | Los diales de un modo, de una vez: «libre» (hace y avisa, persona sólo en lo irreversible, sin verificación), «con_controles» (persona por excepción, relee el 20 %) o «regulado» (aprobación por acción, persona siempre, verificación completa). Lo que mandes además lo pisa. Rige ya; aflojar exige técnico o admin. |
| `human_in_the_loop` | `siempre` · `excepciones` · `solo_irreversible` | Cuándo entra una persona: «siempre» (toda acción con efecto y todo cierre esperan aprobación), «excepciones» (lo irreversible, montos fuera de tope, fallos y discrepancias) o «solo_irreversible» (default: el agente nace barato y se sube después con editar_agente). Lo destructivo, el guardarriel y las herramientas en cuarentena piden persona con cualquier valor. |
| `verificacion` | `completa` · `relectura` · `muestreo` · `ninguna` | Qué relee el verificador independiente después de cada tarea: «completa» (antes y después, 2 corridas), «relectura» (1 corrida), «muestreo» (relectura en un porcentaje de las tareas) o «ninguna» (default: la tarea cierra sin verificar y no cuenta como verificada). Cada nivel arriba de «ninguna» es una corrida más que se cobra; se prende con editar_agente cuando el proceso lo amerita. |
| `verificacion_muestreo` | integer | Sólo con verificacion=muestreo: porcentaje de tareas que se releen (1–99). Default 20. |
| `herramientas` | lista | Reemplaza la lista entera, por nombre. Un nombre que no exista en la organización es un ERROR (el mensaje dice cuáles y qué hay), salvo `ignorar_desconocidas: true`. |
| `ignorar_desconocidas` | boolean | true para que las herramientas que no existan se salteen en vez de rechazar la llamada. La respuesta las lista en `herramientas_ignoradas`. Por defecto false: un nombre mal tipeado no deja al agente sin la herramienta en silencio. |
| `activo` | boolean | false lo manda a descanso: no toma tareas nuevas ni atiende sus rutinas, pero conserva su historia entera (un agente no se borra: sus corridas y versiones son el registro) y deja de contar para el límite de agentes del plan. true lo despierta. |
| `nivel` | `shadow` · `assisted` · `delegated` · `gated_auto` | Nivel de autonomía, de menor a mayor: «shadow» (propone, no ejecuta), «assisted» (ejecuta con aprobación), «delegated» (ejecuta solo dentro del tope; lo irreversible sigue pidiendo firma), «gated_auto» (también cierra solo si el verificador aprueba; un sistema de cliente no pasa de delegated). Subirlo exige técnico o admin. |
| `tope_sin_firma_usd` | number | null | Monto en USD que el agente puede mover sin aprobación (sólo con nivel delegated o gated_auto). `0` es CERO: lo que no maneja montos sale solo y un peso pide firma. `null` lo saca: TODA acción con efecto vuelve a pedir aprobación (es apretar). Subir el número, o pasar de null a un número, es aflojar: exige técnico o admin. Sin mandar, no cambia. |
| `presupuesto_por_tarea_usd` | number | Presupuesto duro de modelo por tarea, en USD (mayor que cero). Subirlo exige técnico o admin. |
| `reparte_trabajo` | boolean | true le deja repartir su tarea en tareas hijas a cargo de OTROS agentes, y pedirle algo puntual a un par. Por defecto false: un agente hace su tarea solo. Prenderlo es aflojar —le da la capacidad de crear trabajo que se paga sin que nadie lo pida tarea por tarea— así que exige técnico o admin; apagarlo lo puede cualquier operador. |
| `reparto_profundidad_max` | number | Cuántos niveles de reparto se permiten desde esta tarea (1 a 10, por defecto 3). Es lo que corta un bucle entre dos agentes que se delegan entre sí sin tener que detectar el ciclo: cada vuelta cuesta un nivel. Subirlo exige técnico o admin. |
| `reparto_hijas_max` | number | Cuántas tareas hijas puede crear de una vez (1 a 20, por defecto 8). Subirlo exige técnico o admin. |
| `desplegar_hasta` | `staging` · `prod` | Además de editar, promover la versión nueva hasta ese ambiente en la misma llamada (dev → staging → prod, cada escalón con sus chequeos). Si producción exige dos firmas, queda el pedido pendiente en `despliegue.promocion_id`. |
| `nota` | string | Sólo con desplegar_hasta: por qué se promueve. Queda en el historial de despliegues. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `promover_agente`

_alcance: escritura_

Sube la versión de un agente hasta el ambiente que pidas: `hasta: «prod»` recorre en UNA llamada todos los escalones que falten (dev → staging → prod), cada uno con sus chequeos (ensayo en verde antes de producción, ventana de cambios), y devuelve los `escalones` que recorrió. Editar un agente despliega la versión nueva sólo a dev (en el modo Libre, también a producción); SIN promoverla, producción sigue corriendo la anterior y los relojes de sus automatizaciones no disparan. Si la organización prendió cuatro ojos para producción y tiene dos o más publicadores (técnicos/admins), la llamada deja una promoción PENDIENTE (`promocion_id`) y la firma OTRA persona con `aprobar_promocion`; quien la pidió no puede aprobarla. Si hay UN solo publicador, la segunda persona no existe: se despliega con una firma, la respuesta lo dice (`una_firma: true`) y queda constancia en la bitácora. Al subir una versión, los pedidos pendientes de versiones anteriores del mismo agente se cancelan solos. Un desarrollador llega hasta pedir.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de listar_agentes. |
| `hasta` | `staging` · `prod` | Hasta dónde subir: «staging» (preproducción) o «prod». Recorre los escalones que falten. |
| `desde` | string | Opcional (compatibilidad): «dev» o «staging». Sin `hasta`, sube UN escalón desde ahí, como antes. |
| `nota` | string | Por qué se promueve. Opcional; queda en el historial de despliegues. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_promociones`

_alcance: lectura · sólo lee · idempotente_

Las promociones a producción de los agentes a los que la persona llega: pendientes de firma, aprobadas, rechazadas y canceladas, con quién pidió, quién decidió y si preproducción todavía corre la versión pedida. `puedo_firmar` dice si quien llama puede aprobar cada una.

| Argumento | Tipo | Qué es |
|---|---|---|
| `estado` | `pendiente` · `aprobada` · `rechazada` · `cancelada` | Sólo las de este estado. Por defecto, todas. |
| `agente_id` | string | Sólo las de este agente. |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `aprobar_promocion`

_alcance: escritura · idempotente_

La segunda firma: despliega a producción la versión que otra persona pidió. La firma un técnico o un admin DISTINTO de quien pidió; un desarrollador no. Se rechaza si preproducción ya no corre esa versión o si la organización está fuera de su ventana de cambios. Mirá antes `metricas_por_version`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `promocion_id` **(requerido)** | string | El pedido, de `listar_promociones` o de `promover_agente`. |
| `nota` | string | Qué se miró para firmar. Opcional; queda en el historial. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `rechazar_promocion`

_alcance: escritura · idempotente_

Cierra un pedido pendiente sin desplegar. Si lo llama quien lo pidió, queda cancelado; si lo llama un técnico o un admin, rechazado. El motivo es obligatorio y es lo que va a leer quien pidió.

| Argumento | Tipo | Qué es |
|---|---|---|
| `promocion_id` **(requerido)** | string | El pedido, de `listar_promociones`. |
| `motivo` **(requerido)** | string | Por qué no sale. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `volver_a_version`

_alcance: escritura_

Rollback: pone a correr en un ambiente una versión que YA corrió ahí. Es un despliegue nuevo apuntando a la vieja —el historial no se toca—. A producción lo hace un técnico o un admin, sin segunda firma ni ventana; en el modo Libre vuelve también la definición del agente (herramientas, control, correa), así la próxima edición no republica lo deshecho. Una versión que nunca corrió en ese ambiente se rechaza: eso es promover, no volver.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de listar_agentes. |
| `ambiente` **(requerido)** | `dev` · `staging` · `prod` | Dónde volver. |
| `version` **(requerido)** | number | A qué versión volver, de `metricas_por_version` o `historial_del_agente`. |
| `motivo` **(requerido)** | string | Por qué se vuelve. Obligatorio; queda en el historial de despliegues. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `metricas_por_version`

_alcance: lectura · sólo lee · idempotente_

Por versión de un agente: en qué ambientes corre hoy, cuántas tareas hizo, cuántas verificadas, discrepancias y fallidas, costo total y por tarea, duración mediana y el último ensayo contra casos. Las tareas se cuentan por la versión con la que corrieron, no por la que corre ahora. Es lo que se mira antes de firmar una promoción o de volver.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de listar_agentes. |

### `politica_de_publicacion`

_alcance: lectura · sólo lee · idempotente_

El modo de control de la organización («libre», «con_controles» o «regulado»: con qué diales nacen sus agentes) y la política de producción: si rige cuatro ojos, la ventana de cambios (días y horas en el huso del cliente) y si ahora mismo está abierta. Se cambia desde la pantalla Seguridad o con `configurar_publicacion`.

Sin argumentos.

### `configurar_publicacion`

_alcance: escritura · idempotente_

Cambia el modo de control de la organización y su política de producción. `modo` («libre», «con_controles» o «regulado») dice con qué diales nacen los agentes nuevos; con `aplicar_a_actuales: true` se los pone también a los que ya existen (la respuesta lista qué le cambió a cada uno). El modo deja cuatro ojos y la ventana como dice él: «regulado» los prende y los otros dos los apagan. Aflojar el modo exige técnico o admin; apretarlo, cualquier operador; si toca cuatro ojos o la ventana, un admin. Sin `modo`, sólo un admin: prende o apaga cuatro ojos y fija o quita la ventana de cambios: `ventana` es `{dias: [1..7], desde: "HH:MM", hasta: "HH:MM"}` en hora del cliente (1 = lunes; una ventana que cruza medianoche vale), o null para no tener ventana. Todo queda asentado en la bitácora.

| Argumento | Tipo | Qué es |
|---|---|---|
| `modo` | `libre` · `con_controles` · `regulado` | El modo de control de la organización. Libre es el de nacimiento: los controles se prenden. |
| `aplicar_a_actuales` | boolean | Con `modo`: true para ponerles sus diales también a los agentes que ya existen. Por defecto false: sólo los nuevos. |
| `cuatro_ojos` | boolean | Si la promoción a producción exige dos personas. |
| `ventana` | object | null | `{dias, desde, hasta}` o null para quitarla. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `exportar_agente`

_alcance: lectura · sólo lee · idempotente_

Devuelve el agente entero como un paquete `yorobot/agente@1` para guardarlo en un repo: instrucción, conocimiento, cómo se verifica, herramientas con su riesgo, permisos y límites, Human in the Loop y verificación, las skills con su SKILL.md, los criterios vigentes y los casos de ensayo. Sin credenciales (sólo sus nombres), sin canales ni ids. Trae el hash del paquete y la versión actual del agente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de listar_agentes. |

### `importar_agente`

_alcance: escritura · idempotente_

Crea un agente desde un paquete `yorobot/agente@1` —o, con `agente_id`, le deja una versión nueva a uno existente— y lo despliega SÓLO a prueba (dev). Producción no cambia hasta ensayar_agente en verde y promover_agente. Guarda las skills del paquete (versión nueva si el cuerpo cambió), suma los criterios y casos que no estaban y valida todo antes de tocar nada: formato, límites, y que ningún texto traiga una credencial pegada. Si el paquete usa herramientas que la organización no declaró, falla y las lista; con `sin_faltantes: true` el agente nace sin ellas.

| Argumento | Tipo | Qué es |
|---|---|---|
| `paquete` | object | El paquete entero, el JSON de exportar_agente o del archivo del repo. O en su lugar `componente`. |
| `componente` | string | En vez de `paquete`: la clave de un componente de la biblioteca (listar_componentes). Se importa tal cual, con `sin_faltantes` implícito porque sus herramientas tienen nombres genéricos que hay que mapear. |
| `nombre` | string | Opcional, con `componente`: el nombre que va a tener el agente. |
| `agente_id` | string | Opcional: a qué agente existente aplicarle el paquete. Sin esto se crea uno nuevo. |
| `clave` | string | Clave estable elegida por vos (p. ej. «triaje-guardia»), única en la organización: si ya hay un agente con esa clave se le aplica el paquete (versión nueva en dev); si no, el que nace la lleva. Es lo que hace que `yorobot agente aplicar` se pueda repetir sin duplicar. Opcional; `agente_id` manda si vienen los dos. |
| `sin_faltantes` | boolean | true: importar aunque falten herramientas, y reportarlas. Por defecto falla. |
| `nota` | string | Por qué se importa (el commit, el PR). Opcional; queda en la auditoría. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_componentes`

_alcance: lectura · sólo lee · idempotente_

Las primitivas reutilizables que salieron de implementaciones reales —Conector, Monitor, Conversador, Validador, Entrevistador, Parte, Cola de excepciones—, cada una un paquete de agente completo con instrucción, herramientas por nombre genérico, permisos, Human in the Loop, verificación, criterios y casos de ensayo. Devuelve el resumen con hash y versión; el paquete entero se ve con ver_componente y se importa con importar_agente(componente).

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `ver_componente`

_alcance: lectura · sólo lee · idempotente_

El paquete completo de un componente de la biblioteca, para leerlo o editarlo antes de importar: cambiarle las herramientas genéricas por las de la organización, ajustar umbrales del conocimiento, sumar casos.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clave` **(requerido)** | string | La clave del componente, de listar_componentes. |

### `listar_trabajos`

_alcance: lectura · sólo lee · idempotente_

Los trabajos que una empresa delega —«Growth: conseguir reuniones», «Atención de clientes», «Cobranzas», «Reporte para gerencia», «Seguimiento de CRM», «Facturación»—, cada uno con lo que gana la empresa, qué hace el agente, los sistemas que usa (y si esta organización ya los conectó), lo que siempre pregunta antes de hacer y el North Star sugerido. `se_crea_al_llamar: true`: hay una pieza armada (en la biblioteca, o un conector de la casa como el de AFIP) y crear_agente_desde_trabajo la instala tal cual; `false`: se arma con el Constructor, y el `pedido` es con qué empezar. Es lo mismo que ofrece «Crear un agente» en el portal.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `crear_agente_desde_trabajo`

_alcance: escritura_

Crea el agente de un trabajo de listar_trabajos, igual que «Crear un agente» del portal: si el trabajo tiene pieza en la biblioteca (un equipo o una plantilla) la instala tal cual. Nace en producción (`ambiente: prod`) si la organización publica con una firma y vos podés publicar; si pide dos firmas o no podés, queda en prueba (`dev`) y `en_prueba_porque` dice por qué. Lo que se edite después cae en prueba y sube con ensayar_agente y promover_agente. De un equipo devuelve el líder, que es quien reparte. Nace aunque sus sistemas no estén conectados; se conectan después. El agente deja su primer mensaje en tu conversación con él; el de Facturación lo deja recién cuando AFIP queda conectado, porque esa conexión se hace en su chat del portal, guiada paso a paso (la persona saca el certificado con su clave fiscal en la página de AFIP: no se carga por acá). Con `meta`, fija además tu North Star (el `north_star_sugerido` de listar_trabajos, si `se_mide_al_nacer`) y lo devuelve medido. Si el trabajo se arma con el Constructor no crea nada (`creado: false`) y devuelve el `pedido` para hablar_con_el_constructor.

| Argumento | Tipo | Qué es |
|---|---|---|
| `trabajo` **(requerido)** | string | La clave del trabajo, de listar_trabajos. |
| `preguntar_todo` | boolean | true: que pida aprobación también antes de lo que se puede deshacer. Por defecto la pide sólo antes de lo que no se deshace. |
| `meta` | number | Opcional: la meta de tu North Star (por ejemplo, 3 reuniones por semana). Con esto queda fijado como el tuyo; si ya tenías uno, lo cambia. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `ensayar_agente`

_alcance: escritura_

Corre la versión actual del agente contra sus casos habilitados, en la misma cola y por el mismo camino que una tarea real. Sin `lote` ni `casos` corre todos los habilitados (techo 100); con `lote` corre los N más viejos habilitados, con `casos` sólo esos ids. Los casos deshabilitados nunca entran. Devuelve el id del ensayo y las tareas abiertas; el resultado se lee con camino_a_produccion o tarea por tarea con ver_traza. Es el requisito para promover a producción cuando el agente tiene casos: sin ensayo en verde de ESTA versión, promover_agente se niega.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de listar_agentes. |
| `lote` | number | Cuántos casos correr, de los habilitados y del más viejo al más nuevo (1 a 100). |
| `casos` | lista | Sólo estos casos, por id de `listar_casos`. Los deshabilitados se saltean. |
| `ambiente` | `dev` · `staging` · `prod` | Dónde corre. Por defecto `prod`, como el ensayo de siempre; para iterar la instrucción conviene `dev`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `camino_a_produccion`

_alcance: lectura · sólo lee · idempotente_

Qué versión corre en prueba, preproducción y producción, cuántos casos tiene el agente, cómo salió el último ensayo (contra qué versión, cuántos pasaron) y, por escalón, si se puede promover ahora o qué lo frena. Es lo que se mira después de importar_agente y antes de promover_agente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de listar_agentes. |

### `listar_agentes`

_alcance: lectura · sólo lee · idempotente_

Los agentes del tenant, con su oficio y cuántas herramientas tienen habilitadas.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `transferir_agente`

_alcance: escritura · idempotente_

Cambia el dueño de un agente, una conexión o una fuente del Cerebro dentro de la organización. Lo hace el dueño actual, un técnico o un admin; quien recibe tiene que ser admin, técnico o desarrollador con asiento vigente. Si el que entrega o el que recibe está recortado por agente, el recorte sigue al agente. Queda en el historial de traspasos y en la bitácora.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clase` | `agente` · `conexion` · `fuente` | Qué se traspasa. Por defecto `agente`. |
| `objeto_id` **(requerido)** | string | El id del agente (listar_agentes), la conexión (listar_herramientas) o la fuente (listar_fuentes). |
| `a_usuario` **(requerido)** | string | El id de la persona que recibe, de `listar_equipo` o `quien_soy`. |
| `motivo` **(requerido)** | string | Por qué; queda en el historial. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `eliminar_agente`

_alcance: escritura · destructiva · idempotente_

Borra el agente de verdad: versiones, despliegues, casos, evaluaciones, memorias, canales, automatizaciones y llamadas, y también sus conversaciones (el chat con cada persona y los mensajes de sus canales). No se puede deshacer. Las tareas que hizo quedan, sin agente ni versión, porque son de quien las pidió y del consumo de la organización. Si era el copiloto de alguien, esa persona se queda sin copiloto. Queda el evento `agente.eliminado` en la auditoría.
Sólo un admin, sólo si el agente está en descanso (`editar_agente` con `activo: false`) y sin tareas corriendo, y con `confirmar` igual a su nombre. Si lo que querés es que deje de trabajar sin perder nada, mandalo a descanso: no cuenta para el plan.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |
| `confirmar` **(requerido)** | string | El nombre del agente, tal cual lo devuelve `listar_agentes`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `traspasar_agentes`

_alcance: escritura · idempotente_

Traspasa de una vez todos los agentes, conexiones y fuentes que una persona tiene a su nombre. Es lo que se hace antes de sacar a un desarrollador del equipo o cuando termina un consultor. Sólo técnico o admin. Cada objeto deja su propio traspaso en el historial.

| Argumento | Tipo | Qué es |
|---|---|---|
| `de_usuario` **(requerido)** | string | Quién entrega. |
| `a_usuario` **(requerido)** | string | Quién recibe: admin, técnico o desarrollador con asiento vigente. |
| `motivo` **(requerido)** | string | Por qué; queda en el historial. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `historial_de_traspasos`

_alcance: lectura · sólo lee · idempotente_

Los traspasos de propiedad de la organización: clase, objeto, de quién, a quién, quién lo hizo, por qué y cuándo. Se puede acotar a un objeto.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clase` | `agente` · `conexion` · `fuente` | Sólo los traspasos de esa clase de objeto. |
| `objeto_id` | string | Sólo los traspasos de ese objeto. |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `ranking_de_agentes`

_alcance: lectura · sólo lee · idempotente_

Lo mismo que la pantalla Ranking: los agentes de la organización comparados por lo que la verificación dio por bueno en los últimos `dias` (30 por defecto), no por tokens. Por agente: tareas, `verificadas` {n, de, tasa} sobre sus tareas, `sin_discrepancia` {n, de, tasa} sobre las medidas, costo por tarea y `crecimiento` contra el período anterior (`nuevo` si antes no trabajaba; null si no hay con qué comparar).
`orden`: verificadas (por defecto), discrepancias (menos discrepancias primero), costo_por_tarea (más barato primero) o crecimiento. Un agente sin tareas va al final; una tasa sin denominador es null, no 100 %. El gasto entero se mira en `consumo_por_esfuerzo`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `orden` | `verificadas` · `discrepancias` · `costo_por_tarea` · `crecimiento` | Por qué ordenar: verificadas, discrepancias, costo_por_tarea o crecimiento. Por defecto verificadas, como la pantalla. |
| `dias` | number | Cuántos días mirar, de 1 a 90. Por defecto 30, como la pantalla. |

### `agentes`

_alcance: lectura · sólo lee · idempotente_

Los agentes de la organización con su id, si están activos y cómo vienen trabajando en los últimos 30 días. Es por dónde se empieza: el resto de las herramientas de lectura piden un `agente_id`.

Sin argumentos.

### `resumen_de_agente`

_alcance: lectura · sólo lee · idempotente_

Cómo viene trabajando un agente en una ventana de días: cuántas tareas, cuántas pasaron verificación a la primera y sobre cuántas medidas, cuántas discrepancias, cuánto costó, cuánto tardó la mediana, y cuántas tareas están esperando a una persona.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `agentes`. |
| `dias` | number | Ventana en días. Por defecto 30. |

### `tareas_del_agente`

_alcance: lectura · sólo lee · idempotente_

Las tareas de un agente, de la más nueva a la más vieja, con su veredicto. El corte `espera` son las que reclaman a una persona y `discrepancia` las que el verificador contradijo: son las dos preguntas que se hacen todos los días.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente. |
| `corte` | string | todas \| abiertas \| espera \| discrepancia \| cerradas. Por defecto todas. |
| `limite` | number | Cuántas traer. Máximo 30. |

### `calidad_del_agente`

_alcance: lectura · sólo lee · idempotente_

Lo que dicen los criterios sobre un agente en las últimas horas: la tasa de la auditoría de bitácora, cuánto coinciden las personas con el auditor, qué dice el juez con su costo aparte, y qué criterios no cubre nadie.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente. |
| `horas` | number | Ventana en horas. Por defecto 24. |


## Probar

Evaluaciones: ensayos, casos y la prueba con traza. Área de búsqueda: `evaluaciones`.

### `ensayar_y_publicar`

_alcance: escritura_

El camino a producción en una llamada: corre la evaluación de la versión actual contra todos sus casos habilitados y, cuando se mide el último, si pasaron todos la sube hasta producción con tu firma — o deja el pedido de firma si la organización pide cuatro ojos. Si algún caso falla, no sube nada y queda escrito qué caso y por qué. Llega un correo cuando termina; `camino_a_produccion` lo muestra en `publicacion`. Sin casos habilitados no corre: para subir sin evaluación está `promover_agente`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de listar_agentes. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `cargar_caso`

_alcance: escritura_

Guarda un caso para ensayar al agente: una entrada y, si se quiere, qué se espera de la salida y qué herramientas tiene que usar o no puede tocar. Nace habilitado. Un paquete importado con `importar_agente` trae los suyos.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de listar_agentes. |
| `titulo` **(requerido)** | string | Qué prueba este caso, en una línea. |
| `entrada` **(requerido)** | object | Los datos con los que entra el agente: lo mismo que pediría `pedir_tarea`. |
| `esperado` | lista | Aserciones sobre `salida.json`: `{ campo, operador, valor }` con operador igual, contiene, existe, falta o entre (`entre` lleva `valor` y `hasta` numéricos). El campo va con puntos: `cotizacion.total`. |
| `herramientas_esperadas` | lista | Herramientas que el agente tiene que usar. |
| `herramientas_prohibidas` | lista | Herramientas que no puede tocar. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_casos`

_alcance: lectura · sólo lee · idempotente_

Los casos del agente, habilitados y deshabilitados, con qué esperan. Los ids sirven para `ensayar_agente(casos)`, `habilitar_caso` y `deshabilitar_caso`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de listar_agentes. |
| `solo_habilitados` | boolean | Sólo los que entrarían en un ensayo. |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `habilitar_caso`

_alcance: escritura · idempotente_

Prende un caso deshabilitado: vuelve a entrar en los ensayos. No cambia nada más del caso.

| Argumento | Tipo | Qué es |
|---|---|---|
| `caso_id` **(requerido)** | string | El caso, de listar_casos. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `deshabilitar_caso`

_alcance: escritura · idempotente_

Apaga un caso: deja de entrar en los ensayos pero queda con su historia, para volverlo a prender. Es lo que se usa para iterar de a diez: se apagan los que todavía no se trabajan y se prenden a medida que se suman.

| Argumento | Tipo | Qué es |
|---|---|---|
| `caso_id` **(requerido)** | string | El caso, de listar_casos. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `probar_agente`

_alcance: escritura_

Corre el agente UNA vez en prueba (dev o staging, nunca prod) y espera el resultado: estado, costo, turnos, herramientas usadas con sus argumentos ya redactados, bloqueos, citas al Cerebro y el veredicto del verificador independiente. El agente no puede pedir más presupuesto ni más turnos que los suyos. Si el worker no la cierra en el plazo, devuelve el estado parcial y el id para seguirla con `ver_traza`. Antes de gastar, mide si `como_se_verifica` se puede releer con las lecturas de la caja y lo devuelve en `criterio_de_verificacion` (con `aviso_verificacion` si no); el veredicto del verificador viene en `verificacion`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |
| `entrada` | object | Los datos que el agente declara en su formulario. |
| `titulo` | string | Qué se prueba, en una línea. Opcional. |
| `ambiente` | `dev` · `staging` | Dónde corre. Por defecto `dev`. |
| `presupuesto_usd` | number | Tope de esta corrida en dólares. Sólo puede ser menor que el del agente. |
| `max_turnos` | number | Máximo de turnos del modelo. Sólo puede ser menor que el del agente; techo 50. |
| `espera_s` | number | Cuánto esperar el cierre, en segundos (5 a 120). Por defecto 60. |
| `en_seco` | boolean | Corrida en seco: las herramientas con efecto se anotan y no se ejecutan; las lecturas corren. Sólo dev/staging. Lo decide quien prueba; el agente no puede cambiarlo. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |


## Equipos y reparto

Equipos de agentes, partir una tarea entre varios, pedirle algo a un par, ver el árbol y cuánta autonomía tiene el equipo técnico sobre cada proyecto. Área de búsqueda: `equipos`.

### `fijar_autonomia_del_proyecto`

_alcance: escritura · idempotente_

Fija qué hace el agente programador con el trabajo verificado de un proyecto: `shadow` (0 · Sombra, propone y el cambio queda en YoRobot), `assisted` (1 · Asistido, tampoco publica), `delegated` (2 · Delegado, abre el PR y lo mergea una persona) o `gated_auto` (3 · Autónomo con gate: abre el PR y se mergearía solo con verificación, CI y revisión en verde, pero el worker todavía no corre la revisión, así que hoy también lo mergea una persona). Un equipo técnico recién instalado no abre PRs hasta que su proyecto llega a `delegated`. Bajar lo hace cualquier operador; subir, un técnico o un admin; `gated_auto` sólo un admin y nunca en un proyecto de cara al cliente. Rige desde el próximo pedido y queda en la auditoría con el antes y el después. La respuesta dice `abre_pr` y `mergea_solo` con el nivel que rige.

| Argumento | Tipo | Qué es |
|---|---|---|
| `proyecto_id` | string | El id del proyecto. O `repo`. |
| `repo` | string | El repositorio del proyecto, `owner/nombre`. O `proyecto_id`. |
| `nivel` **(requerido)** | `shadow` · `assisted` · `delegated` · `gated_auto` | El nivel nuevo. |
| `motivo` | string | Opcional: por qué, para la auditoría. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `declarar_equipo`

_alcance: escritura · idempotente_

Crea o actualiza un equipo de agentes: un líder que recibe el pedido y reparte, especialistas, y la matriz de a quién le puede pedir cada uno. Con la misma `clave` se ACTUALIZA en vez de crear otro, así que se puede aplicar dos veces. El equipo ANGOSTA: sus topes se combinan con los del agente y gana el más chico, y su matriz limita a quién se le puede pedir. Ojo: declarar el equipo NO le prende el reparto al líder — eso es aflojar y lo decide un técnico o un admin con `editar_agente`; la respuesta avisa si falta.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clave` **(requerido)** | string | Clave estable del equipo, única en la organización («redes»). |
| `nombre` **(requerido)** | string | Cómo se lo va a llamar en la pantalla. |
| `lider_agente_id` **(requerido)** | string | El agente que recibe el pedido y reparte. |
| `presupuesto_arbol_usd` | number | null | Techo en USD para TODA la tarea del equipo, hijas incluidas. Es el único techo agregado que existe: sin él, seis hijas respetan prolijamente su presupuesto individual y el total no lo autorizó nadie. `null` lo saca. |
| `profundidad_max` | number | Niveles de reparto (1 a 10, por defecto 2). |
| `hijas_max` | number | Hijas por reparto (1 a 20, por defecto 6). |
| `activo` | boolean | false apaga el equipo: no se le pueden pedir tareas nuevas. |
| `miembros` | lista | Los miembros, reemplazan a los que había (se DECLARA el equipo, no se parchea: un miembro que sacaste del archivo tiene que desaparecer de la base). Cada uno: {agente_id, rol?, puede_pedirle_a?}. `puede_pedirle_a` son ids de OTROS miembros del equipo. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_equipos`

_alcance: lectura · sólo lee · idempotente_

Los equipos de la organización con su líder, sus miembros, la matriz de delegación y sus topes.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `ver_equipo`

_alcance: lectura · sólo lee · idempotente_

Un equipo por clave o por id: líder, miembros con su rol, a quién le puede pedir cada uno, y los topes.

| Argumento | Tipo | Qué es |
|---|---|---|
| `equipo` **(requerido)** | string | La clave del equipo («redes») o su id. |

### `exportar_equipo`

_alcance: lectura · sólo lee · idempotente_

El equipo entero como paquete portable: los agentes por CLAVE (no por id, porque en otra organización los ids son otros) y la matriz reescrita con esas claves. Trae además lo que el equipo usa: las automatizaciones que le piden a él o a sus agentes, las consolas publicadas de sus agentes, las entidades de Datos que esas consolas y automatizaciones miran, y el proyecto del líder. Sin credenciales ni secretos: viajan los nombres de las herramientas y «tiene un webhook», no su URL. Lo que sale de acá entra por `importar_equipo` tal cual.

| Argumento | Tipo | Qué es |
|---|---|---|
| `equipo` **(requerido)** | string | La clave del equipo o su id, de `listar_equipos`. |

### `importar_equipo`

_alcance: escritura · idempotente_

Crea o actualiza un equipo entero desde un paquete: primero las entidades de Datos y el proyecto que el paquete declare, después cada agente por su clave —la segunda vez se le deja una versión nueva en vez de crear otro—, la matriz, las automatizaciones (que NACEN APAGADAS) y la consola (nueva se publica; si ya estaba publicada y cambia, queda propuesta). Aplicar el mismo paquete dos veces deja la organización igual y la respuesta dice `sin_cambios: true`. También dice qué herramientas nombra el paquete que esta organización no tiene declaradas, si al líder le falta prender el reparto, y la URL y el secreto de cada webhook NUEVO — una sola vez.

| Argumento | Tipo | Qué es |
|---|---|---|
| `paquete` **(requerido)** | object | El paquete, como lo devuelve `exportar_equipo` o como está en el bloque `equipo:` de yorobot.yaml. |
| `sin_faltantes` | boolean | true para que los agentes nazcan sin las herramientas que esta organización no tiene declaradas, en vez de rechazar el paquete. Por defecto false: un nombre mal tipeado no deja a un agente sin su herramienta en silencio. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `descomponer_tarea`

_alcance: escritura · idempotente_

Parte una tarea en tareas hijas, cada una con UN agente responsable. La madre queda bloqueada por las hijas y se despierta cuando terminan, con lo que cada una devolvió. Es idempotente por el conjunto de claves: volver a llamarla con el mismo plan no duplica nada y contesta `ya_estaba`. Los límites del agente de la madre (profundidad y cuántas hijas por vez) y el presupuesto del árbol se aplican igual acá que cuando reparte el agente solo.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | La tarea que se reparte. Es la que va a esperar a las hijas. |
| `hijas` **(requerido)** | lista | Las hijas. Cada una: {clave, titulo, descripcion, agente_id, entrada?, bloquea?}. `clave` es un nombre corto y estable del paso: es lo que permite reanudar sin duplicar. `bloquea: false` si la madre puede seguir sin esperarla. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `mandar_mensaje`

_alcance: escritura_

Crea una tarea para otro agente con un pedido puntual adentro: coordinación lateral, no reparto. No entra al árbol de quien pide —a propósito, porque el destinatario puede no tener permiso para leerlo—, así que el pedido tiene que ser autocontenido. Cuesta cuota de `mensajero`: dos agentes que se mandan pedidos son la forma más barata de un bucle que se paga por vuelta.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | La tarea desde la que se pide. Queda como origen del pedido. |
| `agente_id` **(requerido)** | string | El agente al que se le pide. |
| `titulo` **(requerido)** | string | De qué se trata, en una línea. |
| `descripcion` **(requerido)** | string | El pedido completo, autocontenido. Mínimo 30 caracteres. |
| `bloquea` | boolean | Si quien pide no puede seguir sin la respuesta. Por defecto no. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `ver_comunicacion`

_alcance: lectura · sólo lee · idempotente_

El hilo de una tarea que se repartió: quién repartió qué, quién le pidió algo puntual a quién, qué volvió con su veredicto y qué espera una firma, en orden, con el costo de cada tramo. No es un chat: son los actos que quedaron registrados. Sirve para contestar «quién autorizó a quién a gastar cuánto» sin leer la bitácora cruda.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | Cualquier tarea del árbol: el hilo se arma desde la raíz. |

### `arbol_de_tarea`

_alcance: lectura · sólo lee · idempotente_

La madre y las hijas de una tarea, con estado en castellano, si el VERIFICADOR la dio por hecha, si se canceló, cuánto costó y cuáles siguen bloqueando. `verificada` no es lo mismo que terminada: una hija puede estar cerrada sin que nadie la haya comprobado, y ahí su trabajo no se puede dar por hecho.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | La tarea desde la que se mira el árbol. |

### `armar_vigia_de_mercado`

_alcance: escritura · idempotente_

Arma (o devuelve, si ya existe) el Vigía de mercado de quien llama: el sub-agente de su copiloto que sale a internet a buscar noticias, competidores, estrategias e ideas, y vuelve con recomendaciones citadas. Sólo lee: busca y lee páginas públicas por el portal, nunca escribe, publica ni manda nada, y corre contenido porque lo que lee lo escribió un tercero.
Lo suma al equipo del copiloto y, salvo `semanal: false`, programa una automatización del copiloto los lunes a las 8 (zona de la organización) que le reparte una vuelta por internet. Cada hecho del informe vuelve marcado `comprobado` sólo si su cita está en la página que el portal le trajo en esa tarea. Pide un copiloto prendido; lo arma un técnico o un admin.

| Argumento | Tipo | Qué es |
|---|---|---|
| `semanal` | boolean | false para no programar la vuelta de los lunes. Por defecto, true. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `pedir_al_vigia`

_alcance: escritura_

Le pide al Vigía de mercado una búsqueda ahora, sin esperar al lunes. La tarea es del copiloto: le reparte al Vigía y recibe su informe ya comprobado (hechos con url, fuente, fecha de publicación y de consulta; señales, inferencias y recomendaciones con confianza y si requieren aprobación). Seguila con `estado_de_tarea`. Antes, `armar_vigia_de_mercado`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `pregunta` **(requerido)** | string | Qué querés que busque afuera, en una o dos oraciones («qué están haciendo los competidores de VelaFi en cobranzas»). |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |


## Copilotos por persona

El perfil de cada persona —canal, hora, intereses—, su copiloto, su North Star medido y el briefing diario con sus decisiones. Área de búsqueda: `copilotos`.

### `mi_perfil`

_alcance: lectura · sólo lee · idempotente_

Tu perfil en esta organización para tu copiloto: por qué canal te llega el briefing (portal, correo, WhatsApp, Slack, Telegram, Teams) y a qué hora, en qué zona e idioma, qué temas querés ver y cuáles evitar, y cuál es tu copiloto.
`entrega` dice por dónde te llega HOY y, si no es tu canal, por qué: un WhatsApp o un Slack sin vincular no recibe nada hasta que mandes el código desde ahí (`editar_mi_perfil` con `vincular: true`).
Quien opera puede pedir el de otra persona con `persona` (su correo).

| Argumento | Tipo | Qué es |
|---|---|---|
| `persona` | string | El correo de otra persona de la organización (sólo admin o técnico). Vacío: el tuyo. |

### `editar_mi_perfil`

_alcance: escritura · idempotente_

Cambia tu perfil: `canal` (portal, app —los avisos al teléfono de la app—, email, whatsapp, slack, telegram, teams), `direccion` (tu WhatsApp con código de país, tu id de Slack «U…», tu chat de Telegram), `hora` (HH:MM, 24 h), `zona` (IANA, «America/Argentina/Buenos_Aires»), `idioma`, `pais` (ISO-2) e `intereses` ({ temas, evitar, longitud: corta|media|larga }).
Cambiar el canal o la dirección la deja SIN VINCULAR. Con `vincular: true` devuelve un código de un solo uso: mandalo desde ese canal al copiloto de la organización y recién ahí el briefing te llega por ahí y podés elegir decisiones contestando. Así nadie pone su número en tu perfil y firma por vos.
Con hora, zona y copiloto, tu briefing diario queda programado solo. Quien opera edita el de otra persona con `persona` (su correo): queda sin vincular hasta que esa persona mande su código.

| Argumento | Tipo | Qué es |
|---|---|---|
| `persona` | string | El correo de otra persona (sólo admin o técnico). Vacío: el tuyo. |
| `canal` | string | portal, app, email, whatsapp, slack, telegram o teams. `app` avisa al teléfono donde activaste los avisos de la app (app.yorobot.ai → Yo). |
| `direccion` | string | Tu dirección en ese canal. No va con portal ni email (el correo es el de tu usuario). |
| `hora` | string | La hora del briefing, HH:MM en 24 horas. |
| `zona` | string | Tu zona horaria IANA. |
| `idioma` | string | es, en, pt… |
| `pais` | string | Código de dos letras: AR, CL, MX… |
| `intereses` | object | { "temas": ["caja", "competencia"], "evitar": ["fútbol"], "longitud": "corta" }. |
| `silencio_desde` | string | Desde qué hora no te interrumpe tu copiloto (HH:MM, en tu zona). Va con `silencio_hasta`; los dos en null lo sacan. |
| `silencio_hasta` | string | Hasta qué hora (HH:MM). Puede cruzar la medianoche: 22:00 a 07:00. |
| `avisos_por_dia` | number | Cuántos avisos por día acepta (0 a 20; por defecto 3). Lo que sobra te llega en el briefing. |
| `vincular` | boolean | Devolver el código para vincular el canal. Sólo para tu propio perfil. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `asignar_copiloto`

_alcance: escritura · idempotente_

Le asigna a una persona su copiloto: el agente de proceso que le escribe el briefing y al que le contesta. Varias personas pueden compartir el mismo agente —cada corrida lleva el perfil de su persona—, que es lo que se sostiene en el tiempo; un agente por persona, no. Con `agente_id` vacío se lo saca. Si la persona ya tiene hora y zona, su briefing diario queda programado.

| Argumento | Tipo | Qué es |
|---|---|---|
| `persona` **(requerido)** | string | El correo de la persona. |
| `agente_id` | string | El agente, de `listar_agentes`. Vacío para sacárselo. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `programar_briefings`

_alcance: escritura · idempotente_

Deja al día la rutina diaria del briefing de cada persona con copiloto: a SU hora, en SU zona, prendida si tiene copiloto, hora y zona, y apagada si le falta alguno. Es lo mismo que pasa solo al editar un perfil; sirve después de un alta en tanda. Devuelve cada persona con su hora, su zona y si quedó programada, y por qué no si no.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_objetivos`

_alcance: lectura · sólo lee · idempotente_

Cada North Star con su número de hoy, ya medido por el sistema: `valor` y `meta` con su unidad, `falta`, `avance_pct`, `va_bien` (null = todavía no se sabe) con `va_bien_por`, la `proyeccion_a_fecha_meta` marcada estimada, `medido_at`, la `cita` de dónde sale el número, y `no_pude_medir` si la última medición falló. Más sus métricas de entrada y sus contramétricas (`cruzo_el_umbral`).
Ves el tuyo y el de la organización; quien opera ve además el de cada persona. No sumes ni proyectes vos: está calculado.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `ver_objetivo`

_alcance: lectura · sólo lee · idempotente_

Un North Star con lo mismo que `listar_objetivos`, más cómo se mide (`como_se_mide`), su definición (`metrica`, `entradas`, `contrametricas`, `limites`, `cadencia`) y su `version`. Sin `objetivo_id`, el tuyo.

| Argumento | Tipo | Qué es |
|---|---|---|
| `objetivo_id` | string | El id, de `listar_objetivos`. Sin él, tu North Star. |

### `definir_objetivo`

_alcance: escritura · idempotente_

El North Star: el número que, si mejora este trimestre, sabés que te fue bien. Se mide contra una fuente que el sistema sabe leer —una entidad de Datos, una lectura del copiloto o la carga manual— y el número lo calcula el servidor, nunca el modelo.
Sin `guardar: true` es la vista previa: valida la métrica contra las fuentes (la entidad, el campo y la herramienta existen y el copiloto los lee) y la MIDE una vez, sin guardar nada: `hoy` dice «Hoy está en US$ 740.000. La meta de US$ 1.200.000 es +62 % en 91 días». Con `guardar: true` queda como tu North Star, arrancando con ese valor. El de la organización lo fija un admin en su conversación con el copiloto: por acá nadie entra como admin.
Uno activo por persona: definirlo de nuevo lo CAMBIA, y si cambia la métrica o la meta es una versión nueva (queda en la bitácora). Lo persigue tu copiloto, o el agente de `agente_id`. Hasta 3 `entradas` (lo que lo mueve) y 2 `contrametricas` (lo que no puede empeorar, con su `umbral`). `limites` es lo que el copiloto no puede hacer para llegar: contexto, no permiso.

| Argumento | Tipo | Qué es |
|---|---|---|
| `titulo` **(requerido)** | string | El número en tus palabras: «Pipeline calificado de Chile en Q4». |
| `porque` | string | Por qué ese número, en una línea. |
| `metrica` **(requerido)** | object | Contra qué se mide. De Datos: { "fuente": "datos", "entidad", "agregado": "suma"\|"cuenta"\|"promedio"\|"ultimo"\|"proporcion" (el % de los registros con "campo" lleno; va con "unidad": "%", y sin registros que contar queda «no pude medir», no 0 %), "campo" (no hace falta para cuenta), "estado"?: el estado del registro ("demo"), o "estados"?: varios (["lead", "demo"]), "filtro"?: [{ "campo", "op", "valor" }] (o como en los bloques: { "campo", "igual" }), "ventana"?: "todo" (por defecto: el saldo de hoy) \| "semana" \| "mes" \| "trimestre" \| "desde" (con "desde": AAAA-MM-DD), "fecha"?: por qué fecha corta la ventana ("creado", "actualizado" o un campo fecha), "unidad": moneda ISO \| "%" \| "cantidad", "sentido": "subir" \| "bajar" }. De una lectura del copiloto: { "fuente": "herramienta", "herramienta", "args", "ruta": dónde está el número en la respuesta ("total", "data.items[0].monto"), "unidad", "sentido" }. Sin fuente que lo calcule: { "fuente": "manual", "unidad", "sentido" }. |
| `meta` **(requerido)** | number | La meta, en la unidad de la métrica. |
| `linea_base` | number | Desde dónde se cuenta el avance. Sin ella, la primera medición. |
| `fecha_meta` | string | Para cuándo (AAAA-MM-DD). |
| `cadencia` | `diaria` · `semanal` | Cada cuánto lo mide el sistema (por defecto diaria). |
| `entradas` | lista | Hasta 3 métricas que lo mueven: [{ "nombre", "metrica" }]. |
| `contrametricas` | lista | Hasta 2 que no pueden empeorar: [{ "nombre", "metrica", "umbral" }]. |
| `limites` | string | Lo que el copiloto no puede hacer para llegar («no ofrecer descuento arriba de 10 %»). |
| `agente_id` | string | El agente que lo persigue. Sin él, tu copiloto. |
| `padre_id` | string | El objetivo de arriba del que cuelga (opcional), de `listar_objetivos`. |
| `guardar` | boolean | true lo guarda; sin él es la vista previa (mide y no guarda). |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `medir_objetivo`

_alcance: escritura_

Mide ahora un North Star (el tuyo, sin `objetivo_id`) y devuelve cómo quedó. Uno de carga manual se mide con el `valor` que mandás (lo carga su dueña); uno que mide el sistema no acepta un valor a mano. Si no se pudo medir, la falla queda escrita (`no_pude_medir`) y el último valor bueno sigue a la vista.

| Argumento | Tipo | Qué es |
|---|---|---|
| `objetivo_id` | string | El id, de `listar_objetivos`. Sin él, tu North Star. |
| `valor` | number | Sólo para uno de carga manual: el número de hoy. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `pausar_objetivo`

_alcance: escritura · idempotente_

Pausa un North Star (deja de medirse y de viajar al copiloto) o, con `pausar: false`, lo reanuda. No borra nada. Uno activo por persona: para reanudar uno, el otro tiene que estar pausado. El tuyo lo pausás vos; el de la organización, un admin.

| Argumento | Tipo | Qué es |
|---|---|---|
| `objetivo_id` | string | El id, de `listar_objetivos`. Sin él, tu North Star. |
| `pausar` | boolean | true (por defecto) lo pausa; false lo reanuda. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `configurar_despertadores`

_alcance: escritura · idempotente_

De día tu copiloto se despierta por tu North Star y te avisa, con cuota: `despertadores` es la lista de lo que lo despierta — { "tipo": "umbral", "serie": "principal"|"entrada:0"…|"contra:0"…, "operador": "<"|"<="|">"|">=", "valor" } · { "tipo": "fuente_viva", "temas"?: [..] } (algo nuevo en una fuente viva de la organización que toca tus temas) · { "tipo": "evento", "entidad", "a"?: estado } (un registro de Datos que cambia de estado) · { "tipo": "decision_vence", "horas"? } · { "tipo": "reloj", "hora": "HH:MM" }. Una contramétrica que cruza su umbral lo despierta siempre, y es urgente.
`escalon`: investigar (sólo avisa), borrador (te deja la tarea armada para aprobar) o piloto (hace lo que se deshace y no mueve plata sin tu aprobación, y te lo cuenta). Lo irreversible lo firmás siempre vos. Cada despertar pasa antes por una evaluación barata: si no importa para tu número, no te escribe. Lo que cae en tu silencio o pasa tu cuota de avisos (`editar_mi_perfil`) te llega en el briefing.

| Argumento | Tipo | Qué es |
|---|---|---|
| `objetivo_id` | string | Tu North Star, de `listar_objetivos`. Sin él, el tuyo. |
| `despertadores` | lista | Hasta 6; reemplaza los que había. [] los saca. |
| `escalon` | `investigar` · `borrador` · `piloto` | Qué hace cuando se despierta. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `ver_diario_de_sueno`

_alcance: lectura · sólo lee · idempotente_

La noche de tu copiloto (la última, o la de `fecha`): si durmió, se salteó (no hubo nada que repasar: costo cero) o no terminó, y por qué; el `diario` con cada oración marcada `con_evidencia` o `es_inferencia`; lo que aprendió con quién lo decide (`lo_decide`: vos, si es una preferencia tuya; un admin o un técnico, si es del negocio); el `plan` de hoy con su impacto (`impacto_es_estimado: true`), su costo estimado, si es `reversible` y qué encargaría «Hacerlo»; las `preguntas`; las `lecturas` que dejó preparadas, ya calculadas; y la `autoevaluacion` de lo que propuso ayer (efecto verificado o coincidencia).
Dormir no es actuar: de noche sólo lee y propone. Las propuestas se eligen como cualquier decisión (`elegir_decision`).

| Argumento | Tipo | Qué es |
|---|---|---|
| `fecha` | string | AAAA-MM-DD, en tu zona. Sin ella, la última noche. |

### `configurar_sueno`

_alcance: escritura · idempotente_

Tu noche: `prendido` (true/false), `hora` (HH:MM en tu zona; corre siempre antes de tu briefing, y si la pedís después se corre a 3 horas antes y te lo dice `corrida`) y `tope_usd` (lo que puede gastar una noche, entre US$ 0,05 y US$ 5). Sin nada para cambiar, es error. Devuelve cómo quedó: la hora real, si va a dormir esta noche (`duerme`) y por qué no, y el techo del mes de la organización (provisorio).

| Argumento | Tipo | Qué es |
|---|---|---|
| `prendido` | boolean | false la apaga; true la prende. |
| `hora` | string | HH:MM, en tu zona (por defecto 02:00). |
| `tope_usd` | number | Lo que puede gastar una noche (por defecto US$ 0,50). |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_aprendizajes`

_alcance: lectura · sólo lee · idempotente_

Cada cosa que propuso aprender tu copiloto de noche, con cómo está hoy (`propuesto`, `guardado`, `descartado`, `frenado`), quién lo decide (`lo_decide`) y cuántas evidencias del día la respaldan. `estado` filtra: `propuesta`, `activa` o `todas` (por defecto). Tus preferencias se guardan con `aceptar_aprendizaje`; lo del negocio lo acepta un admin o un técnico en Memoria.

| Argumento | Tipo | Qué es |
|---|---|---|
| `estado` | `propuesta` · `activa` · `todas` | Cuáles (por defecto todas). |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `aceptar_aprendizaje`

_alcance: escritura · idempotente_

Guarda una preferencia tuya que tu copiloto aprendió de noche (de `listar_aprendizajes` o `ver_diario_de_sueno`): desde ahí viaja a lo que trabaja para vos, y a nadie más. Con `contenido`, la guarda editada; el texto vuelve a pasar por el filtro de memorias (sin órdenes al modelo, credenciales ni datos de contacto). Sólo las tuyas: lo del negocio lo acepta un admin o un técnico en Memoria.

| Argumento | Tipo | Qué es |
|---|---|---|
| `memoria_id` **(requerido)** | string | El id del aprendizaje. |
| `contenido` | string | Cómo querés que lo recuerde, si no tal cual. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `rechazar_aprendizaje`

_alcance: escritura · idempotente_

Descarta una preferencia tuya que propuso tu copiloto, o la olvida si ya estaba guardada: deja de viajar en la próxima corrida. Queda la constancia en la bitácora. Sólo las tuyas.

| Argumento | Tipo | Qué es |
|---|---|---|
| `memoria_id` **(requerido)** | string | El id del aprendizaje. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |


## Tareas

Pedir trabajo, seguirlo, leer su traza, las fallas que se repiten, preguntarle algo a un agente, tu conversación con cada agente, tus recordatorios y ver qué espera aprobación. Área de búsqueda: `trabajo`.

### `pedir_tarea`

_alcance: escritura_

Le pide una tarea a un agente, o a un EQUIPO de agentes. La ejecuta un worker; esto sólo la encola. Con `equipo` la tarea va al líder y nace con el presupuesto de árbol del equipo; con `agente_id` va a ese agente y sin techo agregado, que es el comportamiento de siempre.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` | string | El id del agente, de `listar_agentes`. Uno de los dos: `agente_id` o `equipo`. |
| `equipo` | string | La clave del equipo («redes»), de `listar_equipos`. La tarea va a su líder, que la reparte entre los miembros según la matriz, con el presupuesto de árbol del equipo como techo de todo. |
| `titulo` **(requerido)** | string | Qué se le pide, en una línea. |
| `entrada` | object | Los datos que el agente declara en su formulario. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `preguntar_a_agente`

_alcance: escritura_

Le hace UNA pregunta a un agente y devuelve su respuesta en segundos, sin crear una tarea: el agente contesta sólo con sus herramientas de LECTURA (también las que leen la base del cliente conectada con `conectar_base`), con su instrucción y su memoria. No cambia nada afuera: si la pregunta pide algo que escribe, la respuesta trae `requiere_tarea` y hay que usar `pedir_tarea`. Un agente que también tiene herramientas que escriben contesta por acá sólo con `solo_lectura: true`. Si tarda más que `espera_s`, devuelve `consulta_id`: volvé a llamar con ese id (sin `pregunta`) para leer la respuesta. Cuenta contra el tope diario de charla del sujeto.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |
| `pregunta` | string | Lo que se le pregunta, en lenguaje natural. |
| `historia` | lista | Turnos anteriores de esta conversación, si los hay, en orden: {de: "persona" \| "agente", texto}. La pregunta va aparte. |
| `solo_lectura` | boolean | Para un agente que también escribe: contestar sólo con sus lecturas. Lo que escribe no se ejecuta nunca por acá. |
| `sujeto` | string | De parte de quién se pregunta (la empresa, el cliente). El tope diario se cuenta contra esto; si falta, contra el agente. |
| `espera_s` | number | Cuánto esperar la respuesta, en segundos (5 a 60). Por defecto 45. |
| `consulta_id` | string | Para retomar una consulta que devolvió `termino: false`. Con esto no hace falta `pregunta`. La retoma sólo la persona que la pidió, y la respuesta se guarda 24 h. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_hilos`

_alcance: lectura · sólo lee · idempotente_

Tu bandeja: cada agente al que llegás, con tu conversación con él si ya le escribiste —el último mensaje, cuándo, y cuántos tenés sin leer—. Primero las fijadas y las que tienen algo sin leer, después las más recientes.
Es la misma conversación que ves en la app: lo que escribas con `escribir_en_hilo` aparece ahí, y al revés. Para leer una entera, `ver_hilo`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `ver_hilo`

_alcance: lectura · sólo lee · idempotente_

Tu conversación con un agente, en orden: tus mensajes y los suyos (con los nombres de lo que leyó para contestar), las tareas que encargó desde la charla con su estado, y los briefings que te entregó como copiloto con sus decisiones (`pendiente`, `vencida` y, por opción, `se_firma_en_el_portal`).
Sólo la tuya: nadie —tampoco un admin— lee la conversación de otra persona. Con `antes` (el `cuando` del primer item que ya tenés) trae la página anterior. Leerla no la marca como leída.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_hilos` o `listar_agentes`. |
| `antes` | string | Para la página anterior: el `cuando` (ISO) del primer item que ya tenés. |
| `limite` | number | Cuántos items traer. Por defecto 50, máximo 200. |

### `escribir_en_hilo`

_alcance: escritura_

Le escribís a un agente en TU conversación con él —la misma de la app— y te contesta en segundos con sus herramientas de lectura y la versión publicada en producción. Si lo que pedís es trabajo (algo que cambia datos), lo encarga como tarea: la respuesta trae `tarea_id`, y la tarea sigue el camino de siempre (worker, verificación y, si hace falta, aprobación). Con `como_tarea: true` va directo como tarea, sin charla.
Cuenta contra tu tope diario de charla con ese agente. Mandá `clave_de_pedido`: con la misma clave, un reintento no manda el mensaje dos veces ni encarga otra tarea (la respuesta completa queda en tu conversación: leela con `ver_hilo`). Estas herramientas piden un token que generaste vos: uno que otra persona emitió a tu nombre no abre tu conversación.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_hilos` o `listar_agentes`. |
| `texto` **(requerido)** | string | Lo que le escribís, en lenguaje natural. Hasta 4000 caracteres. |
| `como_tarea` | boolean | Mandarlo directo como tarea, sin charla: lo que escribís es el pedido. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `generar_pdf`

_alcance: escritura_

Arma un PDF con bloques de Datos —contador, tabla, lista, gráfico, línea de tiempo, mapa— que el servidor resuelve con tu alcance: los números los calcula el sistema, con el período en fechas y lo recortado dicho debajo de cada tabla. Los bloques son los mismos que un agente muestra en el chat, por ejemplo `{ "tipo": "grafico", "titulo": "Pedidos por estado", "entidad": "pedidos", "por": "estado", "periodo": "este_mes" }`.
El PDF queda como archivo en TU conversación con ese agente (lo ves en la app) y la respuesta trae el link para bajarlo con tu sesión, las páginas y el peso. Con `incluir_contenido: true`, además el PDF en base64 (hasta 2 MB).

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de `listar_hilos` o `listar_agentes`: el archivo queda en tu conversación con él. |
| `titulo` **(requerido)** | string | El título del documento. |
| `bloques` **(requerido)** | lista | Hasta 3 bloques de datos, como los del chat. |
| `texto` | string | Un párrafo que va arriba de los bloques. Opcional. |
| `incluir_contenido` | boolean | Devolver también el PDF en base64 (hasta 2 MB). |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_recordatorios`

_alcance: lectura · sólo lee · idempotente_

Los recordatorios que confirmaste en tus conversaciones con los agentes: qué dice cada uno (`que`), con qué agente, cuándo (`cuando`, con día, hora y zona: «todos los lunes a las 09:00 ART»), si `se_repite`, qué pasa a esa hora (`que_hace`: te llega el texto, o el agente te lo contesta con tus datos), el `estado` con sus booleanos (`activo`, `pausado`, `cumplido`), el `proximo` aviso y cómo te llegó el `ultimo_aviso` (por dónde, y si no llegó por tu canal, por qué).
Sólo los tuyos: nadie más los ve, tampoco un admin. `vivos` y `tope` dicen cuántos te quedan. Un recordatorio se crea proponiéndolo en el chat (`escribir_en_hilo`: «recordame el jueves a las 9 que…») y confirmándolo en la app; `propuestas_sin_confirmar` son las que un agente te propuso y todavía no existen.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `pausar_recordatorio`

_alcance: escritura · idempotente_

Pausa uno de tus recordatorios (deja de avisar hasta que lo reanudes) o, con `pausar: false`, lo reanuda. No borra nada. Uno de una sola vez cuyo momento pasó mientras estaba pausado no se reanuda: pedile al agente uno nuevo.

| Argumento | Tipo | Qué es |
|---|---|---|
| `recordatorio_id` **(requerido)** | string | El id, de `listar_recordatorios`. |
| `pausar` | boolean | true (por defecto) lo pausa; false lo reanuda. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `borrar_recordatorio`

_alcance: escritura · destructiva · idempotente_

Borra uno de tus recordatorios: deja de avisar y no vuelve (para frenarlo sin perderlo, `pausar_recordatorio`). Lo que ya te llegó queda en tu conversación con el agente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `recordatorio_id` **(requerido)** | string | El id, de `listar_recordatorios`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `ver_traza`

_alcance: lectura · sólo lee · idempotente_

Todo lo que quedó registrado de una tarea: cada tramo del modelo con duración y costo, cada herramienta con sus argumentos ya redactados y si el puente la dejó pasar, los bloqueos, las citas al Cerebro comprobadas y el veredicto del verificador. Sólo de tareas de agentes a los que la persona llega.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | El id de la tarea, de `probar_agente`, `pedir_tarea` o `listar_tareas`. |

### `ver_actividad`

_alcance: lectura · sólo lee · idempotente_

El hilo de actividad de un agente o de un registro, del más nuevo al más viejo: tareas pedidas y cerradas, tramos del modelo, herramientas con duración y costo, frenos y bloqueos, esperas a una persona, mensajes por canal, llamadas y registros movidos. Es el mismo flujo que la pantalla Actividad del agente, con los mismos filtros. Sólo de agentes y registros a los que la persona llega; el detalle viene recortado y sin argumentos crudos. Para una tarea puntual, `ver_traza` trae más.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` | string | El agente. Obligatorio si no se da `equipo_id` ni `registro_id`. |
| `equipo_id` | string | Un equipo (clave o id, de `listar_equipos`): los hechos de sus últimas corridas, el árbol entero —lo que hizo el líder y lo que hicieron las hijas—. Si se da, `agente_id` se ignora. |
| `registro_id` | string | Un registro de Datos: sólo lo que los agentes hicieron sobre él. Si se da, `agente_id` se ignora. |
| `clase` | string | Sólo hechos de esta clase (una o varias separadas por coma): tarea, modelo, herramienta, freno, verificacion, espera, mensaje, llamada, registro, cierre. |
| `herramienta` | string | Sólo hechos de esta herramienta. |
| `solo_errores` | boolean | Sólo lo que salió mal o se frenó. |
| `tarea_id` | string | Sólo lo de esta tarea. |
| `busca` | string | Una palabra del título o el detalle. |
| `limite` | number | Cuántos traer por página (1 a 100). Por defecto 50. |
| `desde` | number | Desde qué posición arrancar, para paginar. |

### `listar_tareas`

_alcance: lectura · sólo lee · idempotente_

Las tareas de los agentes a los que la persona llega, de la más nueva a la más vieja, con estado, ambiente, origen y su columna del tablero (`columna_texto`; frenada: `que_la_mueve`; madre: `hijas`; corriendo: `silencio`). Filtra por agente, estado, columna, ambiente o sólo abiertas. El total cuenta lo visible para esta persona.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` | string | Sólo las de este agente. |
| `estado` | string | Sólo las que están en este estado: new, dispatched, running, verified, in_review, approved, merged, needs_human, rejected o rehearsed. |
| `columna` | `pendiente` · `trabajando` · `te_espera` · `frenada` · `hecho` | Sólo las de esta columna. |
| `ambiente` | `dev` · `staging` · `prod` | Sólo las de este ambiente. |
| `abiertas` | boolean | Sólo las que todavía se mueven. |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `estado_de_tarea`

_alcance: lectura · sólo lee · idempotente_

En qué anda una tarea y qué midió el verificador, si ya corrió. `resultado`: lo que devolvió el agente (lo dice él, no la verificación). `conversacion`: el hilo con sus hijas, los últimos 30 turnos con el aviso adentro.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | El id que devolvió `pedir_tarea`. |

### `tareas_estancadas`

_alcance: lectura · sólo lee · idempotente_

Las tareas abiertas que no tienen quién las mueva: nadie las está corriendo, no esperan a una persona nombrada y no tienen despertador. Es la lista que contesta «esto está frenado y nadie se enteró», con desde cuándo.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `repetir_tarea`

_alcance: escritura_

Encola una tarea nueva con la misma entrada y el mismo agente que una anterior. La original no se modifica ni se borra: queda su corrida, su claim y lo que midió el verificador. Sirve para reintentar lo que falló por algo de afuera; si falló por cómo está configurado el agente, repetir sin cambiar nada vuelve a fallar y vuelve a costar.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | El id de la tarea a repetir. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `contestar_pregunta`

_alcance: escritura_

Contesta la pregunta que un agente dejó en una tarea («Te pregunta» en Te espera). La tarea vuelve a la cola y sigue desde donde quedó, con lo que ya hizo, lo que ya salió y todas las respuestas anteriores. Contesta quien pidió la tarea o quien opera. Una respuesta que parece una clave se rechaza: las credenciales van en Conexiones. Una pregunta que pide una llave o trae órdenes no se contesta por acá.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | La tarea que espera la respuesta. |
| `respuesta` **(requerido)** | string | La respuesta, en una línea (hasta 1.000 caracteres). |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `seguir_tarea`

_alcance: escritura_

Para una tarea a la que le faltó una herramienta («Le falta algo» en Te espera) o que el agente dejó sin terminar («Frenada»). Si le faltaba algo que la organización ya tiene, se lo prende; si la app no está conectada, dice qué conectar. Si no terminó, la tarea sigue desde donde quedó con lo que ya hizo. Lo hace quien opera.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | La tarea que esperaba la herramienta o que no terminó. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `aprobaciones_pendientes`

_alcance: lectura · sólo lee · idempotente_

Lo que espera a una persona, en el orden que importa: primero las discrepancias (el agente declaró éxito y la medición dijo otra cosa), después lo que el verificador rechazó, al final lo verde, que es trámite.
Cada fila dice `tramite` (verificada en limpio, sin discrepancia ni nada que salga al mundo: lo que se aprueba en lote) o `por_que_no_es_tramite`; `tramite` arriba cuenta toda la cola. Trae el link de cada una. Vos no aprobás: `aprobar` le da a la persona un enlace, por una (`tarea_id`) o por el lote de trámite (`tarea_ids`).

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `resolver_efecto_incierto`

_alcance: escritura · idempotente_

Para una tarea RETENIDA: su corrida murió con una acción con efecto pedida y sin resultado (un mail, un post), y no se vuelve a correr sola porque repetirla podría mandarlo dos veces. La persona de este token mira el sistema y dice qué pasó; queda en la auditoría con su nombre.
`no_salio` y `salio` la vuelven a la cola con una continuación (`salio` marca lo que salió para que no se repita); `a_medias` la deja esperando a una persona.
Sólo quien opera, y siempre con evidencia de al menos 20 caracteres: qué se miró y qué se vio.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | La tarea retenida. |
| `resultado` **(requerido)** | `no_salio` · `salio` · `a_medias` | Qué pasó con lo pedido. |
| `evidencia` **(requerido)** | string | Qué se miró y qué se vio («revisé enviados y el mail no está»). Al menos 20 caracteres. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `aprobar`

_alcance: escritura_

NO aprueba: la IA no se aprueba a sí misma. Devuelve un `enlace` al portal que la persona de este token abre con SU sesión, donde ve qué se aprueba (qué hace, con qué, costo, verificación) y decide. Sirve una vez y vence a los 15 minutos. Pasale el enlace tal cual y decile que la decisión es suya.
Para una tarea que espera aprobación (`tarea_id`, de `aprobaciones_pendientes`) o una promoción a producción pendiente (`promocion_id`, de `listar_promociones`). Rigen las reglas del portal: aprueban un técnico o un admin, y una promoción la aprueba otra persona que la que la pidió.
Varias de una vez: `tarea_ids` (hasta 50) con tareas que son trámite (`tramite: true` en `aprobaciones_pendientes`: verificadas en limpio, sin discrepancia y sin nada que salga al mundo). Devuelve UN `enlace` a Aprobaciones con el lote preseleccionado, que la persona aprueba con su sesión y un botón; lo que no es trámite vuelve en `rechazadas_del_lote` con su motivo y se aprueba de a una, desde la tarea. Tampoco acá aprobás vos.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` | string | La tarea, de `aprobaciones_pendientes`. |
| `promocion_id` | string | O la promoción, de `listar_promociones`. |
| `tarea_ids` | lista | O varias tareas de `aprobaciones_pendientes` que sean trámite (`tramite: true`), hasta 50: un solo enlace para que la persona apruebe el lote. No va con `tarea_id` ni con `promocion_id`. |
| `nota` | string | Opcional: qué se miró, para que la persona lo lea en el enlace (sólo de a una). |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `rechazar`

_alcance: escritura · idempotente_

Rechaza una tarea que espera aprobación (`tarea_id`) o una promoción pendiente (`promocion_id`; si la pediste vos, queda cancelada). Rechazar no ejecuta nada afuera, por eso no pide enlace. El `motivo` es obligatorio: lo lee quien la pidió y queda en la auditoría.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` | string | La tarea, de `aprobaciones_pendientes`. |
| `promocion_id` | string | O la promoción, de `listar_promociones`. |
| `motivo` **(requerido)** | string | Por qué no sale. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `hallazgos`

_alcance: lectura · sólo lee · idempotente_

Las fallas que se repiten en la organización, agrupadas y con su causa probable: pedidos a la API o al MCP que fallan igual, herramientas que el sistema del cliente rechaza (un 401 que vuelve), casos de evaluación que no pasan, discrepancias de la verificación, webhooks que no entregan y llaves rechazadas. Es la respuesta a «¿qué está fallando?». Cada hallazgo trae cuántas veces pasó, el último motivo y dónde se arregla. Lo ven quienes operan la organización.

| Argumento | Tipo | Qué es |
|---|---|---|
| `dias` | number | Ventana en días, hasta 30. Por defecto 7. |

### `que_paso_en_la_tarea`

_alcance: lectura · sólo lee · idempotente_

Una tarea contada entera: en qué estado está, qué versión del agente la corrió, qué dijo el agente de su propio trabajo, qué midió el verificador aparte, si hay discrepancia, a quién está esperando y qué herramientas llegó a usar. Lo que el agente declara NO es el veredicto: viene marcado como claim.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | El id de la tarea, de `tareas_del_agente`. |

### `traza_de_la_tarea`

_alcance: lectura · sólo lee · idempotente_

Los pasos de la ejecución en orden, con lo que tardó y lo que costó cada tramo del modelo. Es con lo que se contesta en qué tramo se fue el tiempo o la plata, y dónde se frenó.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | El id de la tarea. |
| `limite` | number | Cuántos pasos como máximo. Máximo 30. |

### `herramientas_de_la_tarea`

_alcance: lectura · sólo lee · idempotente_

Qué quiso hacer el agente y qué lo dejaron hacer: cada intento de herramienta con su estado, incluidos los que la correa DENEGÓ y los que quedaron esperando una aprobación. Además dice si la cadena de la bitácora sigue sellada.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tarea_id` **(requerido)** | string | El id de la tarea. |


## Conexiones y credenciales

Herramientas, funciones propias, servidores MCP ajenos, aplicaciones conectadas (Che Tienda), credenciales, simulaciones y el modelo. Área de búsqueda: `conexiones`.

### `crear_funcion`

_alcance: escritura · idempotente_

Guarda una función propia: el cuerpo de una función JavaScript asíncrona que recibe `entrada` (los argumentos que manda el agente) y devuelve algo que se pueda pasar a JSON. Es una herramienta más —se habilita por agente con editar_agente—, para lo que el catálogo no cubre y el modelo no tiene que hacer a ojo: un cálculo con las reglas del negocio, un formato, una validación. Corre en el worker, en un contenedor SIN RED, sin credenciales, con 128 MB y 5 segundos: no puede llamar a ningún sistema ni tener efecto, así que es de lectura y no pide aprobación. Para hablar con un sistema, una conexión; para la cuenta, una función. Si ya existe una función con ese nombre, la reescribe. Ejemplo de `codigo`: `const neto = entrada.items.reduce((s, i) => s + i.cantidad * i.precio, 0); return { neto, iva: Math.round(neto * 0.21) };`

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | En minúsculas y guión bajo, como una herramienta: calcular_envio. |
| `descripcion` **(requerido)** | string | Qué hace y qué devuelve: es lo que lee el agente para decidir cuándo llamarla. |
| `parametros` | lista | Los argumentos que manda el agente, como en crear_herramienta: `{ nombre, tipo, requerido, descripcion }`. Llegan juntos en `entrada`. |
| `codigo` **(requerido)** | string | El cuerpo de la función: recibe `entrada` y hace `return` del resultado. Hasta 20.000 caracteres. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `ver_funcion`

_alcance: lectura · sólo lee · idempotente_

Una función propia con su código, su descripción y sus parámetros, para leerla o editarla con crear_funcion.

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | El nombre de la función. |

### `crear_herramienta`

_alcance: escritura · idempotente · toca sistemas ajenos_

Declara una conexión HTTP para que los agentes puedan llamar a un sistema del cliente. NACE ACTIVA: queda usable apenas se declara. Redeclarar una que ya existe la actualiza y NO cambia su estado — la que alguien apagó a mano sigue apagada. Si la redeclaración le SACA parámetros o cabeceras a la existente, se rechaza salvo `reemplazar: true`; para cambiarle una cosa usá `editar_herramienta`. Para que nazca apagada, pedilo con `en_cuarentena: true`. La credencial NO se manda acá: se nombra con `secreto` y se carga aparte, cifrada, desde el portal.

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | Cómo la llama el agente. Minúsculas y guiones bajos: es el nombre MCP. Ej: consultar_movimientos. |
| `descripcion` **(requerido)** | string | Para qué sirve, dicho PARA EL MODELO: es lo que decide si la usa bien y cuándo. |
| `metodo` | string | GET, POST, PUT, PATCH o DELETE. Por defecto GET. |
| `url` **(requerido)** | string | URL completa. Puede llevar `{param}`, que se reemplaza con los argumentos de la llamada. `local://<puerto>/<ruta>` apunta al proyecto que corre en la máquina de quien pide la tarea (por `yorobot puente`): sólo corre en prueba y no lleva `secreto`. |
| `cabeceras` | object | Cabeceras fijas. Para autenticar se escribe el MARCADOR del secreto entre llaves, nunca el valor: { "X-Api-Key": "{mi_credencial}" }. El puente lo sustituye afuera de la jaula y el modelo jamás ve la credencial. |
| `parametros` | lista | Qué puede mandar el agente: [{ nombre, tipo, en, requerido, descripcion, esquema }]. `tipo`: texto (por defecto), numero, booleano, objeto, lista o json. `en` es dónde viaja el parámetro: "cuerpo" (por defecto), "query" o "ruta" — que sustituye {nombre} en la URL. Se aceptan también "body" y "path". `esquema` (sólo lista u objeto) es un JSON Schema acotado —type, description, enum, properties, required, items— con la forma de cada elemento: así una lista puede ser de objetos, p. ej. { nombre: "filterGroups", tipo: "lista", esquema: { type: "object", properties: { filters: { type: "array", items: { type: "object", properties: { propertyName: { type: "string" }, operator: { type: "string" }, value: { type: "string" } }, required: ["propertyName", "operator"] } } }, required: ["filters"] } }. |
| `reemplazar` | boolean | true para aceptar que esta declaración le saque parámetros o cabeceras a una herramienta que ya existe con ese nombre. Sin esto, un recorte se rechaza y el error dice qué se perdería. |
| `riesgo` **(requerido)** | string | read = sólo lee. write = cambia algo reparable. destructive = irreversible, y entonces pide firma humana SIEMPRE. Ante la duda, el más alto. |
| `lectura_por_post` | boolean | true para declarar `read` un POST que sólo consulta: una búsqueda cuyo filtro viaja en el cuerpo (HubSpot search, GraphQL, Elasticsearch) y que no cambia nada afuera. Sin esto, un POST no puede ser read. Sólo POST: un PUT o un DELETE nunca son de lectura. |
| `secreto` | string | Nombre (`kind`) de la credencial del sobre que usa. Vacío si no necesita ninguna. |
| `en_cuarentena` | boolean | true para que nazca APAGADA y nadie la pueda usar hasta que una persona la habilite en Conexiones. Por defecto false: nace activa. Pedila en cuarentena cuando la estés declarando a ciegas —una URL que todavía no probaste, un sistema ajeno, un riesgo que no terminás de medir—. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_servidores_mcp`

_alcance: lectura · sólo lee · idempotente_

Los servidores MCP ajenos que la organización conectó: nombre, URL, qué credencial usan, cuándo se descubrieron por última vez y cuántas herramientas trajeron (y cuántas están activas).

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `conectar_servidor_mcp`

_alcance: escritura · idempotente_

Registra un servidor MCP remoto (streamable HTTP) por URL y le pregunta qué herramientas publica. Lo que trae entra según el modo de control (Libre: sólo queda en cuarentena lo que borra, paga o manda en masa; Con controles: lo que escribe; Regulado: todo) y ningún agente lo usa hasta prender_herramienta, de a una; el riesgo lo clasificamos nosotros (un nombre destructivo es destructivo aunque el servidor jure que sólo lee; sin anotaciones es `write`). La credencial NO viaja acá: se carga antes con cargar_credencial bajo un nombre (`credencial`) y se dice en qué cabecera va (`cabecera`, p. ej. `Authorization` con `Bearer {secreto}`). Volver a llamar con el mismo nombre actualiza la URL y redescubre sin reactivar lo apagado.

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | Nombre del servidor en la organización (p. ej. «hubspot»). Único; repetirlo actualiza. |
| `url` **(requerido)** | string | La URL del endpoint MCP (https://…/mcp). |
| `credencial` | string | Opcional: el nombre de la credencial cargada con cargar_credencial que este servidor usa. |
| `cabecera` | string | Opcional: la cabecera donde va la credencial. Por defecto `Authorization`. |
| `formato` | string | Opcional: cómo se escribe la cabecera; `{secreto}` se reemplaza en el puente. Por defecto `Bearer {secreto}`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `conectar_base`

_alcance: escritura · idempotente · toca sistemas ajenos_

Conecta la base de datos o la API del proyecto del cliente para que los agentes la lean y la usen: `tipo` supabase (PostgREST), openapi (un documento OpenAPI 3) o mcp (un servidor MCP). Dos pasos, porque qué entra y con qué riesgo lo decide la persona, no vos:
1) `modo: previsualizar` lee el documento y devuelve las operaciones propuestas (nombre, método, descripción, riesgo sugerido). No guarda nada. Mostrásela a la persona.
2) `modo: confirmar` con las `operaciones` que eligió y su `riesgo` (read sólo lee; write escribe y pide aprobación según los permisos del agente; destructive no se deshace y pide aprobación siempre), la `credencial` (se guarda sellada y nunca vuelve) y, si querés, `agentes` donde habilitarlas (cada uno queda con versión nueva en prueba). Prueba una lectura y devuelve el dato. mcp: lo que trae entra según el modo de control (en Regulado, todo en cuarentena), no hay operaciones que elegir.
Guía para la base (regla 7): exponé VISTAS pensadas para el agente —etiquetas y no códigos, números ya calculados, fechas con zona horaria—; escribí sólo por funciones (`rpc`), donde viven las reglas; usá un rol de la base con permisos mínimos y un JWT de ese rol. Nunca la service_role ni una sb_secret_: se rechazan. La llave secreta de Supabase va sólo en `llave_de_lectura`, para leer el esquema, y no se guarda.
Las llaves: la persona puede dártelas y las mandás en `llave_de_lectura` y `credencial`; o, si prefiere que no pasen por vos, llamá con `cargar_en_el_portal: true` (mismo `modo`, sin llaves) y devuelve un `enlace` para ella: las pega en el portal, elige y confirma ahí. Preguntale cuál prefiere antes de pedirle una llave.
El proyecto tiene que ser alcanzable desde internet por https: YoRobot corre en la nube y no llega a tu localhost ni a una red privada. Para desarrollo hay puente local: herramientas con URL `local://<puerto>/<ruta>` (crear_herramienta) y `yorobot puente --puerto <puerto>` en tu máquina; sólo en prueba.

| Argumento | Tipo | Qué es |
|---|---|---|
| `modo` **(requerido)** | `previsualizar` · `confirmar` | Primero previsualizar; confirmar con lo que eligió la persona. |
| `tipo` **(requerido)** | `supabase` · `openapi` · `mcp` | Qué se conecta. |
| `nombre` **(requerido)** | string | Cómo se llama la conexión (p. ej. «Reservas»). Es el prefijo de las herramientas. |
| `url` **(requerido)** | string | supabase: la del proyecto (https://<ref>.supabase.co); openapi: la del documento; mcp: la del endpoint. |
| `llave_de_lectura` | string | supabase: la llave secreta, SÓLO para leer el esquema; no se guarda. openapi: si el documento pide una. |
| `llave_publica` | string | supabase, opcional: la publicable (sb_publishable_… o anon), que va en `apikey`. |
| `credencial` | string | confirmar: con qué se autentican las herramientas (supabase: el JWT del rol mínimo). Sellada; no vuelve. |
| `cabecera` | string | mcp, opcional: en qué cabecera va la credencial. Por defecto `Authorization: Bearer`. |
| `operaciones` | lista | confirmar: las elegidas, por `id` o `nombre` de la previsualización, con su riesgo. |
| `agentes` | lista | confirmar, opcional: `agente_id` donde habilitarlas. |
| `probar` | boolean | confirmar: false para no probar una lectura al terminar. |
| `cargar_en_el_portal` | boolean | true: no conecta todavía; devuelve un `enlace` para que la persona pegue las llaves en el portal y confirme ahí, sin que pasen por vos. Mandá lo demás igual (tipo, nombre, url, y en confirmar las operaciones y los agentes); llaves no. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `conectar_aplicacion`

_alcance: escritura · toca sistemas ajenos_

Conecta una aplicación conocida con esta organización sin que nadie copie un token: YoRobot crea un token nuevo a nombre de la persona (alcances lectura y topes, sin vencimiento), se lo entrega a la app de servidor a servidor y firmado, y la app devuelve su credencial, que queda sellada; sus lecturas (GET) quedan como conexiones activas, de sólo lectura. Hoy: `aplicacion: "che-tienda"`.
Si la persona dice «conectá mi tienda de Che Tienda con YoRobot», llamá esta herramienta. NUNCA le pidas un token ni una llave en el chat, y nunca muestres uno: no hacen falta y la respuesta no los trae.
Respuesta: `conectada` (booleano), `estado`, `mensaje` (pasáselo a la persona tal cual) y `que_hacer` si no conectó. Si `estado` es `varias_tiendas`, preguntale cuál de `tiendas` es y volvé a llamar con `tienda`. Si no conectó, el token del intento ya quedó revocado: reintentar es un vínculo nuevo. Un vínculo nuevo reemplaza al anterior de la misma aplicación. Lo hace un técnico o un admin.

| Argumento | Tipo | Qué es |
|---|---|---|
| `aplicacion` **(requerido)** | `che-tienda` | Qué aplicación: `che-tienda`. |
| `tienda` | string | Opcional: cuál tienda, si la persona administra varias (el nombre, el dominio o el subdominio). Sólo si la app contestó `varias_tiendas`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_aplicaciones_conectadas`

_alcance: lectura · sólo lee · idempotente_

Las aplicaciones conectadas con vínculo (Che Tienda): por cada una, la tienda, quién la conectó y cuándo (`conectada_el`, ISO en UTC), los últimos 4 caracteres de su token (`token_termina_en`; el token nunca), si el token sigue vigente (`token_vigente`: false = alguien lo revocó en Accesos y la app ya no entra) y las conexiones que creó. El `vinculo_id` es el que pide desconectar_aplicacion.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `desconectar_aplicacion`

_alcance: escritura · destructiva · idempotente · toca sistemas ajenos_

Da de baja un vínculo: revoca su token, borra la credencial sellada y las conexiones que creó, y le avisa a la app con una entrega firmada (`la_app_confirmo` dice si contestó). No se deshace: para volver a conectar, conectar_aplicacion crea un vínculo nuevo. Lo hace un técnico o un admin.

| Argumento | Tipo | Qué es |
|---|---|---|
| `vinculo_id` **(requerido)** | string | El `vinculo_id` de listar_aplicaciones_conectadas. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `probar_conexion`

_alcance: escritura · idempotente · toca sistemas ajenos_

Llama UNA herramienta de lectura contra el sistema real y devuelve lo que contestó, recortado a 600 caracteres (`recortada` dice si se cortó). Sólo lecturas: probar una que escribe sería ejecutarla sin tarea ni aprobación. Con credencial sellada, este servidor sólo la prueba donde puede abrirla; si no, lo dice (`probada: false`) y la prueba es la de `conectar_base` al confirmar o `probar_agente`. Una `local://` se prueba contra TU máquina por tu puente local (`yorobot puente --puerto <n>`): sin puente, `probada: false` con el comando.

| Argumento | Tipo | Qué es |
|---|---|---|
| `herramienta` **(requerido)** | string | El nombre o el id, de `listar_herramientas` o de `conectar_base`. |
| `argumentos` | object | Los argumentos de la lectura (p. ej. { "limit": "3" }). Vacío si no lleva. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `redescubrir_servidor_mcp`

_alcance: escritura · idempotente_

Relee el catálogo de un servidor MCP ya conectado. Las herramientas nuevas entran según el modo de control (en Regulado, en cuarentena), las que ya estaban conservan su estado (redescubrir no reactiva lo que alguien apagó) y las que el servidor dejó de publicar pasan a cuarentena con motivo, sin borrarse.

| Argumento | Tipo | Qué es |
|---|---|---|
| `servidor_id` **(requerido)** | string | El servidor, de listar_servidores_mcp. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `estado_descubrimiento_mcp`

_alcance: lectura · sólo lee · idempotente_

Cuando el servidor usa una credencial, el catálogo lo trae el worker de la organización (el portal no abre credenciales ni sale a la red del cliente) y conectar/redescubrir devuelven `estado: pendiente` con un `encargo_id`. Esto dice si el encargo sigue pendiente, terminó (`listo`, con cuántas herramientas trajo) o falló (con el motivo, sin la credencial).

| Argumento | Tipo | Qué es |
|---|---|---|
| `servidor_id` | string | El servidor, de listar_servidores_mcp: se mira su último descubrimiento. |
| `encargo_id` | string | O el encargo puntual que devolvió conectar/redescubrir. |

### `autorizar_servidor_mcp`

_alcance: escritura · idempotente_

Para servidores MCP que exigen OAuth 2.1 (Slack oficial, Atlassian, Linear…) en vez de un token estático. Descubre al autorizador desde la URL del servidor (RFC 9728 → RFC 8414/OpenID), registra un cliente por Dynamic Client Registration si el autorizador lo ofrece (o usa `client_id`/`client_secret` si los pasás), y devuelve la URL que UNA PERSONA tiene que abrir en el navegador, logueada en el portal, para dar el permiso. PKCE S256 y state de un solo uso, vence a los 10 minutos. Al volver, la llave (access + refresh) queda sellada en la bóveda para el worker —el portal no la ve, y esta respuesta tampoco— y el servidor pasa a usarla en `Authorization`. Después: redescubrir_servidor_mcp.

| Argumento | Tipo | Qué es |
|---|---|---|
| `servidor_id` **(requerido)** | string | El servidor, de listar_servidores_mcp (conectado sin credencial). |
| `scope` | string | Opcional: los permisos a pedir, separados por espacio. Por defecto los que anuncia el autorizador. |
| `client_id` | string | Opcional: si el autorizador no registra clientes solo, el client_id de una app ya creada. |
| `client_secret` | string | Opcional, junto con client_id: el secreto de esa app. Se sella; no se devuelve ni se registra. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `estado_oauth_mcp`

_alcance: lectura · sólo lee · idempotente_

Dice si la autorización de un servidor está pendiente (falta que la persona abra la URL), autorizada (con cuándo vence el token y cuándo se renovó por última vez) o falló (con el motivo). Nunca devuelve tokens.

| Argumento | Tipo | Qué es |
|---|---|---|
| `servidor_id` **(requerido)** | string | El servidor, de listar_servidores_mcp. |

### `desconectar_servidor_mcp`

_alcance: escritura · idempotente_

Borra el servidor y con él todas las herramientas que trajo: los agentes que las tenían puestas se quedan sin ellas. Sólo un admin. Devuelve cuántas herramientas se fueron.

| Argumento | Tipo | Qué es |
|---|---|---|
| `servidor_id` **(requerido)** | string | El servidor, de listar_servidores_mcp. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_herramientas`

_alcance: lectura · sólo lee · idempotente_

Las conexiones que existen en el tenant, con su nombre, qué hace cada una, su riesgo, si está usable y qué credencial necesita. LLAMALA ANTES DE `crear_agente` o `editar_agente`: esos dos reciben los nombres y rechazan el que no existe, así que adivinar un nombre es una llamada perdida. También dice cuáles están apagadas o en cuarentena, y cuáles no tienen la credencial cargada todavía: una herramienta habilitada sin credencial razona pero no toca nada real. Con `detalle: true` agrega además la URL y los PARÁMETROS de cada una: LLAMALA ASÍ ANTES DE REDECLARAR con `crear_herramienta`, que reescribe la definición entera — todo parámetro que no vuelvas a mandar desaparece, y el agente pierde la mitad de la herramienta sin que nada falle hasta la próxima corrida.

| Argumento | Tipo | Qué es |
|---|---|---|
| `detalle` | boolean | true para incluir url, cabeceras y parámetros de cada conexión. Las cabeceras salen con el MARCADOR del secreto (`{mi_credencial}`), nunca con su valor. |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `habilitar_herramienta`

_alcance: escritura · idempotente_

Saca una conexión de cuarentena para toda la organización (la que nació apagada con `en_cuarentena`, la que trajo un servidor MCP, o la que alguien apagó a mano). Es una decisión de gobierno: la toma un técnico o un admin. No se la da a ningún agente: para eso está prender_herramienta. La que ya estaba activa queda igual.

| Argumento | Tipo | Qué es |
|---|---|---|
| `herramienta` **(requerido)** | string | El nombre de la conexión (de listar_herramientas) o su id. |
| `motivo` | string | Opcional: por qué se habilita. Queda en la bitácora junto al motivo de la cuarentena. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `elegir_modelo`

_alcance: escritura · idempotente_

Qué modelo usa cada rol, y con qué modelo trabaja cada uno. Sin `rol` sólo informa; con `rol` y `modelo` lo cambia. El trabajo no es homogéneo: el `ejecutor` es el que se lleva el grueso de los tokens —ahí se decide casi todo el costo—, mientras que `revisor` y `juez` leen poco y rinden con un modelo chico. Un `modelo` vacío borra el override y ese rol vuelve al modelo de base. NO toca la credencial del proveedor: elegir el modelo y entregar la llave para pagarlo son dos decisiones distintas, y la segunda sigue siendo de un admin en Ajustes → Llave.

| Argumento | Tipo | Qué es |
|---|---|---|
| `rol` | string | orquestador (planifica y decide), ejecutor (hace el trabajo: acá se va el grueso del gasto), revisor (lee poco), encargado (relee el sistema y verifica), juez (califica). Sin esto, sólo informa. |
| `modelo` | string | El identificador tal cual lo pide el proveedor: `claude-sonnet-5` en la API de Anthropic, `anthropic/claude-sonnet-5` en un gateway, un inference profile en Bedrock. Vacío borra el override y vuelve al modelo de base. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `prender_herramienta`

_alcance: escritura · idempotente_

Habilita una herramienta de la organización para un agente. Le da CON QUÉ, no permiso: la correa, el tope sin firma y la aprobación de las irreversibles siguen iguales. Si la herramienta está apagada globalmente o en cuarentena, queda asignada pero no corre hasta que eso se levante.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |
| `herramienta_id` **(requerido)** | string | El id de la herramienta, de `listar_herramientas`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `apagar_herramienta`

_alcance: escritura · idempotente_

Le saca una herramienta a un agente. La herramienta sigue en la organización y en los otros agentes.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |
| `herramienta_id` **(requerido)** | string | El id de la herramienta, de `listar_herramientas`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `cargar_credencial`

_alcance: escritura · idempotente_

Guarda, cifrada, la credencial que las conexiones citan por `secreto` (el `kind`): un private app token de HubSpot, la API key de un ERP. Se sella con la llave pública de la bóveda y no se vuelve a mostrar nunca — la respuesta trae los últimos cuatro caracteres y qué conexiones la usan. Cargarla de nuevo la reemplaza. La llave del proveedor de modelos no entra por acá: es de un admin, en Ajustes → Llave.

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | El `kind` con el que las conexiones la citan: minúsculas y guiones bajos, p. ej. hubspot_token. Tiene que ser el mismo que puso `crear_herramienta` en `secreto`. |
| `valor` **(requerido)** | string | La credencial en claro. Viaja una vez, se sella y no vuelve a salir. |
| `ambiente` | string | `prod` (por defecto), `staging` o `dev`: para qué ambiente vale esta llave. |
| `forzar` | boolean | true para guardar una credencial que NINGUNA conexión cita todavía. Sin esto, un `nombre` huérfano se rechaza y el error dice qué nombres sí están esperando llave: un nombre mal tipeado guardaba una credencial que nadie buscaba y el 401 aparecía en la primera tarea. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `editar_herramienta`

_alcance: escritura · idempotente_

Cambia UNA O VARIAS cosas de una conexión ya declarada sin reescribirla: descripción, método, URL, cabeceras, parámetros, riesgo o el nombre de la credencial (`secreto`). Lo que no se manda no se toca. Bajar el riesgo (destructive → write → read) lo hace un técnico o un admin. Si `parametros` o `cabeceras` le sacan algo a lo que hay, se rechaza salvo `reemplazar: true`. Las herramientas que trae un servidor MCP ajeno sólo aceptan descripción, riesgo y secreto.

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | El nombre MCP de la herramienta a editar (el de `listar_herramientas`). |
| `descripcion` | string | Nueva descripción para el modelo. |
| `metodo` | string | GET, POST, PUT, PATCH o DELETE. |
| `url` | string | Nueva URL completa; puede llevar `{param}`. |
| `cabeceras` | object | Cabeceras completas (reemplaza el mapa). Las sensibles citan el secreto entre llaves, nunca el valor. |
| `parametros` | lista | Lista completa de parámetros, con el mismo formato que `crear_herramienta`. |
| `riesgo` | string | read, write o destructive. |
| `secreto` | string | Nombre de la credencial que usa. Cadena vacía para que no use ninguna. |
| `reemplazar` | boolean | true para aceptar que `parametros`/`cabeceras` le saquen algo a lo que hay. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `simular_herramienta`

_alcance: escritura · idempotente_

Graba la respuesta que una conexión devuelve en dev o staging. Mientras está simulada, el agente la ve y la llama, pero el puente devuelve la respuesta grabada y anota «simulado»: el sistema real no se llama y no viaja ninguna credencial. Producción no se simula nunca. Para volver a la conexión real, quitar_simulacion.

| Argumento | Tipo | Qué es |
|---|---|---|
| `herramienta_id` **(requerido)** | string | La conexión, de `listar_herramientas`. |
| `ambiente` **(requerido)** | `dev` · `staging` | Dónde vale la simulación. |
| `respuesta` **(requerido)** | string | Lo que el agente va a recibir cuando la llame, tal cual (texto o JSON como texto). Máximo 20.000 caracteres. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `quitar_simulacion`

_alcance: escritura · idempotente_

La conexión vuelve a llamar al sistema de ese ambiente: la dirección propia del ambiente si la tenía, o nada (una escritura externa sin conexión propia no entra a la corrida).

| Argumento | Tipo | Qué es |
|---|---|---|
| `herramienta_id` **(requerido)** | string | La conexión, de `listar_herramientas`. |
| `ambiente` **(requerido)** | `dev` · `staging` | De qué ambiente sacarla. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `pedir_conexion`

_alcance: escritura · idempotente_

Deja un pedido: «necesito esta conexión en este ambiente y no tengo la credencial». Le llega a quien puede cargarla (técnico, admin, operador) con link a Conexiones; al guardar la credencial el pedido se cierra solo. Quien pide no ve ni recibe el secreto. Un segundo pedido para la misma conexión y ambiente devuelve el que ya estaba pendiente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `herramienta_id` **(requerido)** | string | La conexión, de `listar_herramientas`. |
| `ambiente` **(requerido)** | `dev` · `staging` · `prod` | Para qué ambiente falta. |
| `motivo` **(requerido)** | string | Para qué la necesitás; lo lee quien la carga. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `crear_link_de_credencial`

_alcance: escritura_

Genera un link de un solo uso para que la persona que tiene la llave (el cliente, su equipo de sistemas) la pegue ella en una página de YoRobot, en vez de mandarla por chat o por correo: queda sellada y nadie la vuelve a ver. Sólo para una credencial que alguna conexión cita. Si ya hay una cargada con ese nombre en ese ambiente, el link no la pisa salvo `reemplaza: true`. Vence (por defecto a las 72 horas) y quien lo generó recibe un correo con los últimos cuatro cuando se usa. Mostrale el link a la persona tal cual: se devuelve una sola vez. NUNCA pidas ni pases la credencial por acá.

| Argumento | Tipo | Qué es |
|---|---|---|
| `credencial` **(requerido)** | string | El nombre de la credencial que cita la conexión (`erp_token`, `hubspot_token`…). |
| `ambiente` | `dev` · `staging` · `prod` | Para qué ambiente. Por defecto prod. |
| `para` | string | A quién se lo mandás, en palabras: sale en el aviso y en la bitácora. |
| `horas` | number | En cuántas horas vence, de 1 a 168. Por defecto 72. |
| `reemplaza` | boolean | true para que pise una credencial ya cargada con ese nombre en ese ambiente. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_pedidos_de_conexion`

_alcance: lectura · sólo lee · idempotente_

Qué credenciales están pedidas, por quién, para qué ambiente y en qué estado. Un desarrollador ve los suyos; técnico, admin, operador y auditor ven todos. Nunca trae el valor de una credencial.

| Argumento | Tipo | Qué es |
|---|---|---|
| `estado` | `pendiente` · `cumplido` · `rechazado` · `todos` | Por defecto `pendiente`. |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `rechazar_pedido_de_conexion`

_alcance: escritura · idempotente_

Cierra un pedido pendiente sin cargar la credencial, con motivo. Lo hace un técnico, un admin o un operador. Un pedido se cumple cargando la credencial (cargar_credencial o Conexiones), no con esta herramienta.

| Argumento | Tipo | Qué es |
|---|---|---|
| `pedido_id` **(requerido)** | string | El pedido, de `listar_pedidos_de_conexion`. |
| `motivo` **(requerido)** | string | Por qué no; lo lee quien pidió. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |


## Canales y avisos

Por dónde entra la gente (chat, WhatsApp, Slack…) y a quién se le avisa. Área de búsqueda: `canales`.

### `listar_canales`

_alcance: lectura · sólo lee · idempotente_

Por dónde le hablan a un agente: chat público/widget, WhatsApp, Instagram, Slack y Telegram, con nombre, ambiente, dominios permitidos, si está atendiendo, último uso y el link (sin token: el token se muestra UNA vez al abrir).

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `abrir_canal`

_alcance: escritura_

Abre un canal de chat para un agente y devuelve UNA sola vez el link completo con el token y el `<script>` para embeber el widget en la web del cliente: guardalos, no se vuelven a mostrar. Lo que entra por ahí es de un tercero: la tarea nace contenida y la cuota es del canal.
Con `dominios` el widget puede hablar desde esas webs (CORS); sin dominios sólo funciona nuestra página /charla. Mandá `clave_de_pedido`: un reintento sin clave abre un segundo canal. Slack y Telegram van por `conectar_canal`; WhatsApp e Instagram, por `conectar_whatsapp` y `conectar_instagram`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |
| `ambiente` | string | `dev` (por defecto), `staging` o `prod`: qué versión del agente atiende ese canal. |
| `nombre` | string | Cómo lo llama la organización: «Chat de la web», «Soporte». Opcional. |
| `dominios` | lista | Orígenes desde los que el widget puede hablar: `https://www.clinica.com`. Hasta 20. Sin esto el canal sólo atiende desde nuestra página. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `conectar_canal`

_alcance: escritura_

Conecta un bot de Slack o un bot de Telegram a un agente, y devuelve la URL del webhook que hay que pegar del otro lado. Los secretos se guardan sellados y no se vuelven a mostrar.
Slack: `token` = Bot User OAuth Token (xoxb-…), `secreto` = Signing Secret; suscribí `message.im` y `app_mention` en Event Subscriptions con la URL devuelta. Telegram: `token` = el del bot de @BotFather; la respuesta trae `secreto_webhook` para registrar con setWebhook (`secret_token`).
WhatsApp e Instagram NO van por acá: `conectar_whatsapp` y `conectar_instagram`. Mandá `clave_de_pedido`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |
| `tipo` **(requerido)** | string | `slack` o `telegram`. |
| `token` **(requerido)** | string | Con qué sale la respuesta: el bot token. |
| `secreto` | string | Sólo Slack: el Signing Secret, con que se comprueba el webhook. Telegram no lo lleva: lo generamos. |
| `nombre` | string | Cómo lo llama la organización. Opcional. |
| `ambiente` | string | `dev` (por defecto), `staging` o `prod`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `conectar_whatsapp`

_alcance: escritura_

Conecta a un agente el WhatsApp Business que la organización ya usa; el número sigue andando en la app del celular. Devuelve un `enlace` a la pantalla de YoRobot y los `pasos` para la persona, que hay que pasarle tal cual y en orden: hoy el número se conecta en una cuenta propia de la organización en el servicio de WhatsApp que nombran los pasos (gratis para un número), y la llave de esa cuenta la pega la persona en la pantalla de YoRobot. Esa llave no pasa por acá: no la pidas.
Cuando la persona termina, el canal aparece prendido en `listar_canales` con su número. Si la respuesta trae `canal_id` (el alta directa con Meta, cuando esté habilitada), consultalo con `estado_de_conexion`. Los cargos de los mensajes los cobra Meta a la cuenta de la organización. Mandá `clave_de_pedido`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente que va a contestar, de `listar_agentes`. |
| `ambiente` | string | `prod` (por defecto: es el número de los clientes de verdad, y contesta la versión publicada), `staging` o `dev`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `conectar_instagram`

_alcance: escritura_

Conecta a un agente los mensajes directos de la cuenta de Instagram de la organización (profesional: empresa o creador). Devuelve un `enlace` a YoRobot: la persona lo abre con su sesión, entra con su Instagram y autoriza los mensajes. La contraseña no pasa por acá.
Cuando la persona termina, el canal queda prendido solo: consultalo con `estado_de_conexion` { canal_id }. El agente contesta dentro de las 24 h del último mensaje de la persona, como pide Instagram. Mandá `clave_de_pedido`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente que va a contestar, de `listar_agentes`. |
| `ambiente` | string | `prod` (por defecto: es la cuenta de los clientes de verdad, y contesta la versión publicada), `staging` o `dev`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `estado_de_conexion`

_alcance: lectura · sólo lee · idempotente_

El estado de un alta de `conectar_whatsapp` o `conectar_instagram`, en una palabra y qué hacer: `esperando_alta` (la persona todavía no terminó), `conectado` (el agente ya contesta), `fallida`, `vencida` o `reemplazada`. Con la cuenta, el agente y `conectado` como booleano. No cambia nada.

| Argumento | Tipo | Qué es |
|---|---|---|
| `canal_id` **(requerido)** | string | El `canal_id` que devolvió `conectar_whatsapp` o `conectar_instagram`. |

### `configurar_canal`

_alcance: escritura · idempotente_

Cambia el nombre de un canal y, si es de chat, los dominios desde los que el widget puede hablar. Lo que no mandás no cambia. Los secretos no se editan: se reconecta.

| Argumento | Tipo | Qué es |
|---|---|---|
| `canal_id` **(requerido)** | string | El id del canal, de `listar_canales`. |
| `nombre` | string | El nombre nuevo, o vacío para sacarlo. |
| `dominios` | lista | La lista completa de orígenes permitidos (reemplaza la anterior). Sólo canales de chat. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `probar_canal`

_alcance: escritura_

Crea una tarea por ese canal como si alguien hubiera escrito, con la misma contención, cuota y ambiente. Devuelve el id de la tarea para leer la respuesta con `ver_tarea`. No manda nada al proveedor: es para comprobar que el agente atiende.

| Argumento | Tipo | Qué es |
|---|---|---|
| `canal_id` **(requerido)** | string | El id del canal, de `listar_canales`. |
| `mensaje` | string | Qué decirle. Por defecto le pide que se presente. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `prender_canal`

_alcance: escritura · idempotente_

Prende un canal apagado: vuelve a responder. Idempotente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `canal_id` **(requerido)** | string | El id del canal, de `listar_canales` o `abrir_canal`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `apagar_canal`

_alcance: escritura · idempotente_

Apaga un canal: el link o el número dejan de responder, pero nada se borra y se vuelve a prender con prender_canal. Es el freno de mano cuando un agente dice algo que no debía.

| Argumento | Tipo | Qué es |
|---|---|---|
| `canal_id` **(requerido)** | string | El id del canal, de `listar_canales`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_conversaciones`

_alcance: lectura · sólo lee · idempotente_

Las sesiones de conversación por canal e interlocutor (una por link de chat, por teléfono en WhatsApp, por hilo en Slack/Telegram): agente, canal, estado (abierta o cerrada y por qué), turnos, último mensaje y el resumen que el agente dejó. Sin el teléfono ni el id del interlocutor. Una sesión se cierra sola tras 6 horas sin mensajes.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` | string | Sólo las de este agente. Opcional. |
| `canal_id` | string | Sólo las de este canal, de `listar_canales`. Opcional. |
| `estado` | string | `abierta` o `cerrada`. Sin esto, todas. |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `ver_conversacion`

_alcance: lectura · sólo lee · idempotente_

Una sesión con lo que la persona escribió en cada turno, lo que la corrida contestó de verdad (leído de la ejecución, no del relato), la tarea de cada turno para abrirla con `ver_tarea`, y el resumen y los datos de trabajo que el agente dejó para el turno siguiente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `conversacion_id` **(requerido)** | string | El id, de `listar_conversaciones`. |

### `cerrar_conversacion`

_alcance: escritura · idempotente_

Cierra una sesión abierta: el próximo mensaje de ese interlocutor abre una nueva sin este contexto. No borra nada: las tareas y los turnos quedan. Idempotente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `conversacion_id` **(requerido)** | string | El id, de `listar_conversaciones`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_destinatarios`

_alcance: lectura · sólo lee · idempotente_

Las personas y canales de equipo que reciben avisos (correo, WhatsApp, Slack, Teams) cuando una tarea espera aprobación, termina o la verificación discrepa. Con cuántos avisos llegaron, fallaron o esperan. Sin direcciones completas ni URLs de webhooks.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `avisar_a`

_alcance: escritura_

Da de alta a quién avisar: `tipo` es `email`, `whatsapp`, `slack` o `teams`. Por defecto recibe `tarea.necesita_firma`: el aviso lleva la tarea, lo que el agente quiere hacer y el link a la cola. El link ABRE la cola; aprobar pide sesión.
Para `slack`, `direccion` es la URL del incoming webhook; para `teams`, la del webhook de Workflows del canal («Post to a channel when a webhook request is received»). Las dos se sellan y no se vuelven a mostrar, y `canal` es el nombre visible. Para `whatsapp`, `direccion` es el número y `plantilla` la plantilla aprobada por Meta con dos parámetros (título y link). Mandá `clave_de_pedido`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tipo` **(requerido)** | string | `email`, `whatsapp`, `slack` o `teams`. |
| `nombre` **(requerido)** | string | Quién es: «Jefa de guardia», «#aprobaciones». |
| `direccion` **(requerido)** | string | Correo, número de WhatsApp, URL del incoming webhook de Slack o URL del webhook de Workflows de Teams. |
| `eventos` | lista | Qué avisar: `tarea.necesita_firma` (por defecto), `tarea.terminada`, `discrepancia.detectada`, `tarea.firmada`, `tarea.rechazada`. |
| `agente_id` | string | Opcional: sólo lo que le pase a ese agente. |
| `plantilla` | string | Sólo WhatsApp: el nombre de la plantilla aprobada. |
| `idioma` | string | Sólo WhatsApp: el idioma de la plantilla, `es_AR` por defecto. |
| `canal` | string | Sólo Slack y Teams: cómo se llama el canal, para mostrarlo. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `prender_destinatario`

_alcance: escritura · idempotente_

Prende un destinatario apagado. Idempotente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `destinatario_id` **(requerido)** | string | El id, de `listar_destinatarios`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `apagar_destinatario`

_alcance: escritura · idempotente_

Apaga un destinatario sin borrarlo: lo que estaba en cola para esa persona no sale. Idempotente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `destinatario_id` **(requerido)** | string | El id, de `listar_destinatarios`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `borrar_destinatario`

_alcance: escritura · destructiva · idempotente_

Borra a quién avisar, con su historial de entregas. Para una pausa usá apagar_destinatario.

| Argumento | Tipo | Qué es |
|---|---|---|
| `destinatario_id` **(requerido)** | string | El id, de `listar_destinatarios`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `probar_destinatario`

_alcance: escritura · idempotente_

Encola un aviso de prueba con el mismo texto que llega cuando un agente espera aprobación. Uno por minuto por destinatario: apretar dos veces manda uno.

| Argumento | Tipo | Qué es |
|---|---|---|
| `destinatario_id` **(requerido)** | string | El id, de `listar_destinatarios`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |


## Automatizaciones

Rutinas, disparadores, cajas y workers. Área de búsqueda: `automatizaciones`.

### `crear_rutina`

_alcance: escritura_

Crea una automatización: una rutina que le pide una tarea a un agente cada vez que un disparador suena. NACE APAGADA: queda escrita pero no dispara nada hasta que alguien la prenda — una persona en Automatizaciones, o este mismo token con prender_rutina. Los disparadores se agregan aparte con agregar_disparador. Con `clave`, volver a declararla con la misma clave la ACTUALIZA (conservando disparadores y estado) en vez de crear otra.

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | Cómo se llama la automatización en la pantalla. Corto y humano. |
| `clave` | string | Clave estable elegida por vos (p. ej. «cierre-diario»), única en la organización. Si ya hay una rutina con esa clave, se actualiza en vez de crear otra; la respuesta dice `actualizada: true`. Opcional. |
| `agente_id` | string | El agente que atiende cada disparo: el id que devolvió crear_agente o listar_agentes. Uno de los dos: `agente_id` o `equipo`. |
| `equipo` | string | La clave o el id de un equipo (de `listar_equipos`), en vez de un agente. Cada disparo va al líder de ESE momento —si el equipo cambia de líder, la rutina lo sigue— y la tarea nace con el presupuesto de árbol del equipo, que es el techo de todo lo que reparta. |
| `titulo` **(requerido)** | string | El título de la tarea que crea cada disparo. Fijo: el payload del disparo viaja aparte, como entrada de la tarea. |
| `descripcion` | string | Qué tiene que hacer la tarea, si el título solo no alcanza. Opcional. |
| `entrada` | object | Datos fijos que acompañan cada disparo. El payload del webhook se suma solo: esto es para lo que no cambia. |
| `concurrencia` | string | Qué pasa cuando un disparo llega y la corrida anterior sigue viva (y «viva» incluye la que espera una firma). «coalesce_if_active» (por defecto): el disparo se absorbe — bien para trabajo que no conviene apilar. «skip_if_active»: se saltea y queda registrado. «always_enqueue»: corre SIEMPRE — es la política para vigilancia periódica, donde una medición esperando firma no puede callar al vigía; las firmas se juntan en Aprobaciones y el vigilante las recuerda, pero nada se frena. |
| `caja` | string | Con qué caja de herramientas corre cada tarea de la rutina: el id o el nombre exacto de una caja de `listar_cajas`. Sin declararla corre con la caja completa del agente. Una caja de otra organización se rechaza. Alias: `perfil`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `editar_rutina`

_alcance: escritura · idempotente_

Cambia lo declarado de una automatización existente sin tocar su estado (prendida/apagada) ni sus disparadores: nombre, título de la tarea, descripción, entrada fija, concurrencia, caja de herramientas. Y el cron de UN disparador de reloj, dando `disparador_id` (de `listar_rutinas`) junto con `cron` y opcionalmente `zona`: un disparador que no sea de reloj, o que no sea de esta rutina, se rechaza. Cada cambio queda en la auditoría.

| Argumento | Tipo | Qué es |
|---|---|---|
| `rutina_id` **(requerido)** | string | El id que devolvió crear_rutina o listar_rutinas. |
| `nombre` | string | Nuevo nombre visible. Opcional. |
| `titulo` | string | Nuevo título de la tarea que crea cada disparo. Opcional. |
| `descripcion` | string | Nueva descripción. Opcional; vacío la borra. |
| `entrada` | object | Nueva entrada fija; reemplaza la anterior entera. Opcional. |
| `concurrencia` | string | coalesce_if_active, skip_if_active o always_enqueue. Opcional. |
| `caja` | string | Id o nombre exacto de una caja de `listar_cajas`; la palabra «completa» vuelve a la caja completa del agente. Opcional. Alias: `perfil`. |
| `disparador_id` | string | Sólo para cambiar el cron: el id del disparador de reloj, de `listar_rutinas`. |
| `cron` | string | Sólo con `disparador_id`: los cinco campos nuevos (min hora día mes díasemana). |
| `zona` | string | Sólo con `disparador_id`: zona horaria IANA nueva. Opcional; sin ella se conserva la que tiene. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_cajas`

_alcance: lectura · sólo lee · idempotente_

Las cajas de herramientas de la organización (perfiles): id, nombre y qué herramientas incluye cada una. El id o el nombre es lo que `crear_rutina`/`editar_rutina` aceptan en `caja`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `agregar_disparador`

_alcance: escritura_

Le agrega un disparador a una rutina: «reloj» (cron), «webhook» (otro sistema avisa con un POST firmado), «api» (sólo dispara cuando se lo llama) u «odoo» (el worker mira el Odoo conectado cada `cada_min` minutos y dispara una tarea por registro de `modelo` que cambió y cumple `dominio`, con el registro ya resuelto en la entrada; más de 20 en una vuelta van en UNA tarea). Para un webhook devuelve la URL pública y el secreto de firma UNA SOLA VEZ: guardalos en el momento, porque no se pueden volver a leer.

| Argumento | Tipo | Qué es |
|---|---|---|
| `rutina_id` **(requerido)** | string | El id que devolvió crear_rutina o listar_rutinas. |
| `tipo` **(requerido)** | string | reloj, webhook, api u odoo. |
| `cron` | string | Sólo para reloj: cinco campos (min hora día mes díasemana), evaluados en `zona`. |
| `zona` | string | Sólo para reloj: zona horaria IANA. Por defecto UTC. |
| `modo` | string | Sólo para webhook: hmac_sha256 (por defecto), bearer o hub_sha256. HMAC firma `${instante}.${cuerpo}`; bearer es un token fijo en Authorization; hub_sha256 es `X-Hub-Signature: sha256=<hmac del cuerpo>`, el que mandan Jira Cloud y GitHub (pegá el secreto en el campo Secret del webhook de Jira). |
| `ventana_seg` | number | Sólo para webhook: ventana anti-replay en segundos, entre 30 y 3600. Por defecto 300. |
| `modelo` | string | Sólo para odoo: el modelo que se mira, p. ej. account.move. |
| `dominio` | lista | Sólo para odoo: tripletas de Odoo; "{{hoy}}" es la fecha del día. Factura vencida: [["move_type","=","out_invoice"],["payment_state","in",["not_paid","partial"]],["invoice_date_due","<","{{hoy}}"]]. |
| `cada_min` | number | Sólo para odoo: cada cuántos minutos mira, mínimo 5. Por defecto 15. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `prender_rutina`

_alcance: escritura · idempotente_

Prende una automatización: desde ese momento sus disparadores crean tareas de verdad. Pide alcance de escritura. Se revierte con apagar_rutina, y el cambio queda asentado en la auditoría.

| Argumento | Tipo | Qué es |
|---|---|---|
| `rutina_id` **(requerido)** | string | El id que devolvió crear_rutina o listar_rutinas. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `apagar_rutina`

_alcance: escritura · idempotente_

Apaga una automatización: sus disparadores dejan de crear tareas (un webhook que llega responde como si la rutina no existiera). No borra nada; se vuelve a prender con prender_rutina.

| Argumento | Tipo | Qué es |
|---|---|---|
| `rutina_id` **(requerido)** | string | El id que devolvió crear_rutina o listar_rutinas. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `borrar_rutina`

_alcance: escritura · destructiva · idempotente_

Borra una automatización con sus disparadores (un webhook borrado deja de responder). Las tareas que ya creó no se tocan. No hay papelera: para frenarla sin perderla, apagar_rutina. Queda asentado en la auditoría.

| Argumento | Tipo | Qué es |
|---|---|---|
| `rutina_id` **(requerido)** | string | El id que devolvió crear_rutina o listar_rutinas. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_workers`

_alcance: lectura · sólo lee · idempotente_

Los workers de la organización y lo que cada uno contó de sí al reclamar: si está vivo (reclamó en el último minuto), qué huellas de bóveda puede abrir (`huellas`), qué versión corre, qué modelo usa por rol, contra qué portal habla, cuántos carriles, si corre con entorno aislado y qué sabe hacer su puente (`capacidades`: sin `efectos_aprobados` no ejecuta lo aprobado, sin `composio` no corre acciones de Composio). `misma_version_que_el_portal: false` quiere decir «corrés X, main es Y». `version_deseada` es la que el portal le pidió correr (desplegar_workers) y `actualizacion_pendiente: true` que todavía no la corre; `actualizacion_fallida` trae versión y motivo si la máquina tuvo que volver atrás. Un worker sin `se_presento` es anterior a esta versión: redesplegalo. Nada de acá es secreto.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `desplegar_workers`

_alcance: escritura · idempotente_

Le pide a los workers de la organización que pasen a correr una versión del código (sha de git). Sin `version`, la del portal (`version_del_portal` en listar_workers): es «poné a los workers al día con main». Nadie entra a la máquina: el worker recibe el pedido en su próximo reclamo, termina la tarea que tenga en curso, y un proceso local trae el código y lo reinicia; si la versión nueva no vuelve a reclamar en cinco minutos, vuelve solo a la anterior y listar_workers muestra `actualizacion_fallida` con el motivo. Esa versión no se vuelve a pedir sola: llamar de nuevo con la misma es la forma de reintentar. Devuelve qué workers quedaron con el pedido, cuáles ya la corrían y cuáles no están vivos (un worker apagado la va a tomar cuando arranque). Un worker cuya máquina no tiene el actualizador instalado lo dice en su log y sigue reclamando con la versión vieja: `salud_de_la_instalacion` lo marca a los 10 minutos.

| Argumento | Tipo | Qué es |
|---|---|---|
| `version` | string | El sha, de 7 a 40 hex. Opcional: sin él, la versión que corre el portal. |
| `worker_id` | string | Sólo este worker (id de listar_workers). Opcional: sin él, todos los de la organización. |
| `nota` | string | Por qué se despliega. Opcional; queda en la actividad. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `salud_de_la_instalacion`

_alcance: lectura · sólo lee · idempotente_

El diagnóstico de la instalación en una llamada, para no tener que abrir la base: variables que le faltan al portal (nombres, nunca valores), con qué huella sella hoy, los workers con lo que declararon, las credenciales selladas y si algún worker vivo puede abrirlas («sellada con A; ningún worker activo tiene A»), el modelo por rol del tenant y la divergencia worker/main. `problemas` es la lista ya redactada de lo que hay que arreglar, en orden. Si una tarea falla al abrir un sobre o el worker reclama y no pasa nada, empezá por acá.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `listar_rutinas`

_alcance: lectura · sólo lee · idempotente_

Las automatizaciones del tenant: qué agente atiende cada una, con qué disparadores (id, tipo, cron), si están prendidas, y los disparos de la última semana que NO crearon tarea (`disparos_sin_tarea_7d`) con el último motivo (`ultimo_disparo_sin_tarea`): p. ej. «rebotado» porque el agente no tiene versión en producción, o «absorbido» detrás de una tarea abierta. `absorbidos_7d` cuenta sólo los absorbidos, y `absorbiendo` dice qué tarea viva está tapando la rutina hoy, cuántos disparos seguidos y desde cuándo. Cada rutina y cada disparador vienen además dichos como en la pantalla de Rutinas: `cuando` (cuándo corre), `proxima` (la próxima corrida, en la zona de quien pregunta —`horas_en_zona`—; `null` si no va a correr sola) y `ultima` (qué pasó la última vez que disparó: creó una tarea, fue absorbida, salteada o rebotó, y hace cuánto). El `cron` crudo se queda, para quien edita. Si prendiste una rutina y no pasa nada, la respuesta está acá.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `disparar_rutina`

_alcance: escritura_

Dispara una automatización una vez, ahora, como si hubiera saltado su reloj. Sirve para probarla sin esperar el cron. Encola la tarea igual que un disparo real —cuesta lo mismo— y una rutina apagada no dispara.

| Argumento | Tipo | Qué es |
|---|---|---|
| `rutina_id` **(requerido)** | string | El id de la rutina, de `listar_rutinas`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |


## Webhooks

Avisos firmados hacia afuera: entregas, reenvío y el aviso de prueba. Área de búsqueda: `webhooks`.

### `listar_webhooks`

_alcance: lectura · sólo lee · idempotente_

Los destinos de avisos (webhooks) de la organización, con cuántas entregas salieron, cuántas esperan y cuántas fallaron, y el último error. Para ver entrega por entrega, listar_entregas_de_webhook.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `listar_entregas_de_webhook`

_alcance: lectura · sólo lee · idempotente_

El registro de entregas de un webhook, de la más nueva a la más vieja (sobre las últimas 100; `limite`/`desde` para paginar, `busca` filtra por evento o sobre): evento, estado (`pendiente`, `entregado`, `fallado`), intentos, status HTTP que contestó el endpoint, error y fechas. `prueba: true` marca las que salieron de disparar_evento_de_prueba. Con `entrega_id` de una fila, ver_entrega_de_webhook trae el cuerpo crudo, la firma y el curl.

| Argumento | Tipo | Qué es |
|---|---|---|
| `webhook_id` **(requerido)** | string | El id del webhook (listar_webhooks). |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `ver_entrega_de_webhook`

_alcance: lectura · sólo lee · idempotente_

Una entrega con el JSON crudo exactamente como viajó (es lo que se firma: no lo reformatees antes de verificar), una firma `t=…,v1=…` fresca calculada con el secreto real (vale 5 minutos), y el comando curl listo para pegar en una terminal y reproducir el aviso contra tu endpoint —sirve para probar un localhost o un túnel. Exige ser operador: con una firma válida cualquiera falsifica un aviso nuestro contra el endpoint del cliente. El secreto no se muestra nunca.

| Argumento | Tipo | Qué es |
|---|---|---|
| `entrega_id` **(requerido)** | string | El id de la entrega (listar_entregas_de_webhook). |

### `reenviar_entrega_de_webhook`

_alcance: escritura · idempotente_

Vuelve a mandar una entrega ahora —fallada, entregada o en cola—, con el mismo `sobre` para que un receptor idempotente la reconozca como el mismo hecho. Los intentos arrancan de cero. Devuelve el status que contestó el endpoint y el estado en que quedó (`entregado`, `pendiente` con reintento programado, `fallado`). Exige operador.

| Argumento | Tipo | Qué es |
|---|---|---|
| `entrega_id` **(requerido)** | string | El id de la entrega (listar_entregas_de_webhook). |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `disparar_evento_de_prueba`

_alcance: escritura_

Manda al webhook un aviso sintético FIRMADO con su secreto real, ahora, y devuelve cómo le fue: status HTTP del endpoint, estado, el cuerpo crudo, la firma y el curl para repetirlo. Es la forma de cerrar el ciclo (recibir → comprobar `x-yorobot-signature` → contestar 2xx) sin esperar a que una tarea termine. El cuerpo tiene la forma exacta del aviso real de `tarea.terminada` (tarea, lo que el agente afirmó, veredicto, url) más `prueba: true` y un id `prueba-…`; el sobre termina en `:prueba`. Se manda aunque el webhook no esté suscripto a ese evento (`suscripto: false` lo dice). Queda en la cola como cualquier entrega. Exige operador.

| Argumento | Tipo | Qué es |
|---|---|---|
| `webhook_id` **(requerido)** | string | El id del webhook (listar_webhooks). |
| `evento` | string | Qué evento simular. Por defecto `tarea.terminada`. Cualquiera de los eventos de aviso (ver /docs o listar_webhooks). |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |


## Datos

Entidades y registros de la organización. Área de búsqueda: `datos`.

### `listar_entidades`

_alcance: lectura · sólo lee · idempotente_

Qué objetos del negocio tiene definidos esta organización en Datos (lead, pedido, repartidor…): por cada una sus campos con tipo, cuáles son requeridos, los estados del ciclo de vida en orden (el primero es el inicial), la versión del esquema y cuántos registros tiene. Es lo primero que hay que mirar antes de consultar o guardar registros, y antes de definir una entidad nueva (para no duplicar una que ya existe con otro nombre).

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `definir_entidad`

_alcance: escritura · idempotente_

Crea una entidad de Datos o cambia una que ya existe (misma `clave`): el CRM, la flota, la cola de triaje arrancan por acá. Si el cuerpo es idéntico al que ya hay no pasa nada; si cambió, se apila una versión y los registros escritos con la anterior siguen leyéndose. Cada campo: { nombre, tipo, requerido?, descripcion? } más lo del tipo. Tipos: texto · numero · booleano · fecha (ISO) · opcion (con `opciones`: 2 a 30) · referencia (con `entidad`: la clave de otra entidad, que tiene que existir; el valor es la clave natural de un registro de ella) · dinero (con `moneda` ISO 4217; el valor es un número) · geo (el valor es { lat, lng }) · persona (el valor es el correo o el id de alguien del equipo; se guarda el id) · telefono (E.164) · email (se guarda en minúsculas) · url (una dirección web; «acme.com» se guarda como https://acme.com). Nombres de campo y estados: minúsculas, números y guión bajo. `id`, `clave`, `estado` y `entidad` están reservados. Los estados son opcionales (una entidad de consulta no tiene ciclo); si hay, el orden ES la declaración. Al definirla, el agente recibe solo las herramientas `leer_registros`, `guardar_registro` y `mover_estado` sobre ella (si el tenant no las tenía). Definir una entidad no otorga permisos a nadie.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clave` **(requerido)** | string | La clave de la entidad («lead», «repartidor»). Minúsculas, números y guión bajo. |
| `nombre` | string | Cómo se lee en la pantalla («Lead», «Repartidor»). Si falta, se usa la clave. |
| `campos` **(requerido)** | lista | Los campos, en orden. Entre 1 y 40. |
| `estados` | lista | El ciclo de vida, en orden; el primero es el inicial. Hasta 20. Omitilo si la entidad no tiene ciclo. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `consultar_registros`

_alcance: lectura · sólo lee · idempotente_

Los registros de una entidad, con el total real y una página. Filtrá por estado, por una palabra de la clave natural (`busca`), por igualdad sobre un campo declarado (`campo` + `valor`) o con `filtros`, que comparan: `<`, `<=`, `>`, `>=` para números, montos y fechas (AAAA-MM-DD), `=` y `!=`, y `vacio` / `con_valor`. `!=` NO incluye los que no tienen valor: «no se renueva» y «no dice» son distintos, y los segundos están en `vacio`. Cada registro trae `datos` ya interpretados: por campo el valor crudo y su `texto` (el dinero con moneda, la ubicación como «lat, lng», la persona con su nombre); y si salió de un documento, `citas` (de dónde salió cada campo) y `no_pude` (lo que el documento no dice). Del más reciente al más viejo. Si `total` es mayor que `mostrando`, paginá con `siguiente_desde`: no cuentes la lista.

| Argumento | Tipo | Qué es |
|---|---|---|
| `entidad` **(requerido)** | string | La clave de la entidad, de `listar_entidades`. |
| `estado` | string | Sólo los que están en este estado. |
| `busca` | string | Una parte de la clave natural (un mail, un número de pedido). |
| `campo` | string | Un campo de la entidad para filtrar por igualdad. Va con `valor`. |
| `valor` | object | El valor exacto de `campo` (texto, número o booleano). |
| `filtros` | lista | Hasta 6, y se cumplen todos: [{"campo": "vigencia_hasta", "op": "<", "valor": "2027-03-01"}, {"campo": "renovacion_automatica", "op": "=", "valor": false}]. |
| `limite` | number | Cuántos traer por página (1 a 200). Por defecto 50. |
| `desde` | number | Desde qué posición arrancar, para paginar. |

### `ver_registro`

_alcance: lectura · sólo lee · idempotente_

Un registro de Datos completo: sus datos interpretados, su estado, y la historia de quién lo movió (persona o agente), cuándo, con qué tarea y qué cambió —del hecho más nuevo al más viejo—. Se pide por `registro_id`, o por `entidad` + `clave` (la clave natural). Para lo que los agentes hicieron alrededor de él, `ver_actividad` con `registro_id`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `registro_id` | string | El id del registro, de `consultar_registros`. |
| `entidad` | string | La clave de la entidad, si se busca por clave natural. |
| `clave` | string | La clave natural del registro (el mail, el número de pedido). |

### `guardar_registro`

_alcance: escritura · idempotente_

Crea o actualiza UN registro de una entidad. La clave natural identifica al objeto en el negocio (el mail del lead, la patente del vehículo): si no existe se crea —con todos los campos requeridos—; si existe, los campos que mandes se combinan con los que tiene, y los que no mandes quedan como estaban. Mandar lo mismo dos veces es el mismo registro. `estado` mueve el ciclo de vida (al crear, si falta, arranca en el inicial). Los valores van con la forma de su tipo (ver `definir_entidad`). Queda anotado en la historia del registro con la persona que firma este token.

| Argumento | Tipo | Qué es |
|---|---|---|
| `entidad` **(requerido)** | string | La clave de la entidad. |
| `clave` **(requerido)** | string | La clave natural del registro. |
| `datos` **(requerido)** | object | Los campos, sólo los declarados por la entidad. |
| `estado` | string | El estado al que pasa. Opcional. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `importar_registros`

_alcance: escritura · idempotente_

Crea o actualiza hasta 100 registros de una entidad en una llamada: para migrar un CRM, cargar la flota, sembrar una cola. Cada fila es { clave, datos, estado? } con las mismas reglas que `guardar_registro`. Se procesa fila por fila: las que fallan no frenan a las demás, y la respuesta dice cuáles entraron, cuáles se actualizaron y cuáles fallaron con su motivo. No es una transacción: lo que entró, entró.

| Argumento | Tipo | Qué es |
|---|---|---|
| `entidad` **(requerido)** | string | La clave de la entidad. |
| `filas` **(requerido)** | lista | Hasta 100. Cada una: { clave, datos, estado? }. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |


## Consolas

Las pantallas declaradas del equipo del cliente. Área de búsqueda: `consolas`.

### `catalogo_de_consola`

_alcance: lectura · sólo lee · idempotente_

Qué se puede poner en la consola de un agente: sus entidades con campos y estados, y las herramientas que tiene HABILITADAS. Empezá siempre por acá: una consola que nombra algo que no está en este catálogo no se guarda.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |

### `biblioteca_de_consolas`

_alcance: lectura · sólo lee · idempotente_

De dónde partir en vez de una hoja en blanco: las formas de supervisión que ya conocemos —bandeja, tablero, revisión, cierre del día, pedirle algo al agente, ficha— armadas contra las entidades y las herramientas habilitadas de ESE agente.
Vuelven todas, también las que no aplican: cada una dice si aplica y, si no, qué le falta al catálogo (estados, entidades, herramientas).
Nada de esto se guarda: para bajar una, `arrancar_consola`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |

### `arrancar_consola`

_alcance: lectura · sólo lee · idempotente_

Arma una plantilla de la biblioteca para este agente y la devuelve SIN guardarla, con los supuestos que tomó (qué entidad eligió, qué estados leyó como «pendiente» o «listo»). Editala y proponela con `proponer_consola`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente. |
| `plantilla` **(requerido)** | string | La clave de la plantilla, de `biblioteca_de_consolas`. |

### `listar_consolas`

_alcance: lectura · sólo lee · idempotente_

Las consolas de la organización: su clave, de qué agente son, qué versión está publicada y si hay algo propuesto sin publicar.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `ver_consola`

_alcance: lectura · sólo lee · idempotente_

El cuerpo de una consola tal como se commitea en el repo del cliente (`.yorobot/consolas/<clave>.json`). Con `borrador: true` devuelve lo propuesto y todavía no publicado.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clave` **(requerido)** | string | La clave de la consola, que es su URL. |
| `borrador` | boolean | Ver lo propuesto en vez de lo publicado. |

### `proponer_consola`

_alcance: escritura · idempotente_

Propone una consola SIN publicarla: queda como borrador con URL de preview y diff contra lo publicado.
Los bloques son de once tipos y nada más (hasta 12 bloques por consola):
· { tipo: "contador", titulo, entidad, filtro? }
· { tipo: "tabla", titulo, entidad, columnas: [...], filtro? } — columnas: campos de la entidad, o clave/estado/actualizado/dueno
· { tipo: "tablero", titulo, entidad, etiqueta?: campo } — una columna por estado
· { tipo: "ficha", titulo, entidad, campos?: [...] } — el registro ELEGIDO (desde una lista, tabla o tablero de la misma consola) con sus campos; sin «campos», todos
· { tipo: "lista", titulo, entidad, encabezado: campo|"clave", detalle?: [hasta 3 campos], filtro?, limite?: 5..100 (20) } — tarjetas de los últimos que se movieron
· { tipo: "mapa", titulo, entidad, campo: campo GEO, etiqueta?: campo, filtro? } — cada registro con lat/lng como punto (hasta 500), en proporción y sin mapa de terceros
· { tipo: "grafico", titulo, entidad, por: campo|"estado", suma?: campo numero|dinero, filtro? } — barras: cuántos por «por», o la suma de «suma» por «por» (hasta 24 barras)
· { tipo: "linea_de_tiempo", titulo, entidad, campo: campo FECHA|"actualizado"|"creado", etiqueta?: campo, filtro?, limite?: 5..100 (20) } — los registros ordenados por ese momento
· { tipo: "actividad", titulo, agente?: id, limite?: 5..100 (20) } — lo que el agente fue haciendo, hecho por hecho, del registro elegido si hay uno
  Los tipos de campo salen del catálogo real del tenant (listar_entidades): un mapa sobre un campo que no es geo,
  una suma sobre un texto o una línea de tiempo sobre un número no validan. Si la entidad o el campo desaparecen
  después, el bloque se poda al leer y la pantalla dice por qué. Declarar un bloque NO habilita nada: quién ve
  esos registros y quién puede operarlos lo siguen decidiendo los roles y el puesto.
· { tipo: "comparacion", titulo, entidad, campoSugerido, campoValidado } — cuánto se le corrige al agente: coincidencias y, si el campo validado declara opciones, cuántas veces una persona SUBIÓ y cuántas BAJÓ (la primera opción es el extremo alto). Lo que nadie validó todavía queda fuera del denominador.
· { tipo: "acciones", titulo, acciones: [ { tipo: "mover_estado", etiqueta, entidad, a: estado, desde?: estado, confirmar?: true, avisar?: "título de la tarea" } | { tipo: "pedir_tarea", etiqueta, titulo } | { tipo: "llamar_herramienta", etiqueta, herramienta } ] }
  o { tipo: "anotar", etiqueta, entidad, campos: [ { campo, opciones?: [...], deEntidad?: entidad, requerido?: true } ], firma?: campo, a?: estado, avisar?: título } ]
  o { tipo: "crear", etiqueta, entidad, clave: campo, campos: [ … ], firma?: campo, a?: estado } ]
  «crear» estrena un registro: es cómo una persona agrega una tarjeta al tablero sin pasar por un agente.
  «clave» nombra cuál de los campos del formulario identifica al registro (el título de la tarea, el mail),
  y ese campo va requerido. Si ya existe uno con esa clave no se pisa: se dice que ya está.
  «anotar» es el formulario: una persona escribe campos del registro. Hasta 4 campos; con «opciones» el valor
  sale de una lista cerrada (un color tipeado a mano llega en tres grafías y deja de ser contable).
  «deEntidad» completa el campo con los REGISTROS de otra entidad (el centro, la sucursal, la zona): la lista
  sale del padrón al abrir la pantalla y el servidor rechaza cualquier valor que no sea uno de ellos. Es lo que
  hace que repartir una cola no pueda inventar un destino, y no envejece cuando abre un centro nuevo. No se
  combina con «opciones»: dos listas para el mismo campo es una que miente.
  «firma» es el campo donde el SERVIDOR escribe quién apretó, tomado de la sesión: no se pide en el formulario
  y no puede estar además en «campos». Un campo así llenado a mano no dice quién decidió, dice qué se tipeó.
  «a» deja el registro en ese estado en la MISMA escritura que la anotación: dos escrituras dejarían un intervalo
  donde el registro ya está validado y todavía no dice qué se validó.
  «desde» en mover_estado exige que el registro ESTÉ en ese estado: es cómo se ordena una cola de dos pasos.
  Sin «desde», el botón que deriva y avisa se puede apretar sobre un registro que nadie validó todavía, y lo
  único que lo evita es que la persona haya apretado los botones en el orden correcto.
  «confirmar» en mover_estado pregunta antes de mover, y es lo que hace seguro el tablero: una tarjeta se
  arrastra a la columna de al lado sin querer, y hay estados de los que no se vuelve («ganado», «perdido»).
  Un tablero deja arrastrar SÓLO a las columnas que tienen su botón declarado acá: lo que no se puede apretar
  tampoco se puede soltar.
  «avisar» en mover_estado y en anotar encola esa tarea DESPUÉS de escribir, con el registro ya actualizado:
  úsalo cuando decidir y comunicar sean el mismo acto y partirlo en dos botones deje a alguien esperando.
  Botones de canal, todos sobre un registro elegido: { tipo: "llamar", etiqueta, entidad, telefono: campo TELEFONO, motivo }
  | { tipo: "mensajear", etiqueta, entidad, telefono: campo TELEFONO, plantilla: plantilla aprobada por Meta, idioma?: "es_AR", parametros?: [campos, hasta 6] }
  | { tipo: "escalar", etiqueta, entidad } | { tipo: "aprobar", etiqueta, entidad }.
  «llamar» exige el canal de voz PRENDIDO en producción y le pide la llamada al agente como tarea (presupuesto,
  guardarriel y bitácora de siempre). «mensajear» exige WhatsApp prendido y encola la plantilla con los parámetros
  tomados del registro, una vez por registro, plantilla y día. «escalar» exige que algún destinatario de Avisos
  reciba «consola.escalada»; la persona escribe el motivo y sale el aviso. «aprobar» lleva a la tarea que espera
  firma por ese registro: NO firma desde la consola. Si el canal está apagado el botón se poda al leer; una vista
  no prende canales (eso es Capacidades), y el teléfono sale del registro, nunca de quien aprieta.
La consola entera se puede partir por un campo con «segmentar»: { campo, etiqueta? } al lado de «bloques».
  La pantalla muestra un selector con los valores que HAY —más «sin valor», que es su propia cola— y lo elegido
  filtra TODOS los bloques, contadores incluidos. Es para un mismo trabajo repartido por sucursal, centro o
  zona: siete consolas publicadas se corrigen de a una y quedan desalineadas seis.
  El campo tiene que existir en TODAS las entidades que la consola mira, o no valida: un bloque que no se puede
  segmentar mostraría todo mientras el encabezado anuncia uno solo. Segmentar es una forma de mirar y NO un
  permiso: quién puede operar sobre esos registros lo siguen decidiendo los roles.
El filtro es una condición { campo, igual } o { campo, vacio: true } (el campo todavía no tiene valor),
o varias que se cumplen TODAS: { y: [ {...}, {...} ] }, hasta 4. Sin «y» un bloque sólo puede pedir una cosa,
y «rojos sin validar» termina contando también los ya validados.
Si algo no valida, la respuesta trae TODOS los problemas: corregí y volvé a proponer.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clave` **(requerido)** | string | Minúsculas y guiones, empieza con letra: es la URL («mesa-de-entradas»). |
| `agente_id` | string | El agente dueño. Obligatorio si la consola es nueva; de él salen las herramientas autorizadas. |
| `titulo` **(requerido)** | string | El encabezado que lee la persona que opera. |
| `subtitulo` | string | Una línea de contexto. Vacío si no aporta. |
| `bloques` **(requerido)** | lista | La consola misma, en orden de arriba hacia abajo. |
| `segmentar` | object | Opcional: { campo, etiqueta? } para partir la consola entera por un campo (centro, sucursal, zona). |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `publicar_consola`

_alcance: escritura · idempotente_

Publica el borrador: recién acá cambia la pantalla con la que trabaja el equipo del cliente. Se vuelve a validar contra lo que hay HOY, y queda en la bitácora con quién publicó.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clave` **(requerido)** | string | La clave de la consola. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `descartar_borrador`

_alcance: escritura · destructiva · idempotente_

Tira lo propuesto. Lo publicado no se toca; una consola que nunca se publicó se borra entera.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clave` **(requerido)** | string | La clave de la consola. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |


## Cerebro y memoria

Conocimiento: documentos, fuentes vivas, memorias y skills. Área de búsqueda: `conocimiento`.

### `listar_memorias`

_alcance: lectura · sólo lee · idempotente_

La memoria de la organización por estado: qué dice cada una, de qué agente es, de dónde salió, si la respalda una medición independiente, y sus usos/aciertos/fallos. Empezá por acá antes de proponer: una lección que ya está activa vuelve a entrar como duplicada.

| Argumento | Tipo | Qué es |
|---|---|---|
| `estado` | string | propuesta \| activa \| suspendida \| jubilada, o varias separadas por coma. Por defecto propuesta,activa. |
| `agente_id` | string | Sólo la memoria de ese agente. Vacío trae también la de la organización (el piso compartido). |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `proponer_memoria`

_alcance: escritura · idempotente_

Propone una memoria para un agente. NACE PROPUESTA: no viaja a ninguna corrida hasta que alguien la acepte con `decidir_memoria`.
El `trigger` es cuándo aplica y `contents` qué hacer: las dos las lee el modelo en la próxima corrida, así que van cortas y en imperativo.
Se rechaza —con motivo— lo que la pantalla también rechaza: instrucciones dirigidas al modelo que vengan de un tercero, credenciales, Unicode invisible, y contenido clínico o identificatorio en un perfil.
Los tipos `episodio` y `perfil` NO se cargan a mano por acá: un episodio sale del verificador de una corrida y un perfil exige sujeto para poder purgarse cuando esa persona pida que la olviden.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` | string | De qué agente es. Vacío = de la organización, el piso que comparten todos. |
| `tipo` | string | hecho (un dato del negocio), regla (una política de la casa) o leccion (lo que salió mal una vez). Por defecto leccion. |
| `trigger` **(requerido)** | string | Cuándo aplica, en una línea: «cuando el pedido no trae número de socio». |
| `contents` **(requerido)** | string | Qué hacer, en imperativo y corto. Es lo que va a leer el modelo. |
| `proyecto_id` | string | Opcional: la limita a las tareas de ese proyecto. |
| `evidencia_tarea_id` | string | La tarea de la que sale, si sale de una. Es el link a la evidencia. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `medir_memoria`

_alcance: escritura_

Manda a medir una memoria: la suite de casos congelados del agente DOS veces, con ella y sin ella, y el veredicto sale por caso.
Sirve sobre una propuesta SIN aceptarla —es el punto: medir antes de decidir— y también sobre una activa, para poder jubilar la que no aporta.
Arregló 3 y rompió 1 es REGRESIÓN y no un neto de +2: es lo que un promedio esconde. Encola las dos pasadas y vuelve; el veredicto lo escribe el último caso.
Cada llamada corre la suite completa dos veces y eso se paga: mandá `clave_de_pedido` para que un reintento no la corra de nuevo.

| Argumento | Tipo | Qué es |
|---|---|---|
| `memoria_id` **(requerido)** | string | El id de la memoria, de `listar_memorias`. |
| `agente_id` | string | Contra qué agente medir. Obligatorio para una memoria de la organización, que no tiene dueño. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `decidir_memoria`

_alcance: escritura · idempotente_

Decide una propuesta: `aceptar` la pone a viajar en las próximas corridas de ese agente, `descartar` la jubila.
Aceptar admite editar el texto en el mismo acto, y lo que se guarda es LO EDITADO: el filtro de contenido vuelve a correr sobre eso, y si la memoria salía de un documento se vuelve a comprobar el respaldo textual contra el fragmento citado.
Es una decisión de gobierno y queda en la bitácora con quién la tomó. NO es una aprobación de tarea: eso sigue estando sólo en la pantalla.

| Argumento | Tipo | Qué es |
|---|---|---|
| `memoria_id` **(requerido)** | string | El id de la propuesta, de `listar_memorias`. |
| `decision` **(requerido)** | string | aceptar o descartar. |
| `trigger` | string | Sólo al aceptar: reemplaza el «cuándo aplica». Vacío deja el propuesto. |
| `contents` | string | Sólo al aceptar: reemplaza el «qué hacer». Vacío deja el propuesto. |
| `motivo` | string | Sólo al descartar: por qué no entra. Queda en la constancia. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_skills`

_alcance: lectura · sólo lee · idempotente_

Las skills instaladas: cómo se llama cada una, cuándo la abre un agente, qué nivel de confianza tiene, su versión y su hash, y a cuántos agentes está puesta. Una skill puesta viaja en el prompt de cada corrida de ese agente. Con `agente_id`, dice además cuáles tiene puestas ESE agente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` | string | Opcional: el id de un agente, para saber cuáles tiene puestas. |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `cargar_skill`

_alcance: escritura · idempotente_

Carga una skill desde su SKILL.md completo, con el frontmatter.
El frontmatter necesita `name` y `description`. La `description` es lo que decide CUÁNDO el agente la abre, así que dice en qué pedidos aplica, no qué es.
CARGAR NO LA ASIGNA: la skill queda en la organización y no viaja a ninguna corrida hasta `asignar_skill`.
El nivel de confianza lo mide la plataforma del contenido, no de lo que el archivo declare: un SKILL.md que trae cosas para ejecutar queda en `scripts_executables` aunque diga otra cosa, y bajo contención esas quedan afuera.

| Argumento | Tipo | Qué es |
|---|---|---|
| `cuerpo` **(requerido)** | string | El SKILL.md entero, con su frontmatter `---`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `asignar_skill`

_alcance: escritura · idempotente_

Pone una skill en un agente, o se la saca con `puesta: false`. Puesta, viaja en el prompt de TODAS las corridas de ese agente — no es una biblioteca que consulta, es contexto que carga siempre. Bajo contención, cuando el agente lee texto que escribió un tercero, las que traen cosas para ejecutar quedan afuera aunque estén puestas.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El id del agente, de `listar_agentes`. |
| `skill_id` **(requerido)** | string | El id de la skill, de `listar_skills`. |
| `puesta` | boolean | true la pone, false la saca. Por defecto true. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_fuentes`

_alcance: lectura · sólo lee · idempotente_

Los documentos del cerebro de la organización: título, cuándo usarlo, alcance, estado, la versión vigente, cuántos fragmentos tiene y cuántos quedaron marcados como sospechosos. Sólo las publicadas llegan a una corrida.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `ver_documento`

_alcance: lectura · sólo lee · idempotente_

Un documento con todas sus versiones (número, formato, estado, hash) y qué agentes lo tienen habilitado. Con `version_id` devuelve además los fragmentos de esa versión con su orden y su hash: son las unidades que se citan, y el orden es lo que una cita nombra.

| Argumento | Tipo | Qué es |
|---|---|---|
| `documento_id` **(requerido)** | string | El id del documento, de `listar_fuentes`. |
| `version_id` | string | Opcional: además, los fragmentos de esa versión. |
| `citas` | boolean | Traer también qué corridas lo citaron, con la versión que leyeron. |

### `cargar_documento`

_alcance: escritura · idempotente_

Carga un documento al cerebro: crea la fuente (o le agrega una versión, con `documento_id`) y la fragmenta.
CARGAR NO PUBLICA: la versión queda en borrador y no llega a ninguna corrida hasta `publicar_documento`.
El texto va en `texto` (Markdown o texto plano). Un PDF va en `contenido_base64` con su `nombre_archivo`; si el PDF no tiene texto —un escaneo— se rechaza CON MOTIVO en vez de entrar vacío: no hay OCR.
El `resumen` es lo único que viaja SIEMPRE —una línea por fuente en el índice de cada corrida—, así que es «cuándo usar este documento» y no un abstract.
`guardar_original` deja además el archivo: va en true para protocolos y contratos de la organización, porque hace falta para auditar una cita, y en FALSE para cualquier documento con datos de personas.

| Argumento | Tipo | Qué es |
|---|---|---|
| `documento_id` | string | Para agregar una versión a un documento que ya existe. Vacío crea uno nuevo. |
| `titulo` | string | Cómo se llama. Obligatorio si es nuevo. |
| `resumen` | string | Cuándo usarlo, en una línea. Obligatorio si es nuevo: es lo que el agente lee en el índice para decidir si lo abre. |
| `alcance` | string | tenant (todos los agentes), proyecto (los de ese proyecto) o agente (sólo los que lo tengan habilitado). Por defecto tenant. |
| `proyecto_id` | string | Obligatorio si el alcance es proyecto. |
| `guardar_original` | boolean | Guardar el archivo además del texto. Por defecto false: el default seguro es el que no deja el original en la base. |
| `texto` | string | El cuerpo, en Markdown o texto plano. |
| `contenido_base64` | string | Alternativa a `texto` para un PDF: el archivo en base64. |
| `nombre_archivo` | string | El nombre con extensión (`protocolo.md`, `contrato.pdf`). Con `contenido_base64` es obligatorio: de la extensión sale cómo se extrae el texto. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_colecciones`

_alcance: lectura · sólo lee · idempotente_

Las colecciones del cerebro («Contratos de proveedores», «Facturas 2026»): cada una con su plantilla de corte, su alcance y cuántos documentos tiene —publicados (los ven las corridas) y en borrador (todavía no)—. Para cargar a una, `cargar_documentos` con su nombre o id.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `crear_coleccion`

_alcance: escritura_

Crea una colección: un conjunto de documentos que se carga por lote y se busca adentro («Contratos de proveedores»). Sus documentos heredan el alcance y la plantilla de corte.
La plantilla decide dónde se parte cada documento en fragmentos citables: `clausulas` para contratos y reglamentos (corta donde empieza cada cláusula numerada: «7.2», «CLÁUSULA PRIMERA», «Artículo 5»), `filas` para planillas (grupos de filas con el encabezado adelante), `parrafos` para todo lo demás.
El nombre no se repite en la organización.

| Argumento | Tipo | Qué es |
|---|---|---|
| `nombre` **(requerido)** | string | Cómo se llama, hasta 80 caracteres. |
| `descripcion` | string | Qué hay adentro, en una línea: va en el «cuándo usarlo» de cada documento. |
| `plantilla` | string | parrafos (por defecto), clausulas o filas. |
| `alcance` | string | tenant (todos los agentes, por defecto), proyecto o agente. |
| `proyecto_id` | string | Obligatorio si el alcance es proyecto. |
| `agente_id` | string | Obligatorio si el alcance es agente: el único agente que la lee. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `cargar_documentos`

_alcance: escritura · idempotente_

Carga hasta 20 documentos por llamada, cada uno por su lado: la respuesta dice qué pasó con cada archivo —`ingerida`, `duplicada` (el mismo archivo ya estaba: dónde) o `rechazada` (con el motivo)—. Un rechazo no deja nada cargado.
A diferencia de `cargar_documento`, PUBLICA por defecto lo que entra limpio (`publicar: false` para dejarlo en borrador). Lo que trae un fragmento que parece una instrucción al modelo queda en borrador igual, con el porqué.
Cada documento va con `nombre_archivo` (de la extensión sale cómo se extrae: .md, .txt, .pdf con texto, .html) y `contenido_base64`, o `texto` para Markdown. El título es el nombre del archivo.
Con `coleccion`, entran a esa colección y heredan su alcance y su plantilla de corte. El cuerpo de la llamada no puede pasar de 4 MB: para una carpeta grande, varias llamadas (o `yorobot cerebro subir`).
Cuenta contra el techo de documentos del plan: lo que lo pasa se rechaza con ese motivo y lo anterior queda.

| Argumento | Tipo | Qué es |
|---|---|---|
| `coleccion` | string | La colección, por nombre o por id. Vacío deja los documentos sueltos en el cerebro. |
| `documentos` **(requerido)** | lista | Hasta 20. |
| `publicar` | boolean | Por defecto true: lo que entra limpio lo ven las corridas enseguida. |
| `guardar_original` | boolean | Guardar el archivo además del texto (por defecto true, para auditar una cita). En false para documentos con datos de personas. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `configurar_extraccion`

_alcance: escritura · idempotente_

Convierte una colección en una TABLA de Datos: un agente por documento (el Extractor de la biblioteca) lee ese documento y llena una fila, con la cita del fragmento de donde sacó cada campo. Lo que el documento no dice queda sin valor y con el porqué (`no_pude`): nunca inventado.
Es la forma de comparar cientos de documentos: después, `consultar_registros` con `filtros` contesta «¿cuáles vencen antes de marzo y no se renuevan solos?» sin volver a leer ninguno.
`plantilla`: `contratos` (partes, objeto, fecha_firma, vigencia_hasta, monto, moneda, renovacion_automatica, plazo_de_rescision, jurisdiccion, penalidades) o `facturas` (proveedor, numero, fecha, vencimiento, total, moneda, concepto). O tu `esquema`, con la pregunta que contesta cada campo.
Encola una tarea por documento publicado, y desde ahí cada documento o versión nueva de la colección se extrae sola. Cambiar el esquema re-extrae todo; repetir con el mismo, nada. La respuesta dice cuántas tareas se crearon, en qué ambiente corren y el TOPE de plata (documentos × presupuesto por documento): decíselo a la persona antes de dar por hecho el gasto.

| Argumento | Tipo | Qué es |
|---|---|---|
| `coleccion` **(requerido)** | string | La colección, por nombre o id. |
| `plantilla` | string | contratos o facturas. Alternativa a `esquema`. |
| `esquema` | object | { entidad, nombre, campos: [{ nombre, tipo, pregunta, opciones?, moneda? }] }. `entidad` en minúsculas («contratos_proveedores»); tipos: texto, numero, booleano, fecha, opcion, dinero, email, url, telefono; `pregunta` es lo que el agente le pregunta al documento («¿Hasta qué fecha rige, sin contar renovaciones?»). Hasta 20 campos. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `extraer_pendientes`

_alcance: escritura · idempotente_

Encola lo que la extracción de una colección dejó sin tarea: la cuota de tareas automáticas llena, el tope de gasto, el Extractor apagado, o más de 1000 documentos de una vez. Con `reintentar_fallidas`, también los documentos cuya tarea terminó sin escribir la fila — no se reintentan solos porque un documento que el agente no puede leer fallaría cada vez, y cada vez se paga.

| Argumento | Tipo | Qué es |
|---|---|---|
| `coleccion` **(requerido)** | string | La colección, por nombre o id. |
| `reintentar_fallidas` | boolean | Volver a pedir también los que fallaron. Por defecto false. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `comparar_documentos`

_alcance: lectura · sólo lee · idempotente_

Compara dos documentos del cerebro sección por sección —o dos versiones del mismo— y devuelve las diferencias ya calculadas: qué cláusulas cambiaron (lo que se sacó y lo que se puso), cuáles se renumeraron, cuáles están de un solo lado y cuáles son idénticas.
Las cláusulas se alinean por número aunque uno escriba «SEGUNDA» y el otro «2», y la que cambió de número se encuentra por el texto. Cada diferencia trae la cita a los DOS documentos: al contarla, citá las dos.
No leas los dos documentos para compararlos a ojo: esto ya lo hizo, y no se saltea la cláusula que se movió.

| Argumento | Tipo | Qué es |
|---|---|---|
| `a` **(requerido)** | string | El id del primer documento. |
| `b` **(requerido)** | string | El id del segundo. Puede ser el mismo que `a`, con otra versión. |
| `version_a` | number | La versión de `a`. Por defecto, la publicada. |
| `version_b` | number | La versión de `b`. Por defecto, la publicada. |

### `publicar_documento`

_alcance: escritura · idempotente_

Publica una versión: recién acá el documento empieza a ofrecerse en las corridas que vengan. La anterior queda archivada y las citas viejas siguen apuntando a la versión que el agente leyó.

| Argumento | Tipo | Qué es |
|---|---|---|
| `documento_id` **(requerido)** | string | El id del documento. |
| `version_id` **(requerido)** | string | La versión a publicar, de `ver_documento`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `despublicar_documento`

_alcance: escritura · destructiva · idempotente_

Retira el documento de las corridas que vengan y SUSPENDE las memorias que se habían promovido de él: una regla destilada de un documento retirado seguiría afirmando lo mismo desde adentro del prompt. No borra el texto ni las citas; para eso está la purga, que es de la pantalla.

| Argumento | Tipo | Qué es |
|---|---|---|
| `documento_id` **(requerido)** | string | El id del documento. |
| `motivo` | string | Por qué se retira. Queda en la bitácora de la fuente. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `alcance_de_documento`

_alcance: escritura · idempotente_

Prende o apaga un documento para UN agente. Es lo que hace que el cerebro compartido no sea un cajón único: un documento de alcance `agente` sólo llega a los que están habilitados acá.

| Argumento | Tipo | Qué es |
|---|---|---|
| `documento_id` **(requerido)** | string | El id del documento. |
| `agente_id` **(requerido)** | string | El id del agente. |
| `habilitado` **(requerido)** | boolean | true lo habilita, false lo saca. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `medicion_del_cerebro`

_alcance: lectura · sólo lee · idempotente_

La medición del cerebro documental, que es el gate para decidir si hacen falta embeddings — y hoy no hacen falta.
Nada está etiquetado a mano: el positivo es una cita válida, así que volver a seleccionar con el mismo pedido mide el recall contra evidencia real.
Separa las tres maneras de tener recall bajo: sin evidencia (0 de 0 no es 0%), `desplazada` (coincidía y le ganaron el lugar en el índice: eso se arregla con el tope, no con vectores) y `no_coincide`, que es la única que un vector store arregla.

Sin argumentos.

### `grafo_del_cerebro`

_alcance: lectura · sólo lee · idempotente_

El cerebro de la organización como grafo: documentos, memorias, agentes y proyectos como nodos, y como relaciones lo que la plataforma registró — `cita` (una ejecución del agente citó el documento, con versión y fragmento; `peso` es cuántas veces), `alcance` (habilitado para el agente sin cita todavía), `promovida` (la memoria salió del documento), `memoria` (del agente, o la usó), `proyecto` y `reemplaza`.
Sirve para contestar de dónde sale lo que un agente afirma, quién más usa un documento, y qué conocimiento publicado no está usando nadie (`sin_uso`). Es lo mismo que dibuja la pantalla Cerebro → Grafo.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tipos` | lista | Qué nodos incluir. Sin esto, todos. |

### `listar_fuentes_vivas`

_alcance: lectura · sólo lee · idempotente_

Las fuentes vivas del cerebro: qué conexión a HubSpot u Odoo hay, qué objetos trae, cuándo sincronizó por última vez, con qué resultado (nuevos, cambiados, iguales, rechazados), cuándo toca la próxima y si la última falló y por qué.
También dice si falta la credencial (`tiene_credencial`): la conexión usa la misma llave que la herramienta del agente, la que se carga con `cargar_credencial` o en Conexiones.

| Argumento | Tipo | Qué es |
|---|---|---|
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `conectar_fuente_viva`

_alcance: escritura_

Conecta HubSpot u Odoo como fuente del cerebro. Se elige OBJETO POR OBJETO (`objetos`): no se trae el CRM o el ERP entero. `catalogo_de_fuentes_vivas` lista los objetos de cada proveedor y cuáles traen datos de personas.
Lo que trae entra por la misma ingestión que un archivo: escaneo, hash, versión sólo si cambió, fragmentos y citas. Por defecto queda EN BORRADOR; `publicar: true` publica solo cada documento que trae.
La primera sincronización la hace el worker de la organización en su próxima vuelta; después, cada `cada_horas`. La credencial tiene que estar cargada con `cargar_credencial` o en Conexiones (`hubspot_token` u `odoo_api_key`); esta llamada no la pide ni la ve.

| Argumento | Tipo | Qué es |
|---|---|---|
| `proveedor` **(requerido)** | `hubspot` · `odoo` | hubspot u odoo. |
| `nombre` | string | Cómo llamar a la conexión. Por defecto, el nombre del proveedor. |
| `url` | string | Sólo Odoo: la URL https del servidor, p. ej. https://miempresa.odoo.com. |
| `objetos` **(requerido)** | lista | Qué traer, por clave del catálogo: articulos, tickets, negocios, empresas, notas (HubSpot); articulos, productos, tickets, notas (Odoo). |
| `limite` | number | Tope de registros por objeto y sincronización, de 1 a 2000. Por defecto 200. |
| `cada_horas` | number | Cada cuántas horas sincronizar, de 1 a 720. Por defecto 24. |
| `alcance` | string | tenant, proyecto o agente. Por defecto tenant. |
| `proyecto_id` | string | Obligatorio si el alcance es proyecto. |
| `publicar` | boolean | Publicar solo lo que trae. Por defecto false: queda en borrador. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `catalogo_de_fuentes_vivas`

_alcance: lectura · sólo lee · idempotente_

Los proveedores que el cerebro puede conectar (HubSpot, Odoo) y, para cada uno, los objetos que se pueden elegir, qué traen y cuáles tienen datos de personas.

Sin argumentos.

### `configurar_fuente_viva`

_alcance: escritura · idempotente_

Cambia objetos, tope, frecuencia, alcance, publicación automática o pausa (`activa: false`) de una conexión. Lo ya traído no se borra: los documentos siguen con sus versiones y citas.

| Argumento | Tipo | Qué es |
|---|---|---|
| `fuente_viva_id` **(requerido)** | string | El id, de `listar_fuentes_vivas`. |
| `nombre` | string | Nuevo nombre. |
| `url` | string | Sólo Odoo: nueva URL https. |
| `objetos` | lista | Nuevos objetos a traer. |
| `limite` | number | Nuevo tope de registros por objeto y sincronización, de 1 a 2000. |
| `cada_horas` | number | Cada cuántas horas sincronizar, de 1 a 720. |
| `alcance` | string | tenant, proyecto o agente. |
| `proyecto_id` | string | Si el alcance es proyecto. |
| `publicar` | boolean | true publica solo lo que trae; false lo deja en borrador. |
| `activa` | boolean | false pausa la conexión: deja de sincronizar hasta reanudarla. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `sincronizar_fuente_viva`

_alcance: escritura · idempotente_

Marca la conexión para que el worker la sincronice en su próxima vuelta, sin esperar el plazo. No trae nada desde acá: el resultado se ve después con `listar_fuentes_vivas`.

| Argumento | Tipo | Qué es |
|---|---|---|
| `fuente_viva_id` **(requerido)** | string | El id de la conexión. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `desconectar_fuente_viva`

_alcance: escritura_

Borra la conexión. Los documentos que trajo QUEDAN, con sus versiones y citas, como documentos sueltos; para que se vayan hay que purgarlos o esperar la retención. La credencial no se toca.

| Argumento | Tipo | Qué es |
|---|---|---|
| `fuente_viva_id` **(requerido)** | string | El id de la conexión. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `buscar_en_cerebro`

_alcance: lectura · sólo lee · idempotente_

Busca en el TEXTO de todos los documentos publicados del Cerebro de la organización —contratos, protocolos, manuales— y devuelve los pasajes que coinciden, cada uno con su cita `[cerebro/…#n]`, el documento, la versión vigente y la sección («Cláusula 7.2 · p. 3»). Buscá con las palabras del documento; si lo que vuelve no alcanza, buscá de nuevo con otras. Dice cuántos pasajes coincidieron en total y si la lista está recortada. Una búsqueda por texto no entiende negaciones: «no se renueva» también coincide con «renovación», así que leé el pasaje antes de afirmar.

| Argumento | Tipo | Qué es |
|---|---|---|
| `consulta` **(requerido)** | string | Qué buscar, con las palabras que usaría el documento. |
| `coleccion` | string | Sólo en esta colección (nombre o id). |
| `documento_id` | string | Sólo adentro de este documento. |
| `limite` | number | Cuántos pasajes, hasta 30. Por defecto 10. |


## Consumo y límites

El plan y la membresía, gasto, topes (también el de cada agente), cuotas, el registro de pedidos, retención y la cartera partner. Área de búsqueda: `consumo`.

### `fijar_cuota_mensual`

_alcance: escritura · idempotente_

Fija el tope mensual de gasto de modelo de la organización, en USD: el número contra el que la cola frena toda tarea nueva. Lo fija un técnico o un admin. Para sacarlo hace falta `sin_tope: true` con todas las letras (sólo tiene sentido si la organización trae su propia llave de modelo). El tope se puede bajar, pero no subir por encima del que trae el plan (ni sacar, si el plan trae uno): eso lo hace un cambio de plan o YoRobot, y el error lo dice con el número. La respuesta dice el tope de antes, el de ahora y el que el plan traería por defecto, para que se vea de qué te alejás.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tope_usd` | number | El tope en USD por mes, cero o más. |
| `sin_tope` | boolean | true para sacar el tope. Incompatible con `tope_usd`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `fijar_tope_diario`

_alcance: escritura · idempotente_

Fija el tope DIARIO de gasto de modelo de la organización, en USD, aparte del mensual: el mensual ve el accidente cuando ya se comió el mes; éste frena la cola el mismo día (un webhook que rebota, una automatización descontrolada). Cuenta todos los ambientes juntos, en el huso de la organización. Va en dólares y no en tokens porque el costo depende del modelo y de entrada/salida, y la factura se lee en dólares. Lo fija un técnico o un admin. `sin_tope: true` lo saca.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tope_usd` | number | El tope en USD por día, mayor que cero. |
| `sin_tope` | boolean | true para sacar el tope diario. Incompatible con `tope_usd`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `ver_cuotas`

_alcance: lectura · sólo lee · idempotente_

Todos los límites de consumo de la organización con lo consumido hasta ahora: el tope mensual y el diario de gasto de modelo (USD), el tope mensual de prueba/preproducción, y los techos por ventana (cuántas tareas o ejecuciones entran por hora o por día, por tipo). Cada techo dice cuánto va usado, cuánto queda y a qué hora se libera. `frenado: true` cuando algún tope de gasto ya está lleno y la cola no despacha.

Sin argumentos.

### `ver_plan`

_alcance: lectura · sólo lee · idempotente_

El plan de la organización y lo que ese plan frena: agentes propios contra el techo (las plantillas de YoRobot no cuentan), si puede crear otro, los ambientes (si llega a producción), quién ejecuta las tareas (el pool de YoRobot o un worker dedicado), el tope de modelo del mes y los techos por ventana que trae el plan. Lo gastado contra cada tope está en `ver_cuotas`. El plan lo cambia YoRobot; la organización puede bajar sus límites, no subirlos.

Sin argumentos.

### `ver_membresia`

_alcance: lectura · sólo lee · idempotente_

La membresía de la organización: el plan (`plan` y `plan_texto`, la palabra que se ve en el portal), su `estado` y si hay algo que pagar (`hay_que_pagar`, `pagar_en`). Mientras YoRobot no cobre por la web es siempre `sin_facturacion` con `pagar_en: null`: no hay link de pago que dar, y el plan lo cambia YoRobot. Lo mismo que `GET /api/v1/membresia`.

Sin argumentos.

### `fijar_tope_de_agente`

_alcance: escritura · idempotente_

Fija el tope de gasto del MES de UN agente, en USD: cuando su gasto del mes llega ahí, sus tareas nuevas frenan igual que con el tope de la organización, y los demás agentes siguen. No puede ser mayor que el tope mensual de la organización. Ponerle uno o bajarlo lo hace cualquiera que opere el agente; subirlo o sacarlo (`sin_tope: true`), un técnico o un admin. El gasto del mes cuenta como el de la organización (mes calendario UTC). La respuesta trae el gasto del mes, el tope, `porciento` y `bloqueado`. Lo mismo que `PUT /api/v1/agentes/{id}/tope`; queda en la auditoría a tu nombre.

| Argumento | Tipo | Qué es |
|---|---|---|
| `agente_id` **(requerido)** | string | El agente, de listar_agentes. |
| `tope_mes_usd` | number | El tope en USD por mes, mayor que cero y no mayor que el tope mensual de la organización. |
| `sin_tope` | boolean | true para sacarle el tope propio (manda sólo el de la organización). Incompatible con `tope_mes_usd`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `listar_pedidos`

_alcance: lectura · sólo lee · idempotente_

El registro de los pedidos que la organización le hizo a la API y al MCP en los últimos 30 días, del más nuevo al más viejo: cuándo, por dónde (api o mcp), el método y la ruta (o la herramienta), el status, cuánto tardó, con qué token, el ambiente y —si falló— el motivo que leyó el cliente. Cada respuesta de la API sale con `X-Request-Id`: con `request_id` se busca ese pedido. `solo_errores: true` trae los 4xx/5xx y los problemas del MCP. Nunca trae cuerpos ni argumentos: no se guardan.

| Argumento | Tipo | Qué es |
|---|---|---|
| `solo_errores` | boolean | true para ver sólo los que fallaron. |
| `request_id` | string | El `X-Request-Id` de una respuesta, para encontrar ese pedido. |
| `canal` | string | `api` o `mcp`. Sin esto, los dos. |
| `limite` | number | Cuántas traer. Por defecto 25, máximo 100. |
| `desde` | number | Desde qué posición seguir. La respuesta trae `siguiente_desde` cuando queda más. |
| `busca` | string | Filtra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo. |

### `fijar_cuota_por_ventana`

_alcance: escritura · idempotente_

Pone un techo de CANTIDAD de trabajo por ventana calendario: cuántas tareas o ejecuciones de un tipo entran por hora o por día, en el huso de la organización. No es dinero: para eso están `fijar_cuota_mensual` y `fijar_tope_diario`. Los tipos cuentan por separado a propósito (un cron descontrolado no come la cuota de las personas). Lo fija un técnico o un admin. Volver a llamar con el mismo tipo y ventana reemplaza el límite; `sacar: true` lo borra. Un techo que trae el plan se puede bajar, pero no subir por encima del plan ni sacar: eso lo hace un cambio de plan o YoRobot.

| Argumento | Tipo | Qué es |
|---|---|---|
| `tipo` **(requerido)** | string | Qué se cuenta: `tareas_humanas`, `tareas_automaticas`, `corridas`, `tareas_de_canal`, `tareas_de_api` o `inferencias`. |
| `ventana` **(requerido)** | string | `hora` o `dia`, calendario. |
| `limite` | integer | Cuántas entran en la ventana: entero mayor que cero. |
| `sacar` | boolean | true para borrar el techo de ese tipo y ventana. Incompatible con `limite`. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `consumo_por_esfuerzo`

_alcance: lectura · sólo lee · idempotente_

Por agente, las tareas cerradas del mes clasificadas por lo que costó ejecutarlas (liviana / media / pesada), los casos ponderados que resultan, la mediana y el p90, cuántas quedaron fuera de serie, y cuánto se llevó aparte la verificación. Más las diez tareas más caras con su link.
Es la base de la tarifa: el caso ponderado es la unidad que sirve para todas las actividades, y la verificación va separada porque es un dial del agente. Los umbrales están en la respuesta; no se cambian desde acá.

| Argumento | Tipo | Qué es |
|---|---|---|
| `mes` | string | Mes a mirar, `AAAA-MM`. Si falta, el mes en curso. |

### `mi_cartera`

_alcance: lectura · sólo lee · idempotente_

Para una organización partner: sus clientes, y por cada uno lo mismo que ve el cliente en su Inicio —agentes, discrepancias, tareas esperando aprobación, frenadas, gasto contra el tope—. Sólo números por cliente, ninguna fila de adentro.
Vacío si la organización no tiene cartera. Para instalar un paquete en varios clientes de una vez: instalar_en_clientes.

Sin argumentos.

### `instalar_en_clientes`

_alcance: escritura · idempotente_

Importa el mismo paquete —o componente de la biblioteca— en cada cliente indicado de la cartera, SÓLO a prueba (dev) en cada uno, con las mismas reglas que importar_agente. Devuelve el resultado por cliente; un cliente que falla no frena a los demás.
Cada instalación queda en la bitácora del cliente a nombre del partner. Producción se gana en cada cliente por separado: ensayar_agente y promover_en_cliente.

| Argumento | Tipo | Qué es |
|---|---|---|
| `clientes` **(requerido)** | lista | Los ids de organización de los clientes (de mi_cartera). |
| `paquete` | object | El paquete entero `yorobot/agente@1`. O en su lugar `componente`. |
| `componente` | string | En vez de `paquete`: la clave de un componente de la biblioteca (listar_componentes). |
| `nombre` | string | Opcional, con `componente`: el nombre que va a tener el agente en cada cliente. |
| `sin_faltantes` | boolean | true: instalar aunque a un cliente le falten herramientas, y reportarlas. |
| `nota` | string | Por qué se instala. Opcional; queda en la bitácora de cada cliente. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `promover_en_cliente`

_alcance: escritura · idempotente_

Lo mismo que promover_agente, pero adentro de un cliente de la cartera: sube la versión desplegada en `desde` («dev» o «staging») al ambiente siguiente. Exige que el ensayo del cliente esté en verde, igual que si lo hiciera el cliente. Queda en la bitácora del cliente a nombre del partner.

| Argumento | Tipo | Qué es |
|---|---|---|
| `cliente` **(requerido)** | string | El id de organización del cliente (de mi_cartera). |
| `agente_id` **(requerido)** | string | El agente, adentro del cliente. |
| `desde` **(requerido)** | string | «dev» o «staging». |
| `nota` | string | Opcional; queda en la auditoría. |
| `clave_de_pedido` | string | Tu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo. |

### `retencion`

_alcance: lectura · sólo lee · idempotente_

Los plazos vigentes en días —ejecuciones, conversaciones, padrón, memoria, cerebro, bitácora— y cuándo se cambiaron. `0` es «no se purga por plazo». Cambiarlos es una decisión de cumplimiento y se hace en Ajustes → Retención, no desde acá.

Sin argumentos.

### `actividad_por_dia`

_alcance: lectura · sólo lee · idempotente_

Lo mismo que las tiras de Consumo: los últimos `dias` (14 por defecto, hasta 90) día por día, en UTC como está guardado: corridas, costo de modelo y la verificación con su denominador (medidas, verificadas en limpio, discrepancias y la tasa sobre las medidas; sin medidas la tasa es null, no 0). Los días sin trabajo van en cero y dicen `sin_trabajo: true`.
Más el total del período y, con 14 días o más, `comparacion`: los últimos 7 días contra los 7 anteriores, que es la respuesta a «¿la semana vino mejor o peor?».

| Argumento | Tipo | Qué es |
|---|---|---|
| `dias` | number | Cuántos días, de 1 a 90. Por defecto 14, como la pantalla. |
