@johpaz/hive-sdk 0.1.5 → 0.2.0

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

@@ -21,27 +21,28 @@
  * TODOS los datos se formatean en TOON para ahorro de tokens.
  */
 
-import { col, fromIndexable } from "../storage/hive"
-import type { AgentDoc, ModelDoc } from "../storage/collections"
-import { logger } from "../utils/logger"
-import type { LLMMessage, LLMToolDef, ContentPart } from "./llm-client"
+import { col, fromIndexable } from "../storage/hive.ts"
+import type { AgentDoc, ModelDoc } from "../storage/collections.ts"
+import { logger } from "../utils/logger.ts"
+import type { LLMMessage, LLMToolDef, ContentPart } from "./llm-client.ts"
 import type { MCPClientManager } from "../mcp/index.ts"
-import { syncToolCatalogToIndex, mcpToolFullName } from "./tool-selector"
-import { syncSkillsToIndex, getMinimalSkills, selectSkills, getSkillByName, type SkillDescriptor } from "./skill-selector"
-import { syncPlaybookToIndex, selectPlaybookRules } from "./playbook-selector"
-import { getRecentMessages, getSummary, getScratchpad, toAPIMessages } from "./conversation-store"
-import { formatContext, estimateTokens } from "../utils/toon"
-import { buildSystemPromptWithProjects } from "./prompt-builder"
+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 { formatContext, estimateTokens } from "../utils/toon.ts"
+import { buildSystemPromptWithProjects } from "./prompt-builder.ts"
 import { createAllTools } from "../tools/index.ts"
-import { resolveUserId } from "../storage/onboarding"
-import { getMCPManager as getSingletonMCPManager } from "../mcp/singleton"
-import { syncMCPToolsToDB, syncMCPToolsToIndex } from "../mcp/tool-sync"
-import { getUserDate, getUserTime } from "../utils/date"
-import { loadConfig } from "../config/loader"
-import { getHiveDb } from "../storage/hivedb"
-import { listCatalogAgents, renderAgentRoutingCatalog } from "./catalog-selector"
-import { expandToolAllowlist } from "./delegation-runtime"
-import { MINIMAL_TOOLS } from "./minimal-loadout"
+import { resolveUserId } from "../storage/onboarding.ts"
+import { getMCPManager as getSingletonMCPManager } from "../mcp/singleton.ts"
+import { syncMCPToolsToDB, syncMCPToolsToIndex } from "../mcp/tool-sync.ts"
+import { getUserDate, getUserTime } from "../utils/date.ts"
+import { loadConfig } from "../config/loader.ts"
+import { getHiveDb } from "../storage/hivedb.ts"
+import { listCatalogAgents, renderAgentRoutingCatalog } from "./catalog-selector.ts"
+import { expandToolAllowlist } from "./delegation-runtime.ts"
+import { MINIMAL_TOOLS } from "./minimal-loadout.ts"
+import { normalizeMcpResult } from "./mcp-result-normalizer.ts"
 
 const log = logger.child("context-compiler")
 
@@ -238,7 +239,7 @@ export async function compileContext(opts: {
 
   if (effectiveMcpManager) {
     try {
-      const mcpServersCol = await col<import("../storage/collections").McpServerDoc>("mcpServers")
+      const mcpServersCol = await col<import("../storage/collections.ts").McpServerDoc>("mcpServers")
       const assignedMcpIds = new Set<string>([
         ...(agent.mcp_server_ids_json ? JSON.parse(agent.mcp_server_ids_json) : []),
         ...(agent.active_mcp_json ? JSON.parse(agent.active_mcp_json) : []),
@@ -293,10 +294,20 @@ export async function compileContext(opts: {
               name: fullName,
               description: mcpTool.description || `Tool from ${server.name}`,
               parameters: mcpTool.inputSchema || { type: "object", properties: {} },
-              execute: async (params: Record<string, unknown>) => {
+              execute: async (params: Record<string, unknown>, config?: { configurable?: Record<string, unknown> }) => {
                 // Return raw JS value — agent-loop will TOON-encode via formatToolResult.
                 // Never pre-stringify here: formatToolResult(string) double-encodes.
-                return await effectiveMcpManager.callTool(resolvedServerKey, mcpTool.name, params)
+                const raw = await effectiveMcpManager.callTool(resolvedServerKey, mcpTool.name, params)
+                // MCP results can carry base64 image/audio/blob content blocks —
+                // normalize those into artifact_ref pointers so a large binary
+                // result never gets serialized whole into the LLM context (see
+                // mcp-result-normalizer.ts for the incident this prevents).
+                const configurable = config?.configurable ?? {}
+                return await normalizeMcpResult(raw, {
+                  userId: configurable.user_id ? String(configurable.user_id) : undefined,
+                  runId: configurable.run_id ? String(configurable.run_id) : null,
+                  taskId: configurable.task_id ? String(configurable.task_id) : null,
+                })
               },
             })
 
@@ -352,17 +363,30 @@ export async function compileContext(opts: {
   // Only native minimal tools in LLM context
   // MCP tools are discovered dynamically via search_knowledge(type="mcp")
   let filteredNativeTools: ContextTool[] = nativeTools.filter(t => MINIMAL_TOOLS.has(t.name))
-  if (isCatalogAgent) {
-    const allowedNames = new Set<string>(
-      agent.tool_allowlist_json
-        ? expandToolAllowlist(
-          JSON.parse(agent.tool_allowlist_json),
-          nativeTools.map((tool) => tool.name),
-        )
-        : agent.tools_json
-          ? JSON.parse(agent.tools_json)
-          : [],
+
+  // La lista blanca se aplica a `allTools`, no sólo al prompt inicial. Filtrar
+  // únicamente el loadout de arranque no restringe nada: `search_knowledge`
+  // busca contra el índice completo y agent-loop.ts inyecta lo que encuentre
+  // resolviéndolo contra `allTools`, así que un agente restringido llegaba
+  // igual a cualquier tool nativa por descubrimiento dinámico. Sacarla de
+  // `allTools` la vuelve irresoluble: se puede encontrar en el índice, pero no
+  // se puede cargar ni llamar.
+  //
+  // Antes esto dependía de `isCatalogAgent`, y los agentes creados por el
+  // usuario —que son los que un host multi-tenant define— quedaban sin límite.
+  // Ahora depende de que el agente declare una lista: el coordinador, que no
+  // declara ninguna, conserva el descubrimiento abierto.
+  const declaredAllowlist = agent.tool_allowlist_json
+    ? expandToolAllowlist(
+      JSON.parse(agent.tool_allowlist_json),
+      nativeTools.map((tool) => tool.name),
     )
+    : agent.tools_json
+      ? (JSON.parse(agent.tools_json) as string[])
+      : null
+
+  if (declaredAllowlist) {
+    const allowedNames = new Set<string>(declaredAllowlist)
     filteredNativeTools = nativeTools.filter((tool) => allowedNames.has(tool.name))
     allTools = [...filteredNativeTools, ...mcpToolExecutors]
   }
@@ -508,7 +532,7 @@ export async function compileContext(opts: {
   }
 
   // [STEP-10b] Inject current date/time (ENTORNO ACTUAL)
-  const usersCol = await col<import("../storage/collections").UserDoc>("users")
+  const usersCol = await col<import("../storage/collections.ts").UserDoc>("users")
   const userRow = await usersCol.get(userId)
   const userTimezone = userRow?.doc.timezone || "UTC"
   const now = new Date()
@@ -585,7 +609,7 @@ export async function compileContext(opts: {
         .filter((line): line is string => !!line)
 
       if (causalLines.length > 0) {
-        systemPrompt += `\n\n# CAUSAL CONTEXT (decisiones y tool calls de este turno, previos a la compactación — priorizá la conversación actual; usalo solo para no repetir algo que ya funcionó o ya falló)\n${causalLines.join("\n")}\n`
+        systemPrompt += `\n\n# CAUSAL CONTEXT (decisiones y tool calls de este turno, previos a la compactación — prioriza la conversación actual; úsalo solo para no repetir algo que ya funcionó o ya falló)\n${causalLines.join("\n")}\n`
         log.info(`[context-compiler] [STEP-9d] ✅ Injected ${causalLines.length} causal context item(s)`)
       }
     } catch (err) {

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

@@ -5,12 +5,13 @@
  * Also manages: summaries and scratchpad, both HiveDB document collections.
  */
 
-import { col, nextId, bumpRollup } from "../storage/hive"
-import { getHiveDb } from "../storage/hivedb"
-import { logger } from "../utils/logger"
-import type { LLMMessage, ContentPart } from "./llm-client"
-import { estimateTokens } from "../utils/toon"
-import type { ConversationDoc, SummaryDoc, MessageSource } from "../storage/collections"
+import { col, nextId, bumpRollup } from "../storage/hive.ts"
+import { getHiveDb } from "../storage/hivedb.ts"
+import { logger } from "../utils/logger.ts"
+import type { LLMMessage, ContentPart } from "./llm-client.ts"
+import { estimateTokens } from "../utils/toon.ts"
+import type { ConversationDoc, SummaryDoc, MessageSource } from "../storage/collections.ts"
+import { touchThread } from "./thread-store.ts"
 
 const log = logger.child("conv-store")
 
@@ -45,13 +46,26 @@ export interface StoredMessage {
 // stays clean and the wording can evolve without a migration.
 
 export const INTERNAL_SOURCES: ReadonlySet<string> =
-  new Set(["task_complete", "delegation_summary", "legacy_internal"])
+  new Set(["task_complete", "delegation_summary", "legacy_internal", "realtime_chat"])
 
 export function isInternalSource(source: string | null | undefined): boolean {
   return !!source && INTERNAL_SOURCES.has(source)
 }
 
 export function formatInternalEvent(source: string, content: string): string {
+  // La charla hablada sí salió del usuario, pero la sesión de voz ya la
+  // respondió: es contexto, no trabajo por hacer. Sin esta distinción el
+  // coordinador leía cada frase suelta de una llamada como un pedido nuevo y
+  // delegaba una tarea por cada una.
+  if (source === "realtime_chat") {
+    return `<hive:voice_context>\n` +
+      `Fragmento de una conversación hablada que la voz de Hive YA respondió en el momento. ` +
+      `Es contexto de lo que vinieron hablando, NO un pedido pendiente: no ejecutes ni delegues nada por esto. ` +
+      `El trabajo real llega siempre como un mensaje aparte y explícito.\n\n` +
+      `${content}\n` +
+      `</hive:voice_context>`
+  }
+
   return `<hive:internal_event source="${source}">\n` +
     `Evento interno del sistema — NO es un mensaje del usuario. No lo cites literalmente, no expongas IDs internos (task_id, worker_id) ni JSON crudo. Respondé al usuario de forma natural y breve.\n\n` +
     `${content}\n` +
@@ -146,6 +160,16 @@ export async function addMessage(
   bumpRollup("activityRollups", hour, { messageCount: 1 }).catch(() => {})
   recentMessageTimestamps.push(now)
 
+  // Igual de opcional: el registro de conversaciones es el catálogo que alimenta la
+  // lista de la web (título, orden, contador). Se actualiza acá y no en cada llamador
+  // para que todo camino que escriba un mensaje —canales, webchat, API, voz— lo
+  // mantenga al día sin repetir la llamada.
+  touchThread(threadId, {
+    role,
+    text: textContent,
+    internal: isInternalSource(opts?.source),
+  }).catch(() => {})
+
   return seq
 }
 

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

@@ -13,8 +13,8 @@
  * (id="curator:lastReflection") instead of SQL's MAX(source_reflection_id).
  */
 
-import { logger } from "../utils/logger"
-import { col, nextId, toIndexable, fromIndexable } from "../storage/hive"
+import { logger } from "../utils/logger.ts"
+import { col, nextId, toIndexable, fromIndexable } from "../storage/hive.ts"
 import type {
   ReflectionDoc,
   PlaybookDoc,
@@ -22,7 +22,7 @@ import type {
   CursorDoc,
   AgentProposalDoc,
   TraceDoc,
-} from "../storage/collections"
+} from "../storage/collections.ts"
 
 const log = logger.child("curator")
 
@@ -149,7 +149,7 @@ async function curateAgentStructure(): Promise<void> {
     })
   }
 
-  const { syncCatalogAgentsToIndex } = await import("./catalog-selector")
+  const { syncCatalogAgentsToIndex } = await import("./catalog-selector.ts")
   await syncCatalogAgentsToIndex()
 }
 

package/packages/core/src/agent/delegation-runtime.ts

@@ -1,4 +1,4 @@
-import { col, toIndexable, fromIndexable, updateDoc } from "../storage/hive";
+import { col, toIndexable, fromIndexable, updateDoc } from "../storage/hive.ts";
 import type {
   AgentDoc,
   McpServerDoc,
@@ -6,11 +6,11 @@ import type {
   ProviderDoc,
   SkillDoc,
   AgentModelOverride,
-} from "../storage/collections";
-import { createAllTools } from "../tools";
-import { loadConfig } from "../config/loader";
+} from "../storage/collections.ts";
+import { createAllTools } from "../tools/index.ts";
+import { loadConfig } from "../config/loader.ts";
 import type { MCPClientManager } from "../mcp/index.ts";
-import { logger } from "../utils/logger";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("delegation-runtime");
 const MCP_IDLE_TTL_MS = 2 * 60_000;

package/packages/core/src/agent/goal-runner.ts

@@ -14,15 +14,15 @@
  * entire run (not per-turn). This prevents endless loops.
  */
 
-import { logger } from "../utils/logger";
-import { callLLM, type LLMMessage } from "./llm-client";
-import { createRun, type AcceptanceCriterion } from "./run-store";
-import { clearOldToolResults } from "./compaction";
-import { loadConfig } from "../config/loader";
+import { logger } from "../utils/logger.ts";
+import { callLLM, type LLMMessage } from "./llm-client.ts";
+import { createRun, type AcceptanceCriterion } from "./run-store.ts";
+import { clearOldToolResults } from "./compaction.ts";
+import { loadConfig } from "../config/loader.ts";
 import { getDurableQueue } from "../gateway/durable-queue.ts";
-import { recordLLMUsage } from "./tracer";
+import { recordLLMUsage } from "./tracer.ts";
 
-export type { AcceptanceCriterion } from "./run-store";
+export type { AcceptanceCriterion } from "./run-store.ts";
 
 export interface AcceptanceResult {
   id: string;
@@ -126,8 +126,8 @@ export async function runGoal(opts: GoalRunOptions): Promise<GoalRunResult> {
 /** Runs a deterministic goal_check_tool, no LLM involved. */
 async function runDeterministicCheck(checkTool: string, goal: string): Promise<{ met: boolean; reason: string } | 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 === checkTool);
     if (!toolDef) {

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

@@ -15,3 +15,4 @@ export * from "./run-store.ts";
 export * from "./service.ts";
 export * from "./skill-selector.ts";
 export * from "./tool-selector.ts";
+export * from "./realtime-providers/index.ts";

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,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class NvidiaProvider extends OpenAICompatBase {
   constructor() { super("nvidia") }

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,11 @@
-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"
 
 const log = logger.child("llm-client")
 
@@ -44,7 +44,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 }

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") }