@johpaz/hive-sdk 0.4.8 → 0.5.0

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/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/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

@@ -51,7 +51,10 @@ async function _get(name: string): Promise<string | null> {
 
   // Durable store first — it is the one every write goes to.
   const stored = await _readCollectionSecret(name)
-  if (stored) return stored
+  if (stored) {
+    _mem.set(name, stored)
+    return stored
+  }
 
   // Legacy/desktop installs may only have the value in the OS keychain.
   const fromKeychain = await _keychainGet(name)
@@ -84,12 +87,8 @@ 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
+    // `_get` caches it; `loadDurableProviderApiKey` must not.
+    return decryptSecret(entry.doc.ciphertext, entry.doc.iv) || null
   } catch {
     return null
   }
@@ -195,6 +194,15 @@ export async function loadProviderApiKey(id: string): Promise<string> {
   return (await _get(`provider:${id}:api_key`)) ?? ""
 }
 
+/**
+ * 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.
+ */
+export async function loadDurableProviderApiKey(id: string): Promise<string> {
+  return (await _readCollectionSecret(`provider:${id}:api_key`)) ?? ""
+}
+
 export async function storeProviderHeaders(id: string, headers: Record<string, unknown>): Promise<boolean> {
   return await _set(`provider:${id}:headers`, JSON.stringify(headers))
 }

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

@@ -117,6 +117,7 @@ export const SEED_DATA: SeedData = {
     { id: "notify", name: "notify", category: "core", description: "Enviar notificación al usuario. Sinónimos: notificar, enviar notificación, alertar, aviso" },
     { id: "save_note", name: "save_note", category: "core", description: "Guardar nota persistente en el scratchpad. Sinónimos: guardar nota, escribir nota, recordatorio rápido, apuntar" },
     { id: "report_progress", name: "report_progress", category: "core", description: "Reportar progreso actual al usuario. Sinónimos: reportar progreso, informar estado, actualizar progreso, porcentaje" },
+    { id: "conversation_read", name: "conversation_read", category: "core", description: "Recuperar mensajes anteriores de esta conversación por ID o búsqueda de texto. Sinónimos: leer conversación, recuperar contexto, historial omitido" },
 
     // ─────────────────────────────────────────
     // 10. OFFICE — Archivos Office (PDF, DOCX, XLSX, PPTX)
@@ -235,6 +236,9 @@ export const SEED_DATA: SeedData = {
     { id: "kimi-k2.6", providerId: "kimi", name: "Kimi K2.6", modelType: "llm", contextWindow: 262144, capabilities: JSON.stringify(["chat", "vision", "json_mode", "function_calling", "streaming", "code"]), inputPer1M: 0.6, outputPer1M: 3.41 },
 
     // ── OpenRouter (fuente: GET https://openrouter.ai/api/v1/models) ──
+    // Jev: modelo de decisiones (API Decisions, nunca chat). `modelType:
+    // "decision"` lo deja fuera de getDefaultLLM y de get_available_models.
+    { id: "typesafe/jev-1.13", providerId: "openrouter", name: "Jev 1.13 (Decisions)", modelType: "decision", contextWindow: 32000, capabilities: JSON.stringify(["choice", "noul", "score"]), inputPer1M: 0.042, outputPer1M: 0 },
     // Solo modelos vivos con `tools` en supported_parameters y publicados desde
     // 2025-07. contextWindow = context_length reportado por el propio catálogo,
     // y los precios también salen de ahí — son los de la ruta de OpenRouter, no

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

@@ -154,6 +154,15 @@ export interface UsageRecord {
   created_at: number;
 }
 
+export interface JevUsageSummary {
+  decisions: number;
+  costUsd: number;
+  /** Estimated main-model input tokens avoided; negative when Jev added more than it removed. */
+  savedTokens: number;
+  savedCostUsd: number;
+  byAgent: Record<string, { decisions: number; costUsd: number; savedTokens: number; savedCostUsd: number }>;
+}
+
 export interface UsageSummary {
   totalTokens: number;
   totalInputTokens: number;
@@ -169,6 +178,7 @@ export interface UsageSummary {
   byProvider: Record<string, { tokens: number; costUsd: number; inputTokens: number; outputTokens: number }>;
   byModel: Record<string, { tokens: number; costUsd: number; provider: string; inputTokens: number; outputTokens: number }>;
   recentRecords: UsageRecord[];
+  jev: JevUsageSummary;
 }
 
 export function recordUsage(options: {
@@ -233,13 +243,15 @@ export async function getUsageStats(hours: number = 24): Promise<UsageSummary> {
   const rollupsCol = await col<UsageRollupDoc>("usageRollups");
   const buckets = hourBucketsSince(hours);
   const rollups = (await Promise.all(buckets.map((id) => rollupsCol.get(id))))
-    .map((e) => e?.doc ?? emptyRollup());
+    // A bucket touched only by recordJevDecision lacks the token fields.
+    .map((e) => ({ ...emptyRollup(), ...e?.doc }));
 
   const providerMap: UsageSummary["byProvider"] = {};
   const modelMap: UsageSummary["byModel"] = {};
   let totalInput = 0, totalOutput = 0, totalCost = 0;
   let toonSavedTokens = 0, toonSavedCost = 0, toonSavedBytes = 0;
   let toonJsonTokens = 0, toonToonTokens = 0, toonJsonBytes = 0;
+  const jev: JevUsageSummary = { decisions: 0, costUsd: 0, savedTokens: 0, savedCostUsd: 0, byAgent: {} };
 
   for (const r of rollups) {
     totalInput += r.inputTokens;
@@ -251,6 +263,18 @@ export async function getUsageStats(hours: number = 24): Promise<UsageSummary> {
     toonJsonTokens += r.toonJsonTokens;
     toonToonTokens += r.toonToonTokens;
     toonJsonBytes += r.toonJsonBytes;
+    jev.decisions += r.jevDecisions ?? 0;
+    jev.costUsd += r.jevCostUsd ?? 0;
+    jev.savedTokens += r.jevSavedTokens ?? 0;
+    jev.savedCostUsd += r.jevSavedCostUsd ?? 0;
+    for (const [agentId, a] of Object.entries(r.jevByAgent ?? {})) {
+      const cur = jev.byAgent[agentId] ?? { decisions: 0, costUsd: 0, savedTokens: 0, savedCostUsd: 0 };
+      cur.decisions += a.jevDecisions ?? 0;
+      cur.costUsd += a.jevCostUsd ?? 0;
+      cur.savedTokens += a.jevSavedTokens ?? 0;
+      cur.savedCostUsd += a.jevSavedCostUsd ?? 0;
+      jev.byAgent[agentId] = cur;
+    }
 
     for (const [provider, p] of Object.entries(r.byProvider ?? {})) {
       const cur = providerMap[provider] ?? { tokens: 0, costUsd: 0, inputTokens: 0, outputTokens: 0 };
@@ -301,10 +325,39 @@ export async function getUsageStats(hours: number = 24): Promise<UsageSummary> {
     toonSavingsPercent,
     byProvider: providerMap,
     byModel: modelMap,
-    recentRecords
+    recentRecords,
+    jev,
   };
 }
 
+/**
+ * Persists one Jev decision into the hourly rollup. The avoided tokens are
+ * priced with the advised agent's own model (input rate), through the same
+ * catalog lookup as real usage, so "saved" and "spent" are comparable.
+ */
+export function recordJevDecision(options: {
+  agentId: string;
+  provider: string;
+  model: string;
+  savedTokens: number;
+  costUsd: number;
+}): void {
+  Promise.resolve().then(async () => {
+    try {
+      const unitCost = await calculateCost(options.provider, options.model, Math.abs(options.savedTokens), 0);
+      const savedCostUsd = Math.sign(options.savedTokens) * unitCost;
+      await bumpRollup("usageRollups", hourBucket(Date.now()), {
+        jevDecisions: 1,
+        jevCostUsd: options.costUsd,
+        jevSavedTokens: options.savedTokens,
+        jevSavedCostUsd: savedCostUsd,
+      }, { field: "jevByAgent", key: options.agentId });
+    } catch (error) {
+      log.warn(`[JEV] Failed to record decision:`, error);
+    }
+  });
+}
+
 /**
  * Record TOON savings for metrics tracking
  * This updates the usage_records table with complete TOON compression metrics

package/packages/core/src/swarm/RoleSwarm.ts

@@ -21,6 +21,7 @@
  */
 
 import { runAgentIsolated } from "../agent/agent-loop.ts"
+import type { JevOption } from "../agent/jev-decisions.ts"
 import type { ProviderCredentials } from "../agent/llm-client.ts"
 import { logger } from "../utils/logger.ts"
 
@@ -50,6 +51,7 @@ export type AgentInvoker = (input: {
   threadId: string
   channel?: string
   credentials?: ProviderCredentials
+  jev?: JevOption
   signal?: AbortSignal
 }) => Promise<string>
 
@@ -60,6 +62,7 @@ export const defaultInvoker: AgentInvoker = async (input) =>
     threadId: input.threadId,
     channel: input.channel,
     credentials: input.credentials,
+    jev: input.jev,
     signal: input.signal,
   })
 
@@ -83,6 +86,8 @@ export interface RoleSwarmOptions {
   maxDelegations?: number
   /** 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>
@@ -129,6 +134,7 @@ export async function runRoleSwarm(opts: RoleSwarmOptions): Promise<RoleSwarmRes
       threadId,
       channel: opts.channel,
       credentials: opts.credentials,
+      jev: opts.jev,
       signal: opts.signal,
     })
   }