@johpaz/hive-sdk 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.5.1
+
+### Seguridad — claves aisladas por inquilino
+
+- **Secretos filtrados entre inquilinos por la caché en memoria.** El
+  almacén de secretos cacheaba cada valor descifrado en un `Map` del proceso
+  indexado sólo por nombre (`provider:openai:api_key`), y el llavero del SO
+  también es de toda la máquina. La colección `secrets` sí está particionada,
+  pero la caché la tapaba: después de que un inquilino leyera o guardara su
+  clave, `loadProviderApiKey` le devolvía esa misma clave a cualquier otro
+  inquilino del proceso, y `resolveProviderConfig` la usaba para cobrarle a
+  la cuenta equivocada cuando la llamada no traía `credentials`. Ahora la
+  caché se indexa por inquilino y, con un inquilino activo, el llavero del SO
+  no se lee, no se escribe ni se borra. Sin inquilino (escritorio) todo sigue
+  igual.
+- **La clave del entorno ya no se usa en nombre de un inquilino.** Con un
+  inquilino activo y sin `credentials` ni clave guardada, `resolveProviderConfig`
+  caía en `<PROVEEDOR>_API_KEY` del proceso, que es la cuenta de la plataforma;
+  lo mismo OCR (`vision-service`), voz (STT/TTS), `computer_use` y Jev. Ahora
+  todos pasan por `envSecret(nombre)`, que dentro de un inquilino devuelve
+  `undefined`. Los adaptadores de Anthropic, Gemini y Gemini Live pasan siempre
+  una cadena al SDK del proveedor, porque con `undefined` esos SDK leían la
+  variable de entorno por su cuenta. **Cambio de comportamiento:** un host
+  multi-inquilino que dependía de ese respaldo tiene que pasar la clave en
+  `credentials` o guardarla en los secretos del inquilino; sin eso la llamada
+  falla por falta de clave en vez de cobrarse a la plataforma. Sin inquilino
+  (escritorio) el entorno sigue siendo el último respaldo.
+- Nuevo `envSecret(nombre)` en `@johpaz/hive-sdk/storage`: la variable de
+  entorno sólo fuera de un inquilino. Úsalo en tus propias tools en lugar de
+  `process.env.X_API_KEY`.
+- Quitado `loadDurableProviderApiKey` (interno, agregado en 0.5.0 y nunca
+  exportado por un barrel): `loadProviderApiKey` ya es seguro por inquilino.
+
 ## 0.5.0
 
 ### Jev — plano de decisión (OpenRouter Decisions)

package/README.md

@@ -25,6 +25,8 @@ bun add @johpaz/hive-sdk
 - **Runtime**: ejecución paralela de tools vía Bun Workers.
 - **Gateway**: servidor HTTP/WebSocket para exponer agentes como API.
 - **Memoria y estado**: HiveDB (colecciones + índice BM25), scratchpad, context compiler con compactación.
+- **Jev (opcional)**: plano de decisión sobre la API Decisions de OpenRouter. Por turno elige qué historial, tools, skills, notas y reglas entran al contexto, poda resultados viejos entre iteraciones y decide si un lote de tools corre en paralelo. Sin clave de OpenRouter no existe y todo corre igual. Ver [API-AGENTS.md](./docs/API-AGENTS.md#jev-plano-de-decisión).
+- **Multi-inquilino**: varios enjambres en una sola HiveDB con `runInTenant`; credenciales y clave de Jev por llamada (`credentials`, `jev`), sin que la clave de un inquilino ni la de la plataforma se usen en nombre de otro.
 - **Servicios**: CRUD tipado de agentes, enjambres, skills, modelos, MCP y cron para montarle **la interfaz que quieras** — móvil, web o escritorio. Ver [API-SERVICES.md](./docs/API-SERVICES.md).
 - **Sesiones**: un hilo por canal y por contacto, con historial, resumen y reanudación tras un corte.
 - **Imágenes**: redimensionar y convertir con `Bun.Image`, sin dependencias nativas. Las imágenes entrantes se normalizan antes de llegar al modelo — una foto de cámara pasa de 217 KB a 4 KB.
@@ -197,7 +199,10 @@ capturar. El SDK lo resuelve con `resolvePort`: avisa y sigue con el default.
 
 La API key de cada provider se guarda cifrada en la base. Como alternativa, el
 SDK cae a `<PROVIDER>_API_KEY` del entorno, en mayúsculas y con el id del
-provider tal cual:
+provider tal cual. **Sólo sin inquilino** (app de escritorio, un proceso por
+instalación): dentro de `runInTenant` el entorno es de la plataforma, no del
+cliente, y no se usa nunca — la clave llega en `credentials` o desde los
+secretos del inquilino. Ver [UPGRADING.md](./docs/UPGRADING.md#051-claves-aisladas-por-inquilino).
 
 ```bash
 OPENAI_API_KEY=sk-...
@@ -205,7 +210,7 @@ ANTHROPIC_API_KEY=sk-ant-...
 GOOGLE_API_KEY=...            # provider "gemini"
 MODELSCOPE_API_KEY=ms-...
 NVIDIA_API_KEY=nvapi-...
-OPENROUTER_API_KEY=sk-or-...
+OPENROUTER_API_KEY=sk-or-...  # también activa Jev (con el provider openrouter habilitado)
 ```
 
 ## Tests
@@ -260,7 +265,7 @@ npm view @johpaz/hive-sdk dist-tags   # verificar después del release
 
 | Documento | Descripción |
 |-----------|-------------|
-| [API-AGENTS.md](docs/API-AGENTS.md) | createAgent, AgentLoop, Tool/Skill Selector, los 16 LLM Providers |
+| [API-AGENTS.md](docs/API-AGENTS.md) | createAgent, AgentLoop, Tool/Skill Selector, los 16 LLM Providers, multi-inquilino y Jev |
 | [API-CONTEXT-COMPILER.md](docs/API-CONTEXT-COMPILER.md) | Context Compiler, historial, Scratchpad, EthicsGuard, ACE |
 | [API-TOOLS-SKILLS-CHANNELS.md](docs/API-TOOLS-SKILLS-CHANNELS.md) | Tools, Skills, MCP, Gateway, Channels, Tool Runtime, Storage |
 | [API-DAG-SCHEDULER.md](docs/API-DAG-SCHEDULER.md) | DAGScheduler, TaskGraph, TaskNode, estrategias, presets |
@@ -271,4 +276,4 @@ npm view @johpaz/hive-sdk dist-tags   # verificar después del release
 
 ---
 
-*Hive SDK v0.5.0 — MIT*
+*Hive SDK v0.5.1 — MIT*

package/docs/API-AGENTS.md

@@ -7,6 +7,8 @@
 3. [Tool Selector](#tool-selector)
 4. [Skill Selector](#skill-selector)
 5. [LLM Providers](#llm-providers)
+6. [Multi-inquilino: credenciales y Jev](#multi-inquilino-credenciales-y-jev)
+7. [Jev: plano de decisión](#jev-plano-de-decisión)
 
 ---
 
@@ -240,6 +242,74 @@ const result = await runAgentIsolated({
 });
 ```
 
+### Multi-inquilino: credenciales y Jev
+
+Un host que sirve a varios clientes desde un mismo proceso corre cada turno
+dentro de `runInTenant(tenantKey, …)` y pasa las claves **por llamada**:
+
+```typescript
+import { runAgent } from "@johpaz/hive-sdk";
+import { runInTenant } from "@johpaz/hive-sdk/storage";
+
+await runInTenant(tenantKey, async () => {
+  for await (const chunk of runAgent({
+    agentId, threadId, userMessage,
+    credentials: { apiKey: claveDelModelo, baseUrl },     // gana y corta ahí
+    jev: claveOpenRouter ? { apiKey: claveOpenRouter } : false,
+    onStep: async (paso) => { /* text · tool_call · tool_result · jev_decision */ },
+  })) { /* … */ }
+});
+```
+
+Reglas con un inquilino activo (desde 0.5.1):
+
+- `credentials.apiKey` gana. Sin ella, la clave sale de los secretos **de ese
+  inquilino** (`storeProviderApiKey` dentro de su `runInTenant`).
+- Nunca se usa `<PROVIDER>_API_KEY` del entorno ni el llavero del SO: son de la
+  máquina, no del cliente. Si no hay clave, la llamada falla en vez de cobrarse
+  a la plataforma. Para tus propias tools usa `envSecret(nombre)`
+  (`@johpaz/hive-sdk/storage`), que aplica la misma regla.
+- `credentials` y `jev` se propagan a `runAgentIsolated`, `runRoleSwarm` y
+  `runSwarm`.
+
+### Jev: plano de decisión
+
+Jev hace preguntas acotadas a la API Decisions de OpenRouter
+(`typesafe/jev-1.13`) y usa las respuestas para recortar lo que recibe el
+modelo principal. **Es opcional**: sin clave no existe, no se hace ninguna
+llamada y el turno corre exactamente igual.
+
+| Momento | Qué decide |
+|---|---|
+| Al compilar el contexto | Qué mensajes previos, tools, skills, notas del scratchpad y reglas del playbook entran; a qué especialista conviene delegar, y si depende de un MCP apagado. Los últimos 4 mensajes siempre quedan. |
+| Entre iteraciones | Qué resultados viejos de tools se omiten y la siguiente acción (continuar, delegar, descubrir, cerrar). Sólo si hay ≥ 4 000 caracteres podables. |
+| Antes de ejecutar tools | Si un lote de lecturas independientes, o de delegaciones a workers distintos, corre en paralelo. |
+
+Lo omitido se puede recuperar: el prompt lista los ids y el coordinador tiene
+`conversation_read`.
+
+**Activación**, por orden:
+
+1. `jev: { apiKey, mcpSettingsPath? }` en la llamada. `mcpSettingsPath` es el
+   texto con el que el coordinador le dice al usuario dónde encender un MCP
+   (por defecto «Ajustes → Entorno → MCP Servers»).
+2. `jev: false` lo apaga.
+3. Sin la opción: el provider `openrouter` habilitado y activo, con su clave
+   guardada; sin inquilino, también `OPENROUTER_API_KEY`.
+
+**Qué ve el host.** Cada decisión llega por `onStep` como
+`{ type: "jev_decision", message, jev }`, con agente, tipo (`context`,
+`iteration`, `parallel`), resumen, tokens ahorrados estimados, latencia, costo,
+especialista recomendado y MCP apagados. También se emite
+`canvas:jev_decision`. `getUsageStats().jev` suma decisiones, costo y ahorro
+(total y por agente). Fallos y cooldown se llevan por inquilino.
+
+**Privacidad.** Se envían a OpenRouter, con la clave de la llamada, extractos
+acotados: el objetivo del turno, fragmentos de mensajes previos, nombres y
+descripciones de tools y skills, notas y reglas, fragmentos de resultados de
+tools y el mapa del enjambre (nombres, no ids con prefijo de inquilino). Nunca
+credenciales ni adjuntos. El detalle está en el [CHANGELOG](../CHANGELOG.md).
+
 ---
 
 ## Tool Selector

package/docs/INDEX.md

@@ -12,7 +12,7 @@
 | [API-RESILIENCE.md](./API-RESILIENCE.md) | Reintentos con backoff y circuit breakers |
 | [API-SESSIONS.md](./API-SESSIONS.md) | Sesiones por canal, historial, reanudación tras un corte |
 | [API-SERVICES.md](./API-SERVICES.md) | **La superficie para una UI** — CRUD de agentes, enjambres, skills, modelos, MCP, cron |
-| [API-AGENTS.md](./API-AGENTS.md) | createAgent, AgentLoop, Tool/Skill Selector, LLM Providers |
+| [API-AGENTS.md](./API-AGENTS.md) | createAgent, AgentLoop, Tool/Skill Selector, LLM Providers, multi-inquilino y Jev |
 | [API-DAG-SCHEDULER.md](./API-DAG-SCHEDULER.md) | DAGScheduler, TaskGraph, Estrategias, Presets |
 | [API-CRON.md](./API-CRON.md) | Tareas programadas: expresiones, zona horaria, misfires, motor sin dependencias |
 | [API-WORKERS-EVENTS.md](./API-WORKERS-EVENTS.md) | **Bun Workers**, createWorker, WorkerPool, AgentBus, EventBus, Canvas |
@@ -181,6 +181,10 @@ ANTHROPIC_API_KEY=sk-ant-...  # Anthropic
 LOG_LEVEL=info                # debug | info | warn | error
 ```
 
+Las `*_API_KEY` del entorno sólo se usan sin inquilino; dentro de
+`runInTenant` la clave llega en `credentials` o desde los secretos del
+inquilino (ver [UPGRADING.md](./UPGRADING.md#051-claves-aisladas-por-inquilino)).
+
 ---
 
 ## Tests

package/docs/UPGRADING.md

@@ -74,6 +74,26 @@ sigue sólo importa con el log causal encendido (`HIVE_CAUSAL_LOG=true` o
   crudo y el SDK lo califica. Los eventos que entrega traen en `agentId` la
   clave del shard; `formatCausalEvent` la muestra sin el tenant.
 
+## 0.5.1: claves aisladas por inquilino
+
+Sólo cambia algo si corres turnos dentro de `runInTenant` (un host
+multi-inquilino). Sin inquilino todo sigue igual.
+
+- **La caché de secretos y el llavero del SO ya no se comparten.** Antes, en
+  cuanto un inquilino leía o guardaba `provider:<id>:api_key`, los demás del
+  mismo proceso recibían esa clave. Ahora la caché es por inquilino y el
+  llavero no se toca dentro de un inquilino. No hay que cambiar código.
+- **El entorno ya no es respaldo dentro de un inquilino.** Si un turno no
+  trae `credentials` y el inquilino no tiene clave guardada, antes se usaba
+  `<PROVIDER>_API_KEY` del proceso (la cuenta de la plataforma); ahora la
+  llamada falla por falta de clave. Aplica al modelo principal, OCR, voz,
+  `computer_use` y Jev. Qué hacer: pasar la clave en `credentials`, o
+  guardarla con `storeProviderApiKey` dentro del `runInTenant` del cliente. Si
+  quieres que un cliente use la cuenta de la plataforma, pásala tú en
+  `credentials`, a propósito.
+- Para tus propias tools: `envSecret("MI_API_KEY")` en lugar de
+  `process.env.MI_API_KEY`.
+
 ## Compatibilidad y CI
 
 Los workflows fijan Bun 1.4.2, instalan con `--frozen-lockfile`, ejecutan el

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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",

package/packages/core/src/agent/jev-decisions.ts

@@ -1,7 +1,7 @@
 /** Optional decision plane. Jev is never used through the chat completions API. */
 import { col } from "../storage/hive.ts"
 import type { ProviderDoc } from "../storage/collections.ts"
-import { loadDurableProviderApiKey, loadProviderApiKey } from "../storage/crypto.ts"
+import { envSecret, loadProviderApiKey } from "../storage/crypto.ts"
 import { recordJevDecision, recordUsage } from "../storage/usage.ts"
 import { catalogModelKey } from "../storage/model-id.ts"
 import { currentTenant } from "../storage/tenant.ts"
@@ -71,17 +71,15 @@ export interface JevResult {
 /**
  * The OpenRouter key Jev would use, or null when Jev is off.
  *
- * With a tenant in scope the key comes only from that tenant's `secrets`
- * partition — never from `OPENROUTER_API_KEY`, which is the platform's, nor
- * from the process-wide secret cache, which is not partitioned.
+ * With a tenant in scope the key comes only from that tenant's secrets —
+ * never from `OPENROUTER_API_KEY`, which is the platform's.
  */
 export async function getJevKey(option?: JevOption): Promise<string | null> {
   if (option === false) return null
   if (option) return option.apiKey || null
   const provider = await (await col<ProviderDoc>("providers")).get("openrouter")
   if (!provider?.doc.enabled || !provider.doc.active) return null
-  if (currentTenant()) return (await loadDurableProviderApiKey("openrouter")) || null
-  return (await loadProviderApiKey("openrouter")) || process.env.OPENROUTER_API_KEY || null
+  return (await loadProviderApiKey("openrouter")) || envSecret("OPENROUTER_API_KEY") || null
 }
 
 export interface JevStatus {

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

@@ -309,7 +309,7 @@ export async function resolveProviderConfig(
   credentials?: ProviderCredentials
 ): Promise<Pick<LLMCallOptions, "provider" | "model" | "apiKey" | "baseUrl" | "numCtx" | "numGpu" | "contextWindow">> {
   const { col } = await import("../storage/hive.ts")
-  const { loadProviderApiKey } = await import("../storage/crypto.ts")
+  const { envSecret, 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")
 
@@ -327,7 +327,7 @@ export async function resolveProviderConfig(
     apiKey = await loadProviderApiKey(providerId)
   }
   if (!apiKey) {
-    apiKey = process.env[`${providerId.toUpperCase()}_API_KEY`] || ""
+    apiKey = envSecret(`${providerId.toUpperCase()}_API_KEY`) || ""
   }
 
   return {

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

@@ -1,3 +1,4 @@
+import { envSecret } from "../../storage/crypto.ts"
 import { logger } from "../../utils/logger.ts"
 import { normalizeToolName, resolveMaxTokens, ensureArrayItems } from "./interface.ts"
 import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall, ThinkingBlock } from "./interface.ts"
@@ -74,7 +75,7 @@ export class AnthropicProvider implements LLMProvider {
 
   async call(options: LLMCallOptions): Promise<LLMResponse> {
     const Anthropic = await import("@anthropic-ai/sdk")
-    const client = new Anthropic.default({ apiKey: options.apiKey })
+    const client = new Anthropic.default({ apiKey: options.apiKey || envSecret("ANTHROPIC_API_KEY") || "" })
 
     // Anthropic requires tool names to match ^[a-zA-Z0-9_-]{1,128}$
     // Native Hive tools use dots (e.g. cron.create) which violate this.

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

@@ -1,3 +1,4 @@
+import { envSecret } from "../../storage/crypto.ts"
 import { logger } from "../../utils/logger.ts"
 import { sanitizeMessages, resolveMaxTokens, ensureArrayItems } from "./interface.ts"
 import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall } from "./interface.ts"
@@ -100,7 +101,8 @@ export class GeminiProvider implements LLMProvider {
   async call(options: LLMCallOptions): Promise<LLMResponse> {
     const { GoogleGenAI } = await import("@google/genai")
 
-    const clientOpts: any = { apiKey: options.apiKey }
+    // A string always: undefined makes @google/genai read GEMINI_API_KEY itself, inside a tenant too.
+    const clientOpts: any = { apiKey: options.apiKey || envSecret("GEMINI_API_KEY") || envSecret("GOOGLE_API_KEY") || "" }
     if (options.baseUrl?.trim()) clientOpts.httpOptions = { baseUrl: options.baseUrl.trim() }
 
     const ai = new GoogleGenAI(clientOpts)

package/packages/core/src/agent/realtime-providers/gemini-live.ts

@@ -10,6 +10,7 @@
  * al contexto inicial en 3.x, así que no se usa acá.
  */
 
+import { envSecret } from "../../storage/crypto.ts"
 import { logger } from "../../utils/logger.ts";
 import { ensureArrayItems } from "../llm-providers/interface.ts";
 import type {
@@ -106,7 +107,7 @@ export class GeminiLiveProvider implements RealtimeProvider {
 
   async connect(options: RealtimeSessionOptions): Promise<RealtimeSession> {
     const { GoogleGenAI } = await import("@google/genai");
-    const ai = new GoogleGenAI({ apiKey: options.apiKey });
+    const ai = new GoogleGenAI({ apiKey: options.apiKey || envSecret("GEMINI_API_KEY") || envSecret("GOOGLE_API_KEY") || "" });
     const cb = options.callbacks;
 
     const config: Record<string, unknown> = {

package/packages/core/src/multimodal/vision-service.ts

@@ -1,6 +1,6 @@
 import { col } from "../storage/hive.ts"
 import type { ChannelDoc, ModelDoc, ProviderDoc } from "../storage/collections.ts"
-import { loadProviderApiKey } from "../storage/crypto.ts"
+import { envSecret, loadProviderApiKey } from "../storage/crypto.ts"
 import { logger } from "../utils/logger.ts"
 import type { ImageInput, DocumentInput, VisionConfig } from "./types.ts"
 import type { ContentPart } from "./types.ts"
@@ -177,7 +177,7 @@ class MultimodalService {
   }
 
   private async ocrWithOpenAI(image: ImageInput): Promise<string> {
-    const key = await this.getProviderApiKey("openai") || process.env.OPENAI_API_KEY
+    const key = await this.getProviderApiKey("openai") || envSecret("OPENAI_API_KEY")
     if (!key) throw new Error("OPENAI_API_KEY not configured for OCR")
 
     const imageUrl = await this.resolveImageUrl(image)
@@ -208,7 +208,7 @@ class MultimodalService {
   }
 
   private async ocrWithGemini(image: ImageInput): Promise<string> {
-    const key = await this.getProviderApiKey("gemini") || process.env.GEMINI_API_KEY
+    const key = await this.getProviderApiKey("gemini") || envSecret("GEMINI_API_KEY")
     if (!key) throw new Error("GEMINI_API_KEY not configured for OCR")
 
     let imagePart: any
@@ -243,7 +243,7 @@ class MultimodalService {
   }
 
   private async ocrWithAnthropic(image: ImageInput): Promise<string> {
-    const key = await this.getProviderApiKey("anthropic") || process.env.ANTHROPIC_API_KEY
+    const key = await this.getProviderApiKey("anthropic") || envSecret("ANTHROPIC_API_KEY")
     if (!key) throw new Error("ANTHROPIC_API_KEY not configured for OCR")
 
     const imageUrl = await this.resolveImageUrl(image)
@@ -299,9 +299,9 @@ class MultimodalService {
     ])
 
     return {
-      openai: openai || !!(process.env.OPENAI_API_KEY),
-      gemini: gemini || !!(process.env.GEMINI_API_KEY),
-      anthropic: anthropic || !!(process.env.ANTHROPIC_API_KEY),
+      openai: openai || !!(envSecret("OPENAI_API_KEY")),
+      gemini: gemini || !!(envSecret("GEMINI_API_KEY")),
+      anthropic: anthropic || !!(envSecret("ANTHROPIC_API_KEY")),
     }
   }
 

package/packages/core/src/storage/crypto.ts

@@ -4,6 +4,7 @@ import * as path from "node:path"
 import { getHiveDir } from "../config/loader.ts"
 import { logger } from "../utils/logger.ts"
 import { col } from "./hive.ts"
+import { currentTenant } from "./tenant.ts"
 
 const log = logger.child("crypto")
 const SERVICE = "hive"
@@ -25,8 +26,28 @@ interface SecretDoc {
 // written *only* there does not survive a server restart. That is exactly
 // what was wiping every provider API key, channel token and MCP header on
 // restart in production.
-
+//
+// Multi-tenant: the `secrets` collection is partitioned by tenant through
+// `col()`, but this process's memory and the OS keychain are not. So the
+// in-memory cache is keyed by tenant as well, and with a tenant in scope the
+// keychain is never read or written — a machine-wide entry named
+// `provider:openai:api_key` belongs to no tenant in particular, and serving it
+// (or overwriting it) on a tenant's behalf would hand one customer another's
+// key.
+
+/** Decrypted values, keyed by {@link _cacheKey}: never shared across tenants. */
 const _mem = new Map<string, string>()
+
+/** `name` for the desktop (no tenant); `<tenant>\0name` inside a tenant. */
+function _cacheKey(name: string): string {
+  const tenant = currentTenant()
+  return tenant ? `${tenant}\0${name}` : name
+}
+
+/** The OS keychain only serves the tenant-less (desktop) scope. */
+function _keychainInScope(): boolean {
+  return currentTenant() === null
+}
 let _keychainOk: boolean | null = null // null = untested
 
 let _keychainApi: unknown = undefined
@@ -46,19 +67,21 @@ function _getKeychainApi(): any {
 }
 
 async function _get(name: string): Promise<string | null> {
-  const cached = _mem.get(name)
+  const cacheKey = _cacheKey(name)
+  const cached = _mem.get(cacheKey)
   if (cached !== undefined) return cached
 
   // Durable store first — it is the one every write goes to.
   const stored = await _readCollectionSecret(name)
   if (stored) {
-    _mem.set(name, stored)
+    _mem.set(cacheKey, stored)
     return stored
   }
 
   // Legacy/desktop installs may only have the value in the OS keychain.
+  if (!_keychainInScope()) return null
   const fromKeychain = await _keychainGet(name)
-  if (fromKeychain) _mem.set(name, fromKeychain)
+  if (fromKeychain) _mem.set(cacheKey, fromKeychain)
   return fromKeychain
 }
 
@@ -69,9 +92,9 @@ async function _get(name: string): Promise<string | null> {
  * silently accepting a secret that dies with the process.
  */
 async function _set(name: string, value: string): Promise<boolean> {
-  _mem.set(name, value)
+  _mem.set(_cacheKey(name), value)
   const durable = await persistSecretToCollection(name, value)
-  const mirrored = await _keychainSet(name, value)
+  const mirrored = _keychainInScope() ? await _keychainSet(name, value) : false
   if (!durable && !mirrored) {
     log.error(`[secrets] ${name} could not be persisted — it will be lost on restart`)
   }
@@ -87,7 +110,6 @@ async function _readCollectionSecret(name: string): Promise<string | null> {
     const secrets = await col<SecretDoc>("secrets")
     const entry = await secrets.get(name)
     if (!entry) return null
-    // `_get` caches it; `loadDurableProviderApiKey` must not.
     return decryptSecret(entry.doc.ciphertext, entry.doc.iv) || null
   } catch {
     return null
@@ -134,11 +156,13 @@ async function _keychainSet(name: string, value: string): Promise<boolean> {
 }
 
 async function _del(name: string): Promise<void> {
-  _mem.delete(name)
-  try {
-    await (Bun as any).secrets.delete({ service: SERVICE, name })
-  } catch {
-    // ignore — might not exist or keychain unavailable
+  _mem.delete(_cacheKey(name))
+  if (_keychainInScope()) {
+    try {
+      await (Bun as any).secrets.delete({ service: SERVICE, name })
+    } catch {
+      // ignore — might not exist or keychain unavailable
+    }
   }
   try {
     const secrets = await col<SecretDoc>("secrets")
@@ -195,12 +219,14 @@ export async function loadProviderApiKey(id: string): Promise<string> {
 }
 
 /**
- * The provider key from the durable `secrets` collection only. That collection
- * is partitioned by tenant; the in-memory cache and the OS keychain are not, so
- * a multi-tenant caller that must never see another tenant's key reads here.
+ * A credential from the process environment (`OPENAI_API_KEY`, …) — only
+ * outside a tenant. The environment is the host's: inside a tenant it belongs
+ * to the platform, not the customer, and using it would bill the platform's
+ * account for a customer's call (or let one customer run on another's key).
+ * A tenant's credentials come from its own secrets or from `credentials`.
  */
-export async function loadDurableProviderApiKey(id: string): Promise<string> {
-  return (await _readCollectionSecret(`provider:${id}:api_key`)) ?? ""
+export function envSecret(name: string): string | undefined {
+  return currentTenant() ? undefined : process.env[name] || undefined
 }
 
 export async function storeProviderHeaders(id: string, headers: Record<string, unknown>): Promise<boolean> {

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

@@ -96,6 +96,7 @@ export {
   deleteSecret,
   storeProviderApiKey,
   loadProviderApiKey,
+  envSecret,
   storeProviderHeaders,
   loadProviderHeaders,
   deleteProviderSecrets,

package/packages/core/src/tools/web/computer-use.ts

@@ -28,7 +28,7 @@
 import type { Tool } from "../types.ts";
 import { logger } from "../../utils/logger.ts";
 import { getBrowserService } from "./browser-service.ts";
-import { loadProviderApiKey } from "../../storage/crypto.ts";
+import { envSecret, loadProviderApiKey } from "../../storage/crypto.ts";
 
 const log = logger.child("computer-use");
 
@@ -417,7 +417,7 @@ export const computerUseTaskTool: Tool = {
     const maxPasos = Math.max(1, Math.min(30, Number(params.max_pasos) || MAX_PASOS));
     const confirmado = params.confirmado === true;
 
-    const apiKey = (await loadProviderApiKey("gemini")) || process.env.GEMINI_API_KEY;
+    const apiKey = (await loadProviderApiKey("gemini")) || envSecret("GEMINI_API_KEY");
     if (!apiKey) {
       return { ok: false, error: "Falta la API key de Gemini (Ajustes → Proveedores)." };
     }

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

@@ -1,7 +1,7 @@
 import { resolvePort } from "../utils/port.ts";
 import { col } from "../storage/hive.ts";
 import type { ChannelDoc, ModelDoc } from "../storage/collections.ts";
-import { loadProviderApiKey } from "../storage/crypto.ts";
+import { envSecret, loadProviderApiKey } from "../storage/crypto.ts";
 import { logger } from "../utils/logger.ts";
 
 export interface VoiceConfig {
@@ -160,7 +160,7 @@ class VoiceService {
   }
 
   private async transcribeWithGroq(audio: AudioInput, modelId: string): Promise<string> {
-    const key = await this.getProviderApiKey("groq") || process.env.GROQ_API_KEY;
+    const key = await this.getProviderApiKey("groq") || envSecret("GROQ_API_KEY");
     if (!key) {
       throw new Error("GROQ_API_KEY not configured. Configúrala en Proveedores o en las variables de entorno.");
     }
@@ -212,7 +212,7 @@ class VoiceService {
   }
 
   private async transcribeWithOpenAIWhisper(audio: AudioInput): Promise<string> {
-    const key = await this.getProviderApiKey("openai") || process.env.OPENAI_API_KEY;
+    const key = await this.getProviderApiKey("openai") || envSecret("OPENAI_API_KEY");
     if (!key) {
       throw new Error("OPENAI_API_KEY not configured. Configúrala en Proveedores o en las variables de entorno.");
     }
@@ -302,7 +302,7 @@ class VoiceService {
 
   private async speakWithElevenLabs(text: string, modelId: string, voiceId?: string): Promise<AudioOutput> {
     const apiKey = await this.getProviderApiKey("elevenlabs");
-    const key = apiKey || process.env.ELEVENLABS_API_KEY;
+    const key = apiKey || envSecret("ELEVENLABS_API_KEY");
     
     if (!key) {
       throw new Error("ELEVENLABS_API_KEY not configured");
@@ -341,7 +341,7 @@ class VoiceService {
 
   private async speakWithOpenAI(text: string, modelId: string = "gpt-4o-mini-tts", voiceId?: string): Promise<AudioOutput> {
     const apiKey = await this.getProviderApiKey("openai-tts");
-    const key = apiKey || process.env.OPENAI_API_KEY;
+    const key = apiKey || envSecret("OPENAI_API_KEY");
 
     if (!key) {
       throw new Error("OPENAI_API_KEY not configured");
@@ -377,7 +377,7 @@ class VoiceService {
   }
 
   private async speakWithGemini(text: string, modelId: string, voiceId?: string): Promise<AudioOutput> {
-    const key = process.env.GEMINI_API_KEY;
+    const key = envSecret("GEMINI_API_KEY");
 
     if (!key) {
       throw new Error("GEMINI_API_KEY not configured");
@@ -431,7 +431,7 @@ class VoiceService {
   }
 
   private async speakWithQwen(text: string, modelId: string, voiceId?: string): Promise<AudioOutput> {
-    const key = process.env.DASHSCOPE_API_KEY;
+    const key = envSecret("DASHSCOPE_API_KEY");
 
     if (!key) {
       throw new Error("DASHSCOPE_API_KEY not configured");
@@ -485,11 +485,11 @@ class VoiceService {
     ]);
 
     return {
-      groq:       groq       || !!(process.env.GROQ_API_KEY),
-      elevenlabs: elevenlabs || !!(process.env.ELEVENLABS_API_KEY),
-      openai:     openai     || !!(process.env.OPENAI_API_KEY),
-      gemini:     gemini     || !!(process.env.GEMINI_API_KEY),
-      qwen:       qwen       || !!(process.env.DASHSCOPE_API_KEY),
+      groq:       groq       || !!(envSecret("GROQ_API_KEY")),
+      elevenlabs: elevenlabs || !!(envSecret("ELEVENLABS_API_KEY")),
+      openai:     openai     || !!(envSecret("OPENAI_API_KEY")),
+      gemini:     gemini     || !!(envSecret("GEMINI_API_KEY")),
+      qwen:       qwen       || !!(envSecret("DASHSCOPE_API_KEY")),
     };
   }
 
@@ -561,7 +561,7 @@ class VoiceService {
 
   async getElevenLabsVoices(): Promise<Array<{ id: string; name: string; category: string }>> {
     const apiKey = await this.getProviderApiKey("elevenlabs");
-    const key = apiKey || process.env.ELEVENLABS_API_KEY;
+    const key = apiKey || envSecret("ELEVENLABS_API_KEY");
     
     if (!key) {
       throw new Error("ELEVENLABS_API_KEY not configured");