@johpaz/hive-sdk 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -17,9 +17,26 @@
   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*.
 
 ### 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 +211,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.7 — MIT*

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

@@ -444,8 +444,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";

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.7",
   "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/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/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/storage/causal-events.ts

@@ -3,32 +3,63 @@
  *
  * Read-side, separate from agent-loop.ts's write-side appendCausalEvent()
  * (module-private there, write-only). This is the read/watch counterpart,
- * co-located with the DB singleton accessor.
+ * co-located with the DB singleton accessor. It also owns the shard key both
+ * sides use (causalAgentKey) and the agent scope of every aggregated read
+ * (causalScope).
  */
 
 import { getHiveDb } from "./hivedb.ts"
-import { currentTenant } from "./tenant.ts"
+import { currentTenant, qualifyDocId, unqualifyDocId } from "./tenant.ts"
 import { loadConfig } from "../config/loader.ts"
 import type { Event, EventPattern } from "@johpaz/hive-db"
 
 export type { Event as CausalEvent, EventPattern as CausalEventPattern }
 
 /**
- * ¿Se pueden hacer lecturas AGREGADAS del log causal en este contexto?
+ * Clave de shard de un agente en el log causal.
  *
- * `causalThread`, `buildAgentContext` y `toolStats` recorren todos los shards
- * de la base y mezclan sus resultados (`log.rs` — `read_stream_all_agents` y
- * `project::<P>()` para proyecciones con scope Agent). Sobre una base
- * compartida eso devolvería hilos y estadísticas de otros inquilinos. Mientras
- * el motor no exponga las variantes acotadas por agente, con un tenant activo
- * estas lecturas se apagan: perder una señal de reflexión es aceptable, cruzar
- * datos entre agencias no.
+ * El log no tiene colecciones que prefijar: cada evento va al shard de su
+ * `agentId`, y ahí está todo el aislamiento. Con un tenant activo la clave
+ * lleva el tenant delante (`t_…:agentId`, la misma forma que usa el índice
+ * BM25 vía `qualifyDocId`), así que dos inquilinos con un agente del mismo id
+ * no comparten shard. Sin tenant es la identidad y un log de un solo dueño no
+ * cambia.
  *
- * La ESCRITURA (`append`) no entra aquí: va al shard del propio agente, y los
- * agentes de Hive Cloud ya llevan el enjambre en el id.
+ * Escritura y lecturas tienen que pasar por aquí: un evento escrito con una
+ * clave y leído con otra simplemente no aparece.
+ */
+export function causalAgentKey(agentId: string): string {
+  return qualifyDocId(agentId)
+}
+
+/**
+ * Lista `agents` para `causalThread`, `toolStats` y `buildAgentContext`.
+ *
+ * Devuelve `null` si no queda ningún agente, y quien llama se salta la
+ * lectura: hive-db trata una lista vacía igual que la ausencia de filtro y
+ * recorre TODOS los shards, que sobre una base compartida es leer los eventos
+ * de otros inquilinos.
+ */
+export function causalScope(agentIds: Iterable<string | null | undefined>): string[] | null {
+  const keys = new Set<string>()
+  for (const id of agentIds) {
+    if (id) keys.add(causalAgentKey(id))
+  }
+  return keys.size > 0 ? [...keys] : null
+}
+
+/**
+ * ¿Se lee el log causal (reflector, contexto causal del compilador)?
+ *
+ * Con hive-db 0.4, `causalThread`, `buildAgentContext` y `toolStats` recorrían
+ * todos los shards y mezclaban sus resultados, así que con un tenant activo
+ * había que apagarlas para no devolver hilos y estadísticas de otros
+ * inquilinos. hive-db 0.5.1 —la mínima que pide el SDK— acepta `agents` en las
+ * tres, y el SDK las llama siempre acotadas con {@link causalScope}: basta con
+ * que el log esté encendido.
  */
 export function causalReadsEnabled(): boolean {
-  return !!loadConfig().causalLog?.enabled && !currentTenant()
+  return !!loadConfig().causalLog?.enabled
 }
 
 /**
@@ -52,10 +83,10 @@ export function causalReadsEnabled(): boolean {
 export async function watchCausalEvents(
   pattern: EventPattern
 ): Promise<AsyncIterable<Event> & { close(): void }> {
-  // El log de eventos no tiene colecciones que prefijar: el aislamiento entre
-  // inquilinos lo da el shard por `agentId`. Un patrón sin `agentId` sobre una
-  // base compartida entregaría los eventos de todos los enjambres, así que se
-  // exige explícitamente en vez de filtrar a medias.
+  // Un patrón sin `agentId` sobre una base compartida entregaría los eventos de
+  // todos los enjambres, así que con un tenant activo se exige explícitamente en
+  // vez de filtrar a medias. Se recibe el id crudo del agente y su shard se
+  // busca por la clave calificada.
   if (currentTenant() && !pattern.agentId) {
     throw new Error(
       "watchCausalEvents: con un tenant activo el patrón debe fijar agentId; " +
@@ -63,7 +94,7 @@ export async function watchCausalEvents(
     )
   }
   const db = await getHiveDb()
-  return db.events(pattern)
+  return db.events(pattern.agentId ? { ...pattern, agentId: causalAgentKey(pattern.agentId) } : pattern)
 }
 
 /** One-line human-readable summary of a causal event, keyed by its kindTag. */
@@ -76,7 +107,7 @@ export function formatCausalEvent(event: Event): string {
   }
 
   const streamShort = event.streamId.slice(0, 8)
-  const header = `[${event.seq}] ${kindIcon(event.kindTag)} ${event.kindTag.padEnd(16)} agent=${event.agentId}  stream=${streamShort}…`
+  const header = `[${event.seq}] ${kindIcon(event.kindTag)} ${event.kindTag.padEnd(16)} agent=${unqualifyDocId(event.agentId)}  stream=${streamShort}…`
 
   switch (event.kindTag) {
     case "IntentLogged":

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

@@ -128,4 +128,4 @@ export { reconcileOnBoot } from "./reconcile.ts";
 
 // ─── Log causal (G9) ─────────────────────────────────────────────────────────
 export type { CausalEvent, CausalEventPattern } from "./causal-events.ts";
-export { watchCausalEvents, formatCausalEvent } from "./causal-events.ts";
+export { watchCausalEvents, formatCausalEvent, causalAgentKey, causalScope } from "./causal-events.ts";