@johpaz/hive-sdk 0.1.6 → 0.3.0

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

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

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

@@ -13,24 +13,25 @@
  * Also used directly by runAgentIsolated() for worker tasks.
  */
 
-import { logger } from "../utils/logger"
-import { col, fromIndexable } from "../storage/hive"
-import { getHiveDb } from "../storage/hivedb"
+import { logger } from "../utils/logger.ts"
+import { col, fromIndexable } from "../storage/hive.ts"
+import { getHiveDb } from "../storage/hivedb.ts"
 import type { HiveDB, EventInput } from "@johpaz/hive-db"
-import type { AgentDoc, TurnSource } from "../storage/collections"
-import { callLLM, resolveProviderConfig, getDefaultLLM, type LLMMessage } from "./llm-client"
-import { addMessage } from "./conversation-store"
-import { saveTrace, recordLLMUsage } from "./tracer"
-import { maybeCompact, clearOldToolResults } from "./compaction"
-import { emitCanvas } from "../canvas/emitter"
+import type { AgentDoc, TurnSource } from "../storage/collections.ts"
+import { callLLM, resolveProviderConfig, getDefaultLLM, type LLMMessage, type ProviderCredentials } from "./llm-client.ts"
+import { addMessage } from "./conversation-store.ts"
+import { saveTrace, recordLLMUsage } from "./tracer.ts"
+import { maybeCompact, clearOldToolResults } from "./compaction.ts"
+import { emitCanvas } from "../canvas/emitter.ts"
 import type { MCPClientManager } from "../mcp/index.ts"
-import { compileContext } from "./context-compiler"
-import { formatToolResult } from "../utils/toon"
-import { resolveUserId, resolveAgentId } from "../storage/onboarding"
-import type { ContentPart } from "../multimodal/types"
-import { loadConfig } from "../config/loader"
-import { executeToolBatch } from "../tool-runtime"
-import { createStuckLoopDetector, getInterventionMessage, type StuckLoopState } from "./stuck-loop"
+import { compileContext } from "./context-compiler.ts"
+import { formatToolResult } from "../utils/toon.ts"
+import { redactBinaryStrings } from "../utils/redact-binary.ts"
+import { resolveUserId, resolveAgentId } from "../storage/onboarding.ts"
+import type { ContentPart } from "../multimodal/types.ts"
+import { loadConfig } from "../config/loader.ts"
+import { executeToolBatch } from "../tool-runtime/index.ts"
+import { createStuckLoopDetector, getInterventionMessage, type StuckLoopState } from "./stuck-loop.ts"
 import {
   createRun as createAgentRun,
   checkpoint as checkpointRun,
@@ -44,9 +45,9 @@ import {
   startLeaseRenewal,
   stopLeaseRenewal,
   type RunCheckpointState,
-} from "./run-store"
-import { publishNarration } from "../events/narration"
-import { getNarration } from "../events/tool-narration"
+} from "./run-store.ts"
+import { publishNarration } from "../events/narration.ts"
+import { getNarration } from "../events/tool-narration.ts"
 
 const log = logger.child("agent-loop")
 
@@ -94,6 +95,50 @@ export async function synthesizeFinalResponse(
   )
 }
 
+type LoadoutContext = {
+  tools: Array<{ type: string; function?: { name?: string } }>
+  allTools: Array<{ name: string }>
+}
+
+/**
+ * Adds artifact_read to the loadout the moment a tool result hands the model an
+ * `artifact_ref` it will need to open.
+ *
+ * mcp-result-normalizer.ts moves oversized MCP text results out of the context
+ * window and leaves a reference behind. Discovery (search_knowledge) can find
+ * the reader, but that costs an iteration and assumes the model thinks to look:
+ * in the incident this comes from, it reached for artifact_inspect instead, got
+ * metadata, and burned the rest of its budget on `find` and `env` before the
+ * turn died on an empty synthesis. Image refs are excluded — those are carried
+ * to the UI, not read back by the model.
+ *
+ * Returns true when the loadout changed.
+ */
+export function injectArtifactReadIfNeeded(toolResult: unknown, ctx: LoadoutContext): boolean {
+  if (!Array.isArray(toolResult)) return false
+
+  const needsReader = toolResult.some((block) =>
+    !!block && typeof block === "object" &&
+    (block as { type?: unknown }).type === "artifact_ref" &&
+    !String((block as { mime_type?: unknown }).mime_type ?? "").startsWith("image/")
+  )
+  if (!needsReader) return false
+  if (ctx.tools.some((t) => t.function?.name === "artifact_read")) return false
+
+  const reader = ctx.allTools.find((t) => t.name === "artifact_read")
+  if (!reader) return false
+
+  ctx.tools.push({
+    type: "function",
+    function: {
+      name: reader.name,
+      description: (reader as any).description ?? "",
+      parameters: (reader as any).parameters ?? { type: "object", properties: {} },
+    },
+  } as LoadoutContext["tools"][number])
+  return true
+}
+
 /** Bounds a single async operation to its own timeout window, independent of any caller. */
 export async function withTimeout<T>(op: () => Promise<T>, timeoutMs: number): Promise<T> {
   let timer: ReturnType<typeof setTimeout>
@@ -171,6 +216,14 @@ export interface AgentLoopOptions {
   taskId?: string
   /** External routing/session id for progress delivery. */
   sessionId?: string
+  /**
+   * Credenciales del proveedor para ESTA llamada, en vez de las del proceso.
+   *
+   * Un host multi-tenant resuelve la key de su inquilino y la pasa acá. Sin esto
+   * la única fuente era el secret store de HiveDB o `process.env`, ambos globales:
+   * dos inquilinos concurrentes en el mismo proceso compartían credencial.
+   */
+  credentials?: ProviderCredentials
   /** Whether to resume from a previously saved checkpoint */
   resume?: boolean
   /** Run budget — overrides agent.max_iterations when set */
@@ -215,6 +268,8 @@ export interface StreamChunk {
   agent?: { messages: any[]; streamed?: boolean }
   tools?: { messages: any[] }
   usage?: { input_tokens: number; output_tokens: number }
+  /** Image artifacts (mcp-result-normalizer.ts) produced by tools this turn. */
+  artifacts?: { images: Array<{ artifactId: string; mimeType: string }> }
 }
 
 // ─── Main agent loop ──────────────────────────────────────────────────────────
@@ -280,7 +335,7 @@ export async function* runAgent(
     agentProvider = agentProvider || defaultLLM.provider
     agentModel = agentModel || defaultLLM.model
   }
-  const providerCfg = await resolveProviderConfig(agentProvider, agentModel)
+  const providerCfg = await resolveProviderConfig(agentProvider, agentModel, opts.credentials)
 
   const cleanModel = providerCfg.model.replace(new RegExp(`^${providerCfg.provider}\\/`), "")
   log.info(`[agent-loop] Starting: agent=${agentName} thread=${opts.threadId} provider=${providerCfg.provider}/${cleanModel}`)
@@ -360,6 +415,10 @@ export async function* runAgent(
   let iterations = 0
   let totalInputTokens = 0
   let totalOutputTokens = 0
+  // Image artifacts produced by tool results this turn (post mcp-result-normalizer.ts) —
+  // surfaced in the final chunk so callers (webchat-turn.ts) can attach them to the
+  // outbound message instead of the model having to describe them in text.
+  const turnImageArtifacts: Array<{ artifactId: string; mimeType: string }> = []
   let lastToolSignature = ""
   let consecutiveRepeat = 0
   let idleIterations = 0
@@ -452,7 +511,7 @@ export async function* runAgent(
     iterations++
 
     const delegationGroupAtCall = opts.turnId && !opts.isolated
-      ? await import("../gateway/delegation-groups").then((mod) => mod.getDelegationGroup(opts.turnId!))
+      ? await import("../gateway/delegation-groups.ts").then((mod) => mod.getDelegationGroup(opts.turnId!))
       : null
     let streamedThisCall = false
     let response: Awaited<ReturnType<typeof callLLM>>
@@ -648,6 +707,27 @@ export async function* runAgent(
       const toolResultJS = batchResult.result
       const toolMs = batchResult.durationMs
 
+      // Surface image artifacts (see mcp-result-normalizer.ts) so the final
+      // response can carry them to the UI/channel — before TOON-encoding,
+      // while toolResultJS is still structured.
+      if (Array.isArray(toolResultJS)) {
+        for (const block of toolResultJS) {
+          if (
+            block && typeof block === "object" &&
+            (block as { type?: unknown }).type === "artifact_ref" &&
+            typeof (block as { mime_type?: unknown }).mime_type === "string" &&
+            (block as { mime_type: string }).mime_type.startsWith("image/")
+          ) {
+            const ref = block as { artifact_id: string; mime_type: string }
+            turnImageArtifacts.push({ artifactId: ref.artifact_id, mimeType: ref.mime_type })
+          }
+        }
+      }
+
+      if (injectArtifactReadIfNeeded(toolResultJS, ctx)) {
+        log.info("[agent-loop] Tool result carries an artifact_ref — injected artifact_read into loadout")
+      }
+
       // Encode TOON only for LLM consumption (with cost calculation)
       const toolResultLLM = formatToolResult(toolResultJS, cleanModel)
 
@@ -812,7 +892,7 @@ export async function* runAgent(
           // Inject skills associated with the injected tools
           if (injectedTools.length > 0) {
             try {
-              const skillsCol = await col<import("../storage/collections").SkillDoc>("skills")
+              const skillsCol = await col<import("../storage/collections.ts").SkillDoc>("skills")
               // Find skills that use any of the injected tools
               const activeSkills = (await skillsCol.scan({})).filter(e => e.doc.active)
               const skillsWithTools = activeSkills
@@ -1032,7 +1112,7 @@ export async function* runAgent(
   // Make one extra call without tools so it summarizes what it did.
   if (!finalContent) {
     const pendingDelegation = opts.turnId && !opts.isolated
-      ? await import("../gateway/delegation-groups").then((mod) => mod.getDelegationGroup(opts.turnId!))
+      ? await import("../gateway/delegation-groups.ts").then((mod) => mod.getDelegationGroup(opts.turnId!))
       : null
     if (pendingDelegation) {
       log.info(`[agent-loop] Suppressing terminal synthesis while delegation group ${opts.turnId} is pending`)
@@ -1085,6 +1165,10 @@ export async function* runAgent(
     yield { usage: { input_tokens: totalInputTokens, output_tokens: totalOutputTokens } }
   }
 
+  if (turnImageArtifacts.length > 0) {
+    yield { artifacts: { images: turnImageArtifacts } }
+  }
+
   // ── Post-loop ────────────────────────────────────────────────────────────
   const durationMs = Math.round(performance.now() - t0)
 
@@ -1203,6 +1287,12 @@ export interface IsolatedAgentOptions {
   userId?: string
   channel?: string
   sessionId?: string
+  /**
+   * Se hereda del turno que delegó. Sin propagarla, un worker delegado volvía a
+   * caer en la credencial global del proceso y la fuga entre inquilinos se
+   * reabría justo en el camino de delegación.
+   */
+  credentials?: ProviderCredentials
 }
 
 export async function runAgentIsolatedDetailed(
@@ -1226,15 +1316,14 @@ export async function runAgentIsolatedDetailed(
     userId: opts.userId,
     channel: opts.channel,
     sessionId: opts.sessionId,
+    credentials: opts.credentials,
   })) {
     if (chunk.agent?.messages?.[0]?.content) {
       lastContent = chunk.agent.messages[0].content
     }
     for (const message of chunk.tools?.messages ?? []) {
       const raw = typeof message.content === "string" ? message.content : JSON.stringify(message.content)
-      const safe = raw
-        .replace(/data:[a-z0-9.+-]+\/[a-z0-9.+-]+;base64,[a-z0-9+/=\s]+/gi, "[REDACTED_BINARY]")
-        .replace(/[A-Za-z0-9+/]{1000,}={0,2}/g, "[REDACTED_BINARY]")
+      const safe = redactBinaryStrings(raw)
       toolEvidence.push(`${message.name ?? "tool"}: ${safe.slice(0, 4000)}`)
       if (toolEvidence.length > 8) toolEvidence.shift()
     }

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

@@ -19,8 +19,8 @@
  */
 
 import type { IndexDoc } from "@johpaz/hive-db";
-import { getHiveDb } from "../storage/hivedb";
-import { logger } from "../utils/logger";
+import { getHiveDb } from "../storage/hivedb.ts";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("capability-search");
 

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

@@ -1,12 +1,12 @@
-import { col } from "../storage/hive";
-import type { AgentDoc } from "../storage/collections";
+import { col } from "../storage/hive.ts";
+import type { AgentDoc } from "../storage/collections.ts";
 import {
   applyRelativeCutoff,
   replaceCapabilityDocs,
   searchCapabilities,
   type CapabilityDoc,
-} from "./capability-search";
-import { logger } from "../utils/logger";
+} from "./capability-search.ts";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("catalog-selector");
 const RELEVANCE_RATIO = 0.35;

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

@@ -15,7 +15,7 @@
  * short summaries in the in-memory message array before model calls.
  */
 
-import { logger } from "../utils/logger"
+import { logger } from "../utils/logger.ts"
 import {
   getTotalTokens,
   getHistory,
@@ -24,11 +24,13 @@ import {
   getMessageCount,
   isInternalSource,
   type StoredMessage,
-} from "./conversation-store"
-import { estimateTokens } from "../utils/toon"
-import { callLLM, resolveProviderConfig, getDefaultLLM, type ContentPart } from "./llm-client"
-import { col, fromIndexable } from "../storage/hive"
-import type { AgentDoc, ModelDoc } from "../storage/collections"
+} from "./conversation-store.ts"
+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)
 
@@ -118,7 +137,7 @@ export function renderTranscript(rows: StoredMessage[], maxMsgChars = MAX_MSG_CH
 /**
  * Compress a thread's history into a summary.
  */
-async function compactThread(
+export async function compactThread(
   threadId: string,
   notify?: { channel: string; userId: string }
 ): Promise<void> {
@@ -187,11 +206,12 @@ async function compactThread(
   // Notify user in their active channel (non-critical)
   if (notify?.channel && notify?.userId) {
     try {
-      const { sendToUserChannel } = await import("../gateway/channel-notify")
+      const { sendToUserChannel } = await import("../gateway/channel-notify.ts")
       await sendToUserChannel(
         notify.channel,
         notify.userId,
-        `🗜️ Resumí ${toSummarize.length} mensajes anteriores para mantener el contexto limpio.`
+        `🗜️ Resumí ${toSummarize.length} mensajes anteriores para mantener el contexto limpio.`,
+        { threadId }
       )
     } catch {
       // Non-critical — don't break the flow if notification fails