@johpaz/hive-sdk 0.4.8 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,57 @@
 # Changelog
 
-## Sin publicar
+## 0.5.0
+
+### Jev — plano de decisión (OpenRouter Decisions)
+
+Portado de hive 1.1.0. Jev decide por turno qué historial, herramientas,
+skills, notas y reglas del playbook entran al contexto; entre iteraciones poda
+resultados viejos de herramientas y sugiere la siguiente acción; decide si un
+lote de herramientas corre en paralelo, y conoce el mapa del enjambre
+(especialistas y estado de cada MCP) para recomendar a quién delegar.
+**Sin clave de OpenRouter, Jev no existe y todo corre igual que antes.**
+
+- **Clave inyectable por llamada**: `jev?: { apiKey, mcpSettingsPath? } | false`
+  en `AgentLoopOptions`, `compileContext`, `IsolatedAgentOptions`,
+  `runRoleSwarm` y `runSwarm`, igual que `credentials`. `false` lo apaga;
+  sin la opción decide la fila `openrouter` del inquilino actual. Con un
+  inquilino activo **nunca** se usa `OPENROUTER_API_KEY` ni la caché de
+  secretos del proceso: la clave de la plataforma no se usa en nombre de un
+  cliente.
+- **Estado por inquilino**: fallos, cooldown y totales se llevan por
+  `currentTenant()`; una clave inválida de un cliente no pone en fallback a
+  los demás.
+- **Evento para el host**: cada decisión llega por `onStep` como
+  `StepEvent` `jev_decision` (`jev`: agente, tipo, resumen, tokens ahorrados,
+  latencia, costo, especialista recomendado, MCP apagados). También se emite
+  `canvas:jev_decision` / `canvas:jev_status` para hosts tipo hive.
+- **Uso y costo**: `recordJevDecision` y los campos `jev*` de
+  `UsageRollupDoc`; `getUsageStats()` devuelve `jev` con el total y el
+  desglose por agente. El ahorro se estima (caracteres/4) y se cotiza con el
+  modelo del agente asesorado.
+- **Catálogo**: modelo `openrouter/typesafe/jev-1.13` con `modelType:
+  "decision"`, excluido de `get_available_models` (y de `getDefaultLLM`, que
+  sólo toma modelos `llm`).
+- Herramienta nueva `conversation_read`: recupera mensajes o notas que Jev
+  dejó fuera del contexto, siempre dentro del hilo actual.
+- `executeToolBatch` acepta `parallelToolCalls` por lote.
+- `NarrationEventDoc.kind` suma `"decision"`: un host puede anotar las
+  decisiones de Jev en `narrationEvents` para sus vistas de actividad.
+  `shouldDeliverToChannel` nunca lo entrega a un canal.
+- `loadDurableProviderApiKey(id)`: lee la clave sólo de la colección
+  `secrets` (particionada por inquilino), sin pasar por la caché de proceso ni
+  el llavero del SO.
+
+**Privacidad.** Con Jev activo se envían a la API de decisiones de OpenRouter
+(`https://openrouter.ai/api/alpha/decisions`), con la clave del workspace:
+el objetivo del turno (hasta 3 500 caracteres), extractos de hasta 450
+caracteres de mensajes previos del hilo, nombre y descripción de herramientas
+y skills candidatas, notas del scratchpad y reglas del playbook (hasta 350
+caracteres cada una), extractos de resultados de herramientas (hasta 650
+caracteres), argumentos de llamadas en lote (hasta 700) y el mapa del enjambre
+(ids, nombres y descripciones de especialistas, nombres y estado de los MCP).
+No se envían ids de MCP con prefijo de inquilino, credenciales ni adjuntos
+binarios. Un host que no quiera enviar nada pasa `jev: false`.
 
 ### Plataforma y seguridad
 
@@ -579,6 +630,29 @@
   job que genera un scaffold con `create-app` y lo typechequea contra el SDK de
   ese commit.
 
+## 0.4.9
+
+### Corregido
+
+- **La compactación de historial dejaba de ser excepcional y corría casi en cada
+  turno.** `agent.context.compactionThreshold` es una proporción de la ventana
+  del modelo —su valor por defecto es `0.8`, o sea el 80 %— pero se leía como un
+  número de tokens: el umbral efectivo quedaba en 0.8 tokens. Cualquier hilo con
+  más de cinco mensajes se resumía en cada turno, lo que cuesta una llamada extra
+  al modelo por mensaje y reemplaza el historial por un resumen desde el primer
+  intercambio. Ahora un valor menor o igual a 1 se aplica sobre la ventana del
+  modelo y uno mayor se sigue leyendo como tokens, para quien fijó un número
+  absoluto. El umbral se calcula además con la ventana del modelo que corre el
+  turno, no con la del coordinador.
+- **El resumen se pedía con una credencial global.** `compactThread` resolvía el
+  modelo con `getDefaultLLM()` y llamaba a `resolveProviderConfig` sin
+  credenciales, así que la llave salía del secret store, del llavero del sistema
+  o del entorno del proceso. En una instalación de un solo usuario da igual; en
+  una multi-inquilino significa resumir la conversación de un cliente con la
+  llave de la plataforma o de otro cliente. `maybeCompact` y `compactThread`
+  aceptan ahora el modelo y las credenciales del turno (`CompactionLLM`), y el
+  agent loop les pasa los suyos. Sin ese dato se comportan como antes.
+
 ## 0.1.5
 
 Sincronización del SDK con el runtime de agentes de `hive`. **Trae rupturas de

package/README.md

@@ -271,4 +271,4 @@ npm view @johpaz/hive-sdk dist-tags   # verificar después del release
 
 ---
 
-*Hive SDK v0.4.8 — MIT*
+*Hive SDK v0.5.0 — MIT*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "private": false,
   "description": "Hive SDK — The Agent Harness SDK. Build, deploy, and scale AI agent applications with multi-channel support, context engineering, and swarm orchestration.",
   "license": "MIT",

package/packages/core/src/agent/agent-loop.ts

@@ -23,9 +23,12 @@ import { callLLM, resolveProviderConfig, getDefaultLLM, type LLMMessage, type Pr
 import { addMessage } from "./conversation-store.ts"
 import { saveTrace, recordLLMUsage } from "./tracer.ts"
 import { maybeCompact, clearOldToolResults } from "./compaction.ts"
-import { emitCanvas } from "../canvas/emitter.ts"
+import { emitCanvas, type CanvasJevDecision } from "../canvas/emitter.ts"
 import type { MCPClientManager } from "../mcp/index.ts"
 import { compileContext } from "./context-compiler.ts"
+import { MINIMAL_TOOLS } from "./minimal-loadout.ts"
+import { jevWantsParallel, planJevIteration } from "./jev-planner.ts"
+import { emitJevDecision, type JevOption } from "./jev-decisions.ts"
 import { formatToolResult } from "../utils/toon.ts"
 import { redactBinaryStrings } from "../utils/redact-binary.ts"
 import { resolveUserId, resolveAgentId } from "../storage/onboarding.ts"
@@ -52,6 +55,10 @@ import { getNarration } from "../events/tool-narration.ts"
 
 const log = logger.child("agent-loop")
 
+const JEV_ACTION_LABELS: Record<string, string> = {
+  continue: "Continuar", delegate: "Delegar", discover: "Descubrir", finish: "Cerrar",
+}
+
 // Per-operation budget for a single LLM call — NOT an aggregate deadline for the
 // whole turn. Each call gets its own fresh window; a slow-but-healthy multi-step
 // turn (many quick operations) is never killed just for taking a while overall.
@@ -226,6 +233,12 @@ export interface AgentLoopOptions {
    * dos inquilinos concurrentes en el mismo proceso compartían credencial.
    */
   credentials?: ProviderCredentials
+  /**
+   * Jev (OpenRouter Decisions) for this run. `{ apiKey }` uses that key,
+   * `false` turns it off, undefined reads the current tenant's `openrouter`
+   * provider row. Travels with the run like `credentials`.
+   */
+  jev?: JevOption
   /** Whether to resume from a previously saved checkpoint */
   resume?: boolean
   /** Run budget — overrides agent.max_iterations when set */
@@ -258,12 +271,17 @@ export interface AgentLoopOptions {
 export type { StepEvent as AgentStepEvent }
 
 export interface StepEvent {
-  type: "text" | "tool_call" | "tool_result"
+  type: "text" | "tool_call" | "tool_result" | "jev_decision"
   message: string
   toolName?: string
   isError?: boolean
+  /** Present on `jev_decision`: what Jev decided for this run, its cost and the estimated savings. */
+  jev?: JevStepDecision
 }
 
+/** One Jev decision as the host receives it through `onStep`. */
+export type JevStepDecision = CanvasJevDecision
+
 // ─── Stream chunk types (compatible with providers/index.ts) ─────────────────
 
 export interface StreamChunk {
@@ -357,12 +375,20 @@ export async function* runAgent(
       channel: opts.channel,
       source: opts.historySource ?? "message",
     })
-    // Run compaction if conversation history is getting large
+    // Run compaction if conversation history is getting large.
+    // El modelo del turno viaja con sus credenciales: el resumen es una llamada
+    // al modelo como cualquier otra y tiene que cobrarse a la misma cuenta.
     await maybeCompact(
       opts.threadId,
       opts.channel && opts.userId
         ? { channel: opts.channel, userId: opts.userId }
-        : undefined
+        : undefined,
+      {
+        provider: providerCfg.provider,
+        model: providerCfg.model,
+        credentials: opts.credentials,
+        contextWindow: providerCfg.contextWindow,
+      }
     )
   }
 
@@ -377,8 +403,25 @@ export async function* runAgent(
     taskContext: opts.taskContext,
     userId: opts.userId,
     causalStreamId,
+    skipJev: !!opts.resume,
+    jev: opts.jev,
   })
 
+  // Every decision goes to the canvas (hosts like hive) and to onStep (hosts
+  // that drive runAgent themselves, like hive-cloud).
+  const publishJev = async (decision: Parameters<typeof emitJevDecision>[0]): Promise<void> => {
+    const event = emitJevDecision(decision)
+    if (!opts.onStep) return
+    try {
+      await opts.onStep({ type: "jev_decision", message: event.summary, jev: event })
+    } catch (err) {
+      log.warn(`[agent-loop] onStep(jev_decision) failed: ${(err as Error).message}`)
+    }
+  }
+  if (ctx.jevDecision) {
+    await publishJev({ ...ctx.jevDecision, agentId: opts.agentId, kind: "context", provider: providerCfg.provider, model: providerCfg.model })
+  }
+
   // Force extra tools into the loadout (tests/evals)
   if (opts.extraTools?.length) {
     const existingNames = new Set(ctx.tools.map((t: any) => t.function?.name))
@@ -409,9 +452,12 @@ export async function* runAgent(
   if (opts.isolated) {
     messages.push({ role: "user", content: opts.userMessage })
   }
+  const jevObjective = typeof opts.userMessage === "string" ? opts.userMessage :
+    opts.userMessage.filter((part) => part.type === "text").map((part) => (part as { text: string }).text).join("\n")
 
   // ── Resume from checkpoint ─────────────────────────────────────────────────
-  let injectedToolNames: string[] = []
+  // Seeded with the compiled loadout so a checkpoint records the tools Jev chose.
+  let injectedToolNames: string[] = ctx.tools.map(t => t.function.name).filter(name => !MINIMAL_TOOLS.has(name))
   let systemPromptSkillSections: string[] = []
   let resumedFromPending = false
   let iterations = 0
@@ -432,6 +478,15 @@ export async function* runAgent(
       if (restored) {
         messages = restored.messages
         injectedToolNames = restored.injectedToolNames ?? []
+        // A resume skips Jev: restore the loadout the checkpoint recorded.
+        const currentTools = new Set(ctx.tools.map(t => t.function.name))
+        for (const name of injectedToolNames) {
+          const tool = ctx.allTools.find(t => t.name === name)
+          if (tool && !currentTools.has(name)) {
+            ctx.tools.push({ type: "function", function: { name: tool.name, description: tool.description, parameters: tool.parameters } })
+            currentTools.add(name)
+          }
+        }
         systemPromptSkillSections = restored.systemPromptSkillSections ?? []
         iterations = restored.iterations ?? 0
         totalInputTokens = restored.totalInputTokens ?? 0
@@ -517,11 +572,27 @@ export async function* runAgent(
       : null
     let streamedThisCall = false
     let response: Awaited<ReturnType<typeof callLLM>>
+    const jevIteration = await planJevIteration({ objective: jevObjective, messages, tools: ctx.tools, jev: opts.jev })
+      .catch((err) => { log.warn(`[agent-loop] Jev iteration fallback: ${(err as Error).message}`); return null })
+    const callMessages = jevIteration?.messages ?? messages
+    const callTools = jevIteration?.tools ?? ctx.tools
+    if (jevIteration) {
+      log.info(`[agent-loop] Jev action=${jevIteration.action} omitted_results=${jevIteration.omittedResults} tools=${callTools.map(t => t.function.name).join(",")}`)
+      // Measured on what the provider actually receives, after the usual truncation.
+      const payloadChars = (msgs: LLMMessage[], tools: typeof ctx.tools) =>
+        JSON.stringify(clearOldToolResults(msgs)).length + JSON.stringify(tools).length
+      await publishJev({
+        agentId: opts.agentId, kind: "iteration", provider: providerCfg.provider, model: providerCfg.model,
+        summary: `${JEV_ACTION_LABELS[jevIteration.action] ?? jevIteration.action} · ${jevIteration.omittedResults} resultado(s) omitido(s) · ${callTools.length}/${ctx.tools.length} herramientas`,
+        savedTokens: Math.round((payloadChars(messages, ctx.tools) - payloadChars(callMessages, callTools)) / 4),
+        latencyMs: jevIteration.decision.latencyMs, costUsd: jevIteration.decision.costUsd,
+      })
+    }
     try {
       response = await withTimeout(() => callLLM({
         ...providerCfg,
-        messages: clearOldToolResults(messages) as LLMMessage[],
-        tools: ctx.tools.length > 0 ? ctx.tools : undefined,
+        messages: clearOldToolResults(callMessages) as LLMMessage[],
+        tools: callTools.length > 0 ? callTools : undefined,
         signal: opts.signal,
         sessionId: opts.threadId,
         onToken: opts.onToken && !delegationGroupAtCall
@@ -681,6 +752,16 @@ export async function* runAgent(
       }
     }
 
+    const jevParallel = await jevWantsParallel(response.tool_calls, opts.jev)
+      .catch((err) => { log.warn(`[agent-loop] Jev parallel fallback: ${(err as Error).message}`); return null })
+    if (jevParallel?.decision) {
+      log.info(`[agent-loop] Jev parallel=${jevParallel.parallel} calls=${response.tool_calls.length}`)
+      await publishJev({
+        agentId: opts.agentId, kind: "parallel", provider: providerCfg.provider, model: providerCfg.model,
+        summary: `${response.tool_calls.length} herramientas ${jevParallel.parallel ? "en paralelo" : "en secuencia"}`,
+        savedTokens: 0, latencyMs: jevParallel.decision.latencyMs, costUsd: jevParallel.decision.costUsd,
+      })
+    }
     const toolResults = await executeToolBatch({
       toolCalls: response.tool_calls,
       allTools: ctx.allTools,
@@ -701,6 +782,7 @@ export async function* runAgent(
       },
       hiveConfig,
       workerPool: hiveConfig.tools?.workerPool,
+      parallelToolCalls: jevParallel?.parallel,
       signal: opts.signal,
     })
 
@@ -1297,6 +1379,8 @@ export interface IsolatedAgentOptions {
    * reabría justo en el camino de delegación.
    */
   credentials?: ProviderCredentials
+  /** Jev for the worker, inherited from the delegating turn like `credentials`. */
+  jev?: JevOption
 }
 
 export async function runAgentIsolatedDetailed(
@@ -1321,6 +1405,7 @@ export async function runAgentIsolatedDetailed(
     channel: opts.channel,
     sessionId: opts.sessionId,
     credentials: opts.credentials,
+    jev: opts.jev,
   })) {
     if (chunk.agent?.messages?.[0]?.content) {
       lastContent = chunk.agent.messages[0].content

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

@@ -26,7 +26,10 @@ import {
   type StoredMessage,
 } from "./conversation-store.ts"
 import { estimateTokens } from "../utils/toon.ts"
-import { callLLM, resolveProviderConfig, getDefaultLLM, type ContentPart } from "./llm-client.ts"
+import {
+  callLLM, resolveProviderConfig, getDefaultLLM,
+  type ContentPart, type ProviderCredentials,
+} from "./llm-client.ts"
 import { col, fromIndexable } from "../storage/hive.ts"
 import type { AgentDoc, ModelDoc } from "../storage/collections.ts"
 import { loadConfig } from "../config/loader.ts"
@@ -41,6 +44,61 @@ const KEEP_LAST_N_MESSAGES = 5         // always keep most recent N messages
 const TOOL_RESULT_MAX_CHARS = 200      // max chars for old tool results after clearing
 const MAX_TRANSCRIPT_MSGS = 30         // cap messages sent to summarizer (avoids OOM on small models)
 const MAX_MSG_CHARS = 300              // chars per message in transcript
+/** Ventana asumida cuando no se conoce la del modelo: `COMPACT_TOKEN_THRESHOLD` es su 25 %. */
+const ASSUMED_CONTEXT_WINDOW = 128_000
+const DEFAULT_CONTEXT_RATIO = 0.25
+
+/**
+ * El modelo con el que se pide el resumen: el del turno que disparó la
+ * compactación, con SUS credenciales.
+ */
+export interface CompactionLLM {
+  provider?: string
+  model?: string
+  /** En multi-inquilino, la llave del cliente. Sin esto se usaría una global. */
+  credentials?: ProviderCredentials
+  /** La ventana del modelo, si quien llama ya la resolvió. */
+  contextWindow?: number
+}
+
+/**
+ * A partir de cuántos tokens de historial se compacta.
+ *
+ * `agent.context.compactionThreshold` es una PROPORCIÓN de la ventana del
+ * modelo —su valor por defecto es 0.8, o sea el 80 %—, pero se leía como si
+ * fueran tokens. Con la configuración por defecto el umbral quedaba en 0.8
+ * tokens: cualquier hilo con más de cinco mensajes se resumía en cada turno,
+ * pagando una llamada extra al modelo y reemplazando el historial por un
+ * resumen desde el primer intercambio. Un valor mayor que 1 se sigue leyendo
+ * como tokens, que es lo que espera quien fijó un número absoluto.
+ */
+export function resolveCompactionThreshold(configured: number | undefined, contextWindow?: number): number {
+  const known = contextWindow && contextWindow > 0 ? contextWindow : undefined
+  if (typeof configured === "number" && Number.isFinite(configured) && configured > 0) {
+    return configured <= 1
+      ? Math.floor((known ?? ASSUMED_CONTEXT_WINDOW) * configured)
+      : Math.floor(configured)
+  }
+  return known ? Math.floor(known * DEFAULT_CONTEXT_RATIO) : COMPACT_TOKEN_THRESHOLD
+}
+
+/** La ventana del modelo del turno; si no se sabe cuál es, la del coordinador. */
+async function modelContextWindow(modelId?: string): Promise<number | undefined> {
+  try {
+    const modelsCol = await col<ModelDoc>("models")
+    if (modelId) return (await modelsCol.get(modelId))?.doc.context_window || undefined
+    const agentsCol = await col<AgentDoc>("agents")
+    const coordinators = await agentsCol.findBy("role", "coordinator", { limit: 1 })
+    // El id se busca completo: recortar el primer segmento rompía cualquier
+    // modelo cuyo nombre lleve barra (meta/llama-3.3-70b-instruct buscaba
+    // "llama-3.3-70b-instruct", no encontraba nada y caía al default).
+    const id = fromIndexable(coordinators[0]?.doc.model_id ?? null)
+    if (!id) return undefined
+    return (await modelsCol.get(id))?.doc.context_window || undefined
+  } catch {
+    return undefined
+  }
+}
 
 /**
  * Check if compaction is needed and run it if so.
@@ -48,37 +106,16 @@ const MAX_MSG_CHARS = 300              // chars per message in transcript
  */
 export async function maybeCompact(
   threadId: string,
-  notify?: { channel: string; userId: string }
+  notify?: { channel: string; userId: string },
+  llm?: CompactionLLM
 ): Promise<void> {
   try {
     const totalTokens = await getTotalTokens(threadId)
-
-    // Orden de precedencia: lo que el usuario configuró gana sobre lo que se
-    // deduce del modelo, y eso gana sobre la constante.
-    //
-    // `agent.context.compactionThreshold` estaba en el esquema de configuración
-    // y **no lo leía nadie**: alguien podía ajustarlo y no pasaba nada. Una
-    // opción que no hace nada es peor que no tenerla, porque el usuario cree
-    // que cambió algo.
-    let effectiveThreshold = COMPACT_TOKEN_THRESHOLD
-    const configurado = loadConfig().agent?.context?.compactionThreshold
-    try {
-      const agentsCol = await col<AgentDoc>("agents")
-      const coordinators = await agentsCol.findBy("role", "coordinator", { limit: 1 })
-      const modelId = fromIndexable(coordinators[0]?.doc.model_id ?? null)
-      if (modelId) {
-        const modelsCol = await col<ModelDoc>("models")
-        // El id se busca completo: recortar el primer segmento rompía cualquier
-        // modelo cuyo nombre lleve barra (meta/llama-3.3-70b-instruct buscaba
-        // "llama-3.3-70b-instruct", no encontraba nada y caía al default).
-        const modelEntry = await modelsCol.get(modelId)
-        if (modelEntry?.doc.context_window) {
-          effectiveThreshold = Math.floor(modelEntry.doc.context_window * 0.25)
-        }
-      }
-    } catch { /* use default threshold */ }
-
-    if (configurado && configurado > 0) effectiveThreshold = configurado
+    const contextWindow = llm?.contextWindow ?? (await modelContextWindow(llm?.model))
+    const effectiveThreshold = resolveCompactionThreshold(
+      loadConfig().agent?.context?.compactionThreshold,
+      contextWindow,
+    )
 
     if (totalTokens < effectiveThreshold) return
 
@@ -96,8 +133,8 @@ export async function maybeCompact(
     // Already summarized up to near the current state
     if (summary && summary.last_message_id > totalMessages - KEEP_LAST_N_MESSAGES) return
 
-    log.info(`[compaction] Compacting thread=${threadId} tokens=${totalTokens}`)
-    await compactThread(threadId, notify)
+    log.info(`[compaction] Compacting thread=${threadId} tokens=${totalTokens} threshold=${effectiveThreshold}`)
+    await compactThread(threadId, notify, llm)
   } catch (err) {
     log.warn("[compaction] Error during compaction check:", err)
   }
@@ -139,7 +176,8 @@ export function renderTranscript(rows: StoredMessage[], maxMsgChars = MAX_MSG_CH
  */
 export async function compactThread(
   threadId: string,
-  notify?: { channel: string; userId: string }
+  notify?: { channel: string; userId: string },
+  llm?: CompactionLLM
 ): Promise<void> {
   const allMessages = await getHistory(threadId)
   if (allMessages.length <= KEEP_LAST_N_MESSAGES) return
@@ -162,10 +200,18 @@ export async function compactThread(
   const capped = toSummarize.slice(-MAX_TRANSCRIPT_MSGS)
   const transcript = renderTranscript(capped)
 
-  const defaultLLM = await getDefaultLLM()
-  if (!defaultLLM) throw new Error("No active LLM providers/models configured in the database")
+  // El modelo del turno y SUS credenciales. Antes el resumen se pedía siempre
+  // con `getDefaultLLM()` y sin credenciales, así que `resolveProviderConfig`
+  // caía al secret store, al llavero del sistema o al entorno: en una
+  // instalación multi-inquilino eso resume la conversación de un cliente con
+  // la llave de la plataforma (o de otro cliente). Sin `llm` se comporta como
+  // antes, que es lo que necesita una instalación de un solo usuario.
+  const target = llm?.provider && llm.model
+    ? { provider: llm.provider, model: llm.model }
+    : await getDefaultLLM()
+  if (!target) throw new Error("No active LLM providers/models configured in the database")
 
-  const providerCfg = await resolveProviderConfig(defaultLLM.provider, defaultLLM.model)
+  const providerCfg = await resolveProviderConfig(target.provider, target.model, llm?.credentials)
 
   const summaryResponse = await callLLM({
     ...providerCfg,