@johpaz/hive-sdk 0.1.4 → 0.1.5

package/packages/core/src/agent/{selectors/ToolSelector.ts → tool-selector.ts}

@@ -1,48 +1,55 @@
 /**
- * FTS5-based Dynamic Tool Selector Module
- * 
+ * HiveDB-based Dynamic Tool Selector Module
+ *
  * Context Compiler Level 3 - Intelligent Tool Selection
- * 
+ *
  * This module intercepts each message BEFORE calling the LLM and uses
- * SQLite FTS5 bm25() scoring to select the most relevant tools (0-4).
- * 
+ * HiveDB BM25 scoring (Spanish stemming + accent folding, per-field boosts)
+ * to select the most relevant tools.
+ *
  * DESIGN DECISIONS:
- * 
+ *
  * 1. Stateless: No memory between turns - each message is evaluated independently.
  *    Rationale: Prevents cascade effects where a bad selection in one turn affects
  *    future turns. Forces fresh evaluation each time.
- * 
- * 2. Maximum 4 tools per turn: Keeps token count low and prevents overwhelming
+ *
+ * 2. Maximum tools per turn: Keeps token count low and prevents overwhelming
  *    the LLM with irrelevant tools. Forces prioritization.
- * 
- * 3. Relevance threshold: If highest bm25 score < MIN_RELEVANCE_THRESHOLD,
- *    the message is considered conversational and returns empty array.
- *    Rationale: Prevents false positives on generic messages like "hola" or
- *    "cómo estás?" which should not trigger any tools.
- * 
+ *
+ * 3. Relative relevance cutoff: BM25 scores are positive (higher = better) but
+ *    their magnitude depends on corpus and document length, so hits are kept
+ *    only if they score at least RELEVANCE_RATIO of the top hit. Conversational
+ *    messages are short-circuited by pattern matching before any search.
+ *
  * 4. Atomic over orchestration: When ambiguous, prefer individual tools over
  *    compound/manager tools. Rationale: Atomic tools are more predictable and
  *    the LLM can combine them as needed.
- * 
- * 5. Performance: Must complete in under 50ms. FTS5 queries are typically
- *    <5ms for small tool catalogs (<100 tools).
- * 
+ *
+ * 5. Performance: Must complete in under 50ms. HiveDB (tantivy) queries are
+ *    sub-millisecond for small tool catalogs (<100 tools).
+ *
  * 6. Tool categorization: Tools are categorized by semantic domain:
  *    - scheduling (cron tools)
- *    - projects (project/task management)
  *    - filesystem (file operations)
  *    - web (search/fetch)
  *    - browser (browser automation)
  *    - memory (notes, memory operations)
  *    - code (exec, terminal)
- *    - canvas (UI rendering)
+ *    - a2ui (interactive panel rendering)
  *    - agents (agent creation/management)
  *    - core (notify, report_progress, save_note)
  */
 
-import { getHiveDB } from "../../storage/HiveDBStorage.ts"
-import { logger } from "../../utils/logger.ts"
-import type { HiveDB, IndexDoc } from "@johpaz/hive-db";
+import { col } from "../storage/hive"
+import type { ToolDoc } from "../storage/collections"
+import { logger } from "../utils/logger"
+import {
+    searchCapabilities,
+    applyRelativeCutoff,
+    replaceCapabilityDocs,
+    type CapabilityDoc,
+} from "./capability-search"
+import { isCalendarOperation } from "./routing-intent"
 
 const log = logger.child("tool-selector")
 
@@ -75,18 +82,13 @@ export interface ToolSelectorResult {
 const MAX_TOOLS_PER_TURN = 12
 
 /**
- * Minimum bm25 score threshold. Below this = conversational, no tools needed.
- *
- * CRITICAL: bm25() returns NEGATIVE scores where closer to 0 = more relevant.
- * - Score of -5 is MORE relevant than -20
- * - We use -30 as threshold to filter noise while allowing valid matches
- *
- * Previous values: -25 (too strict), -100 (too permissive)
- * New value: -30 (balanced filtering, FTS5 MATCH handles the heavy lifting)
+ * Relative relevance cutoff: keep a hit only if it scores at least this
+ * fraction of the top hit. HiveDB BM25 scores are positive (higher = better)
+ * but corpus-dependent, so absolute thresholds don't transfer — a ratio does.
  */
-export const MIN_RELEVANCE_THRESHOLD = -30
+const RELEVANCE_RATIO = 0.3
 
-/** Stopwords to filter out before FTS5 query construction */
+/** Stopwords to filter out before BM25 query construction */
 const STOPWORDS = new Set([
     "que", "con", "para", "por", "una", "uno", "los", "las", "del",
     "como", "esta", "esto", "ese", "eso", "the", "and", "for",
@@ -113,15 +115,15 @@ const CONVERSATIONAL_PATTERNS = [
 //
 // These 47 tools are the core toolset. Each has:
 // - name: unique identifier
-// - description: what the tool does (used for FTS5 matching)
+// - description: what the tool does (used for BM25 matching)
 // - category: semantic domain for grouping
 // - abstractionLevel: atomic (single operation) vs orchestration (manages multiple)
 //
-// The descriptions are enriched with Spanish/English keywords for better FTS5 matching.
+// The descriptions are enriched with Spanish/English keywords for better BM25 matching.
 
 export const CORE_TOOL_CATALOG: ToolDescriptor[] = [
     // Cron tools (cron.*)
-    { name: "cron.create", description: "Create new cron job: recurring (cron expression) or one-shot (fire_at). Requires 'task' field with instruction for the agent. Spanish keywords: programar tarea, crear recordatorio, agendar, automatizar horario, tarea recurrente, recordatorio diario, una vez", category: "scheduling", abstractionLevel: "atomic" },
+    { name: "cron.create", description: "Create a Hive scheduled automation: recurring (cron expression) or one-shot (fire_at). Requires a task instruction. Spanish keywords: programar tarea, crear automatización, ejecutar después, tarea recurrente, recordatorio automático, una vez", category: "scheduling", abstractionLevel: "atomic" },
     { name: "cron.list", description: "List all cron jobs with next execution times and status. Spanish keywords: ver tareas programadas, listar cronograma, próximas ejecuciones, tareas activas, recordatorios pendientes", category: "scheduling", abstractionLevel: "atomic" },
     { name: "cron.update", description: "Update an existing cron job: change expression, task instruction, channel, time window, etc. Use cron.list first to get task_id. Spanish keywords: actualizar tarea, modificar cron, editar recordatorio, cambiar horario, actualizar programación", category: "scheduling", abstractionLevel: "atomic" },
     { name: "cron.pause", description: "Pause a cron job temporarily without deleting it. Spanish keywords: pausar tarea programada, detener temporalmente, suspender recordatorio", category: "scheduling", abstractionLevel: "atomic" },
@@ -130,25 +132,12 @@ export const CORE_TOOL_CATALOG: ToolDescriptor[] = [
     { name: "cron.trigger", description: "Manually trigger immediate execution of a cron job now. Spanish keywords: ejecutar tarea ahora, forzar ejecución, disparar manualmente", category: "scheduling", abstractionLevel: "atomic" },
     { name: "cron.history", description: "Get execution history and run logs for a cron job. Spanish keywords: historial ejecuciones, logs tarea, cuándo corrió, registro de ejecuciones", category: "scheduling", abstractionLevel: "atomic" },
 
-    // Project management tools (high-level orchestration)
-    { name: "project_create", description: "Create project with tasks, start new project for complex multi-step work. Spanish keywords: crear proyecto, nuevo proyecto, iniciar trabajo, proyecto nuevo, comenzar proyecto", category: "projects", abstractionLevel: "orchestration" },
-    { name: "project_list", description: "List all projects with their status. Spanish keywords: listar proyectos, ver proyectos, historial proyectos, todos los proyectos", category: "projects", abstractionLevel: "atomic" },
-    { name: "project_update", description: "Update project progress, mark progress percentage and status changes. Spanish keywords: actualizar progreso, marcar avance, estado del proyecto, porcentaje completado", category: "projects", abstractionLevel: "atomic" },
-    { name: "project_done", description: "Mark project complete, close finished projects and archive results. Spanish keywords: proyecto terminado, cerrar proyecto, finalizar, proyecto completado, marcar como hecho", category: "projects", abstractionLevel: "atomic" },
-    { name: "project_fail", description: "Mark project failed, record failure reason and lessons learned. Spanish keywords: proyecto fallido, error, marcar como fallido, proyecto fracasado, fracaso", category: "projects", abstractionLevel: "atomic" },
-
-    // Task management (atomic)
-    { name: "task_create", description: "Add task to project, create subtasks and action items within projects. Spanish keywords: crear tarea, nueva tarea, agregar pendiente, agregar tarea, crear subtarea", category: "projects", abstractionLevel: "atomic" },
-    { name: "task_update", description: "Update task status, mark tasks as complete or in progress. Spanish keywords: actualizar tarea, cambiar estado, marcar completa, tarea completada, tarea en progreso", category: "projects", abstractionLevel: "atomic" },
-    { name: "task_evaluate", description: "Evaluate task result against acceptance criteria. Spanish keywords: evaluar tarea, validar resultado, criterios aceptación, verificar calidad", category: "projects", abstractionLevel: "atomic" },
-
     // Code execution
     { name: "cli_exec", description: "Execute shell commands, run bash scripts and system commands. Spanish keywords: ejecutar comando, terminal, línea de comandos, bash, script, comando del sistema", category: "cli", abstractionLevel: "atomic" },
 
     // Web tools
     { name: "web_search", description: "Search web for current information, find up-to-date news facts and research. Spanish keywords: buscar en internet, buscar web, información, noticias, investigación, buscar", category: "web", abstractionLevel: "atomic" },
     { name: "web_fetch", description: "Fetch content from URL, download and extract content from web pages. Spanish keywords: obtener página, descargar web, extraer contenido, obtener contenido, página web", category: "web", abstractionLevel: "atomic" },
-    { name: "api_request", description: "Connect to REST APIs, make HTTP requests with authentication and custom headers. Spanish keywords: conectar api, peticion http, llamada api, rest api, endpoint, bearer token, api key, basic auth", category: "web", abstractionLevel: "atomic" },
 
     // Memory tools
     { name: "memory_write", description: "Store in long-term memory, save information to persistent memory for later retrieval. Spanish keywords: guardar memoria, guardar información, recordar, guardar dato, memoria", category: "memory", abstractionLevel: "atomic" },
@@ -158,8 +147,8 @@ export const CORE_TOOL_CATALOG: ToolDescriptor[] = [
     { name: "memory_delete", description: "Delete memory entry, remove saved memory from long-term storage. Spanish keywords: borrar memoria, eliminar información guardada, borrar dato, eliminar memoria", category: "memory", abstractionLevel: "atomic" },
 
     // Agent/worker management
-    { name: "agent_create", description: "Create specialized worker agent, spawn new agent for specific task execution. Spanish keywords: crear agente, nuevo agente, trabajador, crear worker, nuevo trabajador", category: "agents", abstractionLevel: "orchestration" },
-    { name: "agent_find", description: "Find existing worker agents, locate running or idle worker agents. Spanish keywords: buscar agente, encontrar trabajador, localizar, buscar worker, encontrar agente", category: "agents", abstractionLevel: "atomic" },
+    { name: "agent_create", description: "Create a specialized worker, including one persistent MCP server after user confirmation. Spanish keywords: crear agente, nuevo agente, trabajador, crear worker, especialista MCP", category: "agents", abstractionLevel: "orchestration" },
+    { name: "agent_find", description: "Discover available system catalog agents and user-owned workers. Not an execution monitor. Spanish keywords: buscar agente, encontrar trabajador, localizar, buscar worker, encontrar agente", category: "agents", abstractionLevel: "atomic" },
     { name: "agent_archive", description: "Archive unnecessary worker, terminate and archive idle or completed agents. Spanish keywords: archivar agente, terminar agente, borrar trabajador, desactivar agente", category: "agents", abstractionLevel: "atomic" },
 
     // Notes/persistence
@@ -178,29 +167,11 @@ export const CORE_TOOL_CATALOG: ToolDescriptor[] = [
     { name: "browser_script", description: "Execute arbitrary JavaScript in the browser page context and get the result. Spanish keywords: ejecutar javascript, script, código, función, evaluar, js en página", category: "browser", abstractionLevel: "atomic" },
     { name: "browser_wait", description: "Wait for an element to appear or condition to be met on the page. Spanish keywords: esperar, wait, condición, elemento, selector, aguardar carga", category: "browser", abstractionLevel: "atomic" },
 
-    // Canvas/UI rendering tools
-    { name: "canvas_render", description: "Render component on canvas, display UI components and data visualizations. Spanish keywords: renderizar, mostrar en canvas, visualizar, mostrar componente, dibujar", category: "canvas", abstractionLevel: "atomic" },
-    { name: "canvas_ask", description: "Display form and wait for response, show interactive form and collect user input. Spanish keywords: mostrar formulario, pedir datos, solicitar información, formulario interactivo", category: "canvas", abstractionLevel: "atomic" },
-    { name: "canvas_clear", description: "Clear canvas for session, reset canvas display and start fresh. Spanish keywords: limpiar canvas, borrar pantalla, reiniciar, limpiar, borrar", category: "canvas", abstractionLevel: "atomic" },
-    { name: "canvas_show_card", description: "Display card with labeled items, show structured data in card format. Spanish keywords: mostrar tarjeta, visualizar datos, tarjeta de información, mostrar datos", category: "canvas", abstractionLevel: "atomic" },
-    { name: "canvas_show_progress", description: "Display progress bars, show progress indicators and completion status. Spanish keywords: mostrar progreso, barra de progreso, indicador de progreso, avance", category: "canvas", abstractionLevel: "atomic" },
-    { name: "canvas_show_list", description: "Display key-value list, show information in structured list format. Spanish keywords: mostrar lista, listar elementos, lista de valores, mostrar elementos", category: "canvas", abstractionLevel: "atomic" },
-    { name: "canvas_confirm", description: "Show confirmation dialog, request user confirmation for actions. Spanish keywords: confirmar, diálogo de confirmación, confirmar acción, validación", category: "canvas", abstractionLevel: "atomic" },
-
     // A2UI v0.9 rich interactive surfaces
     { name: "a2ui_create_surface", description: "Create A2UI v0.9 surface for rich interactive UIs with forms, dashboards, and workflows. Spanish keywords: crear superficie A2UI, iniciar UI interactiva, crear formulario rico, interfaz A2UI, crear surface", category: "a2ui", abstractionLevel: "orchestration" },
     { name: "a2ui_update_components", description: "Send A2UI v0.9 components to an existing surface (Text, Button, TextField, Row, Column, Card, etc.). Spanish keywords: enviar componentes A2UI, actualizar UI, renderizar componentes, A2UI componentes, update components", category: "a2ui", abstractionLevel: "atomic" },
     { name: "a2ui_update_data_model", description: "Update A2UI v0.9 surface data model with JSON Pointer for dynamic data binding. Spanish keywords: actualizar datos A2UI, poblar formulario, cambiar valores, data model A2UI, actualizar modelo de datos", category: "a2ui", abstractionLevel: "atomic" },
-    { name: "a2ui_delete_surface", description: "Delete A2UI v0.9 surface and remove it from the user's canvas. Spanish keywords: eliminar superficie A2UI, borrar UI, limpiar superficie A2UI, cerrar formulario, delete surface", category: "a2ui", abstractionLevel: "atomic" },
-
-    // CodeBridge (subagent process management)
-    { name: "codebridge_launch", description: "Launch subagent process, spawn new code bridge agent process. Spanish keywords: lanzar proceso, iniciar subagente, ejecutar código, nuevo proceso", category: "code", abstractionLevel: "orchestration" },
-    { name: "codebridge_status", description: "Get status of running subagents, check code bridge agent status. Spanish keywords: estado del proceso, verificar subagente, estado del worker, estado", category: "code", abstractionLevel: "atomic" },
-    { name: "codebridge_cancel", description: "Cancel running subagent, terminate code bridge agent process. Spanish keywords: cancelar proceso, terminar subagente, detener proceso, parar", category: "code", abstractionLevel: "atomic" },
-
-    // Voice tools
-    { name: "voice_transcribe", description: "Transcribe audio to text, convert speech to written text from audio files. Spanish keywords: transcribir audio, voz a texto, convertir audio, transcripción", category: "voice", abstractionLevel: "atomic" },
-    { name: "voice_speak", description: "Convert text to audio and play, synthesize speech from text. Spanish keywords: hablar, sintetizar voz, texto a voz, reproducir audio, voz", category: "voice", abstractionLevel: "atomic" },
+    { name: "a2ui_delete_surface", description: "Delete A2UI v0.9 surface from the user's interactive panel. Spanish keywords: eliminar superficie A2UI, borrar UI, limpiar superficie A2UI, cerrar formulario, delete surface", category: "a2ui", abstractionLevel: "atomic" },
 
     // Filesystem tools
     { name: "fs_read", description: "Read file content from workspace. Spanish keywords: leer archivo, ver contenido, abrir archivo, leer fichero, mostrar archivo", category: "filesystem", abstractionLevel: "atomic" },
@@ -213,11 +184,35 @@ export const CORE_TOOL_CATALOG: ToolDescriptor[] = [
 
     // Agent delegation and communication
     { name: "task_delegate", description: "Delegate general task to worker agent. Spanish keywords: delegar tarea, asignar worker, ejecutar por agente, encomendar tarea", category: "agents", abstractionLevel: "orchestration" },
-    { name: "task_delegate_code", description: "Delegate coding task to CLI subagent (Qwen, Claude Code, Gemini CLI). Spanish keywords: delegar código, subagente CLI, programación, codificar", category: "agents", abstractionLevel: "orchestration" },
+    { name: "task_revise", description: "Send a delegated task back to its worker with feedback when it does not meet its acceptance criteria. Spanish keywords: corregir tarea, devolver al worker, pedir correccion, reencolar tarea", category: "agents", abstractionLevel: "orchestration" },
+    { name: "task_list", description: "List real delegated task executions for the current user from persisted tasks and jobs. Spanish keywords: listar tareas activas, subagentes trabajando, ejecuciones reales", category: "agents", abstractionLevel: "atomic" },
     { name: "task_status", description: "Get execution status of delegated tasks. Spanish keywords: estado tarea delegada, verificar progreso, consultar tarea, progreso delegado", category: "agents", abstractionLevel: "atomic" },
     { name: "bus_publish", description: "Publish message to Agent Bus for worker-to-worker communication. Spanish keywords: publicar mensaje, comunicar workers, enviar bus, mensaje bus", category: "agents", abstractionLevel: "atomic" },
     { name: "bus_read", description: "Read unread messages from Agent Bus. Spanish keywords: leer mensajes bus, recibir mensajes, verificar bus, mensajes workers", category: "agents", abstractionLevel: "atomic" },
-    { name: "project_updates", description: "Get recent status updates from workers in project. Spanish keywords: actualizaciones proyecto, estado workers, progreso equipo, noticias proyecto", category: "agents", abstractionLevel: "atomic" },
+
+    // Model discovery
+    { name: "get_available_models", description: "List configured providers and models with their capabilities and context windows. Spanish keywords: modelos disponibles, proveedores activos, qué modelos hay, listar modelos", category: "agents", abstractionLevel: "atomic" },
+
+    // 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" },
+
+    // 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" },
+
+    // Artifacts
+    { name: "artifact_inspect", description: "Inspect a managed artifact's integrity and metadata without modifying it. Spanish keywords: inspeccionar artefacto, verificar archivo generado, metadatos artefacto, comprobar entrega", category: "web", abstractionLevel: "atomic" },
+
+    // Office documents — read
+    { name: "office_leer_pdf", description: "Read and extract text from a PDF document. Spanish keywords: leer pdf, extraer texto pdf, abrir pdf, contenido pdf", category: "office", abstractionLevel: "atomic" },
+    { name: "office_leer_docx", description: "Read and extract text from a Word document. Spanish keywords: leer word, leer docx, abrir documento word, contenido word", category: "office", abstractionLevel: "atomic" },
+    { name: "office_leer_xlsx", description: "Read rows and sheets from an Excel spreadsheet. Spanish keywords: leer excel, leer xlsx, abrir hoja de cálculo, contenido excel, leer planilla", category: "office", abstractionLevel: "atomic" },
+    { name: "office_leer_pptx", description: "Read slides and text from a PowerPoint presentation. Spanish keywords: leer powerpoint, leer pptx, abrir presentación, contenido diapositivas", category: "office", abstractionLevel: "atomic" },
+
+    // Office documents — write
+    { name: "office_escribir_pdf", description: "Generate a PDF document. Spanish keywords: crear pdf, generar pdf, escribir pdf, exportar a pdf", category: "office", abstractionLevel: "atomic" },
+    { name: "office_escribir_docx", description: "Generate a Word document. Spanish keywords: crear word, generar docx, escribir documento word, exportar a word", category: "office", abstractionLevel: "atomic" },
+    { name: "office_escribir_xlsx", description: "Generate an Excel spreadsheet. Spanish keywords: crear excel, generar xlsx, escribir hoja de cálculo, exportar a excel, armar planilla", category: "office", abstractionLevel: "atomic" },
+    { name: "office_escribir_pptx", description: "Generate a PowerPoint presentation. Spanish keywords: crear powerpoint, generar pptx, escribir presentación, armar diapositivas", category: "office", abstractionLevel: "atomic" },
 ]
 
 // ─── Helper Functions ───────────────────────────────────────────────────────-
@@ -254,27 +249,6 @@ function isConversational(message: string): boolean {
     return false
 }
 
-/**
- * Build FTS5 query from user message
- * 
- * Strips stopwords, special characters, and limits to 8 keywords.
- * Uses OR operator for flexible matching.
- */
-function buildFTSQuery(message: string): string {
-    log.info(`[tool-selector] Building FTS query from message: "${message}"`)
-    const words = message
-        .toLowerCase()
-        .replace(/[^\p{L}\p{N}\s]/gu, " ")
-        .split(/\s+/)
-        .filter((w) => w.length > 2 && !STOPWORDS.has(w))
-        .slice(0, 8)
-
-    if (words.length === 0) return ""
-
-    // Use prefix matching for better recall (e.g., "gener*" matches "generar", "generando", "generación")
-    return words.map(w => `${w}*`).join(" OR ")
-}
-
 /**
  * Determine abstraction level preference
  * 
@@ -289,19 +263,19 @@ function getAbstractionPreference(): "atomic" | "orchestration" {
 // ─── Main Selection Function ─────────────────────────────────────────────────
 
 /**
- * Select tools for a given user message using FTS5 bm25() scoring
- * 
+ * Select tools for a given user message using HiveDB BM25 scoring
+ *
  * @param userMessage - The raw user message
  * @param fullToolList - Full list of available tools (for validation/filtering)
- * @returns Array of 0-4 selected tools with scores
- * 
+ * @returns Array of selected tools
+ *
  * ALGORITHM:
  * 1. If conversational → return []
- * 2. Build FTS5 query from message keywords
- * 3. Query tools_fts with bm25() scoring
- * 4. Filter results below MIN_RELEVANCE_THRESHOLD
- * 5. If ambiguous → prefer atomic over orchestration
- * 6. Return top maxTools results (default: MAX_TOOLS_PER_TURN)
+ * 2. Query the HiveDB capability index with the raw message (the engine
+ *    handles Spanish stemming, accent folding and malformed input)
+ * 3. Keep hits scoring at least RELEVANCE_RATIO of the top hit
+ * 4. If ambiguous → prefer atomic over orchestration
+ * 5. Return top maxTools results (default: MAX_TOOLS_PER_TURN)
  */
 export async function selectTools(
     userMessage: string,
@@ -319,41 +293,64 @@ export async function selectTools(
         return []
     }
 
-    // Step 2: Build search query
-    const searchQuery = buildFTSQuery(userMessage)
-    if (!searchQuery) {
-        log.debug(`[tool-selector] No valid query terms, returning empty array`)
+    // Step 2: Query the capability index with the raw message.
+    // Get more initially (maxTools * 2) for filtering, then limit to maxTools.
+    let hits
+    try {
+        hits = await searchCapabilities(userMessage, {
+            types: ["tool"],
+            k: maxTools * 2,
+        })
+    } catch (err) {
+        log.error(`[tool-selector] Capability search failed:`, err)
         return []
     }
 
-    log.debug(`[tool-selector] Search query: "${searchQuery}"`)
-
-    // Step 3: Execute hybrid search over the HiveDB semantic index
-    const db = await getHiveDB()
-
-    // HiveDB text-only BM25 returns positive scores where higher is better.
-    const hits = await db.queryHybrid({
-        text: searchQuery,
-        k: maxTools * 2,
-        boosts: { name: 5.0, body: 3.0, tags: 1.0 },
-    })
-
     if (hits.length === 0) {
-        log.debug(`[tool-selector] No index matches, returning empty array`)
+        log.debug(`[tool-selector] No matches, returning empty array`)
         return []
     }
 
     // Log raw scores for debugging
-    log.info(`[tool-selector] Raw scores: ${hits.slice(0, 10).map(r => `${r.id}=${r.score.toFixed(2)}`).join(", ")}`)
+    log.info(`[tool-selector] Raw scores: ${hits.slice(0, 10).map(h => `${h.rawId}=${h.score.toFixed(2)}`).join(", ")}`)
+
+    // Step 3: Keep only hits close enough to the best match
+    const relevantHits = applyRelativeCutoff(hits, RELEVANCE_RATIO)
+    if (relevantHits.length === 0) {
+        log.debug(`[tool-selector] All results below ratio cutoff, returning empty`)
+        return []
+    }
 
-    // Step 4: Map to tool descriptors with additional metadata
+    // Step 4: Map to tool descriptors with additional metadata.
+    //
+    // El mapa tiene que cubrir lo mismo que se indexó, o el hit se descarta en
+    // silencio. `syncToolCatalogToIndex` indexa CORE_TOOL_CATALOG **más** las
+    // filas de la colección `tools`; resolver sólo contra `fullToolList` (que
+    // por defecto es CORE_TOOL_CATALOG) hacía que una tool registrada en runtime
+    // —las que la app declara con `defineTool`— puntuara primero en BM25 y aun
+    // así nunca se le ofreciera al modelo.
     const toolMap = new Map(fullToolList.map(t => [t.name, t]))
+    const unresolved = relevantHits.filter(h => !toolMap.has(h.rawId))
+    if (unresolved.length > 0) {
+        const toolsCol = await col<ToolDoc>("tools")
+        for (const hit of unresolved) {
+            const entry = await toolsCol.get(hit.rawId)
+            if (!entry?.doc.enabled || !entry.doc.active) continue
+            toolMap.set(entry.doc.name, {
+                name: entry.doc.name,
+                description: entry.doc.description ?? entry.doc.name,
+                category: (entry.doc.category ?? "core") as any,
+                abstractionLevel: "atomic",
+            })
+        }
+    }
 
-    const scoredTools: SelectedTool[] = []
+    const calendarOperation = isCalendarOperation(userMessage)
 
-    for (const hit of hits) {
-        const tool = toolMap.get(hit.id)
-        if (tool) {
+    const scoredTools: SelectedTool[] = []
+    for (const hit of relevantHits) {
+        const tool = toolMap.get(hit.rawId)
+        if (tool && !(calendarOperation && tool.category === "scheduling")) {
             scoredTools.push({
                 name: tool.name,
                 score: hit.score,
@@ -366,11 +363,12 @@ export async function selectTools(
     const abstractionPref = getAbstractionPreference()
 
     if (scoredTools.length > MAX_TOOLS_PER_TURN) {
-        // Sort by score descending (higher HiveDB score = more relevant)
         scoredTools.sort((a, b) => {
+            // First by score (descending: HiveDB scores are positive, higher = better)
             if (Math.abs(a.score - b.score) > 0.1) {
                 return b.score - a.score
             }
+            // Then by abstraction preference (preferred type first)
             const aTool = toolMap.get(a.name)
             const bTool = toolMap.get(b.name)
             const aLevel = aTool?.abstractionLevel ?? "atomic"
@@ -392,6 +390,7 @@ export async function selectTools(
 
     const timing = performance.now() - startTime
 
+    // Log final selected tools with info level (important for tracking tool selection process)
     if (result.length > 0) {
         log.info(`[tool-selector] Selected ${result.length} tools in ${timing.toFixed(2)}ms:`,
             result.map(t => ({ name: t.name, category: t.category })))
@@ -402,41 +401,52 @@ export async function selectTools(
     return result
 }
 
-// ─── Sync Tools to FTS5 ─────────────────────────────────────────────────────
+// ─── Sync Tools to HiveDB ────────────────────────────────────────────────────
 
 /**
- * Sync tool catalog to FTS5 virtual table
+ * Sync tool catalog to the HiveDB capability index.
  *
- * Called on initialization from gateway/initializer.ts to populate the FTS5 index.
- * Assumes the tools_fts table already exists (created by CONTEXT_ENGINE_SCHEMA).
- * Descriptions are enriched with bilingual keywords for better matching.
+ * Called on initialization from gateway/initializer.ts to populate the index.
+ * Replaces all `type=tool` documents atomically (delete-by-filter + one
+ * batch commit). Descriptions are enriched with bilingual keywords.
  *
  * @param tools - Optional array of tools to sync. If not provided, fetches from DB.
  */
-export async function syncToolCatalogToFTS(tools?: ToolDescriptor[]): Promise<void> {
-    const db = await getHiveDB()
-
+export async function syncToolCatalogToIndex(tools?: ToolDescriptor[]): Promise<void> {
     try {
-        // Step 1: Build full catalog = CORE_TOOL_CATALOG + any explicitly passed tools
+        // Step 1: Build full catalog = CORE_TOOL_CATALOG + any tools in DB not already covered
+        // CORE_TOOL_CATALOG has bilingual keywords; DB tools may be dynamically registered
         const catalogByName = new Map<string, ToolDescriptor>(
             CORE_TOOL_CATALOG.map(t => [t.name, t])
         )
 
-        // Merge in any tools persisted in HiveDB that are missing from the static catalog
-        const toolsCol = db.collection<ToolDescriptor>("tools")
-        const dbTools = await toolsCol.scan()
-        for (const entry of dbTools) {
-            const row = entry.doc
-            if (!catalogByName.has(row.name)) {
-                catalogByName.set(row.name, {
-                    name: row.name,
-                    description: row.description ?? row.name,
-                    category: row.category ?? "core",
-                    abstractionLevel: row.abstractionLevel ?? "atomic",
-                })
+        // Merge in any tools from the DB that are missing from the static catalog
+        const toolsCol = await col<ToolDoc>("tools")
+        const dbTools = (await toolsCol.scan({})).map(e => e.doc)
+        for (const row of dbTools) {
+            if (catalogByName.has(row.name)) continue
+
+            // Check if this is a legacy name with different separator
+            // (e.g. "cron_create" vs "cron.create" — seed was wrong, tools use dots)
+            const altName = row.name.includes("_")
+                ? row.name.replace(/_/g, ".")
+                : row.name.includes(".")
+                    ? row.name.replace(/\./g, "_")
+                    : ""
+            if (altName && catalogByName.has(altName)) {
+                log.info(`[tool-selector] Skipping legacy tool name "${row.name}" — canonical "${altName}" already in catalog`)
+                continue
             }
+
+            catalogByName.set(row.name, {
+                name: row.name,
+                description: row.description ?? row.name,
+                category: (row.category ?? "core") as any,
+                abstractionLevel: "atomic",
+            })
         }
 
+        // Also merge any explicitly passed tools (e.g. from initializer)
         for (const t of (tools || [])) {
             if (!catalogByName.has(t.name)) {
                 catalogByName.set(t.name, t)
@@ -445,44 +455,41 @@ export async function syncToolCatalogToFTS(tools?: ToolDescriptor[]): Promise<vo
 
         const toolCatalog = Array.from(catalogByName.values())
 
-        // Step 2: Build index documents and upsert atomically via batch
-        const docs: IndexDoc[] = toolCatalog.map(tool => ({
-            id: tool.name,
+        // Step 2: Replace all tool documents in the HiveDB capability index
+        const docs: CapabilityDoc[] = toolCatalog.map(tool => ({
+            type: "tool" as const,
+            rawId: tool.name,
             name: tool.name,
             body: enrichToolDescription(tool),
             tags: tool.category,
-            filters: [{ field: "type", value: "tool" }],
         }))
 
-        await db.clearIndex()
-        await db.upsertBatch(docs)
+        await replaceCapabilityDocs("tool", docs)
 
-        log.info(`[tool-selector] Atomic sync complete: ${toolCatalog.length} tools indexed in HiveDB`)
+        log.info(`[tool-selector] Sync complete: ${toolCatalog.length} tools indexed in HiveDB`)
 
     } catch (err) {
-        log.error(`[tool-selector] Transactional sync failed:`, err)
-        throw err
+        log.error(`[tool-selector] Tool index sync failed:`, err)
+        throw err // Re-throw to inform initializer
     }
 }
 
 /**
  * Enrich tool description with category-specific keywords
  * 
- * This improves FTS5 matching for both English and Spanish queries.
+ * This improves BM25 matching for both English and Spanish queries.
  */
-export function enrichToolDescription(tool: ToolDescriptor): string {
+function enrichToolDescription(tool: ToolDescriptor): string {
     const keywordsByCategory: Record<string, string> = {
         scheduling: "programar recordatorio alarma cron schedule reminder task future tiempo",
-        projects: "proyecto tarea plan organizer milestone backlog sprint work",
         filesystem: "archivo file leer escribir editar documento content source code",
         web: "buscar internet google web search find information news research",
         browser: "navegador browser click screenshot form automation web page UI",
         memory: "recordar nota guardar memory store remember persist knowledge",
         code: "code ejecutar run script bash shell terminal command devops",
-        canvas: "canvas diagram visualization graph node edge flow chart",
-        agents: "agente worker specialist create delegate hire team manager",
+        a2ui: "A2UI interactive panel interface form dashboard visualization",
+        agents: "agente worker catalog create delegate hire team manager",
         core: "notificar message alert notify communicate progress status",
-        voice: "voz audio transcribir speech speak sintetizar audio voice transcription",
     }
 
     const extra = keywordsByCategory[tool.category] ?? ""
@@ -497,25 +504,28 @@ export function enrichToolDescription(tool: ToolDescriptor): string {
  * Gemini (and OpenAI) require: start with letter/underscore, only [a-zA-Z0-9_.-:], max 64 chars.
  * Server names from the UI can contain spaces and special chars (e.g. "X antes twiter").
  *
- * Canonical format: `{safeServer}__{safeTool}` (double underscore as separator)
+ * Canonical format: `{safeServer}__{safeTool}` (double underscore as separator).
+ * The server prefix exists only to disambiguate tools with the same name
+ * across servers — when the 64-char budget is exceeded, the SERVER part is
+ * shortened first so the distinctive tool name survives intact (long server
+ * names must never truncate the tool name).
  */
 export function mcpToolFullName(serverName: string, toolName: string): string {
-    const safe = (s: string) => s.replace(/\s+/g, '_').replace(/[^a-zA-Z0-9_.\-:]/g, '_')
-    const full = `${safe(serverName)}__${safe(toolName)}`
-    // Ensure starts with letter/underscore and fits within 64 chars
-    const trimmed = full.length > 64 ? full.substring(0, 64) : full
-    return /^[a-zA-Z_]/.test(trimmed) ? trimmed : `_${trimmed}`.substring(0, 64)
-}
+    const MAX = 64
+    const MIN_SERVER = 8
+    const safe = (s: string) => s.replace(/\s+/g, '_').replace(/[^a-zA-Z0-9_\-]/g, '_')
 
-/**
- * Initialize the tool selector
- *
- * DEPRECATED: syncToolCatalogToFTS() is now called from gateway/initializer.ts
- * This function is kept for backward compatibility but is no longer needed
- */
-export function initializeToolSelector(): void {
-    log.info(`[tool-selector] Initializing (deprecated - sync is done in gateway/initializer.ts)`)
-    // syncToolCatalogToFTS() - No longer needed here, done in gateway/initializer.ts
+    let server = safe(serverName)
+    const tool = safe(toolName)
+
+    const room = MAX - 2 - tool.length
+    if (server.length > room) {
+        server = server.substring(0, Math.max(room, MIN_SERVER))
+    }
+
+    let full = `${server}__${tool}`
+    if (full.length > MAX) full = full.substring(0, MAX)
+    return /^[a-zA-Z_]/.test(full) ? full : `_${full}`.substring(0, MAX)
 }
 
 // ─── Debug/Test Helpers ─────────────────────────────────────────────────────