@johpaz/hive-sdk 0.4.9 → 0.5.1

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

@@ -0,0 +1,298 @@
+import type { LLMMessage, LLMToolDef } from "./llm-client.ts"
+import type { SkillDescriptor } from "./skill-selector.ts"
+import type { ContextTool } from "./context-compiler.ts"
+import type { PlaybookRule } from "./playbook-selector.ts"
+import { MINIMAL_TOOLS } from "./minimal-loadout.ts"
+import { searchCapabilities } from "./capability-search.ts"
+import { mcpToolFullName } from "./tool-selector.ts"
+import { askJev, getJevKey, type JevAnswer, type JevOption, type JevQuestion } from "./jev-decisions.ts"
+import { col } from "../storage/hive.ts"
+import type { AgentDoc, McpServerDoc, McpToolDoc } from "../storage/collections.ts"
+
+export interface JevDecisionMetrics {
+  latencyMs: number
+  costUsd: number
+}
+
+/** "activo": connected now; "disponible": enabled, connects on first use; "apagado": disabled. */
+export type JevMcpState = "activo" | "disponible" | "apagado"
+
+export interface JevMcpServer {
+  id: string
+  name: string
+  state: JevMcpState
+  tools: number
+}
+
+export interface JevSpecialist {
+  id: string
+  name: string
+  description: string
+  tools: string[]
+  mcp: Array<{ name: string; state: JevMcpState }>
+}
+
+/**
+ * What the swarm can do right now: every enabled worker (catalog and
+ * agent_create alike) with its tools, and every MCP server with its state.
+ * Jev routes and selects over this, so it never recommends a specialist whose
+ * MCP is off or proposes a tool that is not connected.
+ */
+export async function describeSwarmCapabilities(
+  mcpManager: { getServerTools(key: string): unknown[] | undefined } | null,
+  opts: { includeSpecialists: boolean },
+): Promise<{ mcpServers: JevMcpServer[]; specialists: JevSpecialist[] }> {
+  const servers = (await (await col<McpServerDoc>("mcpServers")).scan({})).map(e => e.doc)
+  const mcpServers: JevMcpServer[] = servers.map(server => {
+    const tools = mcpManager?.getServerTools(server.id)?.length || mcpManager?.getServerTools(server.name)?.length || 0
+    return { id: server.id, name: server.name, tools, state: !server.enabled ? "apagado" : tools > 0 ? "activo" : "disponible" }
+  })
+  if (!opts.includeSpecialists) return { mcpServers, specialists: [] }
+
+  const byId = new Map(mcpServers.map(s => [s.id, s]))
+  const parse = (json: string | null | undefined): string[] => {
+    try { return json ? (JSON.parse(json) as unknown[]).map(String) : [] } catch { return [] }
+  }
+  const specialists = (await (await col<AgentDoc>("agents")).scan({}))
+    .map(e => e.doc)
+    .filter(a => a.role === "worker" && a.enabled && a.status !== "archived")
+    .map(a => ({
+      id: a.id,
+      name: a.name,
+      description: (a.description ?? a.name).slice(0, 200),
+      tools: parse(a.tool_allowlist_json).slice(0, 12),
+      mcp: parse(a.mcp_server_ids_json).map(id => byId.get(id)).filter((s): s is JevMcpServer => !!s)
+        .map(s => ({ name: s.name, state: s.state })),
+    }))
+  return { mcpServers, specialists }
+}
+
+/** One roster line: what the coordinator needs to pick a specialist without calling agent_find. */
+export function renderSpecialistLine(s: JevSpecialist): string {
+  const mcp = s.mcp.length ? ` · MCP: ${s.mcp.map(m => `${m.name} (${m.state})`).join(", ")}` : ""
+  return `- ${s.id} (${s.name})${mcp}`
+}
+
+export interface JevContextPlan {
+  messages: LLMMessage[]
+  tools: LLMToolDef[]
+  skills: SkillDescriptor[]
+  agentId: string | null
+  /**
+   * MCP servers the recommended specialist depends on that are off. Non-empty
+   * means "this is the right specialist, but the user must turn these on
+   * first" — delegating now would hand it a task it cannot do.
+   */
+  agentMcpOff: string[]
+  selectedMessageIds: number[]
+  selectedToolNames: string[]
+  selectedSkillNames: string[]
+  selectedScratchpadKeys: string[]
+  selectedPlaybookIds: string[]
+  decision: JevDecisionMetrics
+}
+
+const excerpt = (value: unknown, max = 450): string =>
+  (typeof value === "string" ? value : JSON.stringify(value) ?? "").slice(0, max)
+const probability = (answer: JevAnswer | undefined): number | null => answer?.type === "noul" ? answer.noul : null
+const MANDATORY_TAIL = 4
+/** Below this many characters of prunable tool output, a decision costs more latency than it saves. */
+const MIN_PRUNABLE_CHARS = 4000
+
+/** Decisions select only from already authorized, discoverable candidates. */
+export async function planJevContext(input: {
+  objective: string
+  messages: LLMMessage[]
+  tools: LLMToolDef[]
+  allTools: ContextTool[]
+  skills: SkillDescriptor[]
+  scratchpadNotes?: Array<{ key: string; value: string }>
+  playbookRules?: PlaybookRule[]
+  isWorker: boolean
+  /** From describeSwarmCapabilities; absent means "unknown", not "none". */
+  swarm?: { mcpServers: JevMcpServer[]; specialists: JevSpecialist[] }
+  jev?: JevOption
+}): Promise<JevContextPlan | null> {
+  if (!await getJevKey(input.jev).catch(() => null)) return null
+  const { objective, messages, tools, allTools, skills, isWorker } = input
+  const mandatoryMessages = new Set<number>()
+  // The last two exchanges carry the thread's immediate referents ("hazlo otra
+  // vez", "el anterior"); dropping them sent the model into conversation_read loops.
+  for (let i = Math.max(0, messages.length - MANDATORY_TAIL); i < messages.length; i++) mandatoryMessages.add(i)
+  messages.forEach((message, i) => {
+    if (Array.isArray(message.content) || (typeof message.content === "string" && message.content.startsWith("<hive:internal_event"))) mandatoryMessages.add(i)
+  })
+
+  const candidateMessageIds = messages.map((_, i) => i).filter(i => !mandatoryMessages.has(i))
+  let candidateTools: ContextTool[] = tools.filter(t => !MINIMAL_TOOLS.has(t.function.name))
+    .map(t => allTools.find(a => a.name === t.function.name))
+    .filter((t): t is ContextTool => !!t)
+  try {
+    const hits = await searchCapabilities(objective, { types: ["tool", "mcp"], k: 12 })
+    // allTools only holds MCP tools of servers that are enabled, connected and
+    // allowed for this agent — resolving through it is what keeps a dormant or
+    // foreign server's tools out of the plan.
+    const available = new Map(allTools.map(t => [t.name, t]))
+    const mcpTools = await col<McpToolDoc>("mcpTools")
+    const names = await Promise.all(hits.map(async h => {
+      if (h.type !== "mcp") return h.rawId
+      const tool = (await mcpTools.get(h.rawId))?.doc
+      return tool ? mcpToolFullName(tool.server_name, tool.tool_name) : null
+    }))
+    const discovered = names.map(n => n ? available.get(n) : undefined).filter((t): t is ContextTool => !!t && !MINIMAL_TOOLS.has(t.name))
+    candidateTools = [...new Map([...candidateTools, ...discovered].map(t => [t.name, t])).values()].slice(0, 24)
+  } catch { /* index unavailable: retain the current loadout */ }
+
+  const optionalSkills = skills.filter(s => s.active && s.body).slice(0, 8)
+  const scratchpadNotes = (input.scratchpadNotes ?? []).slice(-16)
+  const playbookRules = (input.playbookRules ?? []).slice(0, 8)
+  // Specialists with an MCP off stay eligible: Jev still names the right one,
+  // and the coordinator asks the user to turn the server on instead of
+  // delegating a task the specialist cannot do yet.
+  const agents = isWorker ? [] : (input.swarm?.specialists ?? []).slice(0, 16)
+  const questions: Record<string, JevQuestion> = {}
+  for (const i of candidateMessageIds) questions[`history_${i}`] = { type: "noul", instructions: `Is earlier conversation item ${i} necessary to complete the current objective?` }
+  for (const tool of candidateTools) questions[`tool_${tool.name}`] = { type: "noul", instructions: `Will tool ${tool.name} likely be needed for the current objective?` }
+  for (const skill of optionalSkills) questions[`skill_${skill.id}`] = { type: "noul", instructions: `Are instructions from skill ${skill.name} needed for the current objective?` }
+  for (const note of scratchpadNotes) questions[`note_${note.key}`] = { type: "noul", instructions: `Is scratchpad note ${note.key} needed for the current objective?` }
+  for (const rule of playbookRules) questions[`rule_${rule.id}`] = { type: "noul", instructions: `Does playbook rule ${rule.id} apply to the current objective?` }
+  if (agents.length) questions.agent = {
+    type: "choice", instructions: "Which existing specialist should handle a bounded part of this objective, or should the coordinator handle it?",
+    criteria: {
+      coordinator: "No bounded specialist task is needed",
+      ...Object.fromEntries(agents.map(a => [a.id, [
+        a.description,
+        a.tools.length ? `tools: ${a.tools.join(", ")}` : "",
+        a.mcp.length ? `MCP: ${a.mcp.map(m => `${m.name} (${m.state})`).join(", ")}` : "",
+      ].filter(Boolean).join(" · ").slice(0, 400)])),
+    },
+  }
+  const decision = await askJev({
+    objective: objective.slice(0, 3500),
+    history: candidateMessageIds.map(i => ({ id: i, role: messages[i].role, content: excerpt(messages[i].content) })),
+    tools: candidateTools.map(t => ({ name: t.name, description: t.description.slice(0, 240) })),
+    skills: optionalSkills.map(s => ({ id: s.id, name: s.name, description: s.description.slice(0, 240) })),
+    notes: scratchpadNotes.map(n => ({ key: n.key, value: n.value.slice(0, 350) })),
+    rules: playbookRules.map(r => ({ id: r.id, rule: r.rule.slice(0, 350) })),
+    mcp_servers: (input.swarm?.mcpServers ?? []).map(s => ({ name: s.name, state: s.state, tools: s.tools })),
+  }, questions, { jev: input.jev })
+  if (!decision) return null
+
+  const selected = new Set(messages.map((_, i) => i).filter(i => mandatoryMessages.has(i) ||
+    !candidateMessageIds.includes(i) || (probability(decision.answers[`history_${i}`]) ?? 1) >= 0.35))
+  // A reply travels with the user turn it answered: Gemini silently drops a
+  // model turn that has no preceding user turn.
+  for (const i of [...selected]) {
+    if (messages[i].role !== "assistant") continue
+    for (let j = i - 1; j >= 0; j--) if (messages[j].role === "user") { selected.add(j); break }
+  }
+  const selectedMessageIds = [...selected].sort((a, b) => a - b)
+  const selectedToolNames = candidateTools.filter(t => (probability(decision.answers[`tool_${t.name}`]) ?? 1) >= 0.35).map(t => t.name)
+  const selectedSkills = optionalSkills.filter(s => (probability(decision.answers[`skill_${s.id}`]) ?? 1) >= 0.35)
+  const toolMap = new Map(allTools.map(t => [t.name, t]))
+  const selectedNames = new Set(selectedToolNames)
+  const candidateNames = new Set(candidateTools.map(t => t.name))
+  const combinedTools = tools.filter(t => !candidateNames.has(t.function.name) || selectedNames.has(t.function.name))
+  for (const name of selectedToolNames) {
+    const tool = toolMap.get(name)
+    if (tool && !combinedTools.some(t => t.function.name === name)) combinedTools.push({
+      type: "function", function: { name: tool.name, description: tool.description, parameters: tool.parameters },
+    })
+  }
+  const agentAnswer = decision.answers.agent
+  const agentId = agentAnswer?.type === "choice" && agentAnswer.confidence >= 0.7 && agentAnswer.choice !== "coordinator"
+    ? agentAnswer.choice : null
+  const agentMcpOff = agents.find(a => a.id === agentId)?.mcp.filter(m => m.state === "apagado").map(m => m.name) ?? []
+  return {
+    messages: selectedMessageIds.map(i => messages[i]), tools: combinedTools,
+    skills: selectedSkills, agentId, agentMcpOff, selectedMessageIds, selectedToolNames,
+    selectedSkillNames: selectedSkills.map(s => s.name),
+    selectedScratchpadKeys: scratchpadNotes.filter(n => (probability(decision.answers[`note_${n.key}`]) ?? 1) >= 0.35).map(n => n.key),
+    selectedPlaybookIds: playbookRules.filter(r => (probability(decision.answers[`rule_${r.id}`]) ?? 1) >= 0.35).map(r => r.id),
+    decision: { latencyMs: decision.latencyMs, costUsd: decision.costUsd },
+  }
+}
+
+/**
+ * Only independent reads, or separate delegated tasks, may execute concurrently.
+ * null leaves the batch to the runtime default; `decision` is present only when Jev was asked.
+ */
+export async function jevWantsParallel(
+  calls: Array<{ function: { name: string; arguments: unknown } }>,
+  jev?: JevOption,
+): Promise<{ parallel: boolean; decision?: JevDecisionMetrics } | null> {
+  if (calls.length < 2) return null
+  if (!await getJevKey(jev).catch(() => null)) return null
+  const names = calls.map(c => c.function.name)
+  const readOnly = names.every(n => /^(fs_read|fs_list|fs_glob|fs_exists|web_search|web_fetch|memory_read|memory_search|artifact_read|artifact_inspect|task_status|agent_find)$/.test(n))
+  const delegated = names.every(n => n === "task_delegate")
+  if (!readOnly && !delegated) return { parallel: false }
+  if (delegated) {
+    const ids = calls.map(call => {
+      try {
+        const args = typeof call.function.arguments === "string" ? JSON.parse(call.function.arguments) : call.function.arguments
+        return String(args?.worker_id ?? "")
+      } catch { return "" }
+    })
+    if (ids.some(id => !id) || new Set(ids).size !== ids.length) return { parallel: false }
+    const agentsCol = await col<AgentDoc>("agents")
+    const agents = await Promise.all(ids.map(id => agentsCol.get(id)))
+    const workspaces = agents.map(row => row?.doc.workspace)
+    if (workspaces.some(path => !path) || new Set(workspaces).size !== workspaces.length) return { parallel: false }
+  }
+  const result = await askJev({ calls: calls.map(c => ({ tool: c.function.name, arguments: excerpt(c.function.arguments, 700) })) }, {
+    independent: { type: "noul", instructions: "Can every listed operation run concurrently without needing the result of another listed operation?" },
+  }, { jev })
+  const answer = result?.answers.independent
+  return result && answer?.type === "noul"
+    ? { parallel: answer.noul >= 0.8, decision: { latencyMs: result.latencyMs, costUsd: result.costUsd } }
+    : null
+}
+
+export async function planJevIteration(input: {
+  objective: string
+  messages: LLMMessage[]
+  tools: LLMToolDef[]
+  jev?: JevOption
+}): Promise<{ messages: LLMMessage[]; tools: LLMToolDef[]; action: string; omittedResults: number; decision: JevDecisionMetrics } | null> {
+  const toolIndices = input.messages.map((m, i) => m.role === "tool" ? i : -1).filter(i => i >= 0)
+  if (!toolIndices.length) return null
+  const older = toolIndices.slice(0, -1).slice(-8)
+  const prunableChars = older.reduce((sum, i) => sum + excerpt(input.messages[i].content, Infinity).length, 0)
+  if (prunableChars < MIN_PRUNABLE_CHARS) return null
+  const questions: Record<string, JevQuestion> = {
+    action: {
+      type: "choice",
+      instructions: "What capability should the text model use next to complete the current objective?",
+      criteria: {
+        continue: "Continue reasoning with currently available tools",
+        delegate: "Formulate a bounded task for an existing specialist",
+        discover: "Discover another tool or skill before continuing",
+        finish: "The evidence is sufficient to compose the final answer without more tools",
+      },
+    },
+  }
+  for (const i of older) questions[`result_${i}`] = {
+    type: "noul", instructions: `Is result ${i} still needed to complete the current objective?`,
+  }
+  const result = await askJev({
+    objective: input.objective.slice(0, 2800),
+    results: toolIndices.slice(-9).map(i => ({ id: i, tool: input.messages[i].name, content: excerpt(input.messages[i].content, 650) })),
+  }, questions, { jev: input.jev })
+  if (!result) return null
+  const omitted = new Set(older.filter(i => (probability(result.answers[`result_${i}`]) ?? 1) < 0.35))
+  const projected = input.messages.map((m, i) => omitted.has(i)
+    ? { ...m, content: "[Previous tool result omitted from this call]" } : m)
+  const answer = result.answers.action
+  const latestResult = input.messages[toolIndices[toolIndices.length - 1]]
+  const resultFailed = typeof latestResult.content === "string" && (latestResult.content.startsWith("[Tool Error]") || latestResult.content.includes('"error":true'))
+  const proposedAction = answer?.type === "choice" && answer.confidence >= (answer.choice === "finish" ? 0.85 : 0.7) ? answer.choice : "continue"
+  const action = proposedAction === "finish" && resultFailed ? "continue" : proposedAction
+  let tools = input.tools
+  if (action === "finish") tools = []
+  else if (action === "delegate") tools = tools.filter(t => ["task_delegate", "agent_find", "search_knowledge"].includes(t.function.name))
+  else if (action === "discover") tools = tools.filter(t => t.function.name === "search_knowledge")
+  const decision = { latencyMs: result.latencyMs, costUsd: result.costUsd }
+  if (action !== "finish" && tools.length === 0) return { messages: projected, tools: input.tools, action: "continue", omittedResults: omitted.size, decision }
+  return { messages: projected, tools, action, omittedResults: omitted.size, decision }
+}

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/agent/tool-selector.ts

@@ -195,6 +195,7 @@ export const CORE_TOOL_CATALOG: ToolDescriptor[] = [
 
     // Capability discovery
     { name: "search_knowledge", description: "Search everything Hive knows: native tools, MCP tools, skills, catalog agents and playbook rules. Spanish keywords: buscar herramienta, descubrir capacidades, qué puedo hacer, buscar skill, buscar conocimiento", category: "core", abstractionLevel: "atomic" },
+    { name: "conversation_read", description: "Read earlier messages from this conversation by ID or search text when context is missing. Spanish keywords: recuperar contexto, leer historial, conversación anterior", category: "core", abstractionLevel: "atomic" },
 
     // HTTP / REST
     { name: "api_request", description: "Perform an authorized HTTP request against a REST endpoint and validate the response. Spanish keywords: llamar api, request rest, consumir endpoint, petición http, hacer get, hacer post", category: "api", abstractionLevel: "atomic" },

package/packages/core/src/canvas/emitter.ts

@@ -15,6 +15,8 @@ export type CanvasEventType =
   | "canvas:edge_add"
   | "canvas:edge_remove"
   | "canvas:work_event"
+  | "canvas:jev_decision"
+  | "canvas:jev_status"
   | "ag-ui:event"
 
 export type CanvasWorkPhase =
@@ -65,6 +67,23 @@ export function unsubscribeCanvas(ws: { send: (data: string) => void }) {
   subscribers.delete(ws)
 }
 
+/** One Jev decision, shown by the office's oracle as a beam to the agent it advised. */
+export interface CanvasJevDecision {
+  eventId: string
+  agentId: string
+  kind: "context" | "iteration" | "parallel"
+  /** Short Spanish description of what was selected ("4/15 mensajes · 9/24 herramientas"). */
+  summary: string
+  /** Estimated main-model input tokens this decision avoided (chars/4); negative when it added context. */
+  savedTokens: number
+  latencyMs: number
+  costUsd: number
+  recommendedAgentId?: string | null
+  /** MCP servers the recommended specialist needs that are off; the coordinator asks the user to turn them on. */
+  mcpOff?: string[]
+  totals: { decisions: number; savedTokens: number; costUsd: number }
+}
+
 export function emitCanvas(type: CanvasEventType, data: any) {
   // Track live agent state for new subscribers
   if (type === "canvas:node_update" && data?.nodeId && data?.changes) {

package/packages/core/src/events/channel-narration.ts

@@ -49,6 +49,7 @@ const KIND_PREFIX: Record<NarrationEventDoc["kind"], string> = {
   verified: "✅",
   failed: "❌",
   group_ready: "📝",
+  decision: "🔮",
 };
 
 const DETAIL_MAX_CHARS = 200;
@@ -86,6 +87,8 @@ export async function resolveNarrationMode(channelType: string): Promise<Narrati
 
 export function shouldDeliverToChannel(event: NarrationEventDoc, mode: NarrationMode): boolean {
   if (mode === "off") return false;
+  // Internal bookkeeping for activity views, not something a customer reads.
+  if (event.kind === "decision") return false;
   if (MILESTONE_KINDS.has(event.kind)) return true;
   if (mode !== "all") return false;
   // Even in `all`, a successful tool_result only restates the tool_call that

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/services/swarms.ts

@@ -18,6 +18,7 @@ import { col } from "../storage/hive.ts";
 import type { SwarmDoc, SwarmMemberSpec, AgentDoc } from "../storage/collections.ts";
 import { runRoleSwarm, type RoleSwarmResult, type SwarmMessage } from "../swarm/RoleSwarm.ts";
 import type { ProviderCredentials } from "../agent/llm-client.ts";
+import type { JevOption } from "../agent/jev-decisions.ts";
 import { slugify } from "./agents.ts";
 import { logger } from "../utils/logger.ts";
 import { enableCatalogAgents, planActivationFor, CATALOG_AGENT_IDS, type ActivationGap } from "./setup.ts";
@@ -268,6 +269,8 @@ export interface RunSwarmOptions {
   channel?: string;
   /** Credenciales del inquilino, propagadas a cada agente. */
   credentials?: ProviderCredentials;
+  /** Jev del inquilino, propagado a cada agente igual que `credentials`. */
+  jev?: JevOption;
   signal?: AbortSignal;
   /** Se llama en cada paso; acá persiste el consumidor si quiere. */
   onMessage?: (message: SwarmMessage) => void | Promise<void>;
@@ -301,6 +304,7 @@ export async function runSwarm(
     orchestratorAgentId: swarm.orchestratorAgentId ?? undefined,
     maxDelegations: swarm.maxDelegations ?? undefined,
     credentials: opts?.credentials,
+    jev: opts?.jev,
     signal: opts?.signal,
     onMessage: opts?.onMessage,
   });

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

@@ -41,7 +41,7 @@ export interface ModelDoc {
   provider_id: string
   name: string
   /** "realtime": voz full-duplex (Live API), no confundir con stt+tts encadenados. */
-  model_type: "llm" | "stt" | "tts" | "vision" | "embedding" | "realtime"
+  model_type: "llm" | "stt" | "tts" | "vision" | "embedding" | "realtime" | "decision"
   context_window: number
   capabilities: string | null
   enabled: boolean
@@ -741,7 +741,8 @@ export interface NarrationEventDoc {
   session_id: string
   agent_id: string
   agent_name: string
-  kind: "delegated" | "worker_started" | "tool_call" | "tool_result" | "verified" | "failed" | "group_ready"
+  /** "decision": a Jev decision, recorded for the host's activity views; never delivered to a channel. */
+  kind: "delegated" | "worker_started" | "tool_call" | "tool_result" | "verified" | "failed" | "group_ready" | "decision"
   status: "queued" | "running" | "done" | "error"
   label: string
   detail: string | null
@@ -809,6 +810,12 @@ export interface UsageRollupDoc {
   toonJsonBytes: number
   byProvider: Record<string, { inputTokens: number; outputTokens: number; costUsd: number }>
   byModel: Record<string, { inputTokens: number; outputTokens: number; costUsd: number }>
+  /** Jev decision plane; absent on hours before it existed. Savings are estimates (chars/4) priced at the advised agent's model. */
+  jevDecisions?: number
+  jevCostUsd?: number
+  jevSavedTokens?: number
+  jevSavedCostUsd?: number
+  jevByAgent?: Record<string, { jevDecisions: number; jevCostUsd: number; jevSavedTokens: number; jevSavedCostUsd: number }>
 }
 
 export interface ActivityRollupDoc {

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,16 +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) return stored
+  if (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
 }
 
@@ -66,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`)
   }
@@ -84,12 +110,7 @@ async function _readCollectionSecret(name: string): Promise<string | null> {
     const secrets = await col<SecretDoc>("secrets")
     const entry = await secrets.get(name)
     if (!entry) return null
-    const plain = decryptSecret(entry.doc.ciphertext, entry.doc.iv)
-    if (plain) {
-      // Cache in memory for subsequent lookups in this process
-      _mem.set(name, plain)
-    }
-    return plain || null
+    return decryptSecret(entry.doc.ciphertext, entry.doc.iv) || null
   } catch {
     return null
   }
@@ -135,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,6 +218,17 @@ export async function loadProviderApiKey(id: string): Promise<string> {
   return (await _get(`provider:${id}:api_key`)) ?? ""
 }
 
+/**
+ * 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 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> {
   return await _set(`provider:${id}:headers`, JSON.stringify(headers))
 }