@johpaz/hive-sdk 0.1.6 → 0.3.0

package/packages/core/src/agent/llm-client.ts

@@ -11,26 +11,26 @@
  * Public interface (LLMMessage, callLLM, resolveProviderConfig) is stable.
  */
 
-import { logger } from "../utils/logger"
-import { loadConfig } from "../config/loader"
-import { withRetry, isRetryableError, type RetryPolicy } from "../resilience/retry"
-import { GeminiProvider } from "./llm-providers/gemini"
-import { AnthropicProvider } from "./llm-providers/anthropic"
-import { OllamaProvider } from "./llm-providers/ollama"
-import { OpenAIProvider } from "./llm-providers/openai"
-import { GroqProvider } from "./llm-providers/groq"
-import { MistralProvider } from "./llm-providers/mistral"
-import { OpenRouterProvider } from "./llm-providers/openrouter"
-import { DeepSeekProvider } from "./llm-providers/deepseek"
-import { KimiProvider } from "./llm-providers/kimi"
-import { NvidiaProvider } from "./llm-providers/nvidia"
-import { QwenProvider } from "./llm-providers/qwen"
-import { MiniMaxProvider } from "./llm-providers/minimax"
-import { OpenCodeGoProvider } from "./llm-providers/opencode-go"
-import { HiveAgentsProvider } from "./llm-providers/hiveagents"
-import { ZaiProvider } from "./llm-providers/z-ai"
-import { ModelScopeProvider } from "./llm-providers/modelscope"
-import type { LLMProvider } from "./llm-providers/interface"
+import { logger } from "../utils/logger.ts"
+import { loadConfig } from "../config/loader.ts"
+import { withRetry, isRetryableError, type RetryPolicy } from "../resilience/retry.ts"
+import { GeminiProvider } from "./llm-providers/gemini.ts"
+import { AnthropicProvider } from "./llm-providers/anthropic.ts"
+import { OllamaProvider } from "./llm-providers/ollama.ts"
+import { OpenAIProvider } from "./llm-providers/openai.ts"
+import { GroqProvider } from "./llm-providers/groq.ts"
+import { MistralProvider } from "./llm-providers/mistral.ts"
+import { OpenRouterProvider } from "./llm-providers/openrouter.ts"
+import { DeepSeekProvider } from "./llm-providers/deepseek.ts"
+import { KimiProvider } from "./llm-providers/kimi.ts"
+import { NvidiaProvider } from "./llm-providers/nvidia.ts"
+import { QwenProvider } from "./llm-providers/qwen.ts"
+import { MiniMaxProvider } from "./llm-providers/minimax.ts"
+import { OpenCodeGoProvider } from "./llm-providers/opencode-go.ts"
+import { HiveAgentsProvider } from "./llm-providers/hiveagents.ts"
+import { ZaiProvider } from "./llm-providers/z-ai.ts"
+import { ModelScopeProvider } from "./llm-providers/modelscope.ts"
+import type { LLMProvider } from "./llm-providers/interface.ts"
 
 const log = logger.child("llm-client")
 
@@ -182,20 +182,55 @@ export async function callLLM(options: LLMCallOptions): Promise<LLMResponse> {
     const cleanModel = options.model.replace(new RegExp(`^${options.provider}\\/`), "")
     const status = extractErrorStatus(err)
     const modelUnavailable = status === 404 || status === 410
-    const msg = modelUnavailable
-      ? `El modelo "${cleanModel}" ya no existe en ${options.provider} (HTTP ${status}). `
-        + `El proveedor lo retiró de su catálogo; reintentar no sirve. `
-        + `Elegí otro modelo en Ajustes → Proveedores.`
-      : (err as Error).message
+    const msg = describeProviderFailure(err, status, options.provider, cleanModel)
     log.error(`[llm-client] Error calling ${options.provider}/${cleanModel}: ${msg}`, err)
     return {
-      content: `[LLM Error] ${msg}`,
+      content: `${LLM_ERROR_PREFIX} ${msg}`,
       stop_reason: "error",
       error: { message: msg, status, modelUnavailable },
     }
   }
 }
 
+/**
+ * Marks content that is a provider failure rather than something the agent
+ * said. webchat-turn.ts keys the failed-turn UI off this prefix, and
+ * agent-loop.ts keeps such content out of the conversation history.
+ */
+export const LLM_ERROR_PREFIX = "[LLM Error]"
+
+/**
+ * Turns a provider failure into something the user can act on.
+ *
+ * The raw SDK text is written for whoever is reading a stack trace: "429 status
+ * code (no body)" showed up verbatim in the chat and says nothing about what
+ * happened (the account hit its rate limit) or what to do about it. Statuses
+ * without a specific mapping keep the original message — a wrong explanation is
+ * worse than a technical one.
+ */
+export function describeProviderFailure(
+  err: unknown,
+  status: number | undefined,
+  provider: string,
+  cleanModel: string,
+): string {
+  if (status === 404 || status === 410) {
+    return `El modelo "${cleanModel}" ya no existe en ${provider} (HTTP ${status}). `
+      + `El proveedor lo retiró de su catálogo; reintentar no sirve. `
+      + `Elige otro modelo en Ajustes → Proveedores.`
+  }
+  if (status === 429) {
+    return `${provider} está limitando las peticiones (HTTP 429) y los reintentos tampoco pasaron. `
+      + `Es el límite de uso de tu cuenta, no un problema del modelo: esperá unos minutos, `
+      + `revisa tu cuota con el proveedor, o cambiá de modelo en Ajustes → Proveedores.`
+  }
+  if (status === 401 || status === 403) {
+    return `${provider} rechazó la API key (HTTP ${status}). `
+      + `Revisa que siga siendo válida y tenga acceso a "${cleanModel}" en Ajustes → Proveedores.`
+  }
+  return (err as Error).message
+}
+
 /** Provider SDKs disagree on where the HTTP status lands; check every shape we've seen. */
 function extractErrorStatus(err: unknown): number | undefined {
   const e = err as { status?: number; statusCode?: number; response?: { status?: number } }
@@ -208,10 +243,10 @@ function extractErrorStatus(err: unknown): number | undefined {
  * Returns null when the DB has no usable LLM (e.g. fresh install before setup).
  */
 export async function getDefaultLLM(): Promise<{ provider: string; model: string } | null> {
-  const { col, fromIndexable } = await import("../storage/hive")
-  const agentsCol = await col<import("../storage/collections").AgentDoc>("agents")
-  const modelsCol = await col<import("../storage/collections").ModelDoc>("models")
-  const providersCol = await col<import("../storage/collections").ProviderDoc>("providers")
+  const { col, fromIndexable } = await import("../storage/hive.ts")
+  const agentsCol = await col<import("../storage/collections.ts").AgentDoc>("agents")
+  const modelsCol = await col<import("../storage/collections.ts").ModelDoc>("models")
+  const providersCol = await col<import("../storage/collections.ts").ProviderDoc>("providers")
 
   const coordinators = await agentsCol.findBy("role", "coordinator")
   const coordinator = coordinators[0]
@@ -234,14 +269,34 @@ export async function getDefaultLLM(): Promise<{ provider: string; model: string
 /**
  * Resolve provider config from DB (decrypts API key).
  */
+/**
+ * Credenciales y endpoint resueltos por quien llama, en vez de por el proceso.
+ *
+ * Sin esto, la única forma de elegir la key era el secret store de HiveDB o
+ * `process.env[PROVIDER_API_KEY]` — ambos globales al proceso. Un backend
+ * multi-tenant no tiene un proceso por inquilino: o mutaba `process.env` antes
+ * de cada llamada (y entonces dos workspaces concurrentes se pisaban la key), o
+ * levantaba un proceso por llamada sólo para aislarla. Pasar la credencial en la
+ * llamada elimina las dos cosas.
+ *
+ * Todo es opcional: lo que no venga acá se resuelve como siempre.
+ */
+export interface ProviderCredentials {
+  /** Reemplaza la key del secret store y la de `process.env`. */
+  apiKey?: string
+  /** Reemplaza el `base_url` de la fila del proveedor. */
+  baseUrl?: string
+}
+
 export async function resolveProviderConfig(
   providerId: string,
-  modelId: string
+  modelId: string,
+  credentials?: ProviderCredentials
 ): Promise<Pick<LLMCallOptions, "provider" | "model" | "apiKey" | "baseUrl" | "numCtx" | "numGpu" | "contextWindow">> {
-  const { col } = await import("../storage/hive")
-  const { loadProviderApiKey } = await import("../storage/crypto")
-  const providersCol = await col<import("../storage/collections").ProviderDoc>("providers")
-  const modelsCol = await col<import("../storage/collections").ModelDoc>("models")
+  const { col } = await import("../storage/hive.ts")
+  const { loadProviderApiKey } = await import("../storage/crypto.ts")
+  const providersCol = await col<import("../storage/collections.ts").ProviderDoc>("providers")
+  const modelsCol = await col<import("../storage/collections.ts").ModelDoc>("models")
 
   const providerEntry = await providersCol.get(providerId)
   const providerRow = (providerEntry?.doc.enabled && providerEntry?.doc.active) ? providerEntry.doc : undefined
@@ -249,7 +304,13 @@ export async function resolveProviderConfig(
   // Load model's context window for token budget management
   const modelEntry = await modelsCol.get(modelId)
 
-  let apiKey = await loadProviderApiKey(providerId)
+  // La credencial de la llamada gana, y corta acá: si vino una key explícita no
+  // se consulta el secret store ni el entorno, así que un fallback global no
+  // puede colarse en el lugar de la del inquilino.
+  let apiKey = credentials?.apiKey
+  if (!apiKey) {
+    apiKey = await loadProviderApiKey(providerId)
+  }
   if (!apiKey) {
     apiKey = process.env[`${providerId.toUpperCase()}_API_KEY`] || ""
   }
@@ -258,7 +319,7 @@ export async function resolveProviderConfig(
     provider: providerId,
     model: modelId,
     apiKey,
-    baseUrl: providerRow?.base_url || undefined,
+    baseUrl: credentials?.baseUrl || providerRow?.base_url || undefined,
     numCtx: providerRow?.num_ctx ?? undefined,
     numGpu: providerRow?.num_gpu ?? undefined,
     contextWindow: modelEntry?.doc.context_window ?? undefined,

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

@@ -1,7 +1,7 @@
-import { logger } from "../../utils/logger"
-import { normalizeToolName, resolveMaxTokens, ensureArrayItems } from "./interface"
-import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall, ThinkingBlock } from "./interface"
-import type { ContentPart, LLMMessage } from "../llm-client"
+import { logger } from "../../utils/logger.ts"
+import { normalizeToolName, resolveMaxTokens, ensureArrayItems } from "./interface.ts"
+import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall, ThinkingBlock } from "./interface.ts"
+import type { ContentPart, LLMMessage } from "../llm-client.ts"
 
 const log = logger.child("llm-client")
 

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

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class DeepSeekProvider extends OpenAICompatBase {
   constructor() { super("deepseek") }

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

@@ -1,7 +1,7 @@
-import { logger } from "../../utils/logger"
-import { sanitizeMessages, resolveMaxTokens, ensureArrayItems } from "./interface"
-import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall } from "./interface"
-import type { ContentPart, LLMMessage } from "../llm-client"
+import { logger } from "../../utils/logger.ts"
+import { sanitizeMessages, resolveMaxTokens, ensureArrayItems } from "./interface.ts"
+import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall } from "./interface.ts"
+import type { ContentPart, LLMMessage } from "../llm-client.ts"
 
 const log = logger.child("llm-client")
 

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

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class GroqProvider extends OpenAICompatBase {
   constructor() { super("groq") }

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

@@ -1,6 +1,6 @@
-import { logger } from "../../utils/logger"
-import { OpenAICompatBase } from "./openai-compat-base"
-import type { LLMCallOptions, LLMResponse } from "./interface"
+import { logger } from "../../utils/logger.ts"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
+import type { LLMCallOptions, LLMResponse } from "./interface.ts"
 
 const log = logger.child("llm-client")
 

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

@@ -2,10 +2,10 @@
  * Shared types and utilities for LLM providers.
  */
 
-import type { LLMCallOptions, LLMMessage, LLMResponse, LLMToolCall, ContentPart, ThinkingBlock } from "../llm-client"
+import type { LLMCallOptions, LLMMessage, LLMResponse, LLMToolCall, ContentPart, ThinkingBlock } from "../llm-client.ts"
 export type { LLMCallOptions, LLMMessage, LLMResponse, LLMToolCall, ContentPart, ThinkingBlock }
 
-import { logger } from "../../utils/logger"
+import { logger } from "../../utils/logger.ts"
 const log = logger.child("llm-client")
 
 // ─── Provider interface ────────────────────────────────────────────────────────

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

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class KimiProvider extends OpenAICompatBase {
   constructor() { super("kimi") }

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

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class MiniMaxProvider extends OpenAICompatBase {
   static readonly secretKey = "MINIMAX_API_KEY"

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

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class MistralProvider extends OpenAICompatBase {
   constructor() { super("mistral") }

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

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class ModelScopeProvider extends OpenAICompatBase {
   constructor() { super("modelscope") }

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

@@ -1,5 +1,44 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+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/ollama.ts

@@ -1,7 +1,7 @@
-import { logger } from "../../utils/logger"
-import { sanitizeMessages, resolveMaxTokens, ensureArrayItems } from "./interface"
-import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall } from "./interface"
-import type { ContentPart, LLMMessage } from "../llm-client"
+import { logger } from "../../utils/logger.ts"
+import { sanitizeMessages, resolveMaxTokens, ensureArrayItems } from "./interface.ts"
+import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall } from "./interface.ts"
+import type { ContentPart, LLMMessage } from "../llm-client.ts"
 
 const log = logger.child("llm-client")
 

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

@@ -1,11 +1,37 @@
-import { logger } from "../../utils/logger"
+import { logger } from "../../utils/logger.ts"
 import {
   sanitizeMessages, requiresTemperature1, OPENAI_COMPAT_BASE_URLS,
   getProviderProfile, modelSupportsTools, normalizeToolName, normalizeToolSchema,
   resolveMaxTokens,
-} from "./interface"
-import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall } from "./interface"
-import type { ContentPart, LLMMessage } from "../llm-client"
+} from "./interface.ts"
+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")
 
@@ -44,7 +70,11 @@ function compactBodyForContextOverflow(body: any, err: any): void {
 }
 
 export abstract class OpenAICompatBase implements LLMProvider {
-  constructor(protected readonly providerName: string) {}
+  protected readonly providerName: string
+
+  constructor(providerName: string) {
+    this.providerName = providerName
+  }
 
   /** Override to true when the provider requires reasoning_content to be round-tripped. */
   protected needsReasoningRoundtrip(): boolean { return false }
@@ -183,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
@@ -254,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/llm-providers/openai.ts

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class OpenAIProvider extends OpenAICompatBase {
   constructor() { super("openai") }

package/packages/core/src/agent/llm-providers/opencode-go.ts

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class OpenCodeGoProvider extends OpenAICompatBase {
   static readonly secretKey = "OPENCODE_GO_API_KEY"

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

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class OpenRouterProvider extends OpenAICompatBase {
   constructor() { super("openrouter") }

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

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class QwenProvider extends OpenAICompatBase {
   constructor() { super("qwen") }

package/packages/core/src/agent/llm-providers/z-ai.ts

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class ZaiProvider extends OpenAICompatBase {
   constructor() { super("z-ai") }

package/packages/core/src/agent/mcp-result-normalizer.ts

@@ -0,0 +1,192 @@
+/**
+ * mcp-result-normalizer — keeps large/binary MCP tool results out of the LLM
+ * context window.
+ *
+ * `MCPClientManager.callTool()` (packages/mcp/src/manager.ts) returns the raw
+ * `content` array from the MCP SDK's CallToolResult. Per the MCP spec that
+ * array can contain `image`/`audio` blocks (base64 `data`) or `resource`
+ * blocks (base64 `blob`) alongside plain `text` blocks. Nothing downstream
+ * (agent-loop.ts's formatToolResult) inspects those blocks — a base64 image
+ * would be serialized whole into a `role:"tool"` message and sent to the
+ * model, which is exactly what filled the context window and hung the agent
+ * in the incident this module fixes.
+ *
+ * This mirrors the pattern already used by browser-screenshot.ts: binary
+ * content gets persisted via createArtifact() (artifacts/store.ts) and the
+ * model only ever sees a lightweight { type: "artifact_ref", ... } reference.
+ */
+
+import { createArtifact } from "../artifacts/store.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("mcp-result-normalizer");
+
+/** Blocks longer than this (in chars) get materialized as a text artifact instead of inlined. Override via HIVE_MCP_INLINE_MAX_CHARS. */
+const MCP_INLINE_MAX_CHARS = Number(process.env.HIVE_MCP_INLINE_MAX_CHARS) || 20_000;
+
+export interface McpNormalizeContext {
+  userId?: string;
+  runId?: string | null;
+  taskId?: string | null;
+}
+
+type McpContentBlock = Record<string, unknown> & { type?: unknown };
+
+function isBinaryBlock(block: McpContentBlock): block is McpContentBlock & { type: "image" | "audio"; data: string; mimeType: string } {
+  return (block.type === "image" || block.type === "audio") && typeof block.data === "string";
+}
+
+function isBlobResourceBlock(block: McpContentBlock): block is McpContentBlock & { type: "resource"; resource: { blob: string; mimeType?: string; uri?: string } } {
+  if (block.type !== "resource") return false;
+  const resource = block.resource as Record<string, unknown> | undefined;
+  return !!resource && typeof resource.blob === "string";
+}
+
+function isOversizedTextBlock(block: McpContentBlock): block is McpContentBlock & { type: "text"; text: string } {
+  return block.type === "text" && typeof block.text === "string" && block.text.length > MCP_INLINE_MAX_CHARS;
+}
+
+async function materializeBinary(
+  bytesBase64: string,
+  mimeType: string,
+  kind: string,
+  ctx: McpNormalizeContext,
+): Promise<Record<string, unknown>> {
+  if (!ctx.userId) {
+    // Without a user_id we can't set ownership on the artifact (inspectArtifact
+    // would reject any read against it later) — never let raw base64 through,
+    // just describe what was omitted.
+    const approxBytes = Math.floor((bytesBase64.length * 3) / 4);
+    log.warn(`[materializeBinary] No user_id in tool context — omitting ${mimeType} block (${approxBytes} bytes) instead of creating an artifact`);
+    return { type: "artifact_omitted", mime_type: mimeType, approx_size: approxBytes, reason: "no user_id in tool context" };
+  }
+
+  const bytes = Buffer.from(bytesBase64, "base64");
+  const artifact = await createArtifact({
+    bytes,
+    mimeType,
+    kind,
+    userId: ctx.userId,
+    runId: ctx.runId ?? null,
+    taskId: ctx.taskId ?? null,
+  });
+  log.info(`[materializeBinary] Stored ${kind} as artifact ${artifact.id} (${artifact.size} bytes, ${artifact.mime_type})`);
+  return {
+    type: "artifact_ref",
+    artifact_id: artifact.id,
+    mime_type: artifact.mime_type,
+    size: artifact.size,
+    sha256: artifact.sha256,
+    expires_at: artifact.expires_at,
+  };
+}
+
+/** Above this, parsing the text just to describe it costs more than it explains. */
+const MAX_SHAPE_PROBE_CHARS = 5_000_000;
+
+/**
+ * Describes the shape of a JSON payload so the model can aim `artifact_read`
+ * instead of paging blind.
+ *
+ * The 500-char preview alone is close to useless on the payload this was
+ * written for — a Gmail MCP result where the first message's `received`
+ * headers eat the whole window before a single subject line appears. Knowing
+ * "12 items, keyed id/threadId/labelIds/headers" is what turns a search into
+ * one call.
+ */
+function describeJsonShape(text: string): Record<string, unknown> {
+  if (text.length > MAX_SHAPE_PROBE_CHARS) return {};
+  const trimmed = text.trimStart();
+  if (!trimmed.startsWith("[") && !trimmed.startsWith("{")) return {};
+
+  try {
+    const parsed = JSON.parse(text);
+    if (Array.isArray(parsed)) {
+      const first = parsed.find((item) => item && typeof item === "object" && !Array.isArray(item));
+      return {
+        json_items: parsed.length,
+        ...(first ? { json_item_keys: Object.keys(first as Record<string, unknown>).slice(0, 25) } : {}),
+      };
+    }
+    if (parsed && typeof parsed === "object") {
+      return { json_keys: Object.keys(parsed as Record<string, unknown>).slice(0, 25) };
+    }
+  } catch {
+    // Not JSON, or truncated JSON — the plain preview still stands.
+  }
+  return {};
+}
+
+async function materializeText(text: string, ctx: McpNormalizeContext): Promise<Record<string, unknown>> {
+  if (!ctx.userId) {
+    log.warn(`[materializeText] No user_id in tool context — truncating oversized text block (${text.length} chars) instead of creating an artifact`);
+    return { type: "text", text: `${text.slice(0, 500)}… [truncated: ${text.length} chars total, no user_id to persist full text as artifact]` };
+  }
+
+  const artifact = await createArtifact({
+    bytes: Buffer.from(text, "utf-8"),
+    mimeType: "text/plain",
+    kind: "mcp_text_result",
+    userId: ctx.userId,
+    runId: ctx.runId ?? null,
+    taskId: ctx.taskId ?? null,
+  });
+  log.info(`[materializeText] Stored oversized text result as artifact ${artifact.id} (${artifact.size} bytes)`);
+  return {
+    type: "artifact_ref",
+    artifact_id: artifact.id,
+    mime_type: "text/plain",
+    size: artifact.size,
+    chars: text.length,
+    preview: text.length > 500 ? `${text.slice(0, 500)}…` : text,
+    ...describeJsonShape(text),
+    // Without this the model only knows the data exists somewhere. It used to
+    // reach for artifact_inspect (metadata only), find nothing usable, and
+    // spend its remaining iterations guessing.
+    hint: "Full content is available via artifact_read (artifactId + offset/limit, or search).",
+  };
+}
+
+/**
+ * Normalizes a raw MCP CallToolResult.content array: binary blocks (image,
+ * audio, resource-with-blob) become { type: "artifact_ref", ... }, oversized
+ * text blocks are persisted the same way with a short preview kept inline,
+ * everything else (text, resource_link) passes through unchanged.
+ *
+ * Never pre-stringifies — returns JS values so formatToolResult (toon.ts)
+ * keeps doing the actual TOON/JSON encoding, same contract context-compiler.ts
+ * already documents for MCP tool executors.
+ */
+export async function normalizeMcpResult(content: unknown, ctx: McpNormalizeContext): Promise<unknown> {
+  if (!Array.isArray(content)) return content;
+
+  const out: unknown[] = [];
+  for (const raw of content) {
+    if (!raw || typeof raw !== "object") {
+      out.push(raw);
+      continue;
+    }
+    const block = raw as McpContentBlock;
+    try {
+      if (isBinaryBlock(block)) {
+        out.push(await materializeBinary(block.data, block.mimeType, "mcp_result", ctx));
+        continue;
+      }
+      if (isBlobResourceBlock(block)) {
+        const mimeType = block.resource.mimeType || "application/octet-stream";
+        out.push(await materializeBinary(block.resource.blob, mimeType, "mcp_result", ctx));
+        continue;
+      }
+      if (isOversizedTextBlock(block)) {
+        out.push(await materializeText(block.text, ctx));
+        continue;
+      }
+    } catch (err) {
+      log.error(`[normalizeMcpResult] Failed to materialize block (type=${String(block.type)}): ${(err as Error).message}`);
+      out.push({ type: "artifact_error", mime_type: (block as { mimeType?: string }).mimeType, error: (err as Error).message });
+      continue;
+    }
+    out.push(block);
+  }
+  return out;
+}