@johpaz/hive-sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,8 +2,154 @@
 
 ## Sin publicar
 
+### Corregido
+
+- **`browser_scrape` extraía con una tool que no ve lo que el navegador
+  renderizó.** La skill existe para sitios dinámicos, y su paso de extracción
+  usaba `web_fetch`, que vuelve a pedir la URL al servidor y recibe el HTML sin
+  JavaScript ejecutado: en un SPA, una cáscara vacía. Pasa a usar
+  `browser_extract`, que lee el DOM ya renderizado, con un `browser_wait` previo.
+  (Uno de sus ejemplos citaba además `browser_fetch`, que no existe.)
+
+- **`browser_automate` no esperaba a los elementos.** Sus pasos iban de navegar a
+  hacer clic sin `browser_wait` en el medio, que es la falla más común de la
+  automatización web y falla en silencio. Se agregó el paso y el orden de
+  escalada: selector → `browser_script` → `computer_use_task`.
+
+- **La tabla de campos de `cron_manager` omitía la mitad de lo que acepta la
+  tool**: `max_runs`, `payload`, `agent_id` y `tool_name`. También documentaba
+  expresiones de 5 campos cuando el motor acepta 6, y no aclaraba que la zona
+  horaria sale del perfil del usuario y no se pasa en la llamada.
+
+- **Los contadores del scheduler perdían actualizaciones.** `run_count` y
+  `error_count` se calculaban desde una lectura hecha antes del bucle de
+  reintento de `updateJob`, así que al reintentar por conflicto de versión se
+  reescribía el valor viejo. Con dos corridas solapadas del mismo job —normal en
+  uno que tarda más que su intervalo y no declara `protect`, y garantizado en la
+  puesta al día por misfire, que llama a `execute()` en paralelo con el job ya
+  activado— ambas leían `error_count: 4` y ambas escribían 5. La consecuencia no
+  era el número: es que el umbral de auto-pausa (5 errores seguidos) no se
+  alcanzaba nunca y un job que fallaba siempre se quedaba reintentando para
+  siempre. `updateJob` ahora acepta un parche en forma de función, que se evalúa
+  contra la lectura fresca de cada intento. Es el mismo error que ya se corrigió
+  en `touchThread`. Cubierto por `packages/core/src/scheduler/scheduler.test.ts`.
+
+### Agregado
+
+- **El seed inicial de especialistas es una elección.** `ensureHiveDb()` y
+  `seedAllData()` aceptan `specialists: "all" | "none" | string[]`. Con `"none"`
+  la colmena arranca sin ningún especialista y con sólo las `MINIMAL_TOOLS`
+  activas —la competencia del coordinador—, y son los enjambres los que traen
+  consigo a los suyos. `"all"` sigue siendo el default, así que nada cambia para
+  quien no lo pida.
+
+  La elección alcanza también a las **capacidades**, no sólo a los agentes: una
+  fila de tool o skill que nace en un arranque `"none"` nace inactiva. Antes
+  `active` defaulteaba a `true` para toda fila nueva, así que un arranque sin
+  especialistas dejaba igual las 62 tools encendidas — el usuario terminaba
+  apagando a mano lo que nunca pidió.
+
+  **Nunca borra.** La elección gobierna qué se crea, no qué se conserva: una
+  base que ya tiene sus ocho agentes no pierde ninguno por arrancar con
+  `"none"`, y se siguen reconciliando en cada arranque.
+
+  `createSwarm` acepta ahora miembros del catálogo que todavía no tienen fila:
+  con el seed en `"none"` un enjambre es el **pedido de instalación**, no una
+  referencia a algo que ya debería existir. Un id que no es del catálogo y no
+  existe sigue siendo un error.
+
+- **Crear un enjambre ahora siembra sus especialistas.** El seed selectivo
+  (`applySeedPlan`) dejaba elegir qué personas del catálogo instalar, pero
+  `createSwarm` no lo miraba: guardaba el enjambre **sin una queja** con
+  miembros apagados y sus tools inactivas. La validación de "el agente existe"
+  pasaba igual, porque el seed crea las 8 filas siempre y sólo cambia `enabled`
+  — el enjambre quedaba definido y sin poder trabajar.
+
+  `createSwarm` y `updateSwarm` aceptan `activateMembers`, **`false` por
+  defecto**: crear un enjambre no debería cambiar en silencio qué capacidades
+  tiene la instalación entera, así que sin él el enjambre se crea igual y el
+  faltante vuelve en `pendingActivation` para que la UI lo muestre y el usuario
+  decida. Con `true` se activa la unión con lo que ya estaba, de modo que
+  encender los especialistas de un enjambre nunca apaga los de otro.
+
+  Se agregó `planActivationFor(agentIds)`, que devuelve el faltante **sin
+  encender nada** —para el "esto se va a activar" antes de confirmar— y
+  `enableCatalogAgents(ids)` en plural, porque activarlos de a uno reescribía el
+  catálogo entero una vez por agente. Cubierto por `test/swarm-seed.test.ts`.
+
+- **Skills para las capacidades que no tenían ninguna.** `image_editor`
+  (`image_metadata`, `image_transform`, `artifact_inspect`) y `artifact_reader`
+  (`artifact_read`, `artifact_inspect`). Las tools existían pero ninguna skill
+  las enseñaba, así que el modelo sólo podía dar con ellas de casualidad vía
+  `search_knowledge` — y en el caso de los artefactos eso deja inerte todo el
+  mecanismo de `artifact_ref`, que existe justamente para que los archivos
+  grandes no entren en la ventana de contexto.
+
+
+- **`sessionStart` y `sessionEnd` ya se disparan.** Eran registrables desde que
+  se implementaron los hooks, pero nada los invocaba. Van enganchados a las
+  cuatro transiciones del ciclo de vida del hilo (crear, reabrir, archivar,
+  borrar), todas en `agent/thread-store.ts`. `sessionStart` cuelga del `put` que
+  crea la fila y no de `createSession`, que es idempotente y se llama en cada
+  turno: enganchado ahí habría contado mensajes en vez de conversaciones.
+  `closeSession`/`reopenSession` pasan a delegar en los nuevos `archiveThread`
+  y `unarchiveThread` para que las cuatro transiciones vivan en un solo archivo.
+  Cubierto por `test/hooks.test.ts`.
+
+### Quitado
+
+- **Cero dependencias para el cron: fuera `croner` y `cron-parser`.** El motor
+  ahora es propio (`scheduler/cron/`) y usa sólo `setTimeout` e `Intl` del
+  runtime. `cron-parser` además ni siquiera se importaba: estaba declarada en
+  los dos `package.json` y se la bajaba todo el que instalara el SDK.
+
+  `Bun.cron()` **no** sirve como reemplazo —evaluado contra el runtime 1.4.0—:
+  acepta sólo 5 campos, rechaza una fecha ISO como patrón (que es como se
+  agendan los jobs `one_shot`), ignora la zona horaria en `parse()`, y su handle
+  no expone la próxima corrida, de donde sale `next_run_at` y con lo que se
+  detectan las corridas perdidas al arrancar. Tampoco tiene equivalente de
+  `protect`, `maxRuns`, `interval`, `startAt`/`stopAt` ni `domAndDow`, todos
+  campos persistidos de `CronJobDoc`.
+
+  El motor propio conserva la superficie entera, así que `CronScheduler` no
+  cambió de comportamiento, e implementa además los dos casos de horario de
+  verano que se rompen callados: la hora que **no existe** al adelantar el
+  reloj (se saltea ese día en vez de correr a una hora inventada) y la que
+  **ocurre dos veces** al atrasarlo (corre en la primera, una sola vez). El
+  motor se exporta suelto desde `./scheduler` —`Cron`, `parseCronExpression`,
+  `isValidCronExpression`, `nextOccurrence`— para validar o previsualizar sin
+  montar un scheduler. Documentado en `docs/API-CRON.md`. Cubierto por
+  `packages/core/src/scheduler/cron/cron-engine.test.ts` (28 tests).
+
+- **`CronerOptions` (tipo público).** Estaba declarado dos veces —en
+  `scheduler/types.ts` y en `swarm/types.ts`— y no tipaba nada en ninguna parte:
+  un tipo muerto con el nombre de una librería que ya no se usa. Su forma es la
+  de `CronOptions`, que ahora exporta el motor desde `./scheduler`.
+
+- **Menciones a Croner en lo que lee el modelo.** Las descripciones de
+  `cron.create` (`start_at`, `stop_at`, `dom_and_dow`) y la skill `cron_manager`
+  citaban opciones "de Croner". Eso entra en el prompt: nombrarle al modelo una
+  librería que el código ya no usa lo manda a buscar documentación que no
+  aplica. Quedan sólo las referencias históricas que explican por qué el motor
+  es propio.
+
 ### Seguridad
 
+- **El playbook ACE no distinguía de quién era lo aprendido.** `PlaybookDoc` y
+  `ReflectionDoc` no tenían `user_id`, así que la cadena entera —trazas →
+  reflexión → regla → inyección en el system prompt— era global: lo que el
+  agente aprendía interactuando con una persona se le aplicaba a todas las demás
+  del mismo proceso. Es el mismo supuesto de "un solo usuario" que ya se había
+  cerrado en `memory`. Ahora el reflector agrupa las trazas por usuario
+  (derivado del `thread_id`), el curador propaga el dueño a la regla y deduplica
+  dentro del usuario, y las tres puertas de lectura filtran a global + propio:
+  `selectPlaybookRules(texto, userId)`, `EthicsGuard.getRules(rol, userId)` y la
+  tool `search_knowledge`. Las reglas sembradas siguen siendo globales a
+  propósito (`user_id: ""`): son conocimiento del producto, no de nadie.
+  `ensureHiveDb()` migra las filas anteriores asignándolas al primer usuario de
+  la base — dejarlas sin dueño las volvería globales, que es justo lo que se
+  viene a cerrar. Cubierto por `test/playbook-isolation.test.ts`.
+
 - **La lista blanca de tools no se aplicaba al descubrimiento dinámico.**
   `compileContext` sólo recortaba `allTools` cuando el agente era de catálogo
   (`source === "catalog"`). Un agente creado por el usuario veía su loadout
@@ -51,6 +197,15 @@
   Ahora el test usa un id de proveedor propio (`test-tenant-isolation`) y limpia
   sus secretos, sin tocar el módulo ni la credencial de nadie.
 
+- **El caché de disponibilidad del keychain se envenenaba para todo el proceso.**
+  `_keychainOk` recuerda si `Bun.secrets` respondió, para no reintentar en cada
+  lectura en un servidor sin libsecret. El problema es que ese resultado valía
+  para siempre: una vez marcado como no disponible, sustituir `Bun.secrets` por
+  otro backend —o por un doble de test— no servía de nada, porque la lectura
+  cortaba antes de tocarlo. Ahora se detecta que el objeto cambió de identidad y
+  el sondeo se invalida solo. Era la causa de que el test de compatibilidad con
+  keychain fallara en CI headless (y sólo ahí).
+
 - **`resetKeychainProbe()`** en `storage/crypto.ts`. Si el keychain del SO no
   responde, el resultado se cachea a nivel de módulo para no reintentar en cada
   lectura — correcto en producción, pero significa que el primer sondeo vale
@@ -89,8 +244,82 @@
 
 - CI actualizado a **Bun 1.4.0**, alineado con `hive`.
 
+### Quitado
+
+- **`AgentRunner`** (`agent/providers/index.ts`). Era una capa de compatibilidad
+  con la firma de LangGraph anterior a que el runtime pasara a `agent-loop.ts`, y
+  **nunca llegó a instanciarse**: los cuatro puntos de entrada reales —el
+  gateway, `createAgent`, el worker y los ejecutores del harness— llaman
+  `runAgent()` directo. 158 líneas de código muerto. El subpath
+  `@johpaz/hive-sdk/agent/providers` sigue existiendo con sus tipos (`Provider`,
+  `ModelResponse`), que sí son parte del contrato público.
+
 ### Añadido
 
+- **Streaming por token en la API pública.** `chat(mensaje, { stream: true })`
+  emite eventos `token` con los deltas del proveedor a medida que llegan. El
+  mecanismo ya existía —los proveedores llamaban `onToken` por cada delta— pero
+  **ningún punto de entrada lo pasaba**, así que nunca llegaba a nadie: la
+  respuesta aparecía de golpe al terminar el turno.
+
+- **`@johpaz/hive-sdk/services/images`** — imágenes como servicio para el usuario
+  final, no para el agente: entra y sale por bytes, se persiste por id. Incluye
+  galería (`listImages`), presets y control de retención.
+
+- **`@johpaz/hive-sdk/services` — la superficie que maneja una interfaz.** El SDK
+  estaba construido para que lo condujera el modelo: casi todo el CRUD vivía
+  dentro de las tools (`cronCreateTool`, `memoryWriteTool`, `agentCreateTool`),
+  con argumentos con forma de LLM y respuestas escritas para un prompt. Montar
+  una UI encima obligaba a llamar `tool.execute({...})` y parsear prosa, o a
+  escribir consultas crudas contra HiveDB conociendo un esquema privado.
+
+  Ahora la implementación vive en `services/` y las tools la envuelven — una
+  implementación, dos consumidores. Diez dominios: `agents`, `swarms`, `skills`,
+  `tools`, `providers`, `models`, `mcp`, `cron`, `memory`, `ethics`. Es
+  deliberadamente agnóstico del framework (funciones, no rutas HTTP): una app
+  móvil o de escritorio que embeba el runtime no quiere un servidor.
+
+  Añade tres cosas que hive no hace: **valida que las referencias existan** al
+  asignar tools/skills/MCP a un agente (hive las guarda sin comprobar, y el
+  error aparece cuando el agente intenta usarlas); **`testMcpServer()`**, que
+  allí es "guardá y esperá a que el hot-reload conecte"; y el **rename de modelo
+  transaccional**, que re-apunta a cada agente en el mismo `batch()`.
+
+- **`SwarmDoc` — los enjambres se pueden guardar.** Hasta acá un enjambre existía
+  sólo mientras corría: `runRoleSwarm()` recibe los agentes en la llamada y no
+  persiste nada, así que quien armara uno desde una interfaz lo perdía al cerrar
+  la ventana. Era el bloqueador real para poner una UI encima del SDK, y explica
+  por qué hive-cloud creó sus propias tablas en Postgres.
+
+  La validación ocurre **al guardar, no al correr**: un enjambre jerárquico sin
+  orquestador, o con un agente que ya no existe, es un error de configuración —
+  descubrirlo semanas después, cuando alguien lo ejecuta, es descubrirlo tarde.
+
+- **El harness trae ejecutores listos** (`initHarnessExecutors()`). La cola
+  durable sabía encolar, reintentar y recuperar tras un crash, pero no ejecutar:
+  registrar los ejecutores quedaba en manos de quien usara el SDK, y eso son
+  ~420 líneas de cableado —epoch, proof packets, criterios de aceptación,
+  fan-in de delegaciones— antes de correr un solo enjambre durable. Ahora vienen
+  `worker_task` (worker delegado en contexto aislado, con verificación de sus
+  criterios) y `goal_run` (varios turnos contra un objetivo hasta verificarlo o
+  agotar el presupuesto).
+
+  `chat_turn` no está a propósito: qué es un canal y cómo se transmite un token
+  lo define la aplicación. Se registra desde fuera con `registerExecutor()`.
+  Registrar sigue siendo opt-in — `initHarnessExecutors()` no se llama sola.
+
+- **`getRegisteredExecutorTypes()`** — el registro era privado, así que no había
+  forma de comprobar si un tipo quedó cableado. Un job encolado sin ejecutor no
+  falla al encolarse sino al tomarse, lejos de donde está el error.
+
+- **Superficie pública completa**: 33 subpaths (antes 28). `events/` y
+  `resilience/` no tenían barril, `canvas/` no exportaba su emitter, `artifacts/`
+  no existía como módulo, y `./events` apuntaba a un solo archivo — el
+  **agent-bus**, que es la mensajería entre workers de un enjambre, era
+  inalcanzable desde fuera. También se exponen `./tool-runtime`, `./channels`,
+  `./voice`, y `initializeBrowserService`/`activateBrowserTools`, sin los cuales
+  las browser tools estaban en el catálogo pero nadie podía arrancarlas.
+
 - **`@johpaz/hive-sdk/sessions`** — la conversación de un usuario como una sola
   cosa. Hasta acá "sesión" estaba repartida entre `thread-store` (identidad),
   `conversation-store` (mensajes), `run-store` (ejecución) y un `Map` en memoria
@@ -124,6 +353,83 @@
 
 ### Corregido
 
+- **Las notificaciones no llegaban a ningún lado.** `notifyChannel` era un stub
+  que sólo hacía `console.log`, y está en el camino real: la tool `notify`, los
+  reportes de progreso, el aviso de que una tarea programada terminó, el de un
+  turno interrumpido por un crash. Un agente sobre el SDK **no podía hablarle al
+  usuario por ningún canal**, mientras `channels/manager.ts` tenía adaptadores
+  funcionales de Slack, Discord, Telegram y WhatsApp sin nada que los conectara.
+  Ahora la app registra el suyo con `setChannelManager()`; sin registro se
+  conserva el comportamiento anterior, pero avisando.
+
+- **Las imágenes se reenviaban al modelo en cada turno.** `content_multimodal`
+  guardaba el base64 completo y `toAPIMessages` lo restauraba una y otra vez:
+  cinco fotos en una conversación eran cinco fotos viajando en cada turno
+  siguiente. Ahora se guardan como artefacto y en el historial queda una
+  referencia; las de los últimos mensajes se vuelven a poner en línea, porque un
+  modelo de visión no ve una foto desde un id. Mismo criterio que
+  `clearOldToolResults`.
+
+- **`token_count` no contaba las imágenes**, así que la compactación creía que un
+  hilo lleno de fotos ocupaba lo que ocupa su texto y no se disparaba hasta que
+  el proveedor rechazaba el turno. Ahora se estiman por área, como cobran los
+  proveedores.
+
+- **`agent.context.compactionThreshold` no lo leía nadie.** Estaba en el esquema
+  de configuración y ajustarlo no hacía nada. Una opción que no hace nada es
+  peor que no tenerla, porque el usuario cree que cambió algo.
+
+- **`search_knowledge` filtraba en el lugar equivocado.** Mostraba tools fuera de
+  la lista blanca del agente. La ejecución sí estaba protegida, pero además de
+  contarle qué existe fuera de su alcance, ofrecerle algo que no puede ejecutar
+  es hacerle perder un turno.
+
+- **El seed selectivo no habría sobrevivido a un reinicio.** `reseedToolsAndSkills()`
+  escribía `active: true` para todas las tools y skills en cada arranque, así que
+  la elección del usuario sobre qué capacidades quiere en su colmena duraba hasta
+  el próximo reinicio: apagaba lo que no usaba y volvía todo. Ahora el reseed
+  preserva `active` —la descripción y la categoría siguen viniendo del código,
+  que es su fuente de verdad—, igual que ya hacía con los modelos.
+
+- **La memoria era global al proceso.** El id de `MemoryDoc` era sólo el título y
+  no había `user_id`: dos usuarios no podían tener una memoria con el mismo
+  nombre —la segunda pisaba la primera— y cualquiera veía la del otro. Coherente
+  con hive, que es mono-usuario; inservible para un runtime donde cada quien arma
+  su colmena. El id pasa a ser `${userId}:${title}` y toda lectura filtra por
+  dueño. Las filas anteriores se migran al arrancar.
+
+- **Los ids no manejaban acentos.** "Efímero" quedaba como `ef_mero` y "Diseño"
+  como `dise_o`, porque la í y la ñ no son `[a-z0-9]`. Para un producto en
+  español eso no es cosmético. `slugify()` normaliza los diacríticos antes de
+  filtrar, y se aplica también a skills y servidores MCP.
+
+- **Documentación que describía un backend retirado.** `API-TOOLS-SKILLS-CHANNELS.md`
+  seguía explicando cómo `agent-browser` se instalaba solo en `~/.hive/` al
+  primer uso — un backend que ya no existe. Reescrita para `Bun.WebView`, con la
+  nota de por qué se retiró. También se corrigieron los conteos (58→60 tools,
+  106→110 modelos) y los pies de página congelados en `v0.0.17`.
+
+
+- **Un job que moría por expiración de lease no disparaba su terminal hook.** La
+  ruta normal de fallo sí lo hacía; la de recuperación tras un crash, no. El
+  aviso al usuario y el fan-in de delegaciones se perdían en silencio justo
+  cuando más importaban.
+
+- **Los artefactos de imagen no llegaban al consumidor.** El agent loop ya los
+  emitía (`chunk.artifacts.images`, vía mcp-result-normalizer), pero el wrapper
+  `AgentRunner` no los propagaba, así que una imagen producida por una tool MCP
+  se perdía antes de salir del SDK.
+
+- **NVIDIA no emitía razonamiento.** NIM lo mantiene apagado por defecto y el
+  interruptor no es `reasoning_effort` sino `chat_template_kwargs`, con una
+  clave distinta por familia de modelo. Se añade el reintento sin esos extras
+  cuando el proveedor responde 400/422: perder el razonamiento es mejor que
+  perder el turno.
+
+- **Un turno con más de una tool call podía morir por un hueco de empaquetado.**
+  `resolveWorkerEntry()` lanzaba si no encontraba el worker; ahora devuelve null
+  y degrada a hilo principal.
+
 - **`touchThread` perdía mensajes en el contador.** El incremento se calculaba
   fuera del reintento de `updateDoc`, así que ante un conflicto de versión el
   reintento volvía a escribir el valor viejo. Como `addMessage` la llama sin

package/README.md

@@ -17,17 +17,25 @@ bun add @johpaz/hive-sdk
 **Hive SDK es un Agent Harness**: un marco de trabajo completo para construir, desplegar y escalar aplicaciones de agentes de IA. A diferencia de un simple wrapper de LLM, un *harness* provee todo lo necesario para que un agente opere en producción:
 
 - **Agentes**: ciclo ReAct nativo con checkpoint durable, 16 providers LLM y descubrimiento de tools/skills por búsqueda BM25.
-- **Catálogo**: 18 providers y 106 modelos sembrados, cada uno con su precio por millón de tokens — una sola fuente de verdad para el costo.
-- **Tools**: 58 tools incluidas — filesystem, web search, browser automation (`agent-browser`), APIs (`api_request`), a2ui, office, cron, delegación.
+- **Catálogo**: 18 providers y 110 modelos sembrados, cada uno con su precio por millón de tokens — una sola fuente de verdad para el costo.
+- **Tools**: 60 tools incluidas — filesystem, web search, browser automation (`Bun.WebView`), APIs (`api_request`), a2ui, office, cron, delegación.
 - **Skills**: 23 workflows bundled, más los tuyos con `defineSkill` y `SkillLoader`.
 - **Canales**: Telegram, Discord, WhatsApp, Slack y WebChat con `ChannelManager`.
 - **Swarm**: orquestación multi-agente con `DAGScheduler`, `TaskGraph` y `WorkerPool`.
 - **Runtime**: ejecución paralela de tools vía Bun Workers.
 - **Gateway**: servidor HTTP/WebSocket para exponer agentes como API.
 - **Memoria y estado**: HiveDB (colecciones + índice BM25), scratchpad, context compiler con compactación.
+- **Servicios**: CRUD tipado de agentes, enjambres, skills, modelos, MCP y cron para montarle **la interfaz que quieras** — móvil, web o escritorio. Ver [API-SERVICES.md](./docs/API-SERVICES.md).
+- **Sesiones**: un hilo por canal y por contacto, con historial, resumen y reanudación tras un corte.
+- **Imágenes**: redimensionar y convertir con `Bun.Image`, sin dependencias nativas. Las imágenes entrantes se normalizan antes de llegar al modelo — una foto de cámara pasa de 217 KB a 4 KB.
+- **Harness**: cola durable con leases y recuperación tras crash, y ejecutores listos (`initHarnessExecutors`).
 
 Con Hive SDK no montas un agente desde cero: **enganchas tu lógica de negocio en un harness ya armado**.
 
+Y si además querés ponerle interfaz, no tenés que hablarle a la base de datos ni
+imitar el formato que espera el modelo: `@johpaz/hive-sdk/services` expone el
+mismo CRUD que usan las tools, en funciones tipadas.
+
 ## Instalación
 
 > **Requiere Bun.** El paquete se publica como TypeScript y usa APIs de Bun
@@ -222,4 +230,4 @@ npm view @johpaz/hive-sdk dist-tags   # verificar después del release
 
 ---
 
-*Hive SDK v0.2.0 — MIT*
+*Hive SDK v0.3.0 — MIT*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Hive SDK — The Agent Harness SDK. Build, deploy, and scale AI agent applications with multi-channel support, context engineering, and swarm orchestration.",
   "license": "MIT",
@@ -35,6 +35,9 @@
     "./tools": "./packages/core/src/tools/index.ts",
     "./skills": "./packages/core/src/skills/index.ts",
     "./storage": "./packages/core/src/storage/index.ts",
+    "./services": "./packages/core/src/services/index.ts",
+    "./hooks": "./packages/core/src/hooks/index.ts",
+    "./images": "./packages/core/src/images/index.ts",
     "./sessions": "./packages/core/src/sessions/index.ts",
     "./models": "./packages/core/src/models/index.ts",
     "./swarm": "./packages/core/src/swarm/index.ts",
@@ -42,7 +45,12 @@
     "./swarm/presets": "./packages/core/src/swarm/presets/index.ts",
     "./scheduler": "./packages/core/src/scheduler/index.ts",
     "./workers": "./packages/core/src/workers/index.ts",
-    "./events": "./packages/core/src/events/event-bus.ts",
+    "./events": "./packages/core/src/events/index.ts",
+    "./resilience": "./packages/core/src/resilience/index.ts",
+    "./tool-runtime": "./packages/core/src/tool-runtime/index.ts",
+    "./channels": "./packages/core/src/channels/index.ts",
+    "./voice": "./packages/core/src/voice/index.ts",
+    "./artifacts": "./packages/core/src/artifacts/index.ts",
     "./ethics": "./packages/core/src/ethics/index.ts",
     "./canvas": "./packages/core/src/canvas/index.ts",
     "./config": "./packages/core/src/config/index.ts",
@@ -97,8 +105,6 @@
     "@slack/bolt": "^4.7.2",
     "@whiskeysockets/baileys": "7.0.0-rc11",
     "async-mutex": "^0.5.0",
-    "cron-parser": "^5.5.0",
-    "croner": "^10.0.1",
     "discord.js": "^14.26.4",
     "docx": "^9.6.1",
     "grammy": "^1.42.0",

package/packages/core/src/agent/agent-catalog.ts

@@ -3,7 +3,7 @@ import type {
   AgentAcceptanceCriterion,
   AgentModelOverride,
   AgentWorkspaceScope,
-} from "../storage/collections.ts";
+} from "../storage/collections";
 import { col, toIndexable, fromIndexable } from "../storage/hive.ts";
 import { expandToolAllowlist } from "./delegation-runtime.ts";
 
@@ -37,7 +37,7 @@ ${s.workflow.map((step, index) => `${index + 1}. ${step}`).join("\n")}
 
 # QUÉ NO HACES
 ${s.prohibitions.map((rule) => `- ${rule}`).join("\n")}
-- No hablás con el usuario, no pedís confirmaciones directas y no delegás a otros agentes.
+- No hablas con el usuario, no pedís confirmaciones directas y no delegas a otros agentes.
 - No ampliás el alcance ni usás tools fuera del loadout autorizado.
 - No declarás éxito sin evidencia comprobable para cada criterio.
 
@@ -72,10 +72,10 @@ const CATALOG_PERSONAS: CatalogPersona[] = [
     role: "Tu dominio es investigación web, contraste de fuentes y síntesis basada en evidencia.",
     receives: "Una pregunta acotada, contexto relevante, restricciones de actualidad y criterios de aceptación.",
     workflow: [
-      "Convertí la pregunta en consultas concretas y buscá fuentes primarias o autorizadas.",
-      "Leé las fuentes relevantes y separá hechos, inferencias y datos no confirmados.",
+      "Convertí la pregunta en consultas concretas y busca fuentes primarias o autorizadas.",
+      "Lee las fuentes relevantes y separa hechos, inferencias y datos no confirmados.",
       "Contrastá afirmaciones sensibles o discutidas con más de una fuente.",
-      "Entregá una síntesis concisa con referencias y fechas cuando sean relevantes.",
+      "Entrega una síntesis concisa con referencias y fechas cuando sean relevantes.",
     ],
     prohibitions: [...COMMON_PROHIBITIONS, "No automatizás formularios ni realizás acciones en sitios."],
     quality: "Cada afirmación material debe poder rastrearse a una fuente accesible; los desacuerdos se presentan explícitamente.",
@@ -92,10 +92,10 @@ const CATALOG_PERSONAS: CatalogPersona[] = [
     role: "Tu dominio es navegación y automatización web renderizada.",
     receives: "Una acción web autorizada, URL inicial, datos permitidos, estado final esperado y límites de seguridad.",
     workflow: [
-      "Abrí el sitio y verificá que corresponda al objetivo.",
-      "Inspeccioná el estado antes de interactuar y usá selectores estables.",
-      "Ejecutá solamente los clicks, escritura y esperas necesarios.",
-      "Verificá el estado final mediante extracción y captura de pantalla.",
+      "Abre el sitio y verifica que corresponda al objetivo.",
+      "Inspeccioná el estado antes de interactuar y usa selectores estables.",
+      "Ejecuta solamente los clicks, escritura y esperas necesarios.",
+      "Verifica el estado final mediante extracción y captura de pantalla.",
     ],
     prohibitions: [...COMMON_PROHIBITIONS, "No confirmás compras, envíos, borrados o publicaciones si el principal no autorizó explícitamente ese efecto."],
     quality: "La entrega incluye URL final, estado observado y evidencia visual o estructurada posterior a la acción.",
@@ -112,10 +112,10 @@ const CATALOG_PERSONAS: CatalogPersona[] = [
     role: "Tu dominio es operaciones seguras sobre archivos y carpetas del workspace.",
     receives: "Paths relativos o autorizados, contenido solicitado, operación exacta y estado final esperado.",
     workflow: [
-      "Resolvé todos los paths contra el workspace y comprobá su estado inicial.",
+      "Resuelve todos los paths contra el workspace y comprueba su estado inicial.",
       "Aplicá la mínima operación necesaria sin tocar paths ajenos.",
       "Volvé a leer o listar el resultado para comprobarlo.",
-      "Reportá paths exactos, cambios y evidencia de readback.",
+      "Reporta paths exactos, cambios y evidencia de readback.",
     ],
     prohibitions: [...COMMON_PROHIBITIONS, "No ejecutás comandos shell ni modificás repositorios fuera de la operación de archivos pedida."],
     quality: "Todos los paths permanecen dentro del workspace y su contenido o ausencia final se comprueba después de la operación.",
@@ -134,10 +134,10 @@ const CATALOG_PERSONAS: CatalogPersona[] = [
     workflow: [
       "Inspeccioná el repositorio, convenciones y estado antes de editar.",
       "Determiná la causa o el diseño mínimo y modificá solo archivos pertinentes.",
-      "Ejecutá checks, tests o builds proporcionales al riesgo.",
-      "Entregá archivos cambiados, evidencia de validación y riesgos restantes.",
+      "Ejecuta checks, tests o builds proporcionales al riesgo.",
+      "Entrega archivos cambiados, evidencia de validación y riesgos restantes.",
     ],
-    prohibitions: [...COMMON_PROHIBITIONS, "No sobrescribís cambios ajenos, no publicás y no delegás a subagentes CLI."],
+    prohibitions: [...COMMON_PROHIBITIONS, "No sobrescribís cambios ajenos, no publicás y no delegas a subagentes CLI."],
     quality: "El cambio satisface el comportamiento pedido, preserva compatibilidad y pasa las validaciones relevantes.",
     routingExamples: ["implementar una función", "arreglar un bug", "ejecutar tests de un proyecto"],
     tools: ["fs_*", "cli_exec"],
@@ -153,10 +153,10 @@ const CATALOG_PERSONAS: CatalogPersona[] = [
     role: "Tu dominio es lectura y generación de archivos Office estructurados.",
     receives: "Archivo de entrada o especificación del documento, formato final, contenido y path autorizado.",
     workflow: [
-      "Inspeccioná entradas y confirmá el formato solicitado.",
+      "Inspeccioná entradas y confirma el formato solicitado.",
       "Generá o extraé contenido preservando estructura y datos.",
-      "Comprobá que el archivo existe, no está vacío y puede reabrirse.",
-      "Entregá el path final, resumen de contenido y prueba de reapertura.",
+      "Comprueba que el archivo existe, no está vacío y puede reabrirse.",
+      "Entrega el path final, resumen de contenido y prueba de reapertura.",
     ],
     prohibitions: [...COMMON_PROHIBITIONS, "No editás formatos binarios con tools genéricas de filesystem."],
     quality: "El artefacto debe abrir sin error con la tool lectora correspondiente y contener la estructura solicitada.",
@@ -174,9 +174,9 @@ const CATALOG_PERSONAS: CatalogPersona[] = [
     receives: "Sesión, surfaceId, flujo solicitado, datos, acciones permitidas y criterios visuales.",
     workflow: [
       "Diseñá una jerarquía pequeña con IDs únicos y un root explícito.",
-      "Creá la superficie antes de enviar componentes.",
+      "Crea la superficie antes de enviar componentes.",
       "Enviá componentes válidos y después el data model enlazado.",
-      "Comprobá acknowledgements, IDs y paths; liberá la superficie al cancelar.",
+      "Comprueba acknowledgements, IDs y paths; liberá la superficie al cancelar.",
     ],
     prohibitions: [...COMMON_PROHIBITIONS, "No interpretás acciones del usuario ni conversás; los eventos vuelven al principal."],
     quality: "La superficie usa el catálogo v0.9, no tiene referencias rotas y sus bindings apuntan a paths válidos.",
@@ -194,9 +194,9 @@ const CATALOG_PERSONAS: CatalogPersona[] = [
     receives: "Una automatización que Hive debe ejecutar después, su horario o recurrencia, timezone, canal y comportamiento esperado.",
     workflow: [
       "Normalizá fecha, recurrencia y timezone sin cambiar la intención.",
-      "Creá o modificá únicamente el job solicitado.",
+      "Crea o modificá únicamente el job solicitado.",
       "Consultá el job persistido y su próxima ejecución.",
-      "Entregá ID, estado, timezone y next_run_at.",
+      "Entrega ID, estado, timezone y next_run_at.",
     ],
     prohibitions: [
       ...COMMON_PROHIBITIONS,
@@ -223,9 +223,9 @@ const CATALOG_PERSONAS: CatalogPersona[] = [
     receives: "Endpoint autorizado, método, headers permitidos, payload, status esperado y esquema relevante.",
     workflow: [
       "Validá método, host, payload y alcance antes del request.",
-      "Ejecutá una sola operación idempotente o explícitamente autorizada.",
-      "Comprobá status, headers y forma de la respuesta.",
-      "Entregá evidencia saneada sin secretos.",
+      "Ejecuta una sola operación idempotente o explícitamente autorizada.",
+      "Comprueba status, headers y forma de la respuesta.",
+      "Entrega evidencia saneada sin secretos.",
     ],
     prohibitions: [...COMMON_PROHIBITIONS, "No repetís mutaciones automáticamente ni cambiás método, host o payload para forzar éxito."],
     quality: "El status y contrato observados coinciden con los criterios y la evidencia no contiene credenciales.",
@@ -284,6 +284,63 @@ export function createSeedCatalogAgents(now = Date.now()): AgentDoc[] {
 
 export const CATALOG_AGENT_IDS = CATALOG_PERSONAS.map((s) => s.id);
 
+/**
+ * Qué tools y skills necesita un subconjunto de agentes de catálogo.
+ *
+ * Devuelve la **unión**, no la lista de cada uno, y ahí está todo el asunto: las
+ * tools se comparten. `web_fetch` lo declaran `web_researcher` y
+ * `browser_operator`; `fs_*` lo declaran `workspace_file_operator` y
+ * `software_engineer`. Sembrar "sólo lo de este agente" dejaría a los demás sin
+ * capacidades que sí necesitan, y el fallo aparecería recién cuando el modelo
+ * descubra por BM25 una tool que no puede ejecutar.
+ *
+ * Los patrones se devuelven **sin expandir** a propósito: `expandToolAllowlist`
+ * necesita el registro vivo de tools, que este módulo no debe conocer. Quien
+ * siembre expande.
+ *
+ * `MINIMAL_TOOLS` no se incluye acá: son del coordinador, existan o no estos
+ * agentes, y quien siembra las añade siempre.
+ */
+export function requiredCapabilitiesFor(agentIds: string[]): {
+  toolPatterns: string[];
+  skills: string[];
+} {
+  const conocidos = new Set(CATALOG_AGENT_IDS);
+  const desconocidos = agentIds.filter((id) => !conocidos.has(id));
+  if (desconocidos.length > 0) {
+    throw new Error(`No existen en el catálogo: ${desconocidos.join(", ")}`);
+  }
+
+  const pedidos = new Set(agentIds);
+  const toolPatterns = new Set<string>();
+  const skills = new Set<string>();
+
+  for (const persona of CATALOG_PERSONAS) {
+    if (!pedidos.has(persona.id)) continue;
+    for (const t of persona.tools) toolPatterns.add(t);
+    for (const s of persona.skills) skills.add(s);
+  }
+
+  return { toolPatterns: [...toolPatterns], skills: [...skills] };
+}
+
+/** Las personas del catálogo, para que una UI pueda ofrecerlas al configurar. */
+export function listCatalogPersonas(): Array<{
+  id: string;
+  name: string;
+  description: string;
+  tools: string[];
+  skills: string[];
+}> {
+  return CATALOG_PERSONAS.map((p) => ({
+    id: p.id,
+    name: p.name,
+    description: p.description,
+    tools: p.tools,
+    skills: p.skills,
+  }));
+}
+
 /**
  * Writes the coordinator's provider/model onto every other agent row, so the
  * whole hive is explicitly configured instead of relying on the runtime

package/packages/core/src/agent/compaction.ts

@@ -29,6 +29,8 @@ import { estimateTokens } from "../utils/toon.ts"
 import { callLLM, resolveProviderConfig, getDefaultLLM, type ContentPart } from "./llm-client.ts"
 import { col, fromIndexable } from "../storage/hive.ts"
 import type { AgentDoc, ModelDoc } from "../storage/collections.ts"
+import { loadConfig } from "../config/loader.ts"
+import { runBeforeCompaction } from "../hooks/index.ts"
 
 const log = logger.child("compaction")
 
@@ -51,8 +53,15 @@ export async function maybeCompact(
   try {
     const totalTokens = await getTotalTokens(threadId)
 
-    // Use model's context window if available, otherwise use default
+    // Orden de precedencia: lo que el usuario configuró gana sobre lo que se
+    // deduce del modelo, y eso gana sobre la constante.
+    //
+    // `agent.context.compactionThreshold` estaba en el esquema de configuración
+    // y **no lo leía nadie**: alguien podía ajustarlo y no pasaba nada. Una
+    // opción que no hace nada es peor que no tenerla, porque el usuario cree
+    // que cambió algo.
     let effectiveThreshold = COMPACT_TOKEN_THRESHOLD
+    const configurado = loadConfig().agent?.context?.compactionThreshold
     try {
       const agentsCol = await col<AgentDoc>("agents")
       const coordinators = await agentsCol.findBy("role", "coordinator", { limit: 1 })
@@ -69,8 +78,18 @@ export async function maybeCompact(
       }
     } catch { /* use default threshold */ }
 
+    if (configurado && configurado > 0) effectiveThreshold = configurado
+
     if (totalTokens < effectiveThreshold) return
 
+    // Avisar antes de comprimir: es la última oportunidad de que alguien
+    // conserve algo del historial que está por resumirse.
+    await runBeforeCompaction({
+      threadId,
+      messageCount: await getMessageCount(threadId),
+      totalTokens,
+    }).catch(() => {})
+
     const summary = await getSummary(threadId)
     const totalMessages = await getMessageCount(threadId)