@johpaz/hive-sdk 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,172 @@
 # Changelog
 
+## Sin publicar
+
+### Seguridad
+
+- **La lista blanca de tools no se aplicaba al descubrimiento dinámico.**
+  `compileContext` sólo recortaba `allTools` cuando el agente era de catálogo
+  (`source === "catalog"`). Un agente creado por el usuario veía su loadout
+  inicial restringido, pero `search_knowledge` busca contra el índice completo y
+  el agent loop inyecta lo que encuentre resolviéndolo contra `allTools`: la
+  tool excluida terminaba siendo llamable igual. Ahora la restricción depende de
+  que el agente declare una lista, no de su origen. Cubierto por
+  `test/tool-allowlist-discovery.test.ts`.
+
+- **Aislamiento de credenciales entre inquilinos.** `AgentLoopOptions` no tenía
+  forma de recibir la key del proveedor, así que la única fuente era el secret
+  store de HiveDB o `process.env[PROVIDER_API_KEY]`, ambos globales al proceso.
+  Un host multi-tenant que corriera dos workspaces en el mismo proceso les daba
+  la misma credencial. Se agregó `credentials` en `AgentLoopOptions`,
+  `IsolatedAgentOptions` y `resolveProviderConfig`; la credencial de la llamada
+  gana y corta ahí, sin consultar las fuentes globales ni mutar `process.env`.
+  Retrocompatible: sin `credentials` el comportamiento es el de siempre.
+  Cubierto por `test/tenant-isolation.test.ts`.
+
+
+- **`sanitizeDiagnostic` dejaba el token en claro detrás del esquema de auth.**
+  La regex consumía sólo la palabra `Bearer`, así que un diagnóstico con
+  `authorization: Bearer <token>` quedaba como `authorization: [REDACTED] <token>`
+  y la credencial viajaba al prompt del coordinador. Afecta a **0.1.5 y
+  anteriores**: el archivo viaja en el tarball publicado.
+
+### Cambiado
+
+- **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)
+  el binario está y Chromium muere igual sin `--no-sandbox`, así que ~90 tests
+  de integración fallaban por el entorno. Como los tests son condición para
+  publicar, eso bloqueaba el release. Los describe unitarios de esos mismos
+  archivos —`resolveBackendKind`, detección de motor, `normalizeCookies`,
+  `sessionPersistenceEnabled`— siguen corriendo siempre: son los que cubren el
+  contrato del backend.
+
+- **Se quitó un `mock.module` que se filtraba entre archivos de test.** El test
+  de aislamiento multi-tenant sustituía el módulo `storage/crypto` para no
+  escribir en el keychain del SO. `mock.module` es global al proceso, no al
+  archivo: mientras estuviera activo, cualquier otro test que importara ese
+  módulo recibía el doble, y `loadProviderApiKey` devolvía la key del mock. Que
+  mordiera dependía del orden de ejecución — pasaba en local y fallaba en CI.
+  Ahora el test usa un id de proveedor propio (`test-tenant-isolation`) y limpia
+  sus secretos, sin tocar el módulo ni la credencial de nadie.
+
+- **`resetKeychainProbe()`** en `storage/crypto.ts`. Si el keychain del SO no
+  responde, el resultado se cachea a nivel de módulo para no reintentar en cada
+  lectura — correcto en producción, pero significa que el primer sondeo vale
+  para todo el proceso. Un test que sustituya `Bun.secrets` por un doble queda
+  cortocircuitado si algo ya sondeó y falló antes, que es lo que pasa en CI
+  headless.
+
+
+- **Automatización web: un solo backend, `Bun.WebView`.** Se retiró
+  `AgentBrowserBackend`, que hablaba con el CLI de agent-browser por
+  subproceso. El motivo no es de estilo: medido en Bun 1.4 el WebView **sí**
+  corre headless (Bun lanza Chromium con `--headless`), que era la única razón
+  por la que agent-browser seguía siendo el default. Lo que quedaba era su
+  costo — ~40 ms de `Bun.spawn` por operación contra ~0,3 ms, y ~88 MB con su
+  propia copia de Chrome.
+
+  Lo importante para quien consume el paquete: el backend viejo ejecutaba
+  **`bun add agent-browser@latest` en el entorno del consumidor**, al primer uso
+  de una browser tool. Una versión flotante bajada de npm en runtime, en
+  producción. Eso ya no existe.
+
+  Requisitos ahora: un Chromium instalado (o `BUN_CHROME_PATH`) y **Bun ≥ 1.4**,
+  declarado en `engines`. La clave de config `tools.browser.backend` sobrevive:
+  `"agent-browser"` se acepta, avisa una vez y usa el WebView, así que las
+  configuraciones viejas no se rompen.
+
+- **Sesión de navegador persistente** (`tools/web/browser-session.ts`). El
+  perfil de Chrome que abre Bun es efímero —su ruta lleva un hash que cambia
+  entre procesos— así que las cookies se guardan y restauran a mano. Sin esto
+  cada reinicio empezaba sin logins. Se controla con `tools.browser.persistSession`
+  (activo por defecto).
+
+- **Nueva tool `computer_use_task`**: operar el navegador mirando la pantalla
+  —clic por coordenadas, escribir, navegar— cuando no hay un selector CSS
+  estable (canvas, UIs generadas, visores embebidos).
+
+- CI actualizado a **Bun 1.4.0**, alineado con `hive`.
+
+### Añadido
+
+- **`@johpaz/hive-sdk/sessions`** — la conversación de un usuario como una sola
+  cosa. Hasta acá "sesión" estaba repartida entre `thread-store` (identidad),
+  `conversation-store` (mensajes), `run-store` (ejecución) y un `Map` en memoria
+  que moría con el proceso; no existía la consulta "qué sesiones tiene este
+  usuario". `Session` es una vista compuesta sobre las colecciones que ya
+  existían — no agrega una tercera persistencia — y `Session.id` ES el
+  `threadId`. Incluye `createSession`, `listSessions`, `appendMessage`,
+  `resumeSession`, `closeSession`/`reopenSession` y `deleteSession`.
+
+- **`@johpaz/hive-sdk/models`** — el seed de modelos con nombre propio. El
+  catálogo (18 proveedores, 110 modelos), las claves de modelo y el cálculo de
+  costo seguían viviendo bajo `storage/`; esto les da un punto de entrada sin
+  mover la implementación.
+
+- **Enjambre por roles** (`runRoleSwarm` en `@johpaz/hive-sdk/swarm`) —
+  orquestador/trabajadores con estrategias `sequential`, `parallel` y
+  `hierarchical`. Es la tercera forma de armar un enjambre, junto a la
+  delegación por catálogo y al DAG de tareas, y la única que expresa un enjambre
+  como *configuración persistida* en vez de un grafo conocido de antemano. No
+  persiste nada: `onMessage` es el punto de enganche del consumidor.
+
+- **`bun run drift`** (`scripts/check-drift.ts`) — compara los módulos del
+  cerebro contra `hive` y reporta qué falta y qué difiere, indicando de qué lado
+  está el avance. El SDK es la fuente de verdad pero nada lo garantizaba
+  estructuralmente: la última vez la divergencia llegó a compartir sólo 87 de
+  224 nombres de archivo.
+
+- **`test/exports-contract.test.ts`** — importa de verdad cada subpath declarado
+  en `exports`. Los deep-imports se han roto entre versiones sin aviso, y el
+  consumidor se defendía pineando la versión exacta.
+
+### Corregido
+
+- **`touchThread` perdía mensajes en el contador.** El incremento se calculaba
+  fuera del reintento de `updateDoc`, así que ante un conflicto de versión el
+  reintento volvía a escribir el valor viejo. Como `addMessage` la llama sin
+  esperarla, dos mensajes seguidos del mismo hilo bastaban para que el conteo se
+  quedara corto de forma permanente. Ahora el valor se recalcula dentro del
+  bucle.
+
+- **El paquete publicaba su propia suite de tests.** Sin campo `files`, el
+  tarball llevaba 329 archivos y 2.3 MB, incluidos `test/`, `docs/`, `scripts/`
+  y los `*.test.ts` que conviven con el código. Ahora son 260 archivos y 448 kB.
+
+- **`prepublish` no verificaba nada** (era un `echo`), y además es el hook
+  deprecado. Se reemplazó por `prepublishOnly` con typecheck + tests.
+
+- **Sintaxis TypeScript que ningún runtime salvo Bun puede procesar.** Las 5
+  *parameter properties* (`constructor(private x)`) rompían incluso el
+  type-stripping nativo de Node, y como las clases se re-exportan desde el barrel
+  raíz tumbaban cualquier import del paquete. Se reescribieron a mano, sin
+  cambiar la API, y se normalizaron 355 imports relativos a extensión `.ts`
+  explícita. El paquete sigue requiriendo Bun por el uso de `Bun.*` en 18
+  archivos del core — ahora documentado en el README.
+
+
+- Se fijaron las 8 dependencias que estaban en `latest` (`zod`, `discord.js`,
+  `grammy`, `@slack/bolt`, `@whiskeysockets/baileys`, `@modelcontextprotocol/sdk`,
+  `qrcode-terminal`, `@sapphire/snowflake`). Como `bun.lock` no se publica, cada
+  instalación resolvía `latest` de nuevo: el SDK ya estaba corriendo
+  `@slack/bolt` **5.0.0** mientras hive, con el mismo código de canales, corría
+  **4.7.x**. Ahora quedan alineados.
+
+### Añadido
+
+- **Backend de navegador intercambiable.** Las tools hablan con la interfaz
+  `BrowserBackend`; además del `agent-browser` de siempre (default, sin cambios)
+  hay un `WebViewBackend` sobre `Bun.WebView`, in-process, sin instalación de
+  ~75 MB ni descarga de Chrome. Se elige con `tools.browser.backend`
+  (`"agent-browser" | "webview" | "auto"`) o `HIVE_BROWSER_BACKEND`.
+- Cobertura de `acceptance-checks` (27 tests), del backend de navegador (27) y
+  del selector con tools registradas en runtime (6).
+- Workflow de CI: typecheck, tests, verificación de aislamiento de la base, y un
+  job que genera un scaffold con `create-app` y lo typechequea contra el SDK de
+  ese commit.
+
 ## 0.1.5
 
 Sincronización del SDK con el runtime de agentes de `hive`. **Trae rupturas de

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="docs/assets/logoblack.png" alt="Hive SDK" width="180" />
+</p>
+
 # @johpaz/hive-sdk
 
 > **Hive Agent Harness SDK** — construí, desplegá y escalá aplicaciones de agentes de IA, con soporte multi-canal, Bun Workers y orquestación en swarm.
@@ -26,6 +30,12 @@ Con Hive SDK no montas un agente desde cero: **enganchas tu lógica de negocio e
 
 ## Instalación
 
+> **Requiere Bun.** El paquete se publica como TypeScript y usa APIs de Bun
+> (`Bun.secrets`, `Bun.spawn`, Workers) en 18 archivos del core, así que no
+> corre sobre Node aunque se le apliquen los flags de type-stripping. Si tu
+> backend es Node, hoy la vía es un proceso Bun aparte; el build a JS que
+> levantaría esa restricción todavía no existe.
+
 ```bash
 # Instalar globalmente para el CLI
 bun install -g @johpaz/hive-sdk
@@ -212,4 +222,4 @@ npm view @johpaz/hive-sdk dist-tags   # verificar después del release
 
 ---
 
-*Hive SDK v0.1.5 — MIT*
+*Hive SDK v0.2.0 — MIT*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "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",
@@ -35,6 +35,8 @@
     "./tools": "./packages/core/src/tools/index.ts",
     "./skills": "./packages/core/src/skills/index.ts",
     "./storage": "./packages/core/src/storage/index.ts",
+    "./sessions": "./packages/core/src/sessions/index.ts",
+    "./models": "./packages/core/src/models/index.ts",
     "./swarm": "./packages/core/src/swarm/index.ts",
     "./swarm/strategies": "./packages/core/src/swarm/strategies/index.ts",
     "./swarm/presets": "./packages/core/src/swarm/presets/index.ts",
@@ -59,6 +61,19 @@
   "bin": {
     "hives": "./packages/cli/bin/hives"
   },
+  "files": [
+    "packages/core/src",
+    "packages/cli/bin",
+    "packages/cli/src",
+    "packages/cli/templates",
+    "!packages/**/*.test.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4.0"
+  },
   "workspaces": [
     "packages/core",
     "packages/cli"
@@ -70,22 +85,23 @@
     "skills:bundle": "bun scripts/generate-skill-bundle.ts",
     "version:set": "bun scripts/bump-version.ts",
     "release": "bun scripts/bump-version.ts --push",
-    "prepublish": "echo 'No build needed - Bun runs TypeScript directly'"
+    "prepublishOnly": "bun run typecheck && bun test",
+    "drift": "bun scripts/check-drift.ts"
   },
   "dependencies": {
     "@johpaz/hive-db": "^0.4.0",
     "@anthropic-ai/sdk": "^0.74.0",
     "@google/genai": "^1.43.0",
-    "@modelcontextprotocol/sdk": "latest",
-    "@sapphire/snowflake": "latest",
-    "@slack/bolt": "latest",
-    "@whiskeysockets/baileys": "latest",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@sapphire/snowflake": "^3.5.5",
+    "@slack/bolt": "^4.7.2",
+    "@whiskeysockets/baileys": "7.0.0-rc11",
     "async-mutex": "^0.5.0",
     "cron-parser": "^5.5.0",
     "croner": "^10.0.1",
-    "discord.js": "latest",
+    "discord.js": "^14.26.4",
     "docx": "^9.6.1",
-    "grammy": "latest",
+    "grammy": "^1.42.0",
     "groq-sdk": "^0.37.0",
     "jsonwebtoken": "^9.0.3",
     "jszip": "^3.10.1",
@@ -95,10 +111,10 @@
     "openai": "^6.18.0",
     "pdfjs-dist": "^5.6.205",
     "pptxgenjs": "^4.0.1",
-    "qrcode-terminal": "latest",
+    "qrcode-terminal": "^0.12.0",
     "toon-format-parser": "^1.1.0",
     "xlsx": "^0.18.5",
-    "zod": "latest"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/bun": "^1.3.13",

package/packages/core/src/agent/acceptance-checks.ts

@@ -13,13 +13,13 @@
  * to judge using this checks result plus the raw evidence.
  */
 
-import { col } from "../storage/hive";
-import type { AgentDoc } from "../storage/collections";
-import type { AcceptanceCriterion } from "./run-store";
-import { interpretCheckResult } from "./goal-runner";
-import { inspectArtifact } from "../artifacts/store";
-import { loadConfig } from "../config/loader";
-import { logger } from "../utils/logger";
+import { col } from "../storage/hive.ts";
+import type { AgentDoc } from "../storage/collections.ts";
+import type { AcceptanceCriterion } from "./run-store.ts";
+import { interpretCheckResult } from "./goal-runner.ts";
+import { inspectArtifact } from "../artifacts/store.ts";
+import { loadConfig } from "../config/loader.ts";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("acceptance-checks");
 
@@ -42,15 +42,21 @@ export interface AcceptanceChecks {
 
 export function sanitizeDiagnostic(value: string, limit = 1000): string {
   return value
-    .replace(/(api[_-]?key|token|authorization|secret)(["'=:\s]+)[^\s,}"']+/gi, "$1$2[REDACTED]")
+    .replace(
+      // El esquema de auth va aparte: sin el grupo opcional, "authorization:
+      // Bearer <token>" consumía sólo "Bearer" y dejaba el token en claro.
+      /(api[_-]?key|token|authorization|secret)(["'=:\s]+)(?:(bearer|basic)\s+)?[^\s,}"']+/gi,
+      (_match, key: string, separator: string, scheme?: string) =>
+        `${key}${separator}${scheme ? `${scheme} ` : ""}[REDACTED]`,
+    )
     .slice(0, limit);
 }
 
 async function runCheckTool(criterion: AcceptanceCriterion, objective: string): Promise<AcceptanceCheckResult | null> {
   if (!criterion.checkTool) return null;
   try {
-    const { executeToolBatch } = await import("../tool-runtime");
-    const { createAllTools } = await import("../tools/index");
+    const { executeToolBatch } = await import("../tool-runtime/index.ts");
+    const { createAllTools } = await import("../tools/index.ts");
     const allTools = createAllTools(loadConfig());
     const toolDef = allTools.find((t) => t.name === criterion.checkTool);
     if (!toolDef) {

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

@@ -3,9 +3,9 @@ import type {
   AgentAcceptanceCriterion,
   AgentModelOverride,
   AgentWorkspaceScope,
-} from "../storage/collections";
-import { col, toIndexable, fromIndexable } from "../storage/hive";
-import { expandToolAllowlist } from "./delegation-runtime";
+} from "../storage/collections.ts";
+import { col, toIndexable, fromIndexable } from "../storage/hive.ts";
+import { expandToolAllowlist } from "./delegation-runtime.ts";
 
 interface CatalogPersona {
   id: string;

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,11 @@ 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"
 
 const log = logger.child("compaction")
 
@@ -118,7 +118,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 +187,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