@johpaz/hive-sdk 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -17,9 +17,94 @@
   procedencia, hash y una prueba funcional del OOXML generado.
 - Añadidas las guías `docs/UPGRADING.md` y
   `docs/SECURITY-GUARDRAILS.md` para operación y auditoría.
+- **Requiere `@johpaz/hive-db` ^0.5.1** (antes ^0.4.0). Trae las lecturas del
+  log causal acotadas por agente (`agents` en `causalThread`, `toolStats` y
+  `buildAgentContext`), de las que depende el aislamiento entre inquilinos del
+  log causal descrito en *Corregido*.
+
+### WhatsApp por la API oficial de Meta
+
+- **Canal nuevo `whatsapp_cloud`**: WhatsApp Business por la Cloud API, que es
+  lo que puede usar una empresa. Incluye `WhatsAppCloudClient` (texto con
+  partido automático en 4096 caracteres, plantillas, audio, marcar leído con
+  "escribiendo…" y descarga de medios), las funciones de webhook
+  (`verifyWhatsAppSignature`, `verifyWhatsAppChallenge`, `parseWhatsAppWebhook`)
+  y el canal `WhatsAppCloudChannel`. Sin dependencias nuevas: sólo `fetch`.
+- El gateway enruta `GET|POST /webhooks/whatsapp-cloud/:accountId` cuando se le
+  pasa `channelManager`. Meta exige HTTPS público, así que hace falta un proxy
+  inverso o un túnel por delante.
+- La versión del Graph se resuelve en un solo lugar (`META_GRAPH_API_VERSION`,
+  por defecto **v26.0**). Cada versión caduca a los ~2 años y Meta redirige en
+  silencio a la más vieja que siga viva; tenerla centralizada es lo que evita
+  enterarse tarde.
+- Fuera de la ventana de 24 h el canal manda la plantilla de
+  `windowFallbackTemplate`, y si no hay ninguna configurada lanza un error que
+  lo dice (131047). La narración de progreso no se envía por defecto
+  (`sendProgress: false`): desde el 1/10/2026 Meta cobra cada mensaje de
+  servicio dentro de la ventana.
+- El parser recorre todas las `entry` y `changes` del webhook, y el canal
+  descarta los reintentos de Meta por id de mensaje.
+- **Baileys se carga recién al conectar el canal `whatsapp`.** Antes se
+  importaba al cargar el índice del SDK, así que cualquier consumidor —aunque
+  no usara canales— se traía Baileys entero y su parche de
+  `process.stderr.write` en cada proceso. Quien usa el canal por código QR no
+  ve ningún cambio.
+
+### Catálogo compartido entre inquilinos
+
+- **El catálogo se instala una sola vez.** `tools`, `skills` y `ethics` dejan de
+  copiarse en la partición de cada inquilino: su contenido vive en la colección
+  sin prefijo —la misma que ve una instalación local— y cada inquilino guarda
+  únicamente lo que activó, en `catalogActivations`. Un enjambre nuevo arranca
+  con **cero escrituras** de catálogo, y encender una tool guarda una fila de
+  elección en lugar de una copia de la fila entera.
+- **Providers y modelos ya no se resiembran dentro de un inquilino.** En un host
+  multi-inquilino el catálogo que vale es el del host, así que `seedAllData()`
+  saltea el estático cuando hay tenant activo. Antes borraba y recreaba los 139
+  modelos de `SEED_DATA` en la partición de cada enjambre, en cada arranque, para
+  que un instante después los pisara el host.
+- Lo que un inquilino **crea** sigue siendo suyo y privado: las tools de un
+  endpoint de API, o una skill o un código de ética propios, se escriben en su
+  partición como siempre. Editar el contenido de una fila del catálogo también
+  deja una copia privada, y borrarla la oculta sólo para él.
+- API nueva en `@johpaz/hive-sdk/storage`: `setCatalogActivation`,
+  `clearCatalogActivation`, `listCatalogActivations`, `sharedCatalogCol`,
+  `CATALOG_COLLECTIONS` y el tipo `DocStore`, que es lo que ahora devuelve
+  `col()` — la clase `Collection` de hive-db lo satisface tal cual, así que no
+  cambia nada para quien la recibe.
+- **Sin inquilino en scope no cambia nada**: una instalación local sigue viendo
+  una sola partición, con el catálogo y su `active` en la misma fila.
+- **El índice de capacidades también se comparte, y eso destapa dos fallas que
+  ya existían.** Todo documento declara ahora su ámbito —el inquilino que lo
+  escribió, o `_` si es del catálogo— y `searchCapabilities()` consulta los dos
+  cuando hay inquilino activo:
+  - Antes el catálogo se indexaba **sin** filtro de inquilino y la búsqueda
+    desde un enjambre filtraba **por** su inquilino, así que dentro de un
+    enjambre no se encontraba NADA del catálogo: ni una tool ni una skill. El
+    agente sólo descubría sus tools de MCP y las de sus endpoints.
+  - Y un reindexado del catálogo —el que corre en cada arranque del gateway—
+    borraba por `type` a secas, llevándose por delante lo que cada inquilino
+    tenía indexado. Ahora el borrado va acotado a su ámbito.
+  - Encima de la búsqueda manda la elección: una capacidad que el inquilino
+    apagó no se le ofrece, aunque esté en el catálogo y puntúe primero.
+  Cubierto por `packages/core/src/agent/capability-search.test.ts` y
+  `packages/core/src/storage/catalog.test.ts`.
 
 ### Corregido
 
+- **Con un tenant activo, el log causal se apagaba en lugar de acotarse.**
+  `causalThread`, `toolStats` y `buildAgentContext` recorrían todos los shards
+  de la base, así que con un tenant en scope `causalReadsEnabled()` las apagaba:
+  en un host multi-inquilino el reflector G9 y el contexto causal del
+  compilador no corrían nunca. Ahora las tres lecturas van siempre acotadas a
+  los agentes que corresponden —el agente del turno, o los del lote de trazas— y
+  el apagado desaparece. Además el shard de cada evento pasa a ser
+  `causalAgentKey(agentId)`: con tenant lleva el tenant delante (`t_…:agente`,
+  la misma forma que los ids del índice BM25), así que dos inquilinos con un
+  agente del mismo id ya no comparten shard. Una lista de agentes vacía se salta
+  la lectura en vez de pasarse al motor, que la trataría como "todos los
+  shards". Cubierto por `test/causal-tenant-scope.test.ts`.
+
 - **`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
@@ -194,6 +279,11 @@
 
 ### Cambiado
 
+- **El `toolStats` del reflector se acota a los agentes del lote**, también sin
+  tenant. Antes sumaba el historial de la tool de todos los agentes de la base;
+  ahora el de los agentes cuyas trazas se están analizando. Es la misma
+  semántica con y sin tenant, y no recorre el log entero.
+
 - **Los tests que manejan un navegador real son opt-in (`BROWSER_TESTS=1`).**
   Su guarda era `isWebViewSupported()`, que sólo comprueba que exista un binario
   de Chromium — no que arranque. En un runner de CI (contenedor, a menudo root)

package/README.md

@@ -271,4 +271,4 @@ npm view @johpaz/hive-sdk dist-tags   # verificar después del release
 
 ---
 
-*Hive SDK v0.4.6 — MIT*
+*Hive SDK v0.4.8 — MIT*

package/docs/API-TOOLS-SKILLS-CHANNELS.md

@@ -353,6 +353,7 @@ await manager.initialize();
 import {
   TelegramChannel,
   DiscordChannel,
+  WhatsAppCloudChannel,
   WhatsAppChannel,
   SlackChannel,
   WebChatChannel,
@@ -364,8 +365,20 @@ const telegram = new TelegramChannel({ botToken: process.env.TELEGRAM_BOT_TOKEN!
 // Discord
 const discord = new DiscordChannel({ botToken: process.env.DISCORD_BOT_TOKEN! });
 
-// WhatsApp
-const whatsapp = new WhatsAppChannel();
+// WhatsApp por la API oficial de Meta — el camino para un negocio
+const whatsapp = new WhatsAppCloudChannel({
+  enabled: true,
+  accountId: "ventas",
+  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
+  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+  appSecret: process.env.WHATSAPP_APP_SECRET!,
+  verifyToken: process.env.WHATSAPP_VERIFY_TOKEN!,
+  dmPolicy: "open",
+  allowFrom: [],
+});
+
+// WhatsApp por código QR (Baileys). No es oficial: uso personal.
+const whatsappQr = new WhatsAppChannel();
 
 // Slack
 const slack = new SlackChannel({ botToken: process.env.SLACK_BOT_TOKEN! });
@@ -374,6 +387,45 @@ const slack = new SlackChannel({ botToken: process.env.SLACK_BOT_TOKEN! });
 const webchat = new WebChatChannel();
 ```
 
+### WhatsApp: cuál de los dos
+
+| | `whatsapp_cloud` | `whatsapp` |
+|---|---|---|
+| Qué es | La API oficial de Meta (Cloud API) | Baileys, WhatsApp Web por código QR |
+| Para quién | Un negocio: número de WhatsApp Business propio, plantillas de marketing y atribución de los anuncios que abren la conversación | Uso personal |
+| Riesgo | Ninguno: es el camino soportado | Va contra los términos de WhatsApp; el número puede terminar bloqueado |
+| Cómo recibe | Webhook: hace falta una URL HTTPS pública | Conexión propia, sin URL pública |
+
+El canal oficial no abre ninguna conexión: Meta empuja los mensajes a una URL.
+El gateway la sirve en `/webhooks/whatsapp-cloud/<cuenta>` si se le pasa el
+manager, y esa es la que se registra en el panel de Meta junto con el
+`verifyToken`.
+
+```typescript
+const channelManager = new ChannelManager(await loadConfig());
+await channelManager.initialize();
+
+// Sin esto, el gateway no tiene a quién entregarle lo que manda Meta.
+await startGateway({ channelManager });
+```
+
+Tres cosas que conviene saber antes de ponerlo en producción:
+
+- **La ventana de 24 h.** Pasado ese tiempo desde el último mensaje del cliente,
+  Meta sólo acepta plantillas aprobadas (error 131047). Con
+  `windowFallbackTemplate` el canal manda esa plantilla; sin ella, lanza un
+  error que lo explica en vez de fallar en silencio.
+- **Cada mensaje se cobra.** Desde el 1 de octubre de 2026 los mensajes de
+  servicio dentro de la ventana también se pagan, así que la narración de
+  progreso del agente no se envía salvo que se encienda `sendProgress`. En su
+  lugar se renueva el "escribiendo…", que es gratis.
+- **4096 caracteres por mensaje.** El cliente parte las respuestas largas solo,
+  cortando entre párrafos.
+
+La versión del Graph sale de `META_GRAPH_API_VERSION` (por defecto la estable
+más reciente). Conviene fijarla a conciencia: cada versión caduca a los ~2 años
+y Meta redirige las llamadas a la más vieja que siga viva, sin avisar.
+
 ---
 
 ## Tool Runtime
@@ -444,8 +496,8 @@ unsubscribeCanvas(handler);
 
 ## Storage
 
-HiveDB (`@johpaz/hive-db`), un motor embebido con colecciones de documentos e
-índice BM25. Reemplazó a SQLite + FTS5 en 0.1.5.
+HiveDB (`@johpaz/hive-db` 0.5.1 o posterior), un motor embebido con colecciones
+de documentos e índice BM25. Reemplazó a SQLite + FTS5 en 0.1.5.
 
 ```typescript
 import { ensureHiveDb, col } from "@johpaz/hive-sdk";
@@ -483,6 +535,33 @@ const skills = await selectSkills("investigar en la web");
 Una tool declarada con `defineTool` y pasada a `createAgent` queda indexada
 automáticamente, así que el modelo puede descubrirla igual que a las nativas.
 
+### Catálogo compartido entre inquilinos
+
+En un host multi-inquilino (varios enjambres en una sola HiveDB, ver
+`runInTenant`) el catálogo —`tools`, `skills` y `ethics`— es contenido de la
+INSTALACIÓN, no de cada inquilino: su contenido se instala una sola vez en la
+colección sin prefijo, y cada inquilino guarda únicamente lo que activó.
+
+```typescript
+import { col, runInTenant, setCatalogActivation } from "@johpaz/hive-sdk";
+
+// Sin inquilino: esto instala el catálogo, una vez para todos.
+await ensureHiveDb();
+
+await runInTenant(tenantKey, async () => {
+  const tools = await col<ToolDoc>("tools");
+  await tools.scan({});                              // ve el catálogo entero
+
+  // Encender una tool para ESTE inquilino: guarda su elección, no una copia.
+  await setCatalogActivation("tools", "web_search", { active: true });
+});
+```
+
+Lo que el inquilino crea —la tool de un endpoint de API, una skill propia— se
+escribe en su partición y no lo ve nadie más. Editar el contenido de una fila del
+catálogo deja una copia privada; borrarla la oculta sólo para él. Sin inquilino
+en scope nada de esto se activa y `col()` se comporta como siempre.
+
 ---
 
 ## Config

package/docs/SECURITY-GUARDRAILS.md

@@ -14,13 +14,33 @@ de proceso.
 - SheetJS CE se instala desde la distribución oficial 0.20.3; el paquete npm
   abandonado en 0.18.5 no forma parte del grafo.
 - Baileys está fijado exactamente en `7.0.0-rc14` para evitar retroceder a una
-  release candidate vulnerable.
+  release candidate vulnerable. Además se **carga bajo demanda**: entra en el
+  proceso sólo si alguien conecta el canal `whatsapp` por código QR. Un
+  consumidor que no lo use —hive-cloud, por ejemplo, que usa el canal oficial—
+  no carga su grafo ni su parche de `process.stderr.write`.
 - PptxGenJS 4.0.1 se conserva como artefacto ESM vendorizado, con licencia,
   procedencia y SHA-256. No se instala su dependencia muerta `image-size`.
 
 Toda actualización del artefacto PPTX debe verificar su origen y hash, ejecutar
 la prueba OOXML y volver a ejecutar el audit.
 
+## Webhooks de WhatsApp (Cloud API)
+
+El canal `whatsapp_cloud` recibe por una URL pública, así que todo lo que llega
+es no confiable hasta comprobar dos cosas:
+
+- **La firma.** `verifySignature` recalcula el HMAC-SHA256 del cuerpo **crudo**
+  con el secreto de la app de Meta y lo compara con `X-Hub-Signature-256`
+  usando `timingSafeEqual`. Sin cabecera, sin secreto o con una firma que no
+  coincide, el webhook responde 401 y no se procesa nada. El cuerpo se lee como
+  texto antes de parsearlo: firmar el JSON reserializado daría distinto.
+- **El token de verificación.** El `hub.verify_token` del alta se compara
+  también con `timingSafeEqual`; si no coincide, 403.
+
+El canal además sólo atiende eventos de su propio `phone_number_id` —una misma
+cuenta de WhatsApp Business puede tener varios números apuntando a la misma
+URL— y descarta por id los reintentos de Meta.
+
 ## Archivos PDF
 
 Antes de leer un PDF, `office_leer_pdf` exige un archivo regular y limita el

package/docs/UPGRADING.md

@@ -54,6 +54,26 @@ Estos adaptadores están en la frontera con el runtime. No deben reemplazarse po
 `any`, `@ts-ignore` o `@ts-expect-error`: hacerlo convertiría una incompatibilidad
 real de plataforma en un falso resultado verde.
 
+## hive-db 0.5.1 y log causal por tenant
+
+Hive SDK requiere **`@johpaz/hive-db` 0.5.1 o posterior**. Llega como
+dependencia del SDK, así que una aplicación consumidora no la declara. Lo que
+sigue sólo importa con el log causal encendido (`HIVE_CAUSAL_LOG=true` o
+`causalLog.enabled`):
+
+- Con un tenant activo (`runInTenant`) el reflector y el contexto causal del
+  compilador vuelven a funcionar. Antes se apagaban; ahora leen acotado a los
+  agentes del turno o del lote de trazas.
+- La clave de shard de cada evento es `causalAgentKey(agentId)`: sin tenant, el
+  id del agente tal cual; con tenant, `t_…:agentId`. Los eventos que un host
+  haya escrito con tenant antes de esta versión quedaron con el id crudo y las
+  lecturas acotadas ya no los ven. Sin tenant no cambia nada.
+- El `toolStats` del reflector cuenta el historial de los agentes del lote, no
+  el de toda la base, con y sin tenant.
+- `watchCausalEvents` con tenant sigue exigiendo `agentId`: se le pasa el id
+  crudo y el SDK lo califica. Los eventos que entrega traen en `agentId` la
+  clave del shard; `formatCausalEvent` la muestra sin el tenant.
+
 ## Compatibilidad y CI
 
 Los workflows fijan Bun 1.4.2, instalan con `--frozen-lockfile`, ejecutan el

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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",

package/packages/cli/templates/hive-app/hive.config.ts

@@ -16,6 +16,13 @@ export default {
     webchat: { enabled: true },
     telegram: { enabled: false },
     discord: { enabled: false },
+    // WhatsApp por la API oficial de Meta. Es el camino para un negocio:
+    // número propio de WhatsApp Business, plantillas y atribución de los
+    // anuncios que abren la conversación. Recibe por webhook, así que hace
+    // falta exponer `/webhooks/whatsapp-cloud/<cuenta>` con HTTPS público.
+    whatsapp_cloud: { enabled: false },
+    // WhatsApp por código QR (Baileys). No es oficial: sirve para uso
+    // personal, no para un negocio, y el número puede terminar bloqueado.
     whatsapp: { enabled: false },
     slack: { enabled: false },
   },

package/packages/cli/templates/hive-app/src/main.ts

@@ -31,6 +31,9 @@ async function main() {
     host: config.gateway?.host,
     port: config.gateway?.port,
     agentId: coordinatorAgent.id,
+    // Los canales que reciben por webhook —WhatsApp por la API oficial de
+    // Meta— entran por el gateway, así que necesita el manager.
+    channelManager,
   });
 
   log.info(`{{APP_NAME}} is running at http://${gateway.hostname}:${gateway.port}`);

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

@@ -16,6 +16,7 @@
 import { logger } from "../utils/logger.ts"
 import { col, fromIndexable } from "../storage/hive.ts"
 import { getHiveDb } from "../storage/hivedb.ts"
+import { causalAgentKey } from "../storage/causal-events.ts"
 import type { HiveDB, EventInput } from "@johpaz/hive-db"
 import type { AgentDoc, TurnSource } from "../storage/collections.ts"
 import { callLLM, resolveProviderConfig, getDefaultLLM, type LLMMessage, type ProviderCredentials } from "./llm-client.ts"
@@ -170,7 +171,8 @@ async function appendCausalEvent(
 ): Promise<number | undefined> {
   try {
     return await db.append({
-      agentId: input.agentId,
+      // Shard calificado con el tenant: ver causalAgentKey en causal-events.ts.
+      agentId: causalAgentKey(input.agentId),
       streamId: input.streamId,
       kind: input.kind,
       payload: JSON.stringify(input.payload),

package/packages/core/src/agent/capability-search.ts

@@ -21,10 +21,27 @@
 import type { IndexDoc } from "@johpaz/hive-db";
 import { getHiveDb } from "../storage/hivedb.ts";
 import { currentTenant, qualifyDocId, unqualifyDocId, scopedFilterValue } from "../storage/tenant.ts";
+import { listCatalogActivations } from "../storage/catalog.ts";
 import { logger } from "../utils/logger.ts";
 
 const log = logger.child("capability-search");
 
+/**
+ * Ámbito de los documentos que no son de ningún inquilino: el catálogo.
+ *
+ * Es el mismo `"_"` que `scopedFilterValue()` usa cuando no hay tenant, y por
+ * eso sirve de las dos maneras: como valor del filtro `tenant` para poder
+ * BUSCAR el catálogo desde dentro de un inquilino, y como parte de
+ * `tenant__type` para que un reindexado del catálogo BORRE sólo lo suyo.
+ *
+ * Antes el catálogo se indexaba sin filtro `tenant` alguno, y eso rompía las dos
+ * cosas: desde un enjambre la búsqueda filtraba por su tenant y no encontraba
+ * NADA del catálogo —ni una tool, ni una skill—, y un reindexado desde fuera
+ * borraba por `type` a secas, llevándose por delante los documentos de todos los
+ * inquilinos (las tools de sus endpoints, sus tools de MCP).
+ */
+const CATALOGO = "_";
+
 export type CapabilityType = "tool" | "skill" | "playbook" | "mcp" | "agent";
 
 export interface CapabilityHit {
@@ -91,17 +108,22 @@ export async function searchCapabilities(
   // type; the single-type and all-types cases are one engine call.
   //
   // El índice semántico es UNO solo para todos los inquilinos (no hay
-  // "colección" que prefijar), así que el tenant entra como un filtro más que
-  // el motor AND-ea con el resto. Sin tenant no se añade nada: así un índice ya
-  // construido por la app de escritorio sigue respondiendo igual.
+  // "colección" que prefijar), así que el ámbito entra como un filtro más que el
+  // motor AND-ea con el resto.
+  //
+  // Con inquilino activo se consulta DOS veces: lo suyo —las tools de sus
+  // endpoints, sus tools de MCP— y el catálogo compartido, que se instala una
+  // sola vez y es de todos (ver storage/catalog.ts). Sin inquilino se consulta
+  // sin filtro de ámbito: una instalación local tiene una sola partición y así
+  // un índice ya construido sigue respondiendo igual.
   const tenant = currentTenant();
-  const tenantFilter = tenant ? [{ field: "tenant", value: tenant }] : [];
-  const queries = types
-    ? types.map((t) => ({
-        type: t,
-        filters: [...tenantFilter, { field: "type", value: t }],
-      }))
-    : [{ type: undefined, filters: tenantFilter.length ? tenantFilter : undefined }];
+  const ambitos = tenant ? [tenant, CATALOGO] : [null];
+  const queries = ambitos.flatMap((ambito) => {
+    const filtroAmbito = ambito ? [{ field: "tenant", value: ambito }] : [];
+    return types
+      ? types.map((t) => ({ filters: [...filtroAmbito, { field: "type", value: t }] }))
+      : [{ filters: filtroAmbito.length ? filtroAmbito : undefined }];
+  });
 
   const merged = new Map<string, CapabilityHit>();
   for (const q of queries) {
@@ -129,7 +151,10 @@ export async function searchCapabilities(
     }
   }
 
+  const apagados = tenant && merged.size > 0 ? await apagadosParaElInquilino() : null;
+
   const results = Array.from(merged.values())
+    .filter((hit) => !apagados?.has(hit.id))
     .sort((a, b) => b.score - a.score)
     .slice(0, k);
 
@@ -140,6 +165,27 @@ export async function searchCapabilities(
   return results;
 }
 
+/**
+ * Lo que este inquilino apagó del catálogo compartido.
+ *
+ * El índice del catálogo es uno solo, así que no puede llevar la elección de
+ * nadie: se filtra al leer. Sólo se descarta lo que el inquilino decidió
+ * explícitamente —apagar u ocultar—; lo que nunca tocó hereda lo que diga el
+ * catálogo, igual que en la colección (ver storage/catalog.ts).
+ *
+ * Ofrecerle al modelo una capacidad que su workspace apagó es hacerle perder un
+ * turno, además de contarle que existe algo que no puede usar.
+ */
+async function apagadosParaElInquilino(): Promise<Set<string>> {
+  const apagados = new Set<string>();
+  for (const [tipo, coleccion] of [["tool", "tools"], ["skill", "skills"]] as const) {
+    for (const eleccion of await listCatalogActivations(coleccion)) {
+      if (!eleccion.active || eleccion.hidden) apagados.add(`${tipo}:${eleccion.itemId}`);
+    }
+  }
+  return apagados;
+}
+
 /**
  * Keep only hits scoring at least `ratio` of the top hit. This replaces the
  * old absolute negative-bm25 thresholds: relevance is relative to the best
@@ -169,12 +215,12 @@ export async function replaceCapabilityDocs(
   // `deleteByFilter` acepta UN SOLO filtro, así que en una base compartida
   // borrar por `type` se llevaría por delante los documentos de todos los
   // inquilinos. El campo sintético `tenant__type` (ver scopedFilterValue)
-  // mantiene el borrado en un filtro y acotado a este tenant.
-  await db.deleteByFilter(
-    currentTenant()
-      ? { field: "tenant__type", value: scopedFilterValue(type) }
-      : { field: "type", value: type }
-  );
+  // mantiene el borrado en un filtro y acotado a un ámbito.
+  //
+  // Sin inquilino el ámbito es el catálogo (`_`), no "todo": reindexar el
+  // catálogo al arrancar borraba las tools de los endpoints y las de MCP de cada
+  // inquilino, que nadie volvía a escribir hasta que ese enjambre se reconectara.
+  await db.deleteByFilter({ field: "tenant__type", value: scopedFilterValue(type) });
   if (docs.length === 0) return;
   await db.upsertBatch(docs.map(toIndexDoc));
 }
@@ -198,7 +244,6 @@ export async function deleteCapabilitiesByServer(serverId: string): Promise<void
 
 function toIndexDoc(doc: CapabilityDoc): IndexDoc {
   const extra = doc.extraFilters ?? [];
-  const tenant = currentTenant();
   return {
     id: qualifyDocId(`${doc.type}:${doc.rawId}`),
     name: doc.name,
@@ -207,20 +252,16 @@ function toIndexDoc(doc: CapabilityDoc): IndexDoc {
     filters: [
       { field: "type", value: doc.type },
       ...extra,
-      // Con tenant activo, cada filtro lleva además un gemelo `tenant__<campo>`.
-      // Es lo que permite que los borrados masivos —que sólo aceptan un
-      // filtro— sigan acotados a este inquilino. Sin tenant no se emite nada,
-      // así que un índice ya construido conserva exactamente su forma.
-      ...(tenant
-        ? [
-            { field: "tenant", value: tenant },
-            { field: "tenant__type", value: scopedFilterValue(doc.type) },
-            ...extra.map((f) => ({
-              field: `tenant__${f.field}`,
-              value: scopedFilterValue(f.value),
-            })),
-          ]
-        : []),
+      // Todo documento declara su ámbito —el inquilino que lo escribió, o `_` si
+      // es del catálogo—, y cada filtro lleva además su gemelo
+      // `tenant__<campo>`. Con eso la búsqueda puede pedir un ámbito concreto y
+      // los borrados masivos —que aceptan un solo filtro— quedan acotados a él.
+      { field: "tenant", value: currentTenant() ?? CATALOGO },
+      { field: "tenant__type", value: scopedFilterValue(doc.type) },
+      ...extra.map((f) => ({
+        field: `tenant__${f.field}`,
+        value: scopedFilterValue(f.value),
+      })),
     ],
   };
 }

package/packages/core/src/agent/context-compiler.ts

@@ -38,7 +38,7 @@ import { getMCPManager as getSingletonMCPManager } from "../mcp/singleton.ts"
 import { syncMCPToolsToDB, syncMCPToolsToIndex } from "../mcp/tool-sync.ts"
 import { getUserDate, getUserTime } from "../utils/date.ts"
 import { getHiveDb } from "../storage/hivedb.ts"
-import { causalReadsEnabled } from "../storage/causal-events.ts"
+import { causalReadsEnabled, causalScope } from "../storage/causal-events.ts"
 import { listCatalogAgents, renderAgentRoutingCatalog } from "./catalog-selector.ts"
 import { expandToolAllowlist } from "./delegation-runtime.ts"
 import { MINIMAL_TOOLS } from "./minimal-loadout.ts"
@@ -588,7 +588,10 @@ export async function compileContext(opts: {
   // applies this turn (a real DB round-trip, not a per-turn cost) and
   // there's a causal stream to build it from. episodicSimilarity is omitted:
   // it requires embeddings hive doesn't generate anywhere yet.
-  if (summaryApplies && opts.causalStreamId && causalReadsEnabled()) {
+  // Acotado al shard de este agente: el stream es de una sola invocación suya,
+  // así que el hilo es el mismo y no se recorre el log de nadie más.
+  const causalAgents = causalScope([opts.agentId])
+  if (summaryApplies && opts.causalStreamId && causalAgents && causalReadsEnabled()) {
     try {
       const causalDb = await getHiveDb()
       const objectiveSource = taskContext || userMessage
@@ -605,6 +608,7 @@ export async function compileContext(opts: {
         currentObjective: currentObjective.slice(0, 2000),
         maxTokens: causalMaxTokens,
         strategy: { causalAnchors: true, compressCompletedPhases: true },
+        agents: causalAgents,
       })) as AgentContextShape
 
       const causalLines = [...(causalCtx.items ?? []), ...(causalCtx.anomalies ?? [])]

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

@@ -14,7 +14,8 @@
 import { logger } from "../utils/logger.ts"
 import { col, nextId } from "../storage/hive.ts"
 import { getHiveDb } from "../storage/hivedb.ts"
-import { causalReadsEnabled } from "../storage/causal-events.ts"
+import { causalReadsEnabled, causalScope } from "../storage/causal-events.ts"
+import { unqualifyDocId } from "../storage/tenant.ts"
 import type { HiveDB, ToolStats } from "@johpaz/hive-db"
 import type { TraceDoc, ReflectionDoc, CursorDoc } from "../storage/collections.ts"
 import { parseThreadId } from "./thread-id.ts"
@@ -183,10 +184,16 @@ async function analyzeCausalThreads(traces: TraceDoc[], causalDb: HiveDB | null)
 
   for (const streamId of streamIds) {
     try {
-      const thread = (await causalDb.causalThread(streamId)) as CausalThreadShape
+      // El stream es de una sola invocación, así que sus trazas nombran a los
+      // agentes que escribieron en él. Sin ninguno no hay con qué acotar, y una
+      // lectura sin acotar recorre los shards de todos los inquilinos.
+      const subset = traces.filter((t) => t.causal_stream_id === streamId)
+      const agents = causalScope(subset.map((t) => t.agent_id))
+      if (!agents) continue
+
+      const thread = (await causalDb.causalThread(streamId, agents)) as CausalThreadShape
       if (!thread.decisions?.length && !thread.toolCalls?.length) continue
 
-      const subset = traces.filter((t) => t.causal_stream_id === streamId)
       const originalIntent = subset[0]?.input_summary ?? ""
       const success = subset.every((t) => t.success)
 
@@ -204,13 +211,16 @@ async function analyzeCausalThreads(traces: TraceDoc[], causalDb: HiveDB | null)
       // underlying root cause mint a brand new playbook rule instead of
       // reinforcing one (confirmed via a local before/after canary run).
       if (evaluation.rootCause) {
+        // El log guarda la clave del shard (t_…:agente con tenant); a la regla de
+        // playbook y a affected_agents les llega el id que el host conoce.
+        const rootAgent = unqualifyDocId(evaluation.rootCause.agent)
         const decision = thread.decisions?.find((d) => d.seq === evaluation.rootCause!.seq)
         insights.push({
           type: "root_cause",
           description: decision
-            ? `Root cause: decision "${decision.description}" (agent ${evaluation.rootCause.agent}) preceded a tool failure.`
-            : `Root cause: a decision by agent ${evaluation.rootCause.agent} preceded a tool failure.`,
-          affectedAgents: [evaluation.rootCause.agent],
+            ? `Root cause: decision "${decision.description}" (agent ${rootAgent}) preceded a tool failure.`
+            : `Root cause: a decision by agent ${rootAgent} preceded a tool failure.`,
+          affectedAgents: [rootAgent],
           confidence: 0.6,
         })
       }
@@ -248,14 +258,17 @@ async function analyzeCausalThreads(traces: TraceDoc[], causalDb: HiveDB | null)
 async function analyzeTracesLocally(traces: TraceDoc[], causalDb: HiveDB | null): Promise<Insight[]> {
   const insights: Insight[] = []
 
-  // G9: whole-history stats per tool touched by this batch (undefined when
-  // disabled, or when the tool has no events in the log yet).
+  // G9: historial completo, por tool, de los agentes de este lote (undefined si
+  // el log está apagado o la tool todavía no tiene eventos). Acotado a esos
+  // agentes: con tenant, sin esto se sumarían llamadas de otros inquilinos; sin
+  // tenant, es el historial de estos agentes y no el de toda la base.
   const statsByTool = new Map<string, ToolStats>()
-  if (causalDb) {
+  const agents = causalDb ? causalScope(traces.map((t) => t.agent_id)) : null
+  if (causalDb && agents) {
     const distinctTools = new Set(traces.map((t) => t.tool_used).filter((t): t is string => !!t))
     for (const tool of distinctTools) {
       try {
-        const stats = await causalDb.toolStats(tool)
+        const stats = await causalDb.toolStats(tool, agents)
         if (stats) statsByTool.set(tool, stats)
       } catch (err) {
         log.warn(`[reflector] toolStats(${tool}) failed: ${(err as Error).message}`)

package/packages/core/src/channels/index.ts

@@ -3,5 +3,6 @@ export * from "./telegram.ts";
 export * from "./discord.ts";
 export * from "./webchat.ts";
 export * from "./whatsapp.ts";
+export * from "./whatsapp-cloud/index.ts";
 export * from "./slack.ts";
 export * from "./manager.ts";