@johpaz/hive-sdk 0.4.9 → 0.5.0

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

@@ -0,0 +1,199 @@
+/** 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 { recordJevDecision, recordUsage } from "../storage/usage.ts"
+import { catalogModelKey } from "../storage/model-id.ts"
+import { currentTenant } from "../storage/tenant.ts"
+import { logger } from "../utils/logger.ts"
+import { emitCanvas, type CanvasJevDecision } from "../canvas/emitter.ts"
+
+const log = logger.child("jev-decisions")
+export const JEV_MODEL = "typesafe/jev-1.13"
+const ENDPOINT = "https://openrouter.ai/api/alpha/decisions"
+const TIMEOUT_MS = 3000
+const COOLDOWN_MS = 60_000
+/** Where the user turns an MCP server on, when the host does not say otherwise. */
+export const DEFAULT_JEV_MCP_SETTINGS_PATH = "Ajustes → Entorno → MCP Servers"
+let decisionSequence = 0
+
+/**
+ * How a caller controls Jev for one run.
+ *
+ * - `{ apiKey }`: use this OpenRouter key. A multi-tenant host resolves its
+ *   tenant's key and passes it here, exactly like `credentials`.
+ *   `mcpSettingsPath` names where that host's users turn an MCP server on.
+ * - `false`: Jev is off for this run; nothing is sent to OpenRouter.
+ * - `undefined`: the `openrouter` provider row of the current tenant decides.
+ */
+export type JevOption = { apiKey: string; mcpSettingsPath?: string } | false
+
+/**
+ * Failure and cooldown bookkeeping, per tenant: one tenant's invalid key must
+ * not put every other tenant in the same process into fallback.
+ */
+interface JevTenantState {
+  failures: number
+  cooldownUntil: number
+  lastError: string | null
+  lastSuccessAt: number | null
+  /** Since process start; the office shows them as the oracle's running contribution. */
+  totals: { decisions: number; savedTokens: number; costUsd: number }
+}
+
+const states = new Map<string, JevTenantState>()
+
+function tenantState(): JevTenantState {
+  const key = currentTenant() ?? "default"
+  let state = states.get(key)
+  if (!state) {
+    state = { failures: 0, cooldownUntil: 0, lastError: null, lastSuccessAt: null, totals: { decisions: 0, savedTokens: 0, costUsd: 0 } }
+    states.set(key, state)
+  }
+  return state
+}
+
+export type JevQuestion =
+  | { type: "choice"; instructions: string; criteria: Record<string, string> }
+  | { type: "noul"; instructions: string; criteria?: { true: string; false: string } }
+
+export type JevAnswer =
+  | { type: "choice"; choice: string; confidence: number; probabilities: Record<string, number> }
+  | { type: "noul"; noul: number }
+
+export interface JevResult {
+  answers: Record<string, JevAnswer>
+  inputTokens: number
+  costUsd: number
+  latencyMs: number
+}
+
+/**
+ * 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.
+ */
+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
+}
+
+export interface JevStatus {
+  state: "off" | "ready" | "fallback"
+  lastError: string | null
+  lastSuccessAt: number | null
+  totals: { decisions: number; savedTokens: number; costUsd: number }
+}
+
+export async function getJevStatus(option?: JevOption): Promise<JevStatus> {
+  const key = await getJevKey(option).catch(() => null)
+  const state = tenantState()
+  return {
+    state: !key ? "off" : Date.now() < state.cooldownUntil || state.lastError ? "fallback" : "ready",
+    lastError: key ? state.lastError : null,
+    lastSuccessAt: key ? state.lastSuccessAt : null,
+    totals: { ...state.totals },
+  }
+}
+
+function broadcastStatus(option?: JevOption): void {
+  getJevStatus(option).then(status => emitCanvas("canvas:jev_status", status)).catch(() => { /* best effort */ })
+}
+
+/**
+ * Publishes a served decision to the office and persists it for the dashboard.
+ * Callers estimate savings; Jev itself only answers questions. `provider`/`model`
+ * are the advised agent's main model, used to price the avoided tokens.
+ * Returns the published event so the caller can forward it to its own host.
+ */
+export function emitJevDecision({ provider, model, ...decision }: Omit<CanvasJevDecision, "eventId" | "totals"> & { provider: string; model: string }): CanvasJevDecision {
+  recordJevDecision({ agentId: decision.agentId, provider, model, savedTokens: decision.savedTokens, costUsd: decision.costUsd })
+  const { totals } = tenantState()
+  totals.decisions++
+  totals.savedTokens += decision.savedTokens
+  totals.costUsd += decision.costUsd
+  const event = {
+    ...decision,
+    eventId: `jev:${Date.now().toString(36)}:${++decisionSequence}`,
+    summary: decision.summary.slice(0, 160),
+    totals: { ...totals },
+  } satisfies CanvasJevDecision
+  emitCanvas("canvas:jev_decision", event)
+  return event
+}
+
+/** Clears the current tenant's failure state (after its key changed, for instance). */
+export function resetJevStatus(option?: JevOption): void {
+  const state = tenantState()
+  state.failures = 0
+  state.cooldownUntil = 0
+  state.lastError = null
+  state.lastSuccessAt = null
+  broadcastStatus(option)
+}
+
+export async function askJev(
+  state: unknown,
+  questions: Record<string, JevQuestion>,
+  options: { fetcher?: typeof fetch; signal?: AbortSignal; jev?: JevOption } = {},
+): Promise<JevResult | null> {
+  const key = await getJevKey(options.jev).catch(() => null)
+  const tenant = tenantState()
+  if (!key || Date.now() < tenant.cooldownUntil || Object.keys(questions).length === 0) return null
+  const started = performance.now()
+  try {
+    const response = await (options.fetcher ?? fetch)(ENDPOINT, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ model: JEV_MODEL, state, questions }),
+      signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(TIMEOUT_MS)]) : AbortSignal.timeout(TIMEOUT_MS),
+    })
+    if (!response.ok) {
+      if (response.status === 401 || response.status === 403) tenant.cooldownUntil = Date.now() + COOLDOWN_MS
+      throw new Error(`OpenRouter HTTP ${response.status}`)
+    }
+    const data = await response.json() as {
+      answers?: Record<string, JevAnswer>
+      usage?: { input_tokens?: number; output_tokens?: number; cost?: number }
+    }
+    const answers: Record<string, JevAnswer> = {}
+    for (const [name, question] of Object.entries(questions)) {
+      const answer = data.answers?.[name]
+      if (question.type === "choice") {
+        if (answer?.type !== "choice" || !Object.hasOwn(question.criteria, answer.choice) ||
+          !Number.isFinite(answer.confidence) || answer.confidence < 0 || answer.confidence > 1) {
+          throw new Error(`Invalid choice answer: ${name}`)
+        }
+      } else if (answer?.type !== "noul" || !Number.isFinite(answer.noul) || answer.noul < 0 || answer.noul > 1) {
+        throw new Error(`Invalid noul answer: ${name}`)
+      }
+      answers[name] = answer
+    }
+    const recovered = tenant.lastError !== null
+    tenant.failures = 0
+    tenant.lastError = null
+    tenant.lastSuccessAt = Date.now()
+    if (recovered) broadcastStatus(options.jev)
+    const inputTokens = data.usage?.input_tokens ?? 0
+    const costUsd = data.usage?.cost ?? inputTokens * 0.042 / 1_000_000
+    log.info(`Decision served: questions=${Object.keys(questions).join(",")} latency_ms=${Math.round(performance.now() - started)} input_tokens=${inputTokens} cost_usd=${costUsd}`)
+    if (inputTokens > 0) {
+      recordUsage({ provider: "openrouter", model: catalogModelKey("openrouter", JEV_MODEL), inputTokens, outputTokens: data.usage?.output_tokens ?? 0, latencyMs: Math.round(performance.now() - started) })
+    }
+    return { answers, inputTokens, costUsd, latencyMs: Math.round(performance.now() - started) }
+  } catch (error) {
+    if (options.signal?.aborted) return null
+    tenant.failures++
+    tenant.lastError = error instanceof Error ? error.message : "Jev unavailable"
+    if (tenant.failures >= 3) tenant.cooldownUntil = Date.now() + COOLDOWN_MS
+    log.warn(`Decision fallback: ${tenant.lastError}`)
+    broadcastStatus(options.jev)
+    return null
+  }
+}

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