@johpaz/hive-sdk 0.1.6 → 0.3.0

package/packages/core/src/agent/playbook-selector.ts

@@ -7,15 +7,15 @@
  * folding, lenient parsing — raw user text never throws).
  */
 
-import { col } from "../storage/hive"
-import type { PlaybookDoc } from "../storage/collections"
-import { logger } from "../utils/logger"
+import { col } from "../storage/hive.ts"
+import type { PlaybookDoc } from "../storage/collections.ts"
+import { logger } from "../utils/logger.ts"
 import {
     searchCapabilities,
     applyRelativeCutoff,
     replaceCapabilityDocs,
     type CapabilityDoc,
-} from "./capability-search"
+} from "./capability-search.ts"
 
 const log = logger.child("playbook-selector")
 
@@ -39,20 +39,33 @@ const MAX_RULES_PER_TURN = 5
  */
 const RELEVANCE_RATIO = 0.3
 
+/** Cuántos candidatos se piden de más para sobrevivir al filtro por usuario. */
+const OVERFETCH_FACTOR = 4
+
 // ─── Selection Logic ───────────────────────────────────────────────────────────
 
 /**
- * Select relevant rules from the Playbook based on semantic matching
+ * Select relevant rules from the Playbook based on semantic matching.
+ *
+ * `userId` acota lo aprendido a quien corresponde: una regla se aplica si es
+ * global (`user_id === ""`, el conocimiento sembrado con el producto) o si
+ * salió de las trazas de este mismo usuario. Sin este filtro, lo que el agente
+ * aprende hablando con una persona termina inyectado en el prompt de otra.
+ * Omitirlo devuelve sólo las reglas globales.
  */
-export async function selectPlaybookRules(message: string): Promise<PlaybookRule[]> {
+export async function selectPlaybookRules(message: string, userId?: string): Promise<PlaybookRule[]> {
     const startTime = performance.now()
 
     if (!message.trim()) return []
 
     try {
+        // El índice BM25 es uno solo para todos los usuarios, así que pedir k
+        // resultados y filtrar después dejaría a un usuario sin reglas cuando
+        // las mejor puntuadas son de otro. Se pide un pozo más ancho y se
+        // recorta a MAX_RULES_PER_TURN recién después de filtrar.
         const hits = await searchCapabilities(message, {
             types: ["playbook"],
-            k: MAX_RULES_PER_TURN,
+            k: MAX_RULES_PER_TURN * OVERFETCH_FACTOR,
         })
 
         const relevantIds = applyRelativeCutoff(hits, RELEVANCE_RATIO).map(h => h.rawId)
@@ -64,6 +77,8 @@ export async function selectPlaybookRules(message: string): Promise<PlaybookRule
         const entries = await Promise.all(relevantIds.map(id => playbookCol.get(id)))
         const rules: PlaybookRule[] = entries
             .filter((e): e is NonNullable<typeof e> => !!e && e.doc.active)
+            .filter(e => e.doc.user_id === "" || e.doc.user_id === (userId ?? ""))
+            .slice(0, MAX_RULES_PER_TURN)
             .map(e => ({
                 id: e.id,
                 rule: e.doc.rule,

package/packages/core/src/agent/prompt-builder.ts

@@ -13,11 +13,11 @@
  * - Skills activos
  */
 
-import { col } from "../storage/hive"
+import { col } from "../storage/hive.ts"
 import type { EthicsDoc, AgentDoc, UserDoc } from "../storage/collections"
-import { logger } from "../utils/logger"
-import { formatContext } from "../utils/toon"
-import { resolveUserId } from "../storage/onboarding"
+import { logger } from "../utils/logger.ts"
+import { formatContext } from "../utils/toon.ts"
+import { resolveUserId } from "../storage/onboarding.ts"
 
 const log = logger.child("prompt-builder")
 
@@ -136,7 +136,7 @@ export async function buildSystemPrompt(opts: BuildSystemPromptOpts): Promise<st
     if (Object.keys(userData).length > 0) {
       userSection += formatContext(userData) + "\n\n"
       if (agent.role === "coordinator" && user.email) {
-        userSection += `Cuando el usuario diga "envíame", "mándame" o "a mi correo" sin indicar otro destinatario, usá CorreoPropio. Para terceras personas, resolvé su dirección por separado.\n\n`
+        userSection += `Cuando el usuario diga "envíame", "mándame" o "a mi correo" sin indicar otro destinatario, usa CorreoPropio. Para terceras personas, resuelve su dirección por separado.\n\n`
       }
     } else {
       userSection += `Usuario ID: ${userId}\n\n`

package/packages/core/src/agent/proof-packet.ts

@@ -6,11 +6,11 @@
  * reviewer doesn't have to replay the whole run to trust its outcome.
  */
 
-import { col, nextId, toIndexable } from "../storage/hive";
-import type { ProofPacketDoc } from "../storage/collections";
-import type { AcceptanceResult } from "./goal-runner";
-import type { RunEpoch } from "./run-epoch";
-import { logger } from "../utils/logger";
+import { col, nextId, toIndexable } from "../storage/hive.ts";
+import type { ProofPacketDoc } from "../storage/collections.ts";
+import type { AcceptanceResult } from "./goal-runner.ts";
+import type { RunEpoch } from "./run-epoch.ts";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("proof-packet");
 

package/packages/core/src/agent/providers/index.ts

@@ -7,10 +7,11 @@
 
 import type { Config } from "../../config/loader.ts"
 import { logger } from "../../utils/logger.ts"
-import { getAgentLoop } from "../agent-loop"
-import { resolveUserId, resolveAgentId } from "../../storage/onboarding"
-import type { ContentPart } from "../../multimodal/types"
-import type { TurnSource } from "../../storage/collections"
+import { getAgentLoop, buildAgentLoop } from "../agent-loop.ts"
+import { resolveUserId, resolveAgentId } from "../../storage/onboarding.ts"
+import type { ContentPart } from "../../multimodal/types.ts"
+import type { TurnSource } from "../../storage/collections.ts"
+import type { MCPClientManager } from "../../mcp/index.ts"
 
 export type Provider = "openai" | "anthropic" | "gemini" | "mistral" | "kimi" | "ollama" | "openrouter" | "deepseek" | "nvidia" | "hiveagents" | "z-ai" | "modelscope" | "minimax" | "qwen" | "groq" | "opencode-go"
 
@@ -62,6 +63,34 @@ export interface ModelResponse {
     totalTokens: number
   }
   finishReason?: string
+  /** Image artifacts (mcp-result-normalizer.ts, agent-loop.ts's turnImageArtifacts) produced by tools this turn. */
+  imageArtifacts?: Array<{ artifactId: string; mimeType: string }>
+}
+
+/**
+ * Crea un `AgentRunner` listo para usar.
+ *
+ * `AgentRunner.generate()` necesita que el loop global exista
+ * (`getAgentLoop()`), y construirlo es un paso aparte que hay que recordar:
+ * `new AgentRunner(config)` a secas compila, se instancia sin quejarse y falla
+ * recién en la primera llamada con "AgentLoop not initialized". En hive ese paso
+ * lo hace su initializer; en el SDK no lo hacía nadie, así que la clase estaba
+ * exportada pero no era utilizable.
+ *
+ * Esta fábrica hace las dos cosas en el orden correcto. Es idempotente: llamarla
+ * dos veces reconstruye el loop con el manager que se le pase.
+ *
+ * ```ts
+ * const runner = await createAgentRunner(loadConfig(), { mcpManager });
+ * const res = await runner.generate({ messages: [...] });
+ * ```
+ */
+export async function createAgentRunner(
+  config: Config,
+  opts: { mcpManager?: MCPClientManager | null } = {},
+): Promise<AgentRunner> {
+  buildAgentLoop({ mcpManager: opts.mcpManager ?? null })
+  return new AgentRunner(config)
 }
 
 export class AgentRunner {
@@ -87,6 +116,7 @@ export class AgentRunner {
       throw new Error("AgentLoop not initialized")
     }
 
+    let imageArtifacts: ModelResponse["imageArtifacts"]
     let lastAgentContent = ""
     let accumulatedAgentContent = ""  // Accumulate content from all agent chunks
     let toolCalls: ModelResponse["toolCalls"] = []
@@ -190,6 +220,10 @@ export class AgentRunner {
           totalInputTokens += chunk.usage.input_tokens
           totalOutputTokens += chunk.usage.output_tokens
         }
+
+        if (chunk.artifacts?.images?.length) {
+          imageArtifacts = [...(imageArtifacts ?? []), ...chunk.artifacts.images]
+        }
       }
 
       logger.debug(`[STREAM] done. totalChunks=${chunkCount} lastAgentContent length=${lastAgentContent.length}, accumulated length=${accumulatedAgentContent.length}`)
@@ -208,6 +242,7 @@ export class AgentRunner {
           totalTokens: totalInputTokens + totalOutputTokens,
         },
         finishReason: "stop",
+        imageArtifacts,
       }
     } catch (error) {
       logger.error("AgentRunner error:", error)

package/packages/core/src/agent/realtime-providers/gemini-live.ts

@@ -0,0 +1,238 @@
+/**
+ * Adaptador de la Live API de Gemini (`bidiGenerateContent`).
+ *
+ * Sobre `ai.live.connect()` de @google/genai. El import es dinámico igual que en
+ * ../llm-providers/gemini.ts: el SDK arrastra dependencias de Vertex que no hacen
+ * falta con API key, y cargarlo perezosamente evita pagarlas en el arranque.
+ *
+ * Verificado contra gemini-3.1-flash-live-preview (2026-08): la inyección de
+ * texto va por `sendRealtimeInput({text})`; `sendClientContent` quedó restringido
+ * al contexto inicial en 3.x, así que no se usa acá.
+ */
+
+import { logger } from "../../utils/logger.ts";
+import { ensureArrayItems } from "../llm-providers/interface.ts";
+import type {
+  RealtimeProvider,
+  RealtimeSession,
+  RealtimeSessionOptions,
+  RealtimeToolCall,
+} from "./interface.ts";
+
+const log = logger.child("realtime:gemini");
+
+/** Modelos con `bidiGenerateContent`. El id vive en la BD; esto es sólo el fallback. */
+export const DEFAULT_GEMINI_LIVE_MODEL = "gemini-3.1-flash-live-preview";
+
+class GeminiLiveSession implements RealtimeSession {
+  closed = false;
+
+  readonly model: string;
+  private readonly session: any;
+  private readonly callbacks: RealtimeSessionOptions["callbacks"];
+
+  constructor(
+    model: string,
+    session: any,
+    callbacks: RealtimeSessionOptions["callbacks"],
+  ) {
+    this.model = model;
+    this.session = session;
+    this.callbacks = callbacks;
+  }
+
+  sendAudio(pcm: ArrayBufferLike): void {
+    if (this.closed) return;
+    try {
+      this.session.sendRealtimeInput({
+        audio: {
+          data: Buffer.from(pcm as ArrayBuffer).toString("base64"),
+          mimeType: "audio/pcm;rate=16000",
+        },
+      });
+    } catch (error) {
+      this.fail(error, "sendAudio");
+    }
+  }
+
+  sendVideoFrame(base64: string, mimeType: string): void {
+    if (this.closed) return;
+    try {
+      this.session.sendRealtimeInput({ video: { data: base64, mimeType } });
+    } catch (error) {
+      this.fail(error, "sendVideoFrame");
+    }
+  }
+
+  sendText(text: string): void {
+    if (this.closed || !text.trim()) return;
+    try {
+      this.session.sendRealtimeInput({ text });
+    } catch (error) {
+      this.fail(error, "sendText");
+    }
+  }
+
+  sendToolResult(id: string, name: string, result: Record<string, unknown>): void {
+    if (this.closed) return;
+    try {
+      this.session.sendToolResponse({ functionResponses: [{ id, name, response: result }] });
+    } catch (error) {
+      this.fail(error, "sendToolResult");
+    }
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      this.session.close();
+    } catch {
+      /* el socket ya estaba cerrado */
+    }
+  }
+
+  /** Marca la sesión como muerta: seguir escribiendo en un socket roto sólo genera ruido. */
+  private fail(error: unknown, op: string): void {
+    this.closed = true;
+    const err = error instanceof Error ? error : new Error(String(error));
+    log.warn(`${op} falló: ${err.message}`);
+    this.callbacks.onError?.(err);
+  }
+}
+
+export class GeminiLiveProvider implements RealtimeProvider {
+  readonly id = "gemini";
+
+  async connect(options: RealtimeSessionOptions): Promise<RealtimeSession> {
+    const { GoogleGenAI } = await import("@google/genai");
+    const ai = new GoogleGenAI({ apiKey: options.apiKey });
+    const cb = options.callbacks;
+
+    const config: Record<string, unknown> = {
+      responseModalities: ["AUDIO"],
+      systemInstruction: options.systemInstruction,
+      // Necesarias para persistir el hilo y pintarlo en el chat: sin esto sólo
+      // llegan bytes de audio y la conversación hablada no deja rastro escrito.
+      inputAudioTranscription: {},
+      outputAudioTranscription: {},
+      // Sin compresión la sesión muere a los 15 min de audio.
+      contextWindowCompression: { slidingWindow: {} },
+      // Handle para reanudar tras un goAway sin perder el hilo.
+      sessionResumption: options.resumptionHandle ? { handle: options.resumptionHandle } : {},
+    };
+
+    if (options.voice || options.language) {
+      const speechConfig: Record<string, unknown> = {};
+      if (options.voice) {
+        speechConfig.voiceConfig = { prebuiltVoiceConfig: { voiceName: options.voice } };
+      }
+      if (options.language) speechConfig.languageCode = options.language;
+      config.speechConfig = speechConfig;
+    }
+    if (options.silenceDurationMs || options.startOfSpeechSensitivity) {
+      const deteccion: Record<string, unknown> = {};
+      if (options.silenceDurationMs) deteccion.silenceDurationMs = options.silenceDurationMs;
+      if (options.startOfSpeechSensitivity) {
+        deteccion.startOfSpeechSensitivity = options.startOfSpeechSensitivity;
+      }
+      config.realtimeInputConfig = { automaticActivityDetection: deteccion };
+    }
+    if (options.tools?.length) {
+      config.tools = [
+        {
+          functionDeclarations: options.tools.map((t) => ({
+            name: t.function.name,
+            description: t.function.description,
+            parameters: ensureArrayItems(t.function.parameters),
+          })),
+        },
+      ];
+    }
+
+    let wrapper: GeminiLiveSession | null = null;
+
+    const session = await ai.live.connect({
+      model: options.model,
+      config: config as any,
+      callbacks: {
+        onopen: () => log.info(`sesión abierta (${options.model})`),
+        onmessage: (msg: any) => {
+          try {
+            handleMessage(msg, cb);
+          } catch (error) {
+            cb.onError?.(error instanceof Error ? error : new Error(String(error)));
+          }
+        },
+        onerror: (e: any) => {
+          cb.onError?.(new Error(e?.message ?? String(e)));
+        },
+        onclose: (e: any) => {
+          if (wrapper) wrapper.closed = true;
+          cb.onClose?.(e?.reason || "");
+        },
+      },
+    });
+
+    wrapper = new GeminiLiveSession(options.model, session, cb);
+    return wrapper;
+  }
+}
+
+function handleMessage(msg: any, cb: RealtimeSessionOptions["callbacks"]): void {
+  const content = msg.serverContent;
+  if (content) {
+    for (const part of content.modelTurn?.parts ?? []) {
+      const data = part.inlineData?.data;
+      if (data) cb.onAudio?.(Buffer.from(data, "base64"));
+    }
+    if (content.inputTranscription?.text) cb.onInputTranscript?.(content.inputTranscription.text);
+    if (content.outputTranscription?.text) cb.onOutputTranscript?.(content.outputTranscription.text);
+    if (content.interrupted) cb.onInterrupted?.();
+    if (content.turnComplete) cb.onTurnComplete?.();
+  }
+
+  if (msg.toolCall?.functionCalls?.length) {
+    const calls: RealtimeToolCall[] = msg.toolCall.functionCalls.map((fc: any) => ({
+      id: fc.id ?? "",
+      name: fc.name ?? "",
+      args: (fc.args ?? {}) as Record<string, unknown>,
+    }));
+    cb.onToolCall?.(calls);
+  }
+
+  if (msg.toolCallCancellation?.ids?.length) {
+    cb.onToolCallCancellation?.(msg.toolCallCancellation.ids);
+  }
+
+  if (msg.usageMetadata) {
+    const u = msg.usageMetadata;
+    cb.onUsage?.({
+      inputTokens: Number(u.promptTokenCount ?? 0),
+      outputTokens: Number(u.responseTokenCount ?? 0),
+      totalTokens: Number(u.totalTokenCount ?? 0),
+    });
+  }
+
+  if (msg.sessionResumptionUpdate?.newHandle) {
+    cb.onResumptionHandle?.(msg.sessionResumptionUpdate.newHandle);
+  }
+
+  if (msg.goAway) {
+    cb.onGoAway?.(parseDuration(msg.goAway.timeLeft));
+  }
+}
+
+/** `timeLeft` llega como duración protobuf ("9.5s") o como objeto {seconds,nanos}. */
+function parseDuration(value: unknown): number {
+  if (typeof value === "string") {
+    const seconds = parseFloat(value.replace(/s$/, ""));
+    return Number.isFinite(seconds) ? Math.round(seconds * 1000) : 0;
+  }
+  if (value && typeof value === "object") {
+    const v = value as { seconds?: number | string; nanos?: number };
+    const seconds = Number(v.seconds ?? 0);
+    return Math.round(seconds * 1000 + (v.nanos ?? 0) / 1e6);
+  }
+  return 0;
+}

package/packages/core/src/agent/realtime-providers/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Registro de proveedores de voz en tiempo real.
+ *
+ * Hoy sólo Gemini Live. La interfaz existe desacoplada para que añadir OpenAI
+ * Realtime o Nova Sonic no obligue a tocar el gateway ni el cliente: cambia el
+ * adaptador, no el transporte.
+ */
+
+import { GeminiLiveProvider } from "./gemini-live.ts";
+import type { RealtimeProvider } from "./interface.ts";
+
+export * from "./interface.ts";
+export { DEFAULT_GEMINI_LIVE_MODEL } from "./gemini-live.ts";
+
+const providers = new Map<string, RealtimeProvider>([["gemini", new GeminiLiveProvider()]]);
+
+export function getRealtimeProvider(providerId: string): RealtimeProvider {
+  const provider = providers.get(providerId);
+  if (!provider) {
+    throw new Error(
+      `El proveedor "${providerId}" no soporta voz en tiempo real. Disponibles: ${[...providers.keys()].join(", ")}`,
+    );
+  }
+  return provider;
+}
+
+export function isRealtimeProvider(providerId: string): boolean {
+  return providers.has(providerId);
+}

package/packages/core/src/agent/realtime-providers/interface.ts

@@ -0,0 +1,108 @@
+/**
+ * realtime-providers — sesiones de voz full-duplex (speech-to-speech).
+ *
+ * `LLMProvider` (../llm-providers/interface.ts) es one-shot: `call()` recibe un
+ * historial y devuelve una respuesta. Una sesión Live no encaja ahí — es un
+ * socket que vive minutos, recibe audio continuo y emite audio continuo. De ahí
+ * esta interfaz hermana en vez de una subclase.
+ *
+ * El modelo realtime NO es el cerebro de Hive: sólo oye, habla e interrumpe. El
+ * trabajo real lo hace el agent-loop de siempre (Bee → especialistas → tools).
+ * Por eso las herramientas que se declaran acá son un puñado fijo de funciones
+ * puente (gateway/realtime/bridge-tools.ts) y no el catálogo del agente: la Live
+ * API congela las tools en el `setup` y no admite cambiarlas a mitad de sesión.
+ */
+
+import type { LLMToolDef } from "../llm-client.ts";
+
+/** Lo que el micrófono debe entregar: PCM16 mono little-endian. */
+export const REALTIME_INPUT_SAMPLE_RATE = 16_000;
+/** Lo que el modelo devuelve: PCM16 mono. */
+export const REALTIME_OUTPUT_SAMPLE_RATE = 24_000;
+
+export interface RealtimeToolCall {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+}
+
+export interface RealtimeCallbacks {
+  /** Audio del modelo, PCM16 mono a REALTIME_OUTPUT_SAMPLE_RATE. */
+  onAudio?: (pcm: Buffer) => void;
+  /** Transcripción de lo que dijo el usuario (fragmentos incrementales). */
+  onInputTranscript?: (text: string) => void;
+  /** Transcripción de lo que dijo el modelo (fragmentos incrementales). */
+  onOutputTranscript?: (text: string) => void;
+  onToolCall?: (calls: RealtimeToolCall[]) => void;
+  /** El modelo canceló tool calls ya emitidas (el usuario cambió de tema). */
+  onToolCallCancellation?: (ids: string[]) => void;
+  /** Barge-in: el usuario habló encima. Hay que vaciar la cola de reproducción YA. */
+  onInterrupted?: () => void;
+  onTurnComplete?: () => void;
+  /** Consumo acumulado que reporta el proveedor. */
+  onUsage?: (usage: { inputTokens: number; outputTokens: number; totalTokens: number }) => void;
+  /** Handle para reanudar la sesión tras un corte (válido ~2 h). */
+  onResumptionHandle?: (handle: string) => void;
+  /** El servidor va a cerrar la conexión; hay que reconectar con el handle. */
+  onGoAway?: (timeLeftMs: number) => void;
+  onError?: (error: Error) => void;
+  onClose?: (reason: string) => void;
+}
+
+export interface RealtimeSessionOptions {
+  model: string;
+  apiKey: string;
+  /** Prompt de la sesión de voz (no es el system prompt del agent-loop). */
+  systemInstruction: string;
+  /** Funciones puente. Congeladas: la Live API no permite cambiarlas después. */
+  tools?: LLMToolDef[];
+  /** Voz del proveedor (ej. "Kore"). Ver voiceService.getGeminiVoices(). */
+  voice?: string;
+  /**
+   * Idioma con acento regional, en BCP-47 (es-CO, es-MX, en-US…).
+   *
+   * Los modelos de audio nativo cambian de idioma solos siguiendo al usuario,
+   * pero sin esto eligen el acento por su cuenta: un usuario colombiano puede
+   * terminar escuchando español rioplatense.
+   */
+  language?: string;
+  /** Silencio en ms que cierra el turno del usuario (VAD automático). */
+  silenceDurationMs?: number;
+  /**
+   * Cuánto cuesta que el modelo dé por empezada una intervención del usuario.
+   * `START_SENSITIVITY_LOW` sube el listón: hace falta voz clara para
+   * interrumpirle, en vez de cualquier ruido. Es lo que salva las manos libres,
+   * donde lo que entra por el micrófono incluye su propia voz rebotando.
+   */
+  startOfSpeechSensitivity?: "START_SENSITIVITY_LOW" | "START_SENSITIVITY_HIGH";
+  /** Handle devuelto por una sesión anterior, para retomar el hilo. */
+  resumptionHandle?: string;
+  callbacks: RealtimeCallbacks;
+}
+
+export interface RealtimeSession {
+  readonly model: string;
+  /** PCM16 mono a REALTIME_INPUT_SAMPLE_RATE. */
+  sendAudio(pcm: ArrayBufferLike): void;
+  /**
+   * Un fotograma de la cámara, ya codificado (JPEG en base64).
+   *
+   * Va a baja cadencia a propósito: con vídeo, la Live API recorta la sesión de
+   * 15 minutos a unos 2 y cada imagen cuesta cientos de tokens frente a los 25
+   * por segundo del audio.
+   */
+  sendVideoFrame(base64: string, mimeType: string): void;
+  /** Inyecta texto en la conversación (narración de la colmena, avisos). */
+  sendText(text: string): void;
+  sendToolResult(id: string, name: string, result: Record<string, unknown>): void;
+  close(): void;
+  readonly closed: boolean;
+}
+
+export interface RealtimeProvider {
+  readonly id: string;
+  connect(options: RealtimeSessionOptions): Promise<RealtimeSession>;
+}
+
+/** Toolset fijo de una sesión de voz, en el formato canónico de Hive. */
+export type RealtimeToolset = LLMToolDef[];

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

@@ -11,12 +11,13 @@
  * trick the SQLite version used — HiveDB has no equivalent primitive.
  */
 
-import { logger } from "../utils/logger"
-import { col, nextId } from "../storage/hive"
-import { getHiveDb } from "../storage/hivedb"
-import { loadConfig } from "../config/loader"
+import { logger } from "../utils/logger.ts"
+import { col, nextId } from "../storage/hive.ts"
+import { getHiveDb } from "../storage/hivedb.ts"
+import { loadConfig } from "../config/loader.ts"
 import type { HiveDB, ToolStats } from "@johpaz/hive-db"
-import type { TraceDoc, ReflectionDoc, CursorDoc } from "../storage/collections"
+import type { TraceDoc, ReflectionDoc, CursorDoc } from "../storage/collections.ts"
+import { parseThreadId } from "./thread-id.ts"
 
 const log = logger.child("reflector")
 
@@ -51,25 +52,42 @@ export async function runReflector(): Promise<void> {
 
     log.info(`[reflector] Analyzing ${traces.length} traces...`)
 
+    // Las trazas se agrupan por usuario antes de analizarlas.
+    //
+    // Antes se analizaba el lote entero de una vez, así que una reflexión —y la
+    // regla de playbook que sale de ella— mezclaba lo aprendido de varias
+    // personas. En una instalación de un solo usuario da igual; en un host
+    // multi-inquilino significa que lo aprendido de un workspace se le aplica a
+    // otro. El usuario sale del `thread_id`, que ya lo lleva dentro.
+    const porUsuario = new Map<string, typeof traceEntries>()
+    for (const entry of traceEntries) {
+      const usuario = parseThreadId(entry.doc.thread_id)?.userId ?? ""
+      const grupo = porUsuario.get(usuario) ?? []
+      grupo.push(entry)
+      porUsuario.set(usuario, grupo)
+    }
+
     // G9: when enabled, per-tool insights use whole-history stats from HiveDB's
     // event log (toolStats) instead of counters built from just this batch, and
     // causal threads add root-cause/learning-proposal insights on top.
     const causalDb = loadConfig().causalLog?.enabled ? await getHiveDb() : null
-    const localInsights = await analyzeTracesLocally(traces, causalDb)
-    const causalInsights = await analyzeCausalThreads(traces, causalDb)
-    const insights = [...localInsights, ...causalInsights]
+    const reflectionsCol = await col<ReflectionDoc>("reflections")
+    let totalInsights = 0
 
-    if (insights.length === 0) {
-      log.debug("[reflector] No insights generated")
-    } else {
-      const traceIds = JSON.stringify(traceEntries.map(e => e.id))
-      const reflectionsCol = await col<ReflectionDoc>("reflections")
+    for (const [usuario, entradas] of porUsuario) {
+      const delGrupo = entradas.map(e => e.doc)
+      const localInsights = await analyzeTracesLocally(delGrupo, causalDb)
+      const causalInsights = await analyzeCausalThreads(delGrupo, causalDb)
+      const insights = [...localInsights, ...causalInsights]
+      if (insights.length === 0) continue
 
+      const traceIds = JSON.stringify(entradas.map(e => e.id))
       for (const insight of insights) {
         const id = await nextId("reflections")
         await reflectionsCol.put(id, {
           id,
           trace_ids: traceIds,
+          user_id: usuario,
           insight_type: insight.type,
           description: insight.description,
           affected_tools: insight.affectedTools ? JSON.stringify(insight.affectedTools) : null,
@@ -78,8 +96,13 @@ export async function runReflector(): Promise<void> {
           created_at: Date.now(),
         })
       }
+      totalInsights += insights.length
+    }
 
-      log.info(`[reflector] Generated ${insights.length} insights`)
+    if (totalInsights === 0) {
+      log.debug("[reflector] No insights generated")
+    } else {
+      log.info(`[reflector] Generated ${totalInsights} insights across ${porUsuario.size} user(s)`)
     }
 
     // Advance the cursor regardless of whether insights were generated —
@@ -88,7 +111,7 @@ export async function runReflector(): Promise<void> {
     await cursorsCol.put(CURSOR_ID, { value: newCursor }, cursorEntry ? { expectedVersion: cursorEntry.version } : { expectedVersion: 0 })
 
     // Trigger curator
-    const { runCurator } = await import("./curator")
+    const { runCurator } = await import("./curator.ts")
     await runCurator()
 
     log.info(`[reflector] Reflection cycle completed successfully`)