@johpaz/hive-sdk 0.2.0 → 0.3.1

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)
 

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

@@ -29,7 +29,7 @@ import type { MCPClientManager } from "../mcp/index.ts"
 import { syncToolCatalogToIndex, mcpToolFullName } from "./tool-selector.ts"
 import { syncSkillsToIndex, getMinimalSkills, selectSkills, getSkillByName, type SkillDescriptor } from "./skill-selector.ts"
 import { syncPlaybookToIndex, selectPlaybookRules } from "./playbook-selector.ts"
-import { getRecentMessages, getSummary, getScratchpad, toAPIMessages } from "./conversation-store.ts"
+import { getRecentMessages, getSummary, getScratchpad, toAPIMessages, inflateRecentImages } from "./conversation-store.ts"
 import { formatContext, estimateTokens } from "../utils/toon.ts"
 import { buildSystemPromptWithProjects } from "./prompt-builder.ts"
 import { createAllTools } from "../tools/index.ts"
@@ -188,7 +188,7 @@ export async function compileContext(opts: {
 
   // [STEP-1] Load agent config
   log.info(`[context-compiler] [STEP-1] Loading agent config for id=${agentId}`)
-  let agent: ReturnType<typeof fromAgentDoc>
+  let agent: ReturnType<typeof fromAgentDoc> | undefined
   try {
     const agentsCol = await col<AgentDoc>("agents")
     const entry = await agentsCol.get(agentId)
@@ -518,7 +518,10 @@ export async function compileContext(opts: {
   // or — on a context-overflow retry that keeps only the LAST system message
   // (openai-compat-base.ts) — silently replaces the real prompt. The summary
   // lives in `systemPrompt` instead (see conversationSummarySection below).
-  const messages: LLMMessage[] = toAPIMessages(recentMessages)
+  // En el historial las imágenes son referencias, para no reenviarlas enteras en
+  // cada turno. Las de los últimos mensajes se vuelven a poner en línea: el
+  // modelo todavía puede necesitar mirarlas, y una referencia no se mira.
+  const messages: LLMMessage[] = await inflateRecentImages(toAPIMessages(recentMessages))
 
   // [STEP-10] STRATEGY 4: ISOLATE — Build context based on agent role
   log.info(`[context-compiler] [STEP-10] Building system prompt...`)
@@ -562,7 +565,7 @@ export async function compileContext(opts: {
     : Array.isArray(playbookInput)
       ? playbookInput.filter((part) => part.type === "text").map((part) => (part as any).text).join("\n")
       : String(playbookInput)
-  const playbookRules = (await selectPlaybookRules(playbookText)).filter((rule) => {
+  const playbookRules = (await selectPlaybookRules(playbookText, userId)).filter((rule) => {
     if (!rule.applicable_to || !rule.applicable_to.includes("agent:")) return true
     return isCatalogAgent ? rule.applicable_to.includes(`agent:${agent.id}`) : false
   })

package/packages/core/src/agent/conversation-store.ts

@@ -111,6 +111,66 @@ export function getRecentMessageCount(windowMs = 5 * 60_000): number {
   return recentMessageTimestamps.length
 }
 
+/** El threadId es `${userId}/${canal}/${peer}`, así que el dueño ya está ahí. */
+async function resolveOwnerId(threadId: string): Promise<string> {
+  const { parseThreadId } = await import("./thread-id.ts")
+  return parseThreadId(threadId)?.userId ?? threadId
+}
+
+/**
+ * Cuánto ocupa una imagen en la ventana de contexto.
+ *
+ * Los proveedores cobran por área, no por bytes: la fórmula es la de los
+ * modelos de visión más comunes (~750 px² por token). Es una estimación, pero
+ * cualquier estimación es infinitamente mejor que la anterior, que era cero: la
+ * compactación creía que un hilo con diez fotos ocupaba lo que ocupa su texto,
+ * y no se disparaba hasta que el proveedor rechazaba el turno.
+ */
+export function estimateImageTokens(width?: number | null, height?: number | null): number {
+  if (!width || !height) return 1_500;   // desconocida: el promedio de una foto
+  return Math.ceil((width * height) / 750);
+}
+
+/**
+ * Cambia las imágenes en línea por referencias a un artefacto.
+ *
+ * El base64 se guardaba entero en `content_multimodal` y `toAPIMessages` lo
+ * devolvía al modelo **en cada turno siguiente**: cinco fotos en una
+ * conversación eran cinco fotos reenviadas una y otra vez. Guardar el archivo y
+ * dejar una referencia corta ese crecimiento de raíz.
+ *
+ * La imagen no se pierde: `inflateRecentImages` la vuelve a poner en línea para
+ * los últimos turnos, que es donde el modelo todavía puede necesitar mirarla.
+ */
+async function imagesToRefs(content: ContentPart[], userId: string): Promise<ContentPart[]> {
+  const { createArtifact } = await import("../artifacts/store.ts")
+  const out: ContentPart[] = []
+
+  for (const part of content) {
+    if (part.type !== "image_base64") { out.push(part); continue }
+    try {
+      const bytes = Uint8Array.from(Buffer.from((part as { base64: string }).base64, "base64"))
+      const mimeType = (part as { mimeType?: string }).mimeType || "image/jpeg"
+      // Si no se puede medir, no es una imagen. Guardarla igual crearía un
+      // artefacto de tipo "image" con basura adentro, que aparecería en la
+      // galería del usuario; es mejor dejarla como venía.
+      const { measureImage } = await import("../images/index.ts")
+      const meta = await measureImage(bytes)
+
+      const art = await createArtifact({
+        bytes, mimeType, kind: "image", userId,
+        width: meta.width, height: meta.height, expiresAt: null,
+      })
+      out.push({ type: "artifact_ref", artifact_id: art.id, mime_type: mimeType, width: meta.width, height: meta.height } as unknown as ContentPart)
+    } catch {
+      // No es una imagen medible, o no se pudo guardar: viaja como venía.
+      // Perderla sería peor que no optimizarla.
+      out.push(part)
+    }
+  }
+  return out
+}
+
 export async function addMessage(
   threadId: string,
   role: StoredMessage["role"],
@@ -121,6 +181,8 @@ export async function addMessage(
     tool_call_id?: string
     reasoning_content?: string
     source?: MessageSource
+    /** Dueño de los artefactos que se creen para este mensaje (imágenes). */
+    userId?: string
   }
 ): Promise<number> {
   // Handle multimodal content by extracting text for the content column
@@ -130,7 +192,12 @@ export async function addMessage(
       ? content.filter(p => p.type === "text").map(p => (p as any).text).join("\n")
       : String(content)
 
-  const content_multimodal = Array.isArray(content) ? JSON.stringify(content) : null
+  // Las imágenes se guardan como archivo y en el historial queda una
+  // referencia: el base64 entero se reenviaba al modelo en cada turno.
+  const partes = Array.isArray(content)
+    ? await imagesToRefs(content, opts?.userId ?? (await resolveOwnerId(threadId)))
+    : null
+  const content_multimodal = partes ? JSON.stringify(partes) : null
   const tool_calls_json = opts?.tool_calls ? JSON.stringify(opts.tool_calls) : null
 
   const paddedSeq = await nextId(`conversations:${threadId}`)
@@ -150,7 +217,19 @@ export async function addMessage(
     reasoning_content: opts?.reasoning_content ?? null,
     source: opts?.source ?? "message",
     // Estimate tokens: content + tool_calls JSON
-    token_count: Math.max(1, estimateTokens(textContent) + estimateTokens(tool_calls_json ?? "")),
+    // Las imágenes cuentan: antes sumaban cero y la compactación creía que un
+    // hilo lleno de fotos ocupaba lo que ocupa su texto.
+    token_count: Math.max(
+      1,
+      estimateTokens(textContent) +
+      estimateTokens(tool_calls_json ?? "") +
+      (partes ?? []).reduce((n, p) => {
+        const q = p as { type: string; width?: number | null; height?: number | null }
+        return q.type === "artifact_ref" || q.type === "image_base64" || q.type === "image_url"
+          ? n + estimateImageTokens(q.width, q.height)
+          : n
+      }, 0),
+    ),
     created_at: now,
     updated_at: now,
   }, { expectedVersion: 0 })
@@ -252,6 +331,61 @@ export async function getMessagesAfter(threadId: string, afterId: number): Promi
 
 // ─── Convert stored messages → LLMMessage array ───────────────────────────────
 
+/**
+ * Cuántos mensajes del final conservan sus imágenes en línea.
+ *
+ * Mismo criterio que `clearOldToolResults` (compaction.ts), que ya poda
+ * resultados viejos y deja intactos los recientes. Es el compromiso: el modelo
+ * puede volver a mirar una imagen de hace un rato —"¿qué decía la factura?"—
+ * sin que una conversación larga arrastre todas las fotos para siempre.
+ */
+export const KEEP_IMAGES_LAST_N = 6
+
+/**
+ * Vuelve a poner en línea las imágenes de los últimos mensajes.
+ *
+ * En el historial las imágenes son referencias (ver `imagesToRefs`), que no
+ * ocupan contexto pero tampoco se pueden mirar: un modelo de visión no ve una
+ * foto desde un id. Para los últimos `keepLastN` mensajes se leen del disco y
+ * se devuelven como base64; los anteriores quedan como referencia, con sus
+ * dimensiones, para que el modelo sepa que hubo una imagen y cuál.
+ */
+export async function inflateRecentImages(
+  messages: LLMMessage[],
+  keepLastN = KEEP_IMAGES_LAST_N,
+): Promise<LLMMessage[]> {
+  const desde = Math.max(0, messages.length - keepLastN)
+  const tieneRefs = messages.slice(desde).some((m) =>
+    Array.isArray(m.content) && m.content.some((p) => (p as { type?: string }).type === "artifact_ref"))
+  if (!tieneRefs) return messages
+
+  const { readArtifactBytes } = await import("../artifacts/store.ts")
+
+  return Promise.all(messages.map(async (msg, i) => {
+    if (i < desde || !Array.isArray(msg.content)) return msg
+
+    const partes = await Promise.all(msg.content.map(async (part) => {
+      const p = part as { type: string; artifact_id?: string; mime_type?: string }
+      if (p.type !== "artifact_ref" || !p.artifact_id) return part
+      if (!String(p.mime_type ?? "").startsWith("image/")) return part
+
+      try {
+        const datos = await readArtifactBytes(p.artifact_id)
+        if (!datos) return part   // caducó o se borró: queda la referencia
+        return {
+          type: "image_base64",
+          base64: Buffer.from(datos.bytes).toString("base64"),
+          mimeType: datos.mimeType,
+        } as unknown as ContentPart
+      } catch {
+        return part
+      }
+    }))
+
+    return { ...msg, content: partes }
+  }))
+}
+
 export function toAPIMessages(rows: StoredMessage[]): LLMMessage[] {
   return rows.map((r) => {
     let content: string | ContentPart[] = r.content

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

@@ -201,7 +201,13 @@ async function processReflection(
 
   // Check if a similar rule already exists (fuzzy check by first 60 chars)
   const prefix = reflection.description.substring(0, 60)
-  const existing = allPlaybook.find(e => e.doc.active && e.doc.rule.startsWith(prefix))
+  // La deduplicación también va por usuario: si dos personas producen la misma
+  // observación, son dos reglas. Buscando sólo por texto, lo aprendido de la
+  // segunda reforzaría la regla de la primera y la haría pesar más en un
+  // playbook que no es suyo.
+  const existing = allPlaybook.find(
+    e => e.doc.active && e.doc.user_id === reflection.user_id && e.doc.rule.startsWith(prefix)
+  )
 
   if (existing) {
     // Reinforce existing rule
@@ -216,6 +222,7 @@ async function processReflection(
     id,
     rule: reflection.description,
     category,
+    user_id: reflection.user_id,
     applicable_to: applicableTo,
     helpful_count: 1,
     harmful_count: 0,
@@ -224,7 +231,7 @@ async function processReflection(
     created_at: now,
     updated_at: now,
   }, { expectedVersion: 0 })
-  allPlaybook.push({ id, version: 1, doc: { id, rule: reflection.description, category, applicable_to: applicableTo, helpful_count: 1, harmful_count: 0, active: true, source_reflection_id: toIndexable(reflection.id), created_at: now, updated_at: now } })
+  allPlaybook.push({ id, version: 1, doc: { id, rule: reflection.description, category, user_id: reflection.user_id, applicable_to: applicableTo, helpful_count: 1, harmful_count: 0, active: true, source_reflection_id: toIndexable(reflection.id), created_at: now, updated_at: now } })
 }
 
 function mapInsightTypeToCategory(
@@ -248,12 +255,13 @@ async function addOrUpdateRule(
   opts: {
     rule: string
     category: string
+    user_id: string
     applicable_to: string | null
     sourceReflectionId: string | null
   }
 ): Promise<void> {
   const prefix = opts.rule.substring(0, 60)
-  const existing = allPlaybook.find(e => e.doc.rule.startsWith(prefix))
+  const existing = allPlaybook.find(e => e.doc.user_id === opts.user_id && e.doc.rule.startsWith(prefix))
 
   if (existing) {
     await playbookCol.put(existing.id, { ...existing.doc, helpful_count: existing.doc.helpful_count + 1, updated_at: Date.now() }, { expectedVersion: existing.version })
@@ -264,6 +272,7 @@ async function addOrUpdateRule(
       id,
       rule: opts.rule,
       category: opts.category as PlaybookDoc["category"],
+      user_id: opts.user_id,
       applicable_to: opts.applicable_to,
       helpful_count: 1,
       harmful_count: 0,

package/packages/core/src/agent/llm-providers/nvidia.ts

@@ -1,5 +1,44 @@
 import { OpenAICompatBase } from "./openai-compat-base.ts"
+import type { LLMCallOptions } from "../llm-client.ts"
+
+/**
+ * NIM mantiene el razonamiento APAGADO por defecto en su endpoint compatible
+ * con OpenAI, y el interruptor no es el `reasoning_effort` de OpenAI sino
+ * `chat_template_kwargs`, con una clave distinta por familia de modelo.
+ *
+ * Verificado en vivo contra integrate.api.nvidia.com (2026-08-15):
+ * `z-ai/glm-5.2` no emite un solo `reasoning_content` sin esto — el delta trae
+ * únicamente `role` y `content` — y sí lo emite con `enable_thinking`. Por eso
+ * la app no mostraba razonamiento con los modelos de NVIDIA: no llegaba.
+ *
+ * Las familias que no están acá se dejan en paz a propósito. Nemotron 3 ya
+ * emite `reasoning_content` sin ningún kwarg (también verificado), y mandarle
+ * una clave que su plantilla no acepta es justamente lo que rompe la llamada.
+ */
+const THINKING_KWARGS: Array<{ pattern: RegExp; kwargs: Record<string, unknown> }> = [
+  // Verificado con z-ai/glm-5.2.
+  { pattern: /glm/i, kwargs: { enable_thinking: true, clear_thinking: false } },
+  // Verificado con minimaxai/minimax-m3.
+  { pattern: /minimax/i, kwargs: { thinking_mode: "enabled" } },
+  // Documentado por NVIDIA, sin verificar: moonshotai/kimi-k2.6 responde 404
+  // en la cuenta con la que se probó. Si la plantilla lo rechaza, el reintento
+  // de openai-compat-base repite la llamada sin kwargs.
+  { pattern: /kimi|deepseek/i, kwargs: { thinking: true } },
+  { pattern: /qwen|qwq/i, kwargs: { enable_thinking: true } },
+]
 
 export class NvidiaProvider extends OpenAICompatBase {
   constructor() { super("nvidia") }
+
+  protected modifyRequestBody(body: any, options: LLMCallOptions): any {
+    if (!options.thinking?.enabled) return body
+
+    const match = THINKING_KWARGS.find(({ pattern }) => pattern.test(options.model))
+    if (!match) return body
+
+    return {
+      ...body,
+      chat_template_kwargs: { ...(body.chat_template_kwargs ?? {}), ...match.kwargs },
+    }
+  }
 }

package/packages/core/src/agent/llm-providers/openai-compat-base.ts

@@ -7,6 +7,32 @@ import {
 import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall } from "./interface.ts"
 import type { ContentPart, LLMMessage } from "../llm-client.ts"
 
+/**
+ * Statuses that mean "this body is malformed or unsupported" — the only ones
+ * where dropping the provider extras can possibly help.
+ *
+ * Deliberately narrow. A first version retried on any status and immediately
+ * misfired in production against a 429: a rate limit is not a body problem, so
+ * the retry spent a second request against the very limit that rejected the
+ * first, and turned thinking off for nothing. Same for 401/403 (auth) and 404
+ * (unknown model).
+ */
+const EXTRAS_REJECTED_CODES = [400, 422]
+
+/**
+ * Drops the non-standard fields a provider added on top of an OpenAI-shaped
+ * body, for use on a retry after the body itself was rejected. Right now that
+ * is only NIM's `chat_template_kwargs` (nvidia.ts): it enables the model's
+ * thinking, so losing it costs the reasoning display and nothing else — a far
+ * better outcome than a turn that dies because one model's chat template did
+ * not recognize the switch.
+ */
+function stripProviderExtras(body: any): any {
+  if (!body?.chat_template_kwargs) return body
+  const { chat_template_kwargs: _dropped, ...rest } = body
+  return rest
+}
+
 const log = logger.child("llm-client")
 
 /** Matches both generic "context length exceeded" phrasing and llama.cpp's exceed_context_size_error shape. */
@@ -187,7 +213,14 @@ export abstract class OpenAICompatBase implements LLMProvider {
         delete bodyNoTools.tools
         delete bodyNoTools.tool_choice
         delete bodyNoTools.parallel_tool_calls
-        response = await client.chat.completions.create(this.modifyRequestBody(bodyNoTools, options), { signal: options.signal })
+        response = await client.chat.completions.create(stripProviderExtras(this.modifyRequestBody(bodyNoTools, options)), { signal: options.signal })
+      }
+      // Retry 3: the provider-specific extras are the only other thing we added
+      // to an otherwise standard body (NIM's chat_template_kwargs — see
+      // nvidia.ts). Losing the reasoning display beats failing the turn.
+      else if (EXTRAS_REJECTED_CODES.includes(status) && this.modifyRequestBody(body, options).chat_template_kwargs) {
+        log.warn(`[llm-client] ${this.providerName}: request rejected (HTTP ${status}) — retrying without chat_template_kwargs`)
+        response = await client.chat.completions.create(stripProviderExtras(this.modifyRequestBody(body, options)), { signal: options.signal })
       }
       else {
         throw err
@@ -258,7 +291,10 @@ export abstract class OpenAICompatBase implements LLMProvider {
         delete bodyNoTools.tools
         delete bodyNoTools.tool_choice
         delete bodyNoTools.parallel_tool_calls
-        stream = await client.chat.completions.create({ ...this.modifyRequestBody(bodyNoTools, options), stream: true }, { signal: options.signal })
+        stream = await client.chat.completions.create({ ...stripProviderExtras(this.modifyRequestBody(bodyNoTools, options)), stream: true }, { signal: options.signal })
+      } else if (EXTRAS_REJECTED_CODES.includes(status) && this.modifyRequestBody(body, options).chat_template_kwargs) {
+        log.warn(`[llm-client] ${this.providerName}: request rejected (HTTP ${status}) — retrying stream without chat_template_kwargs`)
+        stream = await client.chat.completions.create({ ...stripProviderExtras(this.modifyRequestBody(body, options)), stream: true }, { signal: options.signal })
       } else {
         throw err
       }

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

@@ -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

@@ -14,7 +14,7 @@
  */
 
 import { col } from "../storage/hive.ts"
-import type { EthicsDoc, AgentDoc, UserDoc } from "../storage/collections.ts"
+import type { EthicsDoc, AgentDoc, UserDoc } from "../storage/collections"
 import { logger } from "../utils/logger.ts"
 import { formatContext } from "../utils/toon.ts"
 import { resolveUserId } from "../storage/onboarding.ts"
@@ -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/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.ts"
+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,9 +116,10 @@ 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"] = []
+    let toolCalls: NonNullable<ModelResponse["toolCalls"]> = []
     let totalInputTokens = 0
     let totalOutputTokens = 0
 
@@ -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/reflector.ts

@@ -17,6 +17,7 @@ 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.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 —

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

@@ -17,7 +17,7 @@
  */
 
 import { col } from "../storage/hive.ts"
-import type { SkillDoc } from "../storage/collections.ts"
+import type { SkillDoc } from "../storage/collections"
 import { logger } from "../utils/logger.ts"
 import { isMinimalSkill } from "./minimal-loadout.ts"
 import { isCalendarOperation } from "./routing-intent.ts"
@@ -109,7 +109,7 @@ const STOPWORDS = new Set([
     "más", "mas", "ya", "yo", "tu", "te", "ti", "mi", "me",
     "hola", "hi", "hello", "hey", "gracias", "thank", "please",
     "ok", "okay", "yes", "si", "no", "bien", "good", "great",
-    "puedes", "necesito", "quiero", "podés", "necesitás", "querés",
+    "puedes", "necesito", "quiero", "necesitas", "quieres",
 ])
 
 /** Conversational patterns that should return empty skill list */